Integration (Partner API)

This guide explains how to connect your system (POS, ERP, e-commerce, in-house biller) to Zentto Digital Print to issue fiscal documents against Zentto’s own series (authorized provider). It mirrors the flow an HKA provider offers: you authenticate with tokenUsuario + secret, receive a session token, and issue.

For the exhaustive field-by-field detail, see API Reference and Document Examples. This page is the implementation walkthrough.

For users

If your company was onboarded as an integrator, you will receive a one-time link by email to view your API credentials (Token Usuario + Secret). That link:

• Opens once and expires (72 h by default).
• Does not contain the secret in the email body (security): only the link.
• If it expires, request a resend from the print shop team via the backoffice.

Store the Secret in a secure manager as soon as you see it: it cannot be shown again. If compromised, it can be rotated (the previous one is revoked and a new one issued).

For developers

1. Prerequisites

• Token Usuario + Secret (delivered via the one-time link).

• Target environment: demo (testing) or production.

• Servers:

  Environment	Base URL
  Production	https://imprenta.zentto.net
  Development	https://imprentadev.zentto.net
  Local	http://localhost:4900

The machine-readable contract (OpenAPI 3.0) is available authenticated at GET /api/openapi.json and in the portal (Backoffice → API Contract), where you can download it to generate clients with openapi-generator or other tools.

2. Authentication — POST /api/Autenticacion

Exchange tokenUsuario + secret for a short JWT (Bearer, 1 h TTL). No refresh: on expiry, authenticate again.

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

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

Use the token on all other calls: Authorization: Bearer <token>. The companyId comes from the token (anti-IDOR): your system operates only on its own series and documents.

Store the secret, not the token

The secret is permanent (until rotated); the token expires in 1 h. Re-authenticate on 401 invalid_token and retry the operation.

3. Issue a document — POST /api/emit

The body is { environment, document }. document uses Zentto’s canonical format (English fields: documentType, documentNumber, serie, currency, issueDate, buyer, items, totals). Minimal example (invoice, one item taxed at 16 %):

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

{
  "environment": "production",
  "document": {
    "documentType": "01",
    "documentNumber": "50370",
    "serie": "A",
    "currency": "BSD",
    "issueDate": "23/01/2026",
    "buyer": { "idType": "J", "idNumber": "59858589-9", "name": "SAMPLE COMPANY", "address": "CARACAS", "country": "VE" },
    "items": [
      { "lineNumber": 1, "description": "SERVICE", "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": "Debit card", "amount": 116.00, "currency": "BSD", "exchangeRate": 0.0 } ]
    }
  }
}

Response 201 (issued) or 422 (business rejection):

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

Store documentoId: it is the reference for status, PDF or annulment.

Full cases (VAT General/Reduced/Additional/Exempt, IGTF on foreign-currency payment, credit/debit notes with affected document, withholdings VAT/ISLR, global and per-item discounts, multi-currency): see Document Examples.

4. Status and PDF

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

The PDF arrives base64-encoded; decode it to store or display. 422 pdf_unavailable if the document has no graphic representation yet.

5. Annul — 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": "Wrong buyer data" }'

Response 200 (annulled) or 422 (could not annul).

6. Numbering — GET /api/numeraciones

Query your own series ranges. Optional query tipoDocumento (default 01) and serie.

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

412 if the company has no provider credentials configured.

7. Environments

• demo: does not consume real fiscal numbering; use it to develop and certify your integration.
• production: issues against real fiscal series (metered/billable).

The default environment comes from your token; you can force it per document with environment in the /api/emit body.

8. Error handling

Code	Meaning	Suggested action
400	Invalid payload (validation)	Fix the body; check issues.
401	Missing/invalid/expired token	Re-authenticate at /api/Autenticacion and retry.
412	Provider credentials not configured	Contact the print shop.
422	Business rejection (issue/annul)	Check result; do not retry without fixing.
404	Document not found (or out of your scope)	Verify the documentoId.

9. Contingency

On fiscal provider outage, the print shop applies its contingency and later regularization flow. Your system must tolerate deferred responses and retry the status query. See Issuance Flow.

Related links

• API Reference — full endpoints and schemas.
• Document Examples — JSON per document type.
• Catalogs — document type, tax rate and payment method codes.
• Errors — business error catalog.