Emitir

Crear el documento, finalizarlo y no emitirlo dos veces.

Petición

curl -X POST https://api.timbre.cr/internal/v1/invoices \
  -H "Authorization: Bearer timbre_sk_…" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 3f6f0e9e-9d29-4a1e-9a25-2a5f2f0f1b77' \
  -d '{
    "issuerId": "…",
    "branchCode": "001",
    "terminalCode": "00001",
    "documentType": "FE",
    "finalize": true,
    "invoice": {
      "proveedorSistemas": "…",
      "codigoActividadEmisor": "620100",
      "emisor": {},
      "condicionVenta": "01",
      "lines": [
        {
          "lineNumber": 1,
          "cabys": "2312000000300",
          "detail": "Harina de arroz, saco de 25 kg",
          "quantity": "2.000",
          "unitOfMeasure": "Unid",
          "unitPrice": "5000.00000"
        }
      ]
    }
  }'

Responde 201 con el documento creado: su id, su status, y —si lo finalizaste— la clave de 50 caracteres y el numeroConsecutivo.

Los campos de arriba

Campo	Obligatorio	Qué es
`issuerId`	sí	Qué emisor factura
`branchCode`	sí	Sucursal
`terminalCode`	sí	Terminal
`invoice`	sí	La venta
`documentType`	no	`FE`, `TE`, `NC` o `ND`. Por defecto `FE`
`finalize`	no	Crear y finalizar en una sola llamada
`environment`	no	Debe coincidir con el ambiente del proyecto

Dentro de invoice, lo obligatorio es proveedorSistemas, codigoActividadEmisor, emisor, condicionVenta y lines.

Borrador o finalizado

Sin finalize, el documento queda en draft: existe, todavía no tiene clave ni consecutivo, y nada se presentó. Lo finalizás cuando quieras:

Petición

curl -X POST https://api.timbre.cr/internal/v1/invoices/{id}/finalize \
  -H "Authorization: Bearer timbre_sk_…"

Finalizar es lo que asigna el consecutivo y arranca el proceso. Con "finalize": true pasan las dos cosas en una llamada.

Idempotencia

Mandá Idempotency-Key en cada emisión. Si repetís la petición con la misma llave —porque se cortó la red, porque tu worker reintentó— recibís el documento que ya existe, no uno nuevo.

Sin ella, un reintento que no viste responder emite dos veces. Y un consecutivo gastado no se recupera: la numeración fiscal no tiene huecos ni marcha atrás.

Los tipos de documento

FE es la factura. TE es el tiquete —su esquema no admite codigoActividadReceptor ni transactionType en las líneas, así que cualquiera de los dos se rechaza. NC y ND son notas de crédito y débito, y ambas requieren al menos una informacionReferencia cuyo numero sea la clave de 50 caracteres del documento que corrigen.

Después

El documento no queda listo al responder. Seguí su estado o esperá el webhook.