KyrFact Developer Guide

Issue, retrieve, and notify Costa Rica electronic invoices over a single REST API. Six document types — FE, TE, NC, ND, FEC, FEE — one consistent request shape.

This guide is everything you need to integrate KyrFact. Hit your API URL with any HTTP client; we handle the rest.

Read these in order if you're starting from scratch:

1. Authentication — get your API key
2. Quick start — issue your first FE in 90 seconds
3. Payload structure — field-by-field reference
4. Endpoints — every URL you can call
5. Document types — pick the right one and copy its payload

Authentication

Every endpoint requires a Bearer token in the Authorization header:

Authorization: Bearer kf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Two environments — pick one per key:

Quick start

Issue an FE for 100 CRC + 13% IVA → 113 CRC total. Copy, paste, set $KYRFACT_KEY:

curl -X POST $KYRFACT_API_BASE/v1/invoices \
  -H "Authorization: Bearer $KYRFACT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-order-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 } }
  }'

You get back, immediately:

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

Store the id and clave. Status flips to completa within 1-3 minutes — see Status & polling.

Payload structure

Every POST /v1/invoices sends a single JSON object. This section documents every field. Required fields produce a 400 if missing; optional ones have safe defaults.

The shape is shared across all document types. For type-specific fields (NC, ND, FEC, FEE), see the per-type pages further down.

Header

Pre-computed totals

v1 expects pre-computed totals — the caller is responsible for the arithmetic before calling. Totals validation checks invariants with ±0.01 tolerance and returns 400 with the detail.

emisor block

The party issuing the invoice. All fields are optional in the payload — anything missing is filled from the tenant's stored profile. See Emisor defaults for the merge rules.

Hacienda's seven required fields are: codigoActividadEmisor, nombre, tipoId, id, provincia, canton, distrito. If any are missing after the tenant merge, the API returns 400 with the exact list.

receptor block

The buyer. Not filled from the tenant — must come in the payload (or use omitirReceptor: "true" for anonymous TEs).

detalles block (line items)

Nested object with numeric string keys ("1", "2", …). Each value is a line on the invoice.

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

Sub-block impuesto["1"]:

options block

Per-call behavior. All defaults are safe.

Type-specific fields

A few fields apply only to certain document types. See the per-type pages below for full examples.

Emisor defaults from your tenant

Every invoice request takes an emisor block describing the issuer (your business). Repeating it on every call gets old, so KyrFact merges the payload with the issuer profile stored on your tenant — payload wins per-field, and any field you omit is filled from the tenant.

Set the issuer profile once via POST or PATCH /v1/admin/tenants. The following tenant fields are used as fallbacks:

Three calling patterns

1. Full payload — every emisor field provided. Works as before; payload values win:

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. Emisor omitted — every required field is read from the 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. Mixed override — override only specific fields. Useful when a business has multiple registered activities:

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

What stays required

• The seven Hacienda-required emisor fields (codigoActividadEmisor, nombre, tipoId, id, provincia, canton, distrito) must be set somewhere — either in the payload or on the tenant. Missing fields surface as a 400 listing them.
• The receptor block is not merged from the tenant — receptors are buyers, not issuers. Use the standard FE/TE/NC patterns to provide it (or omitirReceptor: "true" for anonymous TE).

Validation error shape

If neither the payload nor the tenant has all the required fields, you get:

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"]
}

All endpoints

Every URL the API exposes. All are scoped to your tenant by the API key.

Issuing & reading invoices

Documents (PDF + XML)

Counters

Filters on 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

Usage PDF report

Generates a PDF listing every invoice your business issued in a date range, spanning the three storage collections (FE/TE/NC/ND, FEC, FEE), with per-tarifa IVA totals plus per-type and per-estado breakdowns at the bottom. Authenticate with your own tenant API key — the endpoint only ever returns your own data.

Request

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

Tenant identity is derived from the API key automatically — no tenantId parameter is sent. You'll only ever receive invoices issued by the tenant bound to that key.

Query parameters

Response

On success: 200 OK with Content-Type: application/pdf and a Content-Disposition header carrying the filename:

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

The <slug> is built from tenant.nombreComercial (or nombre, falling back to cedula) — lowercased, accents stripped, non-alphanumeric characters replaced with -, capped at 60 chars. When the type filter is set, the filename gets a -FE-TE (etc.) segment before the date range.

PDF layout

• Centered header: title (with estado and/or types subtitle when filtered), nombreComercial, cedula, "Rango de Fechas" + the range. Page counter top-right.
• Detail table (40 rows per page): Tipo · Consecutivo · Cliente · Fecha · Total Imp - Exo · Total Fact. Alternating white/light-blue rows like fs-fe.
• Currency convention: total columns show the CRC equivalent using each documento's tipocambio. Rows whose tipocambio ≠ 1 are suffixed with *.
• Footer on every page: small grey legend explaining the * ("amount converted to CRC at the document's exchange rate").
• Totals block (last page, bottom-right): Total Sin Impuestos · Total Con Impuestos · Total Impuestos al 13% · al 4% · al 2% · al 1%.
• Extra breakdown (last page, bottom-left): per doc type and per estado.

How totals are computed

The report only sums invoices whose original event was accepted by Hacienda (documentos[0].estado === 'completa'). Credit notes (NC) are subtracted from the totals, not added — their amount and IVA contribute with a negative sign to Total Con Impuestos, Total Sin Impuestos, the per-tarifa breakdown, and the NC row of the "By type" block. Debit notes (ND), FE, TE, FEC, and FEE add normally. This mirrors real fiscal effect: an NC cancels or reduces the IVA charged on a previous invoice.

Examples

Full month, all types and statuses:

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

FE and TE only, accepted by Hacienda:

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-completed.pdf

Credit and debit notes only:

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 credit-debit-notes.pdf

Errors

Compare document types

All six types share the same request shape — the differences are which fields are required and how the parties are arranged.

Quick decision tree

• Selling something?
  • Buyer has a CR cédula → FE
  • Anonymous walk-in customer → TE
  • Foreign buyer (export) → FEE
• Adjusting a previous invoice?
  • Reducing or canceling → NC
  • Adding a charge → ND
• Recording a purchase you made? → FEC

FE — Factura Electrónica

Standard B2B / B2C sale to an identified buyer. Most common doc type.

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

Counter / POS receipt to an unidentified consumer. Same shape as FE, but the receptor block is optional and typically minimal.

Payload (anonymous receptor)

{
  "type": "TE",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "omitirReceptor": "true",
  "emisor": { /* …same as 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

Cancels or reduces a prior FE/TE. The receptor must be the same party as the original document's receptor.

Payload

{
  "type": "NC",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": { /* …same as FE */ },
  "receptor": { /* …MUST match the receptor of the referenced FE/TE */ },
  "totalServGravados": 100, "totalGravados": 100,
  "totalVentas": 100, "totalVentasNeta": 100,
  "totalImpuestos": 13, "totalComprobante": 113,
  "detalles": {
    "1": {
      "cantidad": 1, "unidadMedida": "Sp",
      "detalle": "Anulación de servicio facturado en 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

informacionReferencia codes

ND — Nota de Débito

Adds a charge on top of a prior FE/TE (e.g. late-payment surcharge, agreed price increase). Same structure as NC.

Payload

{
  "type": "ND",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": { /* …same as FE */ },
  "receptor": { /* …MUST match the receptor of the referenced FE/TE */ },
  "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

Records a purchase you made from a supplier who can't issue electronic invoices (paper-only vendors, foreign suppliers, etc.). You — the buyer — are the one signing.

Use the same convention as the other types: emisor is your tenant, receptor is the supplier. KyrFact arranges the wire payload correctly.

Payload

{
  "type": "FEC",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "CRC",
  "tipoCambio": 1,
  "emisor": { /* …your tenant — same as 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

Export sale to a foreign buyer. Currency is typically USD; the receptor often uses tipoId: "05" with a foreign tax ID.

Payload (CR-resident receptor)

{
  "type": "FEE",
  "fecha": "2026-04-28T10:00:00-06:00",
  "condicionVenta": "01",
  "mediosPago": ["01"],
  "codMoneda": "USD",
  "tipoCambio": 510,
  "emisor": { /* …your tenant — same as 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

Status & polling

Every POST /v1/invoices returns immediately with status: "enviada". The status field then transitions to one of:

To detect the transition, poll:

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

Alternatively, set options.email.onAccept: true and the customer email arrives the moment status flips to completa.

Idempotency

An idempotency key is a way to tell us "if you've already seen this exact request, return the same answer instead of doing the work again." It exists because networks fail.

The problem it solves

Without it, this scenario breaks billing:

1. Your app sends POST /v1/invoices.
2. KyrFact issues the invoice, signs it, submits to Hacienda — and starts replying with a 200.
3. The response packet drops on the way back to your app. Your code times out.
4. Your code retries → a second invoice gets issued. Two consecutivos burned, two emails sent, customer charged twice.

How to use it

Pick a string that uniquely identifies the operation (not the HTTP call) — typically your internal order or transaction ID — and send it in the Idempotency-Key header:

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

{ ...your invoice payload... }

If your code retries the same operation (network glitch, app crash, queue redelivery), send the same key. KyrFact recognizes it within a 24-hour window and returns the original response without issuing a new invoice.

Picking a good key

Rules

• Any string up to 256 characters.
• Cached for 24 hours. After that the same key is treated as a new request.
• Scoped per tenant — Tenant A and Tenant B can use the same key without interfering.
• Optional but strongly recommended. Without it, retries cost you real consecutivos.

Pre-flight validation

KyrFact runs three layers of validation before allocating a consecutivo or talking to php-api / Hacienda. If anything is wrong, you get a single 400 Bad Request with every problem in errors[], so you fix the whole payload in one round-trip.

Error response shape

HTTP 400
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "<reason>",
  "errors": [
    "<every problem found>",
    ...
  ]
}

Layer order

1. Emisor merge + required-field check. The payload's emisor block is merged with the tenant's stored issuer profile (see Emisor defaults). Then we verify the seven Hacienda-required fields are present (codigoActividadEmisor, nombre, tipoId, id, provincia, canton, distrito).
2. Structural payload check. Receptor, references, header, and per-line — see the breakdown below.
3. Math check. Per-line invariants and document totals (±0.01 rounding tolerance).

What gets checked

Header

Emisor

Receptor

Type-specific

Per-line

Document totals

Every total you provide must match the line-derived sum, within ±0.01. Optional totals are skipped if omitted; values you send are validated.

• totalVentas, totalDescuentos, totalVentasNeta, totalImpuestos, totalExonerado, totalComprobante — all checked against the lines.

Example: multi-error response

POST /v1/invoices
{
  "type": "FEC",
  "fecha": "yesterday",
  "codMoneda": "crc",
  "tipoCambio": -1,
  "mediosPago": ["77"],
  "receptor": { "nombre": "Supplier 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)."
  ]
}

What we deliberately don't check

• CABYS code registry — we only validate format (13 digits). The CABYS catalog is Hacienda-managed and updates monthly.
• Economic-activity registry — your activity code must be registered to your cedula at Hacienda; we can't verify that here.
• Full impuesto.codigo and codigoTarifa enums — Hacienda has been adding codes in recent revisions; we'd rather pass a valid new code through than false-reject it locally.
• "Fecha too old" policy — Hacienda's window may change; let them surface it.

Errors

All errors follow:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "human readable explanation"
}

Pre-flight validation 400s also include an errors[] field listing every problem found in one response — see Validation.

Totals validation errors

When totals don't match what we recompute from the line items, you get a structured error pointing at the mismatched fields:

{
  "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 }
  ]
}

Fix and retry — no consecutivo is consumed for invalid payloads.

Hacienda rejections

These are not HTTP errors. The invoice was issued and submitted, but Hacienda found a problem with the data. You'll see:

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

Inspect mensajeHacienda for the reason or fetch GET /v1/invoices/:id/respuesta-xml for full detail. Most rejections are 1-line schema fixes — correct, re-submit with a new Idempotency-Key.