Guía para desarrolladores

Emita, consulte y notifique comprobantes electrónicos de Costa Rica desde una sola API REST. Seis tipos de comprobante — FE, TE, NC, ND, FEC, FEE — y una misma estructura de request.

Esta guía contiene todo lo que necesita para integrar KyrFact. Llame a su URL de API con cualquier cliente HTTP; nosotros nos encargamos del resto.

Léalas en orden si va empezando:

1. Autenticación — obtenga su llave de API
2. Inicio rápido — emita su primera FE en 90 segundos
3. Estructura del payload — referencia campo por campo
4. Endpoints — todas las URLs disponibles
5. Tipos de comprobante — escoja el correcto y copie su payload

Autenticación

Cada endpoint requiere un Bearer token en el header Authorization:

Authorization: Bearer kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Hay dos ambientes — escoja uno por llave:

Inicio rápido

Emita una FE de 100 CRC + 13% IVA → 113 CRC en total. Copie, pegue, configure $KYRFACT_KEY:

curl -X POST $KYRFACT_API_BASE/v1/invoices \
  -H "Authorization: Bearer $KYRFACT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-orden-12345" \
  -d '{
    "type": "FE",
    "fecha": "2026-04-28T10:00:00-06:00",
    "condicionVenta": "01",
    "mediosPago": ["01"],
    "codMoneda": "CRC",
    "tipoCambio": 1,
    "emisor": {
      "codigoActividadEmisor": "6201.0",
      "nombre": "Acme Comercializadora S.A.",
      "tipoId": "02", "id": "3101234567",
      "provincia": "1", "canton": "1", "distrito": "01",
      "senas": "Calle 5, Avenida 2",
      "email": "facturas@acme.cr"
    },
    "receptor": {
      "nombre": "Cliente Ejemplo",
      "tipoId": "01", "id": "100100100",
      "provincia": "1", "canton": "1", "distrito": "01",
      "email": "cliente@example.com"
    },
    "totalServGravados": 100, "totalGravados": 100,
    "totalVentas": 100, "totalVentasNeta": 100,
    "totalImpuestos": 13, "totalComprobante": 113,
    "detalles": {
      "1": {
        "cantidad": 1, "unidadMedida": "Sp",
        "detalle": "Servicio profesional",
        "precioUnitario": 100, "montoTotal": 100, "subTotal": 100,
        "montoTotalLinea": 113,
        "codigoCABYS": "8314100000200",
        "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 13 } }
      }
    },
    "options": { "email": { "onAccept": true } }
  }'

Recibe inmediatamente:

{
  "id": "6500000000000000dd000001",
  "type": "FE",
  "env": "live",
  "status": "enviada",
  "clave": "50601012600031012345670010000101000000000412345678",
  "consecutivo": "00100001010000000042",
  "totals": { "totalComprobante": 113, "totalImpuestos": 13, "codMoneda": "CRC" },
  "mensajeHacienda": null
}

Guarde el id y la clave. El estado pasa a completa en 1-3 minutos — vea Estado y polling.

Estructura del payload

Cada solicitud POST /v1/invoices envía un único objeto JSON. Esta sección documenta cada campo. Los campos requeridos generan un 400 si faltan; los opcionales tienen comportamientos por defecto seguros.

El shape es común a todos los tipos de comprobante. Para los campos específicos por tipo (NC, ND, FEC, FEE), vea las páginas individuales más abajo.

Cabecera

Totales pre-calculados

v1 espera totales pre-calculados — el cliente es responsable de la aritmética antes de llamar. La validación de totales revisa los invariantes con tolerancia ±0.01 y retorna 400 con el detalle.

Bloque emisor

Quien emite el comprobante. Todos los campos son opcionales en el payload — los faltantes se rellenan desde el perfil del tenant. Vea Datos del emisor para el merge.

Los siete campos requeridos por Hacienda son: codigoActividadEmisor, nombre, tipoId, id, provincia, canton, distrito. Si faltan tras el merge con el tenant, la API responde 400 con la lista exacta.

Bloque receptor

Quien compra. No se rellena desde el tenant — debe venir en el payload (o usar omitirReceptor: "true" para TE anónimos).

Bloque detalles (líneas)

Objeto anidado con clave numérica como string ("1", "2", …). Cada valor es una línea del comprobante.

"detalles": {
  "1": {
    "cantidad": 1,
    "unidadMedida": "Sp",
    "detalle": "Servicio profesional",
    "precioUnitario": 100,
    "subTotal": 100,
    "montoTotal": 100,
    "montoTotalLinea": 113,
    "codigoCABYS": "8314100000200",
    "impuesto": {
      "1": {
        "codigo": "01", "codigoTarifa": "08",
        "tarifa": 13, "monto": 13
      }
    }
  }
}

Sub-bloque impuesto["1"]:

Bloque options

Comportamiento opcional por llamada. Todos los defaults son seguros.

Campos específicos por tipo

Algunos campos solo aplican a ciertos tipos. Vea las páginas por tipo para los ejemplos completos.

Datos del emisor desde el tenant

Cada solicitud incluye un bloque emisor que describe a su empresa. Repetir esos datos en cada factura es tedioso, así que KyrFact combina el payload con el perfil del emisor guardado en el tenant — el payload tiene prioridad por cada campo, y los campos omitidos se rellenan automáticamente desde el tenant.

Configure el perfil del emisor una sola vez vía POST o PATCH /v1/admin/tenants. Los siguientes campos del tenant se usan como valores por defecto:

Tres formas de llamar

1. Payload completo — todos los campos del emisor incluidos. Funciona igual que antes; los valores del payload ganan:

POST /v1/invoices
{
  "type": "FE",
  "emisor": {
    "codigoActividadEmisor": "6201.0",
    "nombre": "Acme S.A.",
    "tipoId": "02", "id": "3101234567",
    "provincia": "1", "canton": "1", "distrito": "01",
    "senas": "Calle 5, Avenida 2",
    "email": "facturas@acme.cr"
  },
  ...
}

2. Sin emisor — todos los campos requeridos se leen del tenant:

POST /v1/invoices
{
  "type": "FE",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC", "tipoCambio": 1,
  "totalComprobante": 113, "totalImpuestos": 13,
  "totalVentas": 100, "totalVentasNeta": 100,
  "detalles": { "1": { ... } }
}

3. Override parcial — sobrescriba solo los campos que cambian. Útil cuando una empresa tiene varias actividades registradas:

POST /v1/invoices
{
  "type": "FE",
  "emisor": { "codigoActividadEmisor": "8314.0" },
  ...
}

Lo que sigue siendo requerido

• Los siete campos requeridos por Hacienda (codigoActividadEmisor, nombre, tipoId, id, provincia, canton, distrito) deben estar definidos en algún lugar — sea en el payload o en el tenant. Los campos faltantes generan un 400 con la lista exacta.
• El bloque receptor no se rellena desde el tenant — el receptor es el comprador, no el emisor. Use los patrones estándar de FE/TE/NC para suministrarlo (o omitirReceptor: "true" para TE anónimos).

Forma del error de validación

Si ni el payload ni el tenant tienen todos los campos requeridos:

HTTP 400
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "emisor is incomplete after merging with tenant defaults — missing [codigoActividadEmisor, provincia, canton, distrito]. Either include these fields in the request body or set them on the tenant via PATCH /v1/admin/tenants/:id.",
  "missingEmisorFields": ["codigoActividadEmisor", "provincia", "canton", "distrito"]
}

Todos los endpoints

Cada URL que expone la API. Todos están limitados a su tenant por la llave de API.

Emisión y consulta de comprobantes

Documentos (PDF + XML)

Contadores

Filtros en GET /v1/invoices

GET /v1/invoices?type=FE&estado=completa&limit=20&offset=0
                  &receptorCedula=100100100
                  &q=widget
                  &from=2026-01-01&to=2026-12-31
                  &kyrfactOnly=true

Reporte PDF de uso

Genera un PDF con todas las facturas que su empresa emitió en un rango de fechas, abarcando los tres tipos de almacenamiento (FE/TE/NC/ND, FEC, FEE), con totales por tarifa de IVA y desglose por tipo y estado al pie. Auténtica con su propia llave de tenant — el endpoint solo retorna sus propios datos.

Request

GET /v1/reports/usage.pdf?from=YYYY-MM-DD&to=YYYY-MM-DD[&estado=…][&type=FE,TE,…]
Authorization: Bearer kf_live_…   # o kf_test_… para sandbox

El tenant se deduce automáticamente de la llave API — no se envía ningún tenantId. Solo recibirá facturas emitidas por el tenant asociado a esa llave.

Parámetros

Respuesta

Sobre éxito: 200 OK con Content-Type: application/pdf y un encabezado Content-Disposition apuntando al nombre de archivo:

Content-Type: application/pdf
Content-Disposition: attachment; filename="Reporte-de-Uso-<slug>[-<tipos>]-<from>_<to>.pdf"
Cache-Control: no-store

El <slug> se construye desde tenant.nombreComercial (o nombre, o cedula como último recurso) — minúsculas, acentos eliminados, no-alfanuméricos reemplazados por -, máximo 60 caracteres. Cuando se filtra por tipo, se agrega -FE-TE (etc.) antes del rango de fechas.

Layout del PDF

• Encabezado centrado: título (con subtítulo de estado y/o tipos cuando se filtra), nombreComercial, cedula, "Rango de Fechas" y el rango. Numeración de página arriba a la derecha.
• Tabla detalle (40 filas por página): Tipo · Consecutivo · Cliente · Fecha · Total Imp - Exo · Total Fact. Filas alternadas en blanco/azul claro como en fs-fe.
• Convención de moneda: las columnas de total muestran el equivalente en CRC usando el tipocambio de cada documento. Filas con tipocambio ≠ 1 llevan un sufijo *.
• Pie de página en cada hoja: nota explicando el * ("monto convertido a CRC con el tipo de cambio del comprobante").
• Bloque de totales (última página, abajo a la derecha): Total Sin Impuestos · Total Con Impuestos · Total Impuestos al 13% · al 4% · al 2% · al 1%.
• Desglose adicional (última página, abajo a la izquierda): por tipo de comprobante y por estado.

Cómo se calculan los totales

El reporte sólo suma facturas cuyo evento original fue aceptado por Hacienda (documentos[0].estado === 'completa'). Las notas de crédito (NC) se restan de los totales, no se suman — su monto y su IVA contribuyen con signo negativo al Total Con Impuestos, al Total Sin Impuestos, al desglose por tarifa y a la fila NC del bloque "Por tipo". Las notas de débito (ND), FE, TE, FEC y FEE suman normal. Esto refleja el efecto fiscal real: una NC anula o reduce el IVA cobrado por una factura previa.

Ejemplos

Reporte completo del mes (todos los tipos, todos los estados):

curl -H "Authorization: Bearer $KYRFACT_KEY" \
  "$KYRFACT_API_BASE/v1/reports/usage.pdf?from=2026-04-01&to=2026-04-30" \
  -o reporte.pdf

Solo FE y TE aceptadas:

curl -H "Authorization: Bearer $KYRFACT_KEY" \
  "$KYRFACT_API_BASE/v1/reports/usage.pdf?from=2026-04-01&to=2026-04-30&type=FE,TE&estado=completa" \
  -o fe-te-completas.pdf

Solo notas de crédito y débito:

curl -H "Authorization: Bearer $KYRFACT_KEY" \
  "$KYRFACT_API_BASE/v1/reports/usage.pdf?from=2026-04-01&to=2026-04-30&type=NC,ND" \
  -o notas.pdf

Errores

Comparar tipos de comprobante

Los seis tipos comparten la misma estructura de request — las diferencias son cuáles campos son requeridos y cómo se organizan las partes.

Árbol de decisión rápido

• ¿Está vendiendo algo?
  • Comprador con cédula CR → FE
  • Cliente anónimo de mostrador → TE
  • Comprador extranjero (exportación) → FEE
• ¿Está ajustando un comprobante anterior?
  • Reduciendo o anulando → NC
  • Agregando un cargo → ND
• ¿Está registrando una compra que hizo? → FEC

FE — Factura Electrónica

Venta B2B / B2C estándar a un comprador identificado. El tipo de comprobante más común.

Payload

{
  "type": "FE",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": {
    "codigoActividadEmisor": "6201.0",
    "nombre": "Acme Comercializadora S.A.",
    "tipoId": "02", "id": "3101234567",
    "provincia": "1", "canton": "1", "distrito": "01",
    "senas": "Calle 5, Avenida 2",
    "email": "facturas@acme.cr"
  },
  "receptor": {
    "nombre": "Cliente Ejemplo S.A.",
    "tipoId": "02", "id": "3101987654",
    "provincia": "1", "canton": "1", "distrito": "01",
    "email": "cliente@example.com"
  },
  "totalServGravados": 100, "totalGravados": 100,
  "totalVentas": 100, "totalVentasNeta": 100,
  "totalImpuestos": 13, "totalComprobante": 113,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Sp",
      "detalle": "Servicio profesional",
      "precioUnitario": 100, "montoTotal": 100, "subTotal": 100,
      "montoTotalLinea": 113,
      "codigoCABYS": "8314100000200",
      "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 13 } }
    }
  },
  "options": { "email": { "onAccept": true } }
}

Endpoint: POST /v1/invoices

TE — Tiquete Electrónico

Tiquete de mostrador / POS al consumidor sin identificar. Misma estructura que FE, pero el bloque de receptor es opcional y típicamente mínimo.

Payload (receptor anónimo)

{
  "type": "TE",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "omitirReceptor": "true",
  "emisor": { /* …igual que FE */ },
  "totalMercGravada": 100, "totalGravados": 100,
  "totalVentas": 100, "totalVentasNeta": 100,
  "totalImpuestos": 13, "totalComprobante": 113,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Unid",
      "detalle": "Sandwich + bebida",
      "precioUnitario": 100, "montoTotal": 100, "subTotal": 100,
      "montoTotalLinea": 113,
      "codigoCABYS": "5611901100100",
      "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 13 } }
    }
  }
}

Endpoint: POST /v1/invoices

NC — Nota de Crédito

Anula o reduce un FE/TE previo. El receptor debe ser el mismo que el del documento original.

Payload

{
  "type": "NC",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": { /* …igual que FE */ },
  "receptor": { /* …DEBE coincidir con el receptor del FE/TE referenciado */ },
  "totalServGravados": 100, "totalGravados": 100,
  "totalVentas": 100, "totalVentasNeta": 100,
  "totalImpuestos": 13, "totalComprobante": 113,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Sp",
      "detalle": "Anulación de servicio facturado por error",
      "precioUnitario": 100, "montoTotal": 100, "subTotal": 100,
      "montoTotalLinea": 113,
      "codigoCABYS": "8314100000200",
      "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 13 } }
    }
  },
  "informacionReferencia": [{
    "tipoDoc": "01",
    "numero": "50601012600031012345670010000101000000000412345678",
    "fechaEmision": "2026-04-15T10:00:00-06:00",
    "codigo": "01",
    "razon": "Anulación por error de digitación"
  }]
}

Endpoint: POST /v1/invoices

Códigos de informacionReferencia

ND — Nota de Débito

Agrega un cargo sobre un FE/TE previo (e.g. recargo por mora, aumento de precio acordado). Misma estructura que NC.

Payload

{
  "type": "ND",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": { /* …igual que FE */ },
  "receptor": { /* …DEBE coincidir con el receptor del FE/TE referenciado */ },
  "totalServGravados": 50, "totalGravados": 50,
  "totalVentas": 50, "totalVentasNeta": 50,
  "totalImpuestos": 6.5, "totalComprobante": 56.5,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Sp",
      "detalle": "Cargo adicional por mora",
      "precioUnitario": 50, "montoTotal": 50, "subTotal": 50,
      "montoTotalLinea": 56.5,
      "codigoCABYS": "8314100000200",
      "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 6.5 } }
    }
  },
  "informacionReferencia": [{
    "tipoDoc": "01",
    "numero": "50601012600031012345670010000101000000000412345678",
    "fechaEmision": "2026-04-15T10:00:00-06:00",
    "codigo": "04",
    "razon": "Cargo adicional sobre factura original"
  }]
}

Endpoint: POST /v1/invoices

FEC — Factura Electrónica de Compra

Registra una compra que usted hizo a un proveedor que no puede emitir comprobantes electrónicos (proveedores de papel, proveedores extranjeros, etc.). Usted — el comprador — es quien firma.

Use la misma convención que los demás tipos: emisor es su tenant, receptor es el proveedor. KyrFact organiza el payload final correctamente.

Payload

{
  "type": "FEC",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": { /* …su tenant — igual que FE */ },
  "receptor": {
    "nombre": "Proveedor Servicios Test",
    "tipoId": "02", "id": "3101234500",
    "provincia": "1", "canton": "1", "distrito": "01",
    "senas": "Oficina San José centro",
    "email": "proveedor@example.cr"
  },
  "totalServGravados": 100, "totalGravados": 100,
  "totalVentas": 100, "totalVentasNeta": 100,
  "totalImpuestos": 13, "totalComprobante": 113,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Sp",
      "detalle": "Servicio comprado al proveedor",
      "precioUnitario": 100, "montoTotal": 100, "subTotal": 100,
      "montoTotalLinea": 113,
      "codigoCABYS": "8314100000200",
      "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 13 } }
    }
  },
  "informacionReferencia": [{
    "tipoDoc": "08",
    "numero": "PAPER-INV-12345",
    "fechaEmision": "2026-04-28T10:00:00-06:00",
    "codigo": "04",
    "razon": "Compra a proveedor sin facturación electrónica"
  }]
}

Endpoint: POST /v1/invoices

FEE — Factura Electrónica de Exportación

Venta de exportación a un comprador extranjero. La moneda suele ser USD; el receptor con frecuencia usa tipoId: "05" con un ID fiscal extranjero.

Payload (receptor residente en CR)

{
  "type": "FEE",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "USD",
  "tipoCambio": 510,
  "emisor": { /* …su tenant — igual que FE */ },
  "receptor": {
    "nombre": "Foreign Buyer LLC",
    "tipoId": "02", "id": "3101000000",
    "provincia": "1", "canton": "1", "distrito": "01",
    "senas": "Foreign address",
    "email": "buyer@example.com"
  },
  "totalServGravados": 100, "totalGravados": 100,
  "totalVentas": 100, "totalVentasNeta": 100,
  "totalImpuestos": 13, "totalComprobante": 113,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Sp",
      "detalle": "Servicio exportado",
      "precioUnitario": 100, "montoTotal": 100, "subTotal": 100,
      "montoTotalLinea": 113,
      "codigoCABYS": "8314100000200",
      "impuesto": { "1": { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 13 } }
    }
  }
}

Endpoint: POST /v1/invoices

Estado y polling

Cada POST /v1/invoices devuelve inmediatamente con status: "enviada". El estado luego transiciona a uno de:

Para detectar la transición, haga polling de:

GET /v1/invoices/:id

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $KEY" \
    $KYRFACT_API_BASE/v1/invoices/$ID | jq -r '.status')
  case "$STATUS" in
    completa|rechazada) break ;;
    *) sleep 30 ;;
  esac
done

Alternativamente, configure options.email.onAccept: true y el correo al cliente llega en el momento en que el estado pasa a completa.

Idempotencia

Una llave de idempotencia es una manera de decirnos "si ya has visto este request exacto, devuélveme la misma respuesta en lugar de hacer el trabajo de nuevo". Existe porque las redes fallan.

El problema que resuelve

Sin ella, este escenario rompe la facturación:

1. Su app envía POST /v1/invoices.
2. KyrFact emite el comprobante, lo firma, lo envía a Hacienda — y empieza a responder con un 200.
3. El paquete de respuesta se pierde en el camino. Su código hace timeout.
4. Su código reintenta → se emite un segundo comprobante. Dos consecutivos quemados, dos correos enviados, el cliente cobrado dos veces.

Cómo usarla

Escoja un string que identifique únicamente la operación (no la llamada HTTP) — típicamente su ID interno de orden o transacción — y envíelo en el header Idempotency-Key:

POST /v1/invoices
Authorization: Bearer kf_live_…
Idempotency-Key: orden-12345
Content-Type: application/json

{ ...el payload del comprobante... }

Si su código reintenta la misma operación (problema de red, crash de la app, redelivery de cola), envíe la misma llave. KyrFact la reconoce en una ventana de 24 horas y devuelve la respuesta original sin emitir un comprobante nuevo.

Cómo escoger una buena llave

Reglas

• Cualquier string de hasta 256 caracteres.
• Se cachea por 24 horas. Después de eso, la misma llave se trata como un request nuevo.
• Limitada por tenant — Tenant A y Tenant B pueden usar la misma llave sin interferir.
• Es opcional pero fuertemente recomendada. Sin ella, los reintentos le cuestan consecutivos reales.

Validación previa al consecutivo

KyrFact corre tres capas de validación antes de asignar un consecutivo o llamar a php-api / Hacienda. Si algo está mal, devolvemos un solo 400 Bad Request con todos los problemas en errors[], así usted los corrige en una sola iteración.

Forma del error

HTTP 400
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "<motivo>",
  "errors": [
    "<cada problema encontrado>",
    ...
  ]
}

Orden de las capas

1. Emisor merge + campos requeridos. El bloque emisor del payload se combina con el perfil del tenant (vea Datos del emisor). Después se valida que los siete campos requeridos por Hacienda estén presentes (codigoActividadEmisor, nombre, tipoId, id, provincia, canton, distrito).
2. Estructura del payload. Receptor, referencias, encabezado y cada línea — vea la lista debajo.
3. Matemática. Invariantes por línea y totales del documento (tolerancia ±0.01 por redondeo).

Qué se valida

Encabezado

Emisor

Receptor

Por tipo de comprobante

Por línea

Totales

Cada total que envía debe coincidir con la suma derivada de las líneas, dentro de ±0.01. Si lo omite (cuando es opcional) se ignora; si lo envía, se valida.

• totalVentas, totalDescuentos, totalVentasNeta, totalImpuestos, totalExonerado, totalComprobante — todos contra las líneas.

Ejemplo: respuesta con varios errores

POST /v1/invoices
{
  "type": "FEC",
  "fecha": "yesterday",
  "codMoneda": "crc",
  "tipoCambio": -1,
  "mediosPago": ["77"],
  "receptor": { "nombre": "Proveedor X", "tipoId": "02", "id": "3101234567" },
  "informacionReferencia": [{
    "tipoDoc": "08",
    "numero": "PAPER-INV-1",
    "fechaEmision": "2026-04-29",
    "codigo": "04"
  }],
  ...
}

HTTP 400
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "invoice payload validation failed",
  "errors": [
    "fecha must be ISO 8601 with offset (got \"yesterday\", expected e.g. \"2026-04-29T10:00:00-06:00\").",
    "mediosPago[0] \"77\" is not a Hacienda payment-method code (valid: 01-07, 99).",
    "codMoneda must be a 3-letter ISO 4217 code in uppercase (got \"crc\").",
    "tipoCambio must be > 0 (got -1).",
    "informacionReferencia[0].razon is required (free-text reason, max 180 chars).",
    "FEC.receptor.senas is required and must be non-empty (php-api gen_xml_fec rejects FEC with empty supplier senas)."
  ]
}

Lo que no validamos (lo deja Hacienda)

• Registro CABYS — solo validamos formato (13 dígitos). El catálogo CABYS lo mantiene Hacienda y cambia mensualmente.
• Catálogo de actividades económicas — el código tiene que estar registrado a su cédula con Hacienda; no podemos verificar eso desde aquí.
• Listas completas de impuesto.codigo y codigoTarifa — Hacienda ha agregado códigos en revisiones recientes; preferimos que un código nuevo válido pase y deje que Hacienda lo confirme, en vez de rechazarlo aquí.
• Política de "fecha demasiado antigua" — la ventana de Hacienda puede cambiar.

Errores

Todos los errores siguen el formato:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "explicación legible"
}

Los 400 de validación previa al consecutivo incluyen además un campo errors[] con cada problema encontrado — vea Validación.

Errores de validación de totales

Cuando los totales no coinciden con lo que recalculamos a partir de las líneas, recibe un error estructurado señalando los campos con diferencia:

{
  "statusCode": 400,
  "message": "invoice totals failed validation",
  "errors": [
    { "path": "totalComprobante", "expected": 113, "actual": 100, "diff": -13 },
    { "path": "detalles.1.impuesto.1.monto", "expected": 13, "actual": 12.5, "diff": -0.5 }
  ]
}

Corrija y reintente — ningún consecutivo se consume con payloads inválidos.

Rechazos de Hacienda

No son errores HTTP. El comprobante se emitió y se envió, pero Hacienda encontró un problema con los datos. Verá:

HTTP 200 OK
{
  "id": "...",
  "status": "rechazada",
  "mensajeHacienda": "El código del tipo de identificación no corresponde…",
  ...
}

Inspeccione mensajeHacienda para ver la razón o haga GET /v1/invoices/:id/respuesta-xml para el detalle completo. La mayoría de rechazos son correcciones de una línea — corrija, reenvíe con un Idempotency-Key nuevo.