warnings

La respuesta de POST /api/v1/documents (también la de un duplicado y la 202 con async) trae warnings, una lista que viene vacía cuando no hay nada que avisar. Hoy un aviso no detiene la emisión; más adelante el mismo caso responderá 422.

{
  "success": true,
  "data": { "...": "..." },
  "warnings": [
    {
      "code": "BILLING_INDICATOR_MISSING",
      "field": "items.1.billing_indicator",
      "message": "Línea 2 sin billing_indicator en un comprobante con ITBIS: se declaró ITBIS 18% (indicador 1). Envía el indicador explícito (1=18%, 2=16%, 3=0%, 4=exento)."
    }
  ]
}

totals

Antes de emitir se comprueba que subtotal + itbis sea igual a total, con una tolerancia de dos centavos para absorber redondeos. Si no cuadra:

{
  "success": false,
  "error": {
    "code": "INVALID_TOTALS",
    "message": "total (5800.00) does not match subtotal + itbis (5900.00).",
    "field": "totals.total"
  }
}

payment

payment.method y payment.amount solo llegan al XML cuando payment.type es 2: la tabla de formas de pago es parte del bloque de crédito. En una venta de contado puedes omitirlos.

reference

Tipos de comprobante

El tipo 42 (Comprobante Gubernamental de uso interno) no se emite por esta API. Los documentos se emiten siempre en pesos dominicanos.

Factura de consumo (32)

No lleva expiration_date y el buyer es opcional. Si el total queda por debajo de RD$250,000 viaja por el canal de resumen B2C y el veredicto llega en la misma respuesta, con 200 en vez de 202.

{
  "type": "32",
  "encf": "E320000000001",
  "external_ref": "pos-2026-000891",
  "items": [
    { "description": "Almuerzo", "quantity": 2, "unit_price": 350.00, "amount": 700.00, "itbis_amount": 126.00 }
  ],
  "totals": { "subtotal": 700.00, "exempt_amount": 0.00, "itbis": 126.00, "total": 826.00 }
}

Notas de crédito y débito (34 y 33)

Necesitan el bloque reference apuntando al comprobante que modifican. La nota de crédito (34) prohíbe expiration_date; la nota de débito (33) lo exige.

{
  "type": "34",
  "encf": "E340000000001",
  "external_ref": "nc-2026-000037",
  "reference": {
    "encf": "E310000000001",
    "date": "14-08-2026",
    "reason_code": "01",
    "reason": "Devolución parcial de mercancía"
  },
  "buyer": { "rnc": "101000001", "name": "Cliente de Prueba SRL" },
  "items": [
    { "description": "Devolución servicio de consultoría", "quantity": 1, "unit_price": 1000.00, "amount": 1000.00, "itbis_amount": 180.00 }
  ],
  "totals": { "subtotal": 1000.00, "exempt_amount": 0.00, "itbis": 180.00, "total": 1180.00 }
}

PDF, XML y código QR

Cada documento expone sus artefactos en _links. Todos aceptan el ULID del documento.

Enlaces temporales para compartir

Para enviarle el comprobante a un cliente sin darle una API key, genera un enlace firmado. Vale 15 minutos y no requiere autenticación:

curl -X POST \
  -H "X-API-Key: ffs_live_ejemplodeclavenoreal000000000000000000" \
  https://api.fiscalflowsupport.com/api/v1/documents/01jz8k4qm2n5p7r9t1v3w5x7y9/share-link/pdf

{
  "success": true,
  "data": {
    "type": "pdf",
    "url": "https://api.fiscalflowsupport.com/api/v1/documents/01jz8k4qm2n5p7r9t1v3w5x7y9/share/pdf?expires=1786000000&signature=...",
    "expires_at": "2026-08-14T15:21:02+00:00"
  }
}

Los tipos validos son pdf, xml y qr. Como el enlace caduca en quince minutos, genéralo cuando el usuario lo pida, no al emitir.

Enviar el comprobante por correo

curl -X POST \
  -H "X-API-Key: ffs_live_ejemplodeclavenoreal000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}' \
  https://api.fiscalflowsupport.com/api/v1/documents/01jz8k4qm2n5p7r9t1v3w5x7y9/notify

Solo funciona sobre documentos aceptados; sobre uno en processing devuelve 422. El envío se encola, así que un 200 significa "aceptado para enviar", no "entregado".

Ver el PDF antes de emitir

POST /api/v1/documents/preview devuelve el PDF de un documento que no existe y no se emite: sirve para que el usuario revise cómo quedará. Toma el mismo payload más company_rnc, responde con los bytes del PDF (Content-Type: application/pdf) y no consume secuencia ni cuota.

Consultar y listar

GET /api/v1/documents/{id} devuelve un documento. GET /api/v1/documents lista los de la empresa de tu key, del más reciente al más antiguo, con paginación por cursor de 15 en 15. Filtros disponibles: type, status, encf, external_ref, environment, date_from y date_to.

curl -H "X-API-Key: ffs_live_ejemplodeclavenoreal000000000000000000" \
  "https://api.fiscalflowsupport.com/api/v1/documents?status=rejected&date_from=2026-08-01"

{
  "success": true,
  "data": [ "..." ],
  "meta": {
    "next_cursor": "eyJpZCI6NDIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null,
    "has_more": true,
    "total": 137
  }
}

Para pedir la página siguiente, pasa ?cursor= con el valor de meta.next_cursor. Cuando has_more es false, terminaste.