Tezora

Primer flujo

El flujo mínimo registra un cliente jurídico, crea un producto, emite un Crédito Fiscal (CCF) a crédito y descarga su JSON y su PDF.

sequenceDiagram
  participant S as Sistema integrado
  participant T as Tezora
  participant H as Hacienda
  S->>T: POST /customers
  S->>T: POST /products
  S->>T: POST /sales con Idempotency-Key
  T->>H: Documento firmado
  H-->>T: Sello de recepción
  T-->>S: 201 con la venta y su documento

Registrar el cliente

Un CCF requiere un receptor con NIT, NRC, actividad económica y dirección. Los códigos válidos provienen de GET /catalogs/economic-activities, departments, municipalities y districts.

Un DUI se escribe con o sin guion (05678901-8 o 056789018). GET /customers lo devuelve con guion; el customer.document.number de una venta y de sus webhooks lo trae como lo firmó el documento, los nueve dígitos sin guion, porque así lo pide Hacienda. Para cruzar un cliente con sus ventas por documento, se comparan los dígitos. El NIT va sin guiones en los dos.

{
  "document_type": "36",
  "document_number": "06140101011011",
  "name": "Distribuidora El Trébol, S.A. de C.V.",
  "nrc": "1234567",
  "trade_name": "El Trébol",
  "economic_activity_code": "10502",
  "address": {
    "department": "06",
    "municipality": "23",
    "district": "14",
    "complement": "Calle Los Pinos 123, Colonia Escalón"
  },
  "email": "compras@eltrebol.example.com",
  "phone": "22223333"
}

POST /customers responde 201 con el cliente. Un documento o un code ya registrado responde 409 customer_already_exists con el cliente existente en data.

Crear el producto

{
  "code": "HEL-GAL-01",
  "description": "Galón de helado de vainilla",
  "unit_price": "12.50",
  "item_type": "goods",
  "unit_of_measure": "59",
  "tax_treatment": "taxed"
}

unit_price incluye el IVA. Un code ya registrado responde 409 product_already_exists con el producto en data.

Crear la venta

POST /sales con la cabecera Idempotency-Key: 7b0f2c3e-5d6a-4e1b-9f8c-2a4d6e8b1c3f:

{
  "dte_type": "03",
  "customer": { "document_type": "36", "document_number": "06140101011011" },
  "reference": "PEDIDO-1042",
  "operation_condition": "credit",
  "credit_days": 30,
  "lines": [{ "product": "HEL-GAL-01", "quantity": "2" }],
  "payments": [{ "method_code": "13", "amount": "25.00" }],
  "email": "compras@eltrebol.example.com"
}

La respuesta 201 trae la venta con totals y su documento: status, generation_code, control_number, received_stamp, summary (el resumen del documento firmado, sin recalcular) y los enlaces json_url y pdf_url. pdf_url es nulo mientras el documento sigue en curso. Un documento emitido lo trae siempre, aunque sea demasiado largo para que la ruta lo entregue (ver abajo).

Descargar el documento

GET /sales/{uuid}/document/json entrega la estructura firmada con el sello de recepción; GET /sales/{uuid}/document/pdf, su representación gráfica. Ambas responden 404 document_not_issued si la venta no tiene documento o solo tiene uno rechazado: no hay nada que esperar. La ruta del PDF responde lo mismo mientras el documento sigue en curso (document.status.value pending, o pending_contingency sin firma), y en ese caso se pide de nuevo hasta que pdf_url traiga el enlace. Además, la ruta del PDF responde 422 document_too_long a un documento de más de 100 líneas o de más de 100000 caracteres de descripción, y 429 rate_limited por encima de 20 PDF por minuto o si otro PDF caro se está generando: ver Límites.

Compartir el documento

Los enlaces json_url y pdf_url de la venta piden la llave, así que no se le dan al cliente final. Para que el cliente vea su factura sin que el sistema integrado guarde el archivo ni exponga la llave, se piden enlaces firmados en el momento en que el cliente la quiere ver:

  1. El backend del integrador llama POST /sales/{uuid}/document/links (o POST /sales/{uuid}/adjustment-notes/{note}/document/links para una nota), con el alcance sales:read.
  2. La respuesta trae { "data": { "pdf_url": "...", "json_url": "...", "expires_at": "..." } }.
  3. El backend redirige al cliente a pdf_url o a json_url. Los enlaces abren sin la llave hasta expires_at, 10 minutos después de pedirlos; pasado ese tiempo se piden otros.

Los enlaces se piden desde el backend, nunca desde el navegador del cliente, porque la llamada lleva la llave. No se guardan ni se mandan por correo: vencen pronto, y quien tiene uno abre el documento.

Solo un documento sellado, firmado en contingencia o invalidado después de sellado recibe enlaces; cualquier otro responde 404 document_not_issued. Un documento de más de 100 líneas o de más de 100000 caracteres de descripción recibe pdf_url nulo y su json_url. El PDF sale siempre en español, con Cache-Control: private, no-store y Referrer-Policy: no-referrer.

Un documento invalidado también recibe enlaces, y el PDF lo muestra invalidado: el cliente puede abrir una factura anulada y verla anulada. Si el documento se invalida después de pedir el enlace, el enlace sigue abriendo igual. Un enlace vencido o alterado responde 403 con una página corta para el cliente, no con JSON. Abrir enlaces no gasta el límite de PDF de la llave, y tiene su límite propio: ver Límites.

Sincronización de clientes y productos

Clientes y productos admiten un code propio del integrador, único en la empresa y guardado en mayúsculas (hasta 50 caracteres en un cliente). Con él, el sistema integrado no necesita guardar el uuid de Tezora.