Almendro Factura Electrónica
Guía de integración 23 abril 2026 · 10 min de lectura

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

Conecte su POS, e-commerce, ERP o CRM a la facturación electrónica del Ministerio de Hacienda en 4 pasos. Con código funcional y sandbox para probar sin riesgo.

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.

¿No tiene cuenta? Créela gratis en fe.almendro.cr/register. El plan gratuito incluye 5 comprobantes/mes y acceso API de lectura. Para emitir vía API necesita al menos el plan Emprendedor ($36/año).

Los 4 pasos de la integración

1

Cree su cuenta y obtenga su token API

Regístrese en fe.almendro.cr con su cédula y correo. Desde el portal, vaya a Configuración → Token API y genere un token Bearer. Guárdelo — no se muestra de nuevo.

Este token se usa en el header Authorization de todos los requests:

bash 
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh...
2

Suba su certificado digital .p12

Cada comprobante se firma con su certificado del BCCR. Súbalo desde el portal (Configuración → Certificado) o vía API:

bash 
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"
Sandbox primero. Use environment=sandbox para pruebas. Los comprobantes de sandbox se envían al sandbox de Hacienda — sin valor fiscal y sin consumir su cuota mensual.
3

Emita su primer comprobante

Envíe un POST /vouchers con el JSON del comprobante. Almendro genera el XML v4.4, valida contra los XSD de Hacienda, firma con XAdES-EPES y envía. La respuesta es HTTP 202 Accepted — el procesamiento es asíncrono.

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

Respuesta exitosa:

json — 202 Accepted 
{
  "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."
}
HTTP 202 ≠ aceptado por Hacienda. Solo confirma que Almendro recibió el request, generó el XML, lo firmó y lo encoló. Hacienda responde en 5-60 segundos. Para obtener el resultado, use webhooks (paso 4) o consulte el estado con GET /vouchers/{clave}.
4

Reciba el resultado con webhooks

En lugar de hacer polling, configure un webhook para que Almendro le notifique automáticamente cuando Hacienda responda:

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

Almendro envía un POST a su URL con la clave del comprobante, el estado y un HMAC-SHA256 en el header X-AlmendroFEC-Signature para que verifique la autenticidad. Si su servidor no responde, reintenta con backoff exponencial.

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:

Ambiente Base URL Valor fiscal
Producción /api/v1/public/vouchers Sí
Sandbox /api/v1/public/sandbox/vouchers No

Token, headers y payload son exactamente iguales. Solo cambie la URL. Disponible desde el plan Pyme ($96/año).

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:

Código Tipo Uso
01 Factura Electrónica Venta con receptor identificado
02 Nota de Débito Incrementar monto de factura previa
03 Nota de Crédito Anular o reducir monto
04 Tiquete Electrónico Venta al consumidor final
08 Factura de Compra Compra a proveedor no inscrito
09 Factura de Exportación Venta al exterior
10 Recibo de Pago Confirmar pago en venta a crédito

¿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.

Grupo Endpoints Ejemplo
Comprobantes 8 Emitir, listar, anular, descargar XML/PDF
Clientes (receptor) 5 CRUD de receptores frecuentes
Items/Productos 5 Catálogo CABYS reutilizable
Webhooks 6 Notificaciones en tiempo real
Reportes 7 Ventas, IVA, MensajeReceptor
Integrador 13 Gestión de múltiples clientes
Certificados 3 Subir/listar/desactivar .p12
PDF Templates 8 Editor visual de plantillas
Catálogos 3 CABYS, actividades, ubicaciones

¿Cuánto cuesta?

Almendro es la opción más económica para facturar electrónicamente por API en Costa Rica. Plan gratuito real con API incluida:

Plan Precio Comprobantes/mes Sandbox Webhooks
Gratis $0 5 No No
Emprendedor $36/año 100 No No
Pyme $96/año 500 Sí 1
Profesional $19/mes 2,000 Sí 3
Empresa $39/mes 8,000 Sí 5
Integrador $79/mes 50,000 Sí 15

Empiece a facturar hoy

Cuenta gratis en 2 minutos. Sandbox incluido desde plan Pyme. 84 endpoints documentados.

Crear cuenta gratis Ver documentación API