API v1 · REST · JSON

ZipFactura API

Integrá la emisión de comprobantes fiscales electrónicos de Uruguay directamente en tu sistema. Endpoints REST, webhooks en tiempo real, y sandbox de pruebas.

Base URL

https://nube.zipfactura.com.uy/api

Sandbox

Para pruebas, los CFEs se emiten contra el ambiente de test de DGI y no tienen validez fiscal. Usá las mismas credenciales — el ambiente de test se activa automáticamente mientras tu empresa esté en modo prueba.

Autenticación

Todos los endpoints requieren una API Key en el header Authorization. Las API Keys se generan desde el portal en Plan y facturación → API Keys (requiere plan API).

Authorization: Bearer zip_xxxxxxxxxxxxxxxx
Las API Keys empiezan siempre con zip_. Nunca las compartas ni las pongas en código del lado del cliente.

# Ejemplo con curl
curl https://nube.zipfactura.com.uy/api/comprobantes \
  -H "Authorization: Bearer zip_tu_api_key_aqui"

Errores

ZipFactura usa códigos HTTP estándar. Los errores devuelven un JSON con el campo error.

Código	Significado
200	OK
201	Creado correctamente
400	Error en los datos enviados
401	API Key inválida o faltante
402	Límite del plan alcanzado
403	Sin permisos para esta acción
404	Recurso no encontrado
422	DGI rechazó el comprobante
500	Error interno

// Ejemplo de respuesta de error
{
  "error": "No hay CAEs disponibles para este tipo de comprobante"
}

Comprobantes

POST /comprobantes Emitir un CFE

Crea y emite un comprobante fiscal electrónico en tiempo real. El CFE se envía a DGI y retorna con su número y URL oficial.

Body

Campo	Tipo	Descripción
tipo REQ	string	`eticket` · `efactura` · `nc_ticket` · `nc_factura`
items REQ	array	Lista de ítems del comprobante (ver abajo)
cliente	object	Datos del cliente (opcional para consumidor final)
moneda	string	`UYU` (default) o `USD`
forma_pago	number	`1` = Contado · `2` = Crédito
id_externo	string	Tu ID interno para idempotencia (evita duplicados)

Items

Campo	Tipo	Descripción
concepto REQ	string	Descripción del producto o servicio
cantidad REQ	number	Cantidad
precio REQ	number	Precio unitario con IVA incluido
indicador_facturacion	number	`3` = IVA 22% (default) · `1` = exento · `2` = IVA 10%

Ejemplo

POST /api/comprobantes
Authorization: Bearer zip_tu_api_key

{
  "tipo": "eticket",
  "moneda": "UYU",
  "forma_pago": 1,
  "id_externo": "pedido-12345",
  "cliente": {
    "tipo_doc": 3,
    "nro_doc": "45123456",
    "nombre": "Juan García",
    "email": "juan@email.com"
  },
  "items": [
    {
      "concepto": "Servicio de diseño web",
      "cantidad": 1,
      "precio": 12200
    }
  ]
}

Respuesta exitosa

{
  "id": "uuid-del-comprobante",
  "tipo": "eticket",
  "serie": "A",
  "numero": 42,
  "estado": "aprobado",
  "monto_total": "12200.00",
  "feu_url": "https://efactura.dgi.gub.uy/...",
  "cae_numero": 90000000001,
  "created_at": "2026-06-25T18:00:00Z"
}

GET /comprobantes Listar comprobantes

Query params

Param	Descripción
estado	Filtrar: `aprobado` · `pendiente` · `rechazado`
tipo	Filtrar: `eticket` · `efactura`
desde	Fecha inicio (ISO 8601)
hasta	Fecha fin (ISO 8601)
limit	Resultados por página (max 100, default 50)
offset	Para paginación

GET /api/comprobantes?estado=aprobado&limit=10
Authorization: Bearer zip_tu_api_key

GET /comprobantes/:id Consultar un CFE

El :id puede ser el UUID interno de ZipFactura o tu id_externo.

GET /api/comprobantes/pedido-12345
Authorization: Bearer zip_tu_api_key

POST /comprobantes/:id/anular Anular un CFE

Genera una Nota de Crédito automáticamente que anula el comprobante indicado. Solo se pueden anular CFEs con estado aprobado.

POST /api/comprobantes/uuid-del-comprobante/anular
Authorization: Bearer zip_tu_api_key

Empresa

GET /empresa Datos e info de la empresa

GET /api/empresa
// Retorna: rut, razon_social, plan, estado, setup_step, etc.

GET /empresa/caes CAEs disponibles

Retorna todos los CAEs de la empresa con sus rangos, disponibles y fecha de vencimiento. Útil para monitorear antes de que se agoten.

Webhooks

ZipFactura puede notificar a tu sistema cuando ocurren eventos importantes. Configurá una URL y recibirás un POST con el payload del evento.

Verificar la firma

Cada webhook incluye el header X-Zipfactura-Signature: sha256=.... Verificalo para confirmar que el request viene de ZipFactura:

const crypto = require('crypto');

function verificarFirma(payload, firma, secret) {
  const esperada = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=\${esperada}` === firma;
}

Eventos disponibles

Evento	Cuándo se dispara
cfe.aprobado	DGI aprobó el comprobante
cfe.rechazado	DGI rechazó el comprobante
cfe.anulado	Se emitió una NC que anula el CFE
cae.por_vencer	Un CAE vence en menos de 30 días

Payload de ejemplo (cfe.aprobado)

{
  "evento": "cfe.aprobado",
  "timestamp": 1719334800000,
  "data": {
    "id": "uuid-comprobante",
    "tipo": "eticket",
    "serie": "A",
    "numero": 42,
    "monto_total": "12200.00",
    "feu_url": "https://efactura.dgi.gub.uy/...",
    "id_externo": "pedido-12345"
  }
}