Integraciones: conecte su sistema por API

Si ya tiene un sistema (un punto de venta, una tienda en línea, un ERP o una app propia) no necesita cambiarlo para facturar electrónicamente en Costa Rica. Su sistema hace una sola cosa: enviar un JSON con los datos de la venta a un endpoint. Almendro se encarga de todo lo demás.

Qué hace su sistema y qué hace Almendro

• Almendro asigna el consecutivo y la clave de 50 dígitos.
• Construye y firma el XML con el certificado (.p12) del contribuyente. Usted nunca maneja llaves criptográficas.
• Envía el comprobante a Hacienda y le da seguimiento (aceptado, rechazado, reintentos).
• Genera el PDF y el XML descargables, y envía el correo al receptor si así está configurado.
• Le notifica el resultado por webhook firmado, o usted lo consulta por GET cuando quiera.

Descargue la guía completa

Preparamos una guía autoconclusiva con el contrato completo del endpoint, el significado de cada campo, las reglas por tipo de comprobante, todas las tablas de valores permitidos de Hacienda y un ejemplo JSON listo para enviar por cada uno de los 7 tipos de la versión 4.4.

Un detalle pensado para su equipo: la guía está escrita para que la lea una persona o una IA. Puede dársela a su asistente de programación y pedirle que arme el JSON de emisión; ahí vienen las fórmulas de los montos y los errores comunes de Hacienda para que el comprobante salga aceptado a la primera.

Pruebe primero en sandbox

Antes de emitir de verdad, haga todas las pruebas en el ambiente sandbox: los comprobantes se arman, se firman y se envían igual que en producción, pero no tienen valor fiscal ni consumen su numeración. Se usa exactamente el mismo JSON, el mismo token y los mismos headers; lo único que cambia es que la URL lleva /sandbox. Cuando Hacienda acepte sus pruebas, quita /sandbox de la URL y ya está emitiendo en producción.

Un único endpoint para los 7 tipos

POST /api/v1/public/vouchers            (producción, facturas reales)
POST /api/v1/public/sandbox/vouchers    (pruebas, mismo cuerpo, sin valor fiscal)

El campo voucher_type decide el tipo de comprobante y las reglas que se aplican:

Así se ve una factura completa

Este es el JSON de una Factura Electrónica con IVA 13%, listo para enviar (cambie identificaciones, CABYS y montos por los reales):

{
  "voucher_type": "01",
  "situation": "1",
  "issued_at": "2026-07-24T10:30:00-06:00",
  "issuer_activity_code": "6201.0",
  "sale_condition": "01",
  "currency_code": "CRC",
  "exchange_rate": 1.00000,
  "receiver": {
    "id_type": "02",
    "id_number": "3101704304",
    "name": "Hotel Las Palmas S.A.",
    "emails": ["recepcion@hotellaspalmas.cr"]
  },
  "line_items": [
    {
      "line_number": 1,
      "cabys_code": "8511000000000",
      "quantity": 1,
      "unit_of_measure": "Sp",
      "detail": "Desarrollo de sitio web",
      "unit_price": 500000.00000,
      "total_amount": 500000.00000,
      "sub_total": 500000.00000,
      "taxes": [
        { "codigo": "01", "codigoTarifa": "08", "tarifa": 13, "monto": 65000.00000 }
      ],
      "impuesto_neto": 65000.00000,
      "total_line_amount": 565000.00000
    }
  ],
  "payment_methods": [
    { "tipo": "04" }
  ]
}

La respuesta es un 202 Accepted con la voucher_key. Con esa clave consulta el estado, descarga el PDF y el XML, o anula el comprobante. Los errores de validación llegan como 422 con el detalle campo por campo, antes de gastar cuota o de llegar a Hacienda, así que corregir y reintentar no tiene costo.

Cómo se entera del resultado

• Webhook (recomendado): configure un endpoint una vez y Almendro le avisa cuando el comprobante cambia de estado. El webhook va firmado.
• Consulta puntual: GET /api/v1/public/vouchers/{clave} devuelve el estado actual.
• Descargas: PDF, XML y respuesta de Hacienda por GET con la misma clave.

Los errores que más rechaza Hacienda

• Actividad económica sin punto: el código va en formato XXXX.X y debe estar inscrito y activo.
• Referencias sin motivo: references.*.reason es obligatorio en la práctica. Póngalo siempre.
• Exportación con tarifa equivocada: en FEE las líneas exentas usan codigoTarifa=10, no 01.
• Líneas en cero: ninguna línea puede tener monto 0; para regalar algo use un descuento con codigo=03.
• Identificación del receptor con largo incorrecto según el tipo.

La guía PDF trae la lista completa con los códigos de error y cómo evitarlos.

Empiece hoy

La referencia interactiva completa de la API está en fe.almendro.cr/docs-v2. El token se obtiene en el panel de Almendro, en la sección del SDK / API, con un plan que incluya acceso a la API. Si tiene alguna consulta técnica, escríbanos y con gusto le ayudamos.