Integración (API para terceros)

Esta guía explica cómo conectar tu sistema (POS, ERP, e-commerce, facturador propio) a Zentto Imprenta Digital para emitir documentos fiscales contra las series propias de Zentto (proveedor autorizado). Modela el mismo flujo que un proveedor HKA ofrece: te autenticas con tokenUsuario + secret, recibes un token de sesión y emites.

Para el detalle exhaustivo de cada campo, ve a Referencia de API y Ejemplos de documentos. Esta página es el recorrido de implementación.

Para usuarios

Si tu empresa fue dada de alta como integrador, recibirás por correo un enlace de un solo uso para ver tus credenciales de API (Token Usuario + Secret). Ese enlace:

Se abre una sola vez y expira (por defecto 72 h).
No contiene la clave en el cuerpo del correo (seguridad): solo el enlace.
Si vence, pide un reenvío al equipo de la imprenta desde el backoffice.

Guarda el Secret en un gestor seguro apenas lo veas: no se puede volver a mostrar. Si se compromete, se puede rotar (se revoca el anterior y se emite uno nuevo).

Para desarrolladores

1. Requisitos previos

Token Usuario + Secret (entregados por el enlace de un solo uso).
Ambiente objetivo: demo (pruebas) o production.
Servidores:

Ambiente Base URL
Producción https://imprenta.zentto.net
Desarrollo https://imprentadev.zentto.net
Local http://localhost:4900

Ambiente	Base URL
Producción	`https://imprenta.zentto.net`
Desarrollo	`https://imprentadev.zentto.net`
Local	`http://localhost:4900`

El contrato máquina-legible (OpenAPI 3.0) está disponible autenticado en GET /api/openapi.json y en el portal (Backoffice → Contrato API), desde donde puedes descargarlo para generar clientes con openapi-generator u otras herramientas.

2. Autenticación — `POST /api/Autenticacion`

Intercambia tokenUsuario + secret por un JWT corto (Bearer, TTL 1 h). No hay refresh: al expirar, repite la autenticación.

curl -X POST https://imprenta.zentto.net/api/Autenticacion \
  -H "Content-Type: application/json" \
  -d '{ "tokenUsuario": "imp_xxx", "secret": "<secret>" }'

{
  "ok": true,
  "token": "<jwt corto>",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "integrador": { "id": 12, "nombre": "Mi POS", "ambiente": "production" }
}

Usa el token en el resto de llamadas: Authorization: Bearer <token>. El companyId sale del token (anti-IDOR): tu sistema solo opera sobre sus propias series y documentos.

3. Emitir un documento — `POST /api/emit`

El cuerpo es { environment, document }. document usa el formato canónico de Zentto (campos en inglés: documentType, documentNumber, serie, currency, issueDate, buyer, items, totals). Ejemplo mínimo (factura, un ítem gravado 16 %):

curl -X POST https://imprenta.zentto.net/api/emit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @factura.json

{
  "environment": "production",
  "document": {
    "documentType": "01",
    "documentNumber": "50370",
    "serie": "A",
    "currency": "BSD",
    "issueDate": "23/01/2026",
    "buyer": { "idType": "J", "idNumber": "59858589-9", "name": "PRUEBA DE EMPRESA", "address": "CARACAS", "country": "VE" },
    "items": [
      { "lineNumber": 1, "description": "SERVICIO", "quantity": 1, "unitPrice": 100.00,
        "discount": 0.00, "netPrice": 100.00, "taxCode": "G", "taxRate": 16, "taxAmount": 16.00, "lineTotal": 116.00 }
    ],
    "totals": {
      "itemCount": 1, "taxedAmount": 100.00, "subtotal": 100.00, "totalIva": 16.00,
      "totalWithIva": 116.00, "totalToPay": 116.00,
      "taxSubtotals": [ { "code": "G", "rate": 16, "base": 100.00, "amount": 16.00 } ],
      "payments": [ { "method": "05", "description": "Tarjeta de débito", "amount": 116.00, "currency": "BSD", "exchangeRate": 0.0 } ]
    }
  }
}

Respuesta 201 (emitido) o 422 (rechazo de negocio):

{ "ok": true, "documentoId": 8123, "result": { "...": "..." } }

Guarda documentoId: es la referencia para consultar estado, PDF o anular.

Casos completos (IVA General/Reducida/Adicional/Exento, IGTF por pago en divisa, notas de crédito/débito con documento afectado, retenciones IVA/ISLR, descuentos globales y por ítem, multimoneda): ver Ejemplos de documentos.

4. Consultar estado y PDF

GET /api/documentos/{id}/status   → { ok, result }
GET /api/documentos/{id}/pdf      → { ok, fileType, base64 }

El PDF llega en base64; decodifícalo para guardarlo o mostrarlo. 422 pdf_unavailable si el documento aún no tiene representación gráfica disponible.

5. Anular — `POST /api/documentos/{id}/annul`

curl -X POST https://imprenta.zentto.net/api/documentos/8123/annul \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Error en datos del comprador" }'

Respuesta 200 (anulado) o 422 (no se pudo anular).

6. Numeración — `GET /api/numeraciones`

Consulta los rangos de tus series propias. Query opcional tipoDocumento (default 01) y serie.

GET /api/numeraciones?tipoDocumento=01&serie=A → { ok, ... rangos }

412 si la empresa no tiene credenciales del proveedor configuradas.

7. Ambientes

demo: no consume numeración fiscal real; úsalo para desarrollar y certificar tu integración.
production: emite contra series fiscales reales (metered/facturable).

El ambiente por defecto sale de tu token; puedes forzarlo por documento con environment en el cuerpo de /api/emit.

8. Manejo de errores

Código	Significado	Acción sugerida
`400`	Payload inválido (validación)	Corrige el cuerpo; revisa `issues`.
`401`	Token ausente/inválido/expirado	Reautentica en `/api/Autenticacion` y reintenta.
`412`	Credenciales del proveedor no configuradas	Contacta a la imprenta.
`422`	Rechazo de negocio (emisión/anulación)	Revisa `result`; no reintentes sin corregir.
`404`	Documento no encontrado (o fuera de tu scope)	Verifica el `documentoId`.

9. Contingencia

Ante caída del proveedor fiscal, la imprenta aplica su flujo de contingencia y regularización posterior. Tu sistema debe tolerar respuestas diferidas y reintentar la consulta de estado. Ver Flujo de emisión.

Enlaces relacionados

Referencia de API — endpoints y esquemas completos.
Ejemplos de documentos — JSON por tipo de documento.
Catálogos — códigos de tipo de documento, alícuotas y formas de pago.
Errores — catálogo de errores de negocio.