Cómo integrar facturación electrónica en Costa Rica vía API

Desde 2018, toda empresa en Costa Rica está obligada a emitir comprobantes electrónicos ante el Ministerio de Hacienda. El esquema actual (XML v4.4) exige generar un documento XML, firmarlo digitalmente con XAdES-EPES y enviarlo al API de la DGT. Suena complejo, pero con una API REST como la de Almendro, su sistema solo envía un JSON y nosotros nos encargamos del resto.

Esta guía le muestra cómo integrar facturación electrónica en cualquier sistema que pueda hacer requests HTTP, en 4 pasos, con código curl que puede copiar y probar ahora mismo.

Los 4 pasos de la integración

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh...

curl -X POST https://fe.almendro.cr/api/v1/public/certificates \
  -H "Authorization: Bearer {su_token}" \
  -F "p12_file=@/ruta/certificado.p12" \
  -F "p12_password=contraseña_del_p12" \
  -F "hacienda_pin=1234" \
  -F "environment=sandbox"

curl -X POST https://fe.almendro.cr/api/v1/public/vouchers \
  -H "Authorization: Bearer {su_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "voucher_type": "01",
    "situation": "1",
    "issuer_activity_code": "6201.0",
    "sale_condition": "01",
    "currency_code": "CRC",
    "payment_methods": [{"tipo": "02"}],
    "receiver": {
      "id_type": "02",
      "id_number": "3101000001",
      "name": "EMPRESA RECEPTORA S.A."
    },
    "line_items": [{
      "line_number": 1,
      "cabys_code": "8311000000000",
      "quantity": "1.000",
      "unit_of_measure": "Sp",
      "detail": "Servicio de consultoría",
      "unit_price": "100000.00000",
      "total_amount": "100000.00000",
      "sub_total": "100000.00000",
      "base_imponible": "100000.00000",
      "taxes": [{
        "codigo": "01",
        "codigoTarifa": "08",
        "tarifa": "13.00",
        "monto": "13000.00000"
      }],
      "impuesto_neto": "13000.00000",
      "total_line_amount": "113000.00000"
    }]
  }'

{
  "success": true,
  "data": {
    "voucher_key": "50623042600310100000100100001010000000001112345678",
    "voucher_type": "01",
    "voucher_type_label": "Factura Electrónica",
    "consecutive_number": "00100001010000000001",
    "status": "pending",
    "environment": "sandbox"
  },
  "message": "Comprobante generado y encolado para envío a Hacienda."
}

curl -X POST https://fe.almendro.cr/api/v1/public/webhooks \
  -H "Authorization: Bearer {su_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-sistema.com/webhooks/almendro",
    "events": ["voucher.accepted", "voucher.rejected"]
  }'

Sandbox: pruebe sin riesgo fiscal

Almendro ofrece un ambiente sandbox que replica la API de producción contra el sandbox oficial de Hacienda. Los comprobantes emitidos no tienen valor fiscal y no consumen su cuota mensual. Para usar sandbox, cambie la URL:

Token, headers y payload son exactamente iguales. Solo cambie la URL. Disponible en todos los planes.

Los 7 tipos de comprobante soportados

La misma API (POST /vouchers) emite los 7 tipos oficiales del esquema XML v4.4. Solo cambie el campo voucher_type:

¿Qué incluye la API?

Almendro expone 84 endpoints REST organizados en 19 grupos. Además de emitir comprobantes, puede gestionar clientes, productos, plantillas PDF, webhooks, reportes financieros y más. Toda la documentación está disponible en fe.almendro.cr/docs con ejemplos en curl, JavaScript y PHP.

¿Cuánto cuesta?

Almendro es de las opciones más económicas para facturar electrónicamente en Costa Rica. La API va incluida en todos los planes. Lo que escala con el precio es el cupo de comprobantes y las llamadas por minuto, no el acceso: