Cómo integrarse a una API de facturación electrónica en Costa Rica

Integrarte a una API de facturación electrónica significa que tu sistema (un ERP, un POS, un e-commerce o tu propia app) le pide a un servicio externo "emití esta factura" y ese servicio se encarga de armar el XML v4.4, firmarlo con el certificado del emisor y enviárselo a Hacienda. Vos no implementás firma digital, ni XSD, ni la comunicación con el Ministerio: hablás HTTP y recibís el resultado.

¿Por qué una API y no hacerlo yo?

Facturar directo contra Hacienda implica generar la clave de 50 dígitos, firmar con XAdES-BES, manejar consecutivos, reintentos, tarifas de IVA, catálogos CABYS y el ciclo de estados. Una API te lo abstrae todo detrás de un POST. Lo que antes eran semanas de desarrollo pasa a ser una integración de un día.

Qué mirar antes de elegir una API

• Autenticación server-to-server (API key/secret), no un login de humano.
• Sandbox gratis para probar sin emitir documentos reales.
• Idempotencia en la emisión (que un reintento no genere doble factura).
• Webhooks para enterarte del resultado sin estar consultando.
• Documentación viva con los catálogos incluidos (tarifas, condición de venta, CABYS).
• Cobertura de comprobantes: FE, TE, NC, ND, y también FEC, FEE y REP.

La ruta de la primera factura

1. Autenticá cada llamada

Todas las peticiones llevan tus credenciales en headers. Las emisiones además llevan un Idempotency-Key:

curl -X POST https://api.facturaencr.com/v2/efactura/documents/factura \
  -H "X-API-Key: efk_…" \
  -H "X-API-Secret: efs_…" \
  -H "Idempotency-Key: pedido-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "emisorLegalId": "3101000000",
    "condicionVenta": "01",
    "medioPago": ["01"],
    "receptor": { "tipoIdentificacion": "01", "numeroIdentificacion": "102340567" },
    "detalle": [
      { "codigoCabys": "8399000000000", "cantidad": 1, "unidadMedida": "Sp",
        "detalle": "Servicio de consultoría", "precioUnitario": 50000 }
    ]
  }'

2. Recibís un 202, no una aceptación

La respuesta es 202 Accepted: encolamos el documento, generamos la clave y el consecutivo, firmamos y enviamos a Hacienda. La aceptación real llega segundos después.

3. Enterate del resultado (webhook > polling)

Podés consultar el estado cada tanto (polling), pero lo recomendado es registrar un webhook: una URL HTTPS tuya a la que te avisamos apenas cambia el estado.

{
  "event": "document.accepted",
  "documentId": "65fe…",
  "clave": "506…199999999",
  "haciendaStatus": "aceptado"
}

Verificá siempre la firma HMAC-SHA256 del webhook antes de procesarlo, y respondé 2xx en menos de 10 segundos.

4. Sandbox → producción

Toda la integración se prueba en sandbox gratis. Cuando emitís en pruebas una factura y una nota de crédito que la referencia, ambas aceptadas, seguís el checklist (certificado de producción probado, secret en un vault) y pedís el cambio a production.

Un error clásico: confundir el 202 con "listo"

El 202 significa "lo recibí", no "Hacienda lo aceptó". Nunca le entregués el comprobante a tu cliente antes de recibir el estado aceptado. Ese es el bug número uno de las integraciones nuevas.

La documentación completa de la API, con todos los catálogos y ejemplos en varios lenguajes, está publicada. Si querés ver qué incluye y cuánto cuesta, mirá la API de factura electrónica de Factura en CR. El sandbox es gratis: podés dejar la integración lista antes de emitir un solo documento real.