Introduction

API RESTful para emisión, consulta, descarga y gestión completa de comprobantes electrónicos ante el Ministerio de Hacienda de Costa Rica. Compatible al 100% con la normativa vigente del esquema XML v4.4 y la firma digital XAdES-EPES. Soporta los 7 tipos de comprobante: Factura Electrónica (01), Nota de Débito (02), Nota de Crédito (03), Tiquete Electrónico (04), Factura de Compra (08), Factura de Exportación (09) y Recibo Electrónico de Pago (10). Diseñada para e-commerce, ERP, PMS, CRM y POS.

Bienvenido a la API de Almendro Factura Electrónica

Almendro Factura Electrónica le permite integrar facturación electrónica costarricense en cualquier sistema en minutos. Emita comprobantes, consulte estados, descargue XML y PDF, gestione clientes y productos, reciba notificaciones en tiempo real y administre múltiples contribuyentes desde una sola API.

La API cumple al 100% con la normativa version 4.4, vigente del Ministerio de Hacienda:

• Reglamento de Comprobantes Electrónicos (Decreto Ejecutivo N.° 41820-H)
• Resolución General sobre disposiciones técnicas (MH-DGT-RES-0019-2022)
• Anexos y Estructuras v4.4 de la Dirección General de Tributación
• Esquemas XSD v4.4 oficiales publicados por la DGT

Primeros pasos

Integrar facturación electrónica con Almendro requiere solo cuatro pasos. No necesita conocer el esquema XML ni la especificación de firma digital: Almendro se encarga de todo lo técnico.

Paso 1 | Cree su cuenta. Regístrese en fe.almendro.cr. Su cuenta queda activa inmediatamente. Recibirá un correo de verificación para confirmar su dirección de email.

Paso 2 | Obtenga su token API. Desde el portal, vaya a Configuración y genere su token API. Este token es su credencial para autenticarse en todos los endpoints. Guárdelo en un lugar seguro: por razones de seguridad, el token solo se muestra una vez al momento de generarlo. Si lo pierde, puede generar uno nuevo (el anterior se revoca automáticamente).

Paso 3 | Suba su certificado digital. Envíe su archivo .p12 de firma digital (emitido por una entidad certificadora registrada ante el BCCR) con POST /api/v1/public/certificates. Almendro valida el certificado, extrae su información y lo almacena de forma segura. La llave privada nunca se expone en ningún endpoint. Necesitará también el PIN de Hacienda que usa para acceder al sistema de comprobantes electrónicos del Ministerio.

Paso 4 | Emita su primer comprobante. Envíe los datos de la factura con POST /api/v1/public/vouchers. Almendro genera el XML conforme al esquema v4.4 de Hacienda, lo valida contra los esquemas oficiales, lo firma digitalmente con XAdES-EPES y lo envía automáticamente al Ministerio de Hacienda. Usted recibe la clave de 50 dígitos del comprobante y puede consultar el resultado con GET /api/v1/public/vouchers/{key} o recibir una notificación automática por Webhook cuando Hacienda responda.

Recomendación: antes de emitir en producción, pruebe su integración usando el ambiente sandbox. Los comprobantes de sandbox se envían al sandbox oficial de Hacienda, no tienen valor fiscal y no consumen su cuota mensual. Vea la sección "Ambiente Sandbox" más adelante.

Autenticación

Todas las peticiones a la API requieren un Bearer Token en el header Authorization:

Authorization: Bearer {YOUR_AUTH_KEY}

Obtenga su token desde el portal en Configuración. Cada contribuyente genera y administra su propio token de forma independiente.

Aislamiento de datos: cada token está vinculado a un contribuyente específico. Todas sus consultas retornan exclusivamente los comprobantes, clientes, productos y configuración de su propio contribuyente. Es imposible acceder a datos de otro contribuyente, incluso si conociera su token. Este aislamiento se aplica automáticamente en todos los endpoints sin excepción.

Gestión del token: puede consultar los metadatos de su token activo (fecha de creación, último uso) con GET /api/v1/public/tokens/current. Para generar un nuevo token y revocar el anterior, use POST /api/v1/public/tokens.

Formato de respuesta

Todas las respuestas de la API siguen un formato JSON consistente:

{
    "success": true,
    "data": {},
    "message": "Descripción legible en español",
    "errors": null
}

Cuando ocurre un error de validación (422), el campo errors detalla cada campo que falló con mensajes específicos en español:

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "voucher_type": ["El tipo de comprobante (voucher_type) es obligatorio."],
        "line_items.0.cabys_code": ["El código CABYS no existe en el catálogo."]
    }
}

En las respuestas paginadas (listados), se incluyen los campos meta y links para facilitar la navegación entre páginas:

{
    "success": true,
    "data": [...],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 73,
        "from": 1,
        "to": 15
    },
    "links": {
        "first": "...?page=1",
        "last": "...?page=5",
        "prev": null,
        "next": "...?page=2"
    }
}

Emisión de comprobantes

La emisión es el corazón de la API. El proceso es asíncrono: el endpoint retorna 202 Accepted en milisegundos y el envío a Hacienda ocurre en segundo plano.

sequenceDiagram
    participant I as Su sistema
    participant A as Almendro
    participant H as Hacienda

    I->>+A: POST /vouchers
    Note right of A: Almendro genera clave, XML v4.4 y firma XAdES-EPES
    A-->>-I: 202 Accepted (clave de 50 dígitos)

    rect rgba(128, 128, 128, 0.08)
        Note over A,H: Procesamiento asíncrono (5 a 60 segundos)
        A->>+H: XML firmado
        H-->>-A: Respuesta fiscal
    end

    alt
        A-->>I: Webhook voucher.accepted
    else
        A-->>I: Webhook voucher.rejected
    end

El endpoint retorna 202 Accepted inmediatamente. Esto confirma que el comprobante fue generado, validado contra los esquemas XSD oficiales de Hacienda y firmado digitalmente. El envío a Hacienda ocurre automáticamente en segundo plano.

Importante: el código 202 Accepted no significa "aceptado por Hacienda". Es la confirmación de que Almendro recibió y procesó su solicitud correctamente. La respuesta fiscal de Hacienda se obtiene consultando el estado del comprobante o configurando Webhooks.

Atajos para emisión rápida: si tiene clientes y productos registrados en su catálogo de Almendro, puede simplificar el payload de emisión. Envíe client_id para resolver automáticamente los datos del receptor, y item_id en cada línea para resolver código CABYS, descripción, unidad de medida, precio e impuesto. Si incluye campos explícitos junto con el client_id o item_id, los valores explícitos siempre tienen prioridad.

Anulación: para anular un comprobante previamente aceptado por Hacienda, use POST /api/v1/public/vouchers/{key}/cancel. Almendro genera automáticamente una Nota de Crédito (tipo 03) que referencia al comprobante original.

Estados del comprobante:

Impuestos y cálculo de totales

Almendro calcula automáticamente todos los totales del ResumenFactura a partir de las líneas de detalle. Usted solo necesita enviar los impuestos correctamente en cada línea.

Estructura del impuesto por línea

Cada línea (line_items[]) puede tener un array taxes[] con uno o más impuestos:

{
    "taxes": [
        {
            "codigo": "01",
            "codigoTarifa": "08",
            "tarifa": "13.00",
            "monto": "1300.00000"
        }
    ]
}

Clasificación automática de cada línea

Almendro clasifica cada línea en dos dimensiones para calcular los 8 subtotales del ResumenFactura:

Dimensión 1 | Tipo de bien (primer dígito del código CABYS):

Dimensión 2 | Condición del IVA (determinado por el array taxes[]):

Estas dos dimensiones generan los 8 subtotales del XML:

                    Servicio              Mercancía
                    ────────              ─────────
Gravado         TotalServGravados     TotalMercanciasGravadas
Exento          TotalServExentos      TotalMercanciasExentas
Exonerado       TotalServExonerado    TotalMercExonerada
No sujeto       TotalServNoSujeto     TotalMercNoSujeta

Ejemplo 1 | Servicio gravado con IVA 13%

{
    "line_items": [{
        "line_number": 1,
        "cabys_code": "7331100000000",
        "detail": "Servicio de consultoría",
        "quantity": "1.000",
        "unit_of_measure": "Sp",
        "unit_price": "10000.00000",
        "total_amount": "10000.00000",
        "sub_total": "10000.00000",
        "base_imponible": "10000.00000",
        "taxes": [{"codigo": "01", "codigoTarifa": "08", "tarifa": "13.00", "monto": "1300.00000"}],
        "impuesto_neto": "1300.00000",
        "total_line_amount": "11300.00000"
    }]
}

CABYS 7 → servicio. IVA tarifa 08 → gravado. Aporta ₡10,000 a TotalServGravados.

Ejemplo 2 | Mercancía gravada con IVA 13%

{
    "line_items": [{
        "line_number": 1,
        "cabys_code": "1234500000000",
        "detail": "Producto de limpieza",
        "quantity": "2.000",
        "unit_of_measure": "Unid",
        "unit_price": "5000.00000",
        "total_amount": "10000.00000",
        "sub_total": "10000.00000",
        "base_imponible": "10000.00000",
        "taxes": [{"codigo": "01", "codigoTarifa": "08", "tarifa": "13.00", "monto": "1300.00000"}],
        "impuesto_neto": "1300.00000",
        "total_line_amount": "11300.00000"
    }]
}

CABYS 1 → mercancía. IVA tarifa 08 → gravado. Aporta ₡10,000 a TotalMercanciasGravadas.

Ejemplo 3 | Servicio exento de IVA

Opción A | Tarifa exenta (10):

{"taxes": [{"codigo": "01", "codigoTarifa": "10", "tarifa": "0.00", "monto": "0.00000"}], "impuesto_neto": "0.00000"}

Opción B | Sin taxes:

{"taxes": [], "impuesto_neto": "0.00000"}

Ambas clasifican como exento → TotalServExentos o TotalMercanciasExentas.

Ejemplo 4 | Factura mixta (servicio + mercancía gravados)

{
    "line_items": [
        {
            "line_number": 1,
            "cabys_code": "7331100000000",
            "detail": "Consultoría técnica",
            "quantity": "1.000", "unit_of_measure": "Sp",
            "unit_price": "50000.00000", "total_amount": "50000.00000",
            "sub_total": "50000.00000", "base_imponible": "50000.00000",
            "taxes": [{"codigo": "01", "codigoTarifa": "08", "tarifa": "13.00", "monto": "6500.00000"}],
            "impuesto_neto": "6500.00000", "total_line_amount": "56500.00000"
        },
        {
            "line_number": 2,
            "cabys_code": "1234500000000",
            "detail": "Material de oficina",
            "quantity": "10.000", "unit_of_measure": "Unid",
            "unit_price": "1000.00000", "total_amount": "10000.00000",
            "sub_total": "10000.00000", "base_imponible": "10000.00000",
            "taxes": [{"codigo": "01", "codigoTarifa": "08", "tarifa": "13.00", "monto": "1300.00000"}],
            "impuesto_neto": "1300.00000", "total_line_amount": "11300.00000"
        }
    ]
}

ResumenFactura: TotalServGravados=₡50,000 · TotalMercanciasGravadas=₡10,000 · TotalGravado=₡60,000 · TotalImpuesto=₡7,800 · TotalComprobante=₡67,800.

Ejemplo 5 | Payload completo funcional (servicio gravado 13%)

{
    "voucher_type": "01",
    "situation": "1",
    "issued_at": "2026-04-20T10:00:00-06:00",
    "issuer_activity_code": "6201.0",
    "sale_condition": "01",
    "currency_code": "CRC",
    "exchange_rate": "1.00000",
    "payment_methods": [{"tipo": "01"}],
    "receiver": {
        "id_type": "02",
        "id_number": "3101234567",
        "name": "Empresa Receptora S.A.",
        "emails": ["facturacion@receptor.com"]
    },
    "line_items": [{
        "line_number": 1,
        "cabys_code": "7331100000000",
        "detail": "Servicio de desarrollo de software",
        "quantity": "1.000",
        "unit_of_measure": "Sp",
        "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"
    }]
}

Ejemplo 6 | IVA reducido 4% (canasta básica)

{"taxes": [{"codigo": "01", "codigoTarifa": "04", "tarifa": "4.00", "monto": "400.00000"}], "impuesto_neto": "400.00000"}

Fórmulas de cada línea

total_amount     = unit_price × quantity
sub_total        = total_amount - descuentos (si aplica)
base_imponible   = sub_total (normalmente igual, salvo exoneraciones parciales)
monto (impuesto) = base_imponible × tarifa / 100
impuesto_neto    = monto - monto_exonerado (si aplica)
total_line_amount = sub_total + impuesto_neto

Todos los montos: exactamente 5 decimales ("10000.00000").

Errores comunes de Hacienda

Regla de oro

1. cabys_code: 13 dígitos válidos. Verifique con GET /catalogs/cabys?search={código}.
2. Gravado (IVA > 0%): taxes con codigo + codigoTarifa + tarifa + monto, más impuesto_neto y base_imponible.
3. Exento: tarifa 10 con monto 0.00000, O taxes: [].
4. monto = base_imponible × tarifa / 100 (5 decimales).
5. total_line_amount = sub_total + impuesto_neto.
6. 5 decimales siempre: "10000.00000".

Almendro calcula automáticamente los 23 campos del ResumenFactura | no envíe totales.

Consulta y descarga de comprobantes

Una vez emitido un comprobante, dispone de varios endpoints para consultarlo y descargar sus archivos:

• Listado con filtros: GET /vouchers permite filtrar por estado, tipo, fecha, cédula del receptor, ambiente y moneda. Soporta múltiples valores separados por coma (ejemplo: ?status=accepted,rejected o ?voucher_type=01,04).
• Detalle individual: GET /vouchers/{key} retorna todos los datos del comprobante incluyendo líneas de detalle, referencias, medios de pago, totales y el estado de Hacienda.
• XML firmado: GET /vouchers/{key}/xml descarga el XML con firma digital tal como fue enviado a Hacienda.
• Respuesta de Hacienda: GET /vouchers/{key}/xml-response descarga el XML de respuesta (MensajeHacienda) que confirma la aceptación o el rechazo.
• PDF: GET /vouchers/{key}/pdf descarga la representación gráfica del comprobante, generada según la plantilla PDF activa del contribuyente, con código QR conforme a la normativa vigente.

Gestión de clientes y productos

Almendro le permite mantener un catálogo de clientes (receptores frecuentes) y productos o servicios (líneas de detalle reutilizables). Esto simplifica la emisión de comprobantes al permitir referenciar un client_id o item_id en lugar de repetir todos los datos en cada factura.

Clientes (/clients): registre la razón social, cédula, correos, dirección y teléfono de sus receptores frecuentes. Al emitir un comprobante con client_id, los datos del receptor se completan automáticamente.

Productos/Servicios (/items): registre código CABYS, descripción, unidad de medida, precio unitario e impuesto de cada producto o servicio. Al emitir con item_id en una línea, esos campos se resuelven automáticamente. Puede asignar un código interno (SKU, PLU) único por contribuyente para localizar rápidamente sus productos.

Ambos catálogos ofrecen los cinco endpoints estándar: listar, crear, consultar, actualizar y eliminar.

Plantillas PDF y personalización visual

Cada contribuyente puede personalizar cómo lucen sus comprobantes en formato PDF. El sistema de plantillas permite configurar colores, fuentes, márgenes, qué secciones mostrar u ocultar, y subir su propio logotipo.

Cinco estilos predefinidos: Predeterminado, Moderno, Clásico, Minimalista y Dividido. Cada uno ofrece un diseño distinto que se adapta a diferentes tipos de negocio.

Configuración visual: a través del campo config_json puede ajustar colores (primario, secundario, texto, acento en formato hexadecimal), familias tipográficas, tamaños de fuente para encabezado, cuerpo y pie de página, y márgenes en milímetros.

Logotipo: suba el logo de su empresa con POST /pdf-templates/{id}/logo (formatos JPG, PNG o SVG, máximo 2 MB). El logo aparecerá en la posición configurada (izquierda, centro o derecha) de todos los comprobantes generados con esa plantilla.

Restricciones normativas: el código QR debe medir al menos 2.5 cm de alto por 2.5 cm de ancho y ubicarse en la parte inferior derecha del PDF, conforme al artículo 5 de la Resolución. Estas restricciones se validan automáticamente y no pueden modificarse.

Puede tener varias plantillas y marcar una como predeterminada. La cantidad máxima de plantillas depende de su plan.

Configuración de email transaccional

Almendro envía automáticamente los comprobantes por correo electrónico al receptor, adjuntando el XML firmado y el PDF con código QR, conforme al artículo 18 del Reglamento que obliga la entrega del comprobante electrónico y su representación gráfica.

Desde PUT /email-settings puede configurar:

• Envío automático: activar o desactivar el envío al aceptar el comprobante.
• Momento del envío: enviar solo cuando Hacienda acepta, o también al emitir.
• Adjuntos: incluir o excluir el XML y/o el PDF del correo.
• Reply-to: dirección personalizada para que las respuestas del receptor lleguen a su correo en lugar del correo del sistema.
• BCC: hasta 4 direcciones de copia oculta (por ejemplo, su departamento de contabilidad).
• Asunto personalizado: con placeholders dinámicos como {tipo}, {consecutivo}, {receptor}, {total}, {moneda} y {emisor}.
• Mensaje personalizado: texto que aparece en el cuerpo del correo antes de los datos del comprobante.

Webhooks | notificaciones en tiempo real

En lugar de consultar repetidamente el estado de un comprobante, puede configurar Webhooks para que Almendro le notifique automáticamente cuando ocurran eventos relevantes. Al recibir la notificación, su sistema puede actualizar sus registros, notificar al usuario final o ejecutar cualquier lógica de negocio.

Eventos disponibles:

Seguridad: cada notificación incluye una firma HMAC-SHA256 en el header para que su servidor pueda verificar que la notificación proviene de Almendro y no fue alterada en tránsito. La URL de su endpoint debe usar HTTPS.

Tolerancia a fallos: si su servidor no responde o retorna un error, Almendro reintenta con intervalos crecientes. Tras 10 fallos consecutivos, el endpoint se desactiva automáticamente. Puede reactivarlo en cualquier momento con PUT /webhooks/{id}.

Historial de entregas: consulte el registro de entregas con GET /webhooks/{id}/logs para verificar qué notificaciones se enviaron, cuáles fallaron y cuáles se reintentaron.

La cantidad de endpoints webhook disponibles depende de su plan (desde 1 en el plan Pyme hasta 15 en el plan Integrador).

Reportes y análisis financiero

La API ofrece siete endpoints de reportes diseñados para alimentar tableros de control, preparar la declaración D-104 y analizar el desempeño del negocio. Todos comparten los mismos filtros: rango de fechas, tipo de comprobante, estado, moneda, ambiente, cédula del receptor, condición de venta y medio de pago.

• Resumen general (/reports/summary): totales de ventas, impuestos y cantidad de comprobantes para el período seleccionado.
• Ventas por período (/reports/sales-by-period): evolución temporal agrupada por día, semana o mes. La agrupación se detecta automáticamente según el rango de fechas, pero puede forzarla con el parámetro group_by.
• Ventas por receptor (/reports/sales-by-receiver): ranking de los receptores con mayor volumen de ventas.
• Ventas por actividad (/reports/sales-by-activity): desglose por actividad económica CIIU del emisor.
• Resumen de IVA (/reports/tax-summary): desglose de IVA por tarifa, útil para preparar la declaración D-104.
• Comprobantes por estado (/reports/vouchers-by-status): distribución de comprobantes según su estado (aceptados, rechazados, pendientes, etc.).
• Resumen de MensajeReceptor (/reports/receiver-messages): estado de las confirmaciones pendientes con información de plazos.

Valores por defecto: si no envía filtros, los reportes cubren el mes actual, solo comprobantes de producción aceptados por Hacienda, en colones costarricenses. Estos valores corresponden al período y criterios más comunes para la declaración tributaria mensual.

Catálogos oficiales

La API expone tres catálogos oficiales de Hacienda necesarios para construir comprobantes electrónicos válidos:

• CABYS (/catalogs/cabys): catálogo de bienes y servicios con aproximadamente 20,500 códigos. Busque por texto o por prefijo numérico del código. Cada resultado incluye el código de 13 dígitos, la descripción, la tarifa de IVA asociada y si el bien es mercancía o servicio.
• Actividades económicas (/catalogs/activities): catálogo CIIU 4 con aproximadamente 800 actividades. El código de actividad es obligatorio en el campo issuer_activity_code de todos los comprobantes.
• Ubicaciones (/catalogs/locations): división territorial de Costa Rica (provincia, cantón, distrito). Consulta jerárquica: sin parámetros retorna las 7 provincias; con ?province=1 retorna los cantones de San José; con ?province=1&canton=01 retorna los distritos.

Consulta de contribuyentes

El endpoint GET /taxpayer/{id_number} permite verificar los datos de una cédula ante el registro de Hacienda antes de emitir un comprobante. Retorna el nombre oficial, tipo de identificación, régimen tributario, situación (activo/inactivo) y actividades económicas inscritas.

Casos de uso frecuentes:

• Autocompletar los datos del receptor al digitar la cédula en su formulario de emisión.
• Validar que la cédula existe antes de emitir, para evitar rechazos de Hacienda.
• Obtener las actividades económicas del receptor para el campo receiver_activity_code de la Factura de Compra (tipo 08).

Para cédulas físicas de 9 dígitos y planes con la funcionalidad habilitada, el endpoint enriquece la respuesta con datos del Padrón Electoral del TSE (nombre completo, vigencia de la cédula, ubicación). Si la persona no está inscrita como contribuyente ante Hacienda pero sí aparece en el Padrón TSE, el endpoint la identifica como consumidor final, indicando que puede recibir Tiquetes Electrónicos (tipo 04) pero no Facturas Electrónicas.

Los resultados se almacenan en caché durante 24 horas para respuestas rápidas en consultas posteriores.

Confirmación del Receptor (MensajeReceptor)

Conforme al artículo 15 del Reglamento, los receptores de comprobantes tienen 8 días hábiles (excluyendo fines de semana y feriados nacionales de Costa Rica) para responder a un comprobante recibido de un proveedor. Vencido el plazo, se considera aceptación tácita.

El endpoint POST /receiver/confirm le permite enviar la respuesta a Hacienda con tres opciones:

Al aceptar (total o parcialmente), debe indicar la condición del impuesto (crédito IVA general, crédito parcial, bienes de capital, gasto sin crédito, o proporcionalidad), el monto del impuesto acreditable y la actividad económica asociada.

La respuesta incluye información detallada del plazo: días hábiles transcurridos, días restantes, fecha límite y alertas de vencimiento próximo.

Modo Integrador | gestión de múltiples contribuyentes

Si usted es integrador (plan Integrador), puede administrar la facturación de múltiples clientes desde su propia cuenta. Esto es ideal para empresas que desarrollan software de punto de venta, e-commerce, hotelería o cualquier sistema que facture en nombre de terceros.

Cómo funciona:

Vincular un cliente nuevo: créelo con POST /my-contributors indicando su cédula, razón social, correos y actividades económicas. Almendro crea la cuenta del cliente con un usuario propietario y una contraseña temporal. El cliente recibe un email de bienvenida con instrucciones para acceder a su portal. Automáticamente recibe el plan Gratis (5 comprobantes por mes) para que pueda probar el servicio.

Vincular un cliente que ya tiene cuenta: si el cliente ya está registrado en Almendro, solicite acceso con POST /access-requests. El cliente recibe una notificación por email y en su portal, y puede aceptar (total o parcialmente, eligiendo qué ambientes autoriza) o rechazar la solicitud. Al aceptar, usted recibe acceso al certificado digital del cliente con una terminal exclusiva que evita colisión de consecutivos.

Emitir en nombre del cliente: incluya managed_contributor_id en el payload de emisión. El comprobante se registra bajo la cédula del cliente ante Hacienda (el cliente aparece como emisor, nunca el integrador), se firma con el certificado digital del cliente y se envía desde su cuenta. El comprobante cuenta contra el límite mensual de su plan de integrador, no del plan del cliente.

Administrar certificados: suba el certificado .p12 del cliente con POST /my-contributors/{id}/certificates. El certificado queda vinculado a la cuenta del cliente, no a la suya. Puede listar los certificados activos y su estado de vigencia.

Revocar acceso: el cliente puede revocar su acceso en cualquier momento desde DELETE /certificate-grants/{id}. Usted también puede renunciar voluntariamente a un acceso desde DELETE /my-access/{grantId}.

Ejemplo completo | emitir una factura en nombre de un cliente

A continuación se muestra el flujo completo desde cero. Todos los pasos usan el token del integrador | no se necesita el token del cliente en ningún momento.

Paso 1 | Buscar al cliente por cédula (opcional, para autocompletar datos)

curl -X GET "https://fe.almendro.cr/api/v1/public/taxpayer/3101234567" \
  -H "Authorization: Bearer {TOKEN_DEL_INTEGRADOR}"

Retorna nombre oficial, tipo de identificación, régimen tributario y actividades económicas del contribuyente según el registro de Hacienda. Use estos datos para prellenar el paso 2.

Paso 2 | Crear al cliente como contribuyente gestionado

curl -X POST "https://fe.almendro.cr/api/v1/public/my-contributors" \
  -H "Authorization: Bearer {TOKEN_DEL_INTEGRADOR}" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Empresa del Cliente S.A.",
    "id_type": "02",
    "id_number": "3101234567",
    "email": "cliente@ejemplo.com",
    "password": "ContraseñaSegura123!"
  }'

La respuesta incluye el UUID del cliente en el campo data.id. Guarde este UUID: lo necesita para todos los pasos siguientes. El objeto managed_relationship describe el vínculo activo entre usted (integrador) y el cliente | incluye la terminal exclusiva asignada (5 dígitos) para evitar colisión de consecutivos.

{
    "success": true,
    "data": {
        "id": "019d867d-0241-7288-8ece-fd64da75616d",
        "legal_name": "Empresa del Cliente S.A.",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101234567",
        "is_active": true,
        "production_enabled": false,
        "plan_id": "019d0001-0000-0000-0000-000000000001",
        "can_emit_from_portal": true,
        "managed_relationship": {
            "id": "019d870a-0001-7288-8ece-fd64da75a001",
            "assigned_terminal": "00002",
            "retention_months_override": null,
            "default_pdf_template_id": null,
            "linked_at": "2026-04-18T10:00:00-06:00"
        }
    },
    "message": "Cliente creado correctamente. Se envió email de bienvenida.",
    "errors": null
}

Paso 3 | Subir el certificado digital .p12 del cliente

El certificado debe pertenecer al cliente (emitido por una CA registrada ante el BCCR para la cédula del cliente). Almendro lo almacena cifrado y lo vincula a la cuenta del cliente, no a la del integrador.

curl -X POST "https://fe.almendro.cr/api/v1/public/my-contributors/019d867d-0241-7288-8ece-fd64da75616d/certificates" \
  -H "Authorization: Bearer {TOKEN_DEL_INTEGRADOR}" \
  -F "p12_file=@/ruta/al/certificado-cliente.p12" \
  -F "p12_password=ContraseñaDelP12" \
  -F "hacienda_pin=PinDeHaciendaDelCliente" \
  -F "environment=sandbox"

Paso 4 | Emitir un comprobante en nombre del cliente

Use POST /vouchers con su token de integrador y agregue el campo managed_contributor_id con el UUID del cliente obtenido en el paso 2. El resto del payload es idéntico a una emisión normal:

curl -X POST "https://fe.almendro.cr/api/v1/public/vouchers" \
  -H "Authorization: Bearer {TOKEN_DEL_INTEGRADOR}" \
  -H "Content-Type: application/json" \
  -d '{
    "managed_contributor_id": "019d867d-0241-7288-8ece-fd64da75616d",
    "voucher_type": "01",
    "situation": "1",
    "issued_at": "2026-04-18T10:00:00-06:00",
    "sale_condition": "01",
    "payment_methods": [{"tipo": "01"}],
    "receiver": {
        "name": "Juan Pérez Solís",
        "id_type": "01",
        "id_number": "101230456"
    },
    "line_items": [{
        "line_number": 1,
"cabys_code": "4321500000100",
        "detail": "Servicio de consultoría",
        "unit_of_measure": "Sp",
        "quantity": "1.000",
        "unit_price": "10000.00000",
        "sub_total": "10000.00000",
        "total_amount": "10000.00000",
        "taxes": [{
            "codigo": "01",
            "codigoTarifa": "08",
            "tarifa": "13.00",
            "monto": "1300.00000"
        }],
        "impuesto_neto": "1300.00000",
        "total_line_amount": "11300.00000"
    }]
  }'

¿Qué sucede internamente?

Cuando envía managed_contributor_id, Almendro ejecuta automáticamente lo siguiente:

1. Verifica que el UUID pertenece a un cliente vinculado a su cuenta de integrador
2. Genera la clave de 50 dígitos usando la cédula del cliente (no la del integrador)
3. Construye el XML v4.4 con el cliente como emisor (EmisorType) ante Hacienda
4. Firma digitalmente con el certificado .p12 del cliente
5. Asigna el consecutivo en los contadores del cliente, usando la terminal exclusiva del integrador
6. Descuenta el comprobante del límite mensual del plan del integrador

Hacienda siempre ve al cliente como el emisor del comprobante. El integrador nunca aparece en el XML ni en la clave de 50 dígitos.

Sin managed_contributor_id

Si omite el campo managed_contributor_id, el comprobante se emite bajo su propia cédula de integrador, como si fuera un contribuyente normal (emisión directa).

Consultar comprobantes de un cliente gestionado

Use el filtro managed_contributor_id en GET /vouchers para ver solo los comprobantes emitidos en nombre de un cliente específico:

curl -X GET "https://fe.almendro.cr/api/v1/public/vouchers?managed_contributor_id=019d867d-0241-7288-8ece-fd64da75616d" \
  -H "Authorization: Bearer {TOKEN_DEL_INTEGRADOR}"

Reportes agregados por cliente

Los endpoints de reportes (/reports/*) agregan automáticamente los datos de todos sus clientes gestionados. Para filtrar los datos de un solo cliente, use el parámetro ?managed_contributor_id={UUID} en cualquier endpoint de reportes.

Control de acceso | solicitudes y grants

El sistema de control de acceso regula la relación entre integradores y clientes, garantizando que el cliente siempre tiene soberanía sobre sus certificados digitales conforme al artículo 16 del Reglamento.

Solicitudes de acceso (/access-requests): el integrador solicita, el cliente decide. Una solicitud puede estar en estado pendiente, aceptada (total o parcialmente), rechazada o cancelada. El integrador puede ver sus solicitudes enviadas; el cliente, las recibidas.

Grants de certificados (/certificate-grants): cuando el cliente acepta una solicitud, se crean grants que autorizan al integrador a firmar con el certificado del cliente en los ambientes aprobados. Cada grant tiene una terminal exclusiva asignada para evitar duplicación de consecutivos.

El cliente puede consultar qué integradores tienen acceso a sus certificados con GET /certificate-grants, y revocar cualquier acceso en cualquier momento.

Notificaciones

El sistema de notificaciones mantiene informado al usuario sobre eventos importantes que requieren su atención:

• Solicitudes de acceso recibidas de un integrador.
• Respuestas a solicitudes de acceso enviadas.
• Certificados próximos a vencer.
• Cancelaciones de solicitudes.
• Revocaciones de acceso.

Use GET /notifications para obtener la lista paginada de notificaciones con un conteo de no leídas para actualizar badges en su interfaz. Las notificaciones no leídas aparecen primero. Puede marcar una notificación como leída con POST /notifications/{id}/read o marcar todas de una vez con POST /notifications/read-all.

Planes y límites

El volumen de comprobantes, la cantidad de peticiones por minuto y las funcionalidades disponibles dependen del plan contratado:

Límite de peticiones por minuto: cuando se excede, la API retorna 429 Too Many Requests con el header Retry-After indicando cuántos segundos esperar. Las operaciones de lectura (GET) están exentas del límite; solo las operaciones transaccionales (POST, PUT, DELETE) cuentan contra la cuota.

Límite mensual de comprobantes: solo cuentan comprobantes de producción aceptados por Hacienda. Los comprobantes de sandbox no consumen cuota. El plan Gratis bloquea la emisión al alcanzar el límite. Desde el plan Emprendedor, se permite emitir por encima del límite con un cargo automático por comprobante adicional.

Otros límites por plan: cada plan define también la cantidad máxima de clientes en catálogo, productos en catálogo, plantillas PDF, tokens API, emails diarios, sucursales y días de anticipación para alertas de vencimiento de certificado. Consulte los detalles completos en fe.almendro.cr.

Ambiente Sandbox

Almendro ofrece un ambiente sandbox que replica los endpoints de emisión contra el sandbox oficial del Ministerio de Hacienda. Los comprobantes emitidos en sandbox no tienen valor fiscal y no cuentan contra su límite mensual.

Para usar el sandbox, reemplace /api/v1/public/ por /api/v1/public/sandbox/ en la URL. El token, los headers y el payload son exactamente iguales:

Producción:  https://fe.almendro.cr/api/v1/public/vouchers
Sandbox:     https://fe.almendro.cr/api/v1/public/sandbox/vouchers

Endpoints sandbox disponibles: emisión de los 7 tipos de comprobante, consulta, descarga XML/PDF, anulación, confirmación del receptor y consulta de contribuyentes. Los demás endpoints (clientes, productos, webhooks, reportes, plantillas, certificados, configuración) no necesitan URL sandbox porque operan sobre los mismos datos en ambos ambientes.

El acceso al sandbox requiere plan Pyme o superior.

Retención y disponibilidad de XML

Almendro retiene el XML firmado y la respuesta de Hacienda de cada comprobante durante 3 meses en todos los planes. Transcurrido ese período, el contenido XML se elimina automáticamente, pero los metadatos del comprobante (totales, estado, receptor, líneas de detalle) y la generación de PDF permanecen disponibles de forma indefinida.

Cuando el XML ya no está disponible, los endpoints GET /vouchers/{key}/xml y GET /vouchers/{key}/xml-response retornan 410 Gone con la fecha en que se eliminó el archivo.

Retención extendida: puede ampliar la retención de XML hasta 5 años por $12/año (disponible desde el plan Emprendedor). Al vencer la retención extendida, se otorga un período de gracia de 7 días para que descargue sus documentos antes de la eliminación definitiva.

Seguridad y tratamiento de sus datos

Esta es la respuesta técnica a la pregunta que más hacen las empresas antes de integrarse: quién puede ver la información que pasa por la API.

Credenciales de firma cifradas. El certificado .p12, su contraseña y el PIN de Hacienda se guardan cifrados con AES-256-GCM, con una llave dedicada que no forma parte del código de la aplicación. Estos valores no se devuelven en ninguna respuesta de la API, ni siquiera al dueño del certificado: se usan para firmar y nunca salen del servidor.

Aislamiento entre contribuyentes. Cada token pertenece a un contribuyente y toda consulta se filtra por él automáticamente. Además, los endpoints que leen o escriben comprobantes exigen que el token esté vinculado a un contribuyente activo: una petición sin contribuyente asociado se rechaza con 403 antes de tocar la base de datos. No existe ningún parámetro que permita salir de ese ámbito.

Un integrador solo alcanza los comprobantes de un cliente gestionado cuando existe una relación activa, y el alcance depende del rol de esa relación: en rol integrador ve únicamente los comprobantes que él mismo emitió por el cliente; en rol contador ve la facturación completa del cliente. Lo que el cliente emita por su cuenta o con otro proveedor no aparece en el primer caso. El permiso lo otorga el cliente sobre su propio certificado y lo puede revocar cuando quiera.

Qué ve el personal de Almendro. El panel administrativo no tiene ninguna pantalla que liste, abra o exporte comprobantes de un cliente. Lo que el equipo ve son cifras de operación de la cuenta: cantidad de comprobantes emitidos, usuarios, plan y estado de pago. Las acciones administrativas sensibles quedan registradas con autor y fecha.

Respaldos. Se genera un respaldo diario que se cifra en el servidor con criptografía asimétrica: el servidor solo tiene la llave pública, de modo que produce respaldos que él mismo no puede leer. La llave privada vive fuera del servidor.

El límite honesto. Como en cualquier plataforma en la nube, el personal técnico con acceso al servidor tiene acceso material a la base de datos. Eso no lo resuelve el software sino el contrato: firmamos acuerdo de confidencialidad y de tratamiento de datos conforme a la Ley 8968 de Costa Rica. Los respaldos se almacenan en Estados Unidos, siempre cifrados, lo que constituye una transferencia internacional declarada en dicho acuerdo.

El detalle completo, con la referencia al código que sostiene cada afirmación, está en el documento de tratamiento de datos que entregamos a solicitud.

Clave de 50 dígitos

Cada comprobante se identifica con una Clave numérica de exactamente 50 dígitos, definida por los Anexos y Estructuras v4.4 de la DGT. Esta clave se usa en todos los endpoints que reciben el parámetro {key}:

[3 país][6 fecha DDMMAA][12 cédula emisor][20 consecutivo][1 situación][8 seguridad]

Ejemplo: 50613032600206270652001000010100000000011 12345678

• País: siempre 506 (Costa Rica)
• Fecha: día, mes y año de emisión en formato DDMMAA
• Cédula: identificación del emisor, rellenada con ceros hasta 12 dígitos
• Consecutivo: 20 dígitos compuestos por sucursal (3), terminal (5), tipo (2) y secuencia (10)
• Situación: 1 Normal, 2 Contingencia, 3 Sin Internet
• Seguridad: 8 dígitos aleatorios generados por el sistema

Tipos de comprobante soportados

Las Notas de Débito (02), Notas de Crédito (03), Facturas de Compra (08) y Recibos de Pago (10) requieren al menos una referencia al comprobante original en el campo references.

Códigos de estado HTTP

Soporte y contacto

• Documentación: fe.almendro.cr/docs
• Soporte técnico para desarrolladores: developers@almendro.cr
• Soporte general: support@almendro.cr
• Ventas e información comercial: ventas@almendro.cr
• Seguridad: seguridad@almendro.cr

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Obtenga su token desde el portal en Configuración → Token API. Cada token está vinculado a un contribuyente específico y hereda los límites de su plan. El aislamiento de datos se aplica automáticamente | un token solo puede acceder a los comprobantes y datos de su propio contribuyente.

Comprobantes Electrónicos

Listar comprobantes con filtros y paginación

requires authentication

Devuelve todos los comprobantes emitidos por el contribuyente, con paginación y filtros por estado, tipo, rango de fechas, receptor, ambiente y moneda. Los filtros status y voucher_type aceptan múltiples valores separados por coma.

El listado retorna campos resumidos (sin XML ni totales detallados) para máxima eficiencia. Para el detalle completo de un comprobante, use GET /vouchers/{key}.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers?status=accepted%2Crejected&voucher_type=01%2C04&date_from=2026-04-01&date_to=2026-04-30&receiver_id_number=3101234567&external_reference=ORD-12345&environment=production&currency_code=CRC&contributor_id=019d867d-0241-7288-8ece-fd64da75616d&scope=own&sort_by=issued_at&sort_dir=desc&per_page=15&page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers"
);

const params = {
    "status": "accepted,rejected",
    "voucher_type": "01,04",
    "date_from": "2026-04-01",
    "date_to": "2026-04-30",
    "receiver_id_number": "3101234567",
    "external_reference": "ORD-12345",
    "environment": "production",
    "currency_code": "CRC",
    "contributor_id": "019d867d-0241-7288-8ece-fd64da75616d",
    "scope": "own",
    "sort_by": "issued_at",
    "sort_dir": "desc",
    "per_page": "15",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'status' => 'accepted,rejected',
            'voucher_type' => '01,04',
            'date_from' => '2026-04-01',
            'date_to' => '2026-04-30',
            'receiver_id_number' => '3101234567',
            'external_reference' => 'ORD-12345',
            'environment' => 'production',
            'currency_code' => 'CRC',
            'contributor_id' => '019d867d-0241-7288-8ece-fd64da75616d',
            'scope' => 'own',
            'sort_by' => 'issued_at',
            'sort_dir' => 'desc',
            'per_page' => '15',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": [
        {
            "voucher_key": "50620032600206270652001000010100000000011XXXXXXXX",
            "voucher_type": "01",
            "voucher_type_label": "Factura Electrónica",
            "consecutive_number": "00100001010000000001",
            "issued_at": "2026-03-20T10:30:00-06:00",
            "situation": "1",
            "sale_condition": "01",
            "sale_condition_label": "Contado",
            "receiver": {
                "id_type": "02",
                "id_number": "3102345678",
                "name": "Empresa S.A."
            },
            "currency_code": "CRC",
            "total_comprobante": "56500.00000",
            "status": "accepted",
            "hacienda": {
                "status": "aceptado",
                "sent_at": "2026-03-20T10:31:00-06:00",
                "processed_at": "2026-03-20T10:32:00-06:00"
            },
            "environment": "sandbox",
            "is_xml_available": true,
            "line_items_count": 3,
            "created_at": "2026-03-20T10:30:00-06:00",
            "updated_at": "2026-03-20T10:32:00-06:00"
        }
    ],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 15,
        "total": 72,
        "from": 1,
        "to": 15
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": "..."
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

GET /api/v1/public/vouchers/issuers

requires authentication

Opciones disponibles para los filtros del listado, calculadas a partir de los comprobantes que realmente existen (acotados al ambiente). Evita ofrecer en los desplegables valores que no devolverían nada.

Retorna: has_own → true si la cuenta tiene comprobantes propios clients → clientes gestionados con al menos un comprobante voucher_types → tipos de comprobante presentes (01, 03, …) statuses → estados presentes (accepted, rejected, …)

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/issuers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/issuers"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/issuers';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Emitir un comprobante electrónico

requires authentication

Genera, valida contra el XSD oficial v4.4, firma digitalmente con XAdES-EPES y envía automáticamente a Hacienda cualquiera de los 7 tipos de comprobante soportados.

La respuesta es HTTP 202 Accepted | el envío a Hacienda es asíncrono. Para obtener el resultado final (aceptado/rechazado), suscríbase a los eventos voucher.accepted y voucher.rejected vía webhooks (ver grupo Webhooks), o consulte periódicamente GET /vouchers/{key}.

HTTP 202 no significa "aceptado por Hacienda". Solo confirma que el comprobante fue generado, firmado y encolado exitosamente. El estado inicial en la respuesta es pending.

Para ejemplos completos de payload por cada tipo de comprobante, revise la sección "Ejemplos completos de payload por tipo" de la guía de integración al inicio de este grupo.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Idempotency-Key: Identificador único de ESTA emisión, generado por usted (recomendado: un" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"voucher_type\": \"01\",
    \"situation\": \"1\",
    \"local_code\": \"564\",
    \"terminal_code\": \"56425\",
    \"voucher_key\": \"56425593142326822820492192294472586671521743076933\",
    \"consecutive_number\": \"56425593142326822820\",
    \"issued_at\": \"2026-04-20T10:30:00-06:00\",
    \"issuer_activity_code\": \"6201.0\",
    \"receiver_activity_code\": \"4711.0\",
    \"sale_condition\": \"01\",
    \"sale_condition_other\": \"Acuerdo especial de intercambio\",
    \"credit_term\": \"30\",
    \"currency_code\": \"CRC\",
    \"exchange_rate\": \"1.00000\",
    \"external_reference\": \"ORD-12345\",
    \"xml_otros\": [
        {
            \"tipo\": \"texto\",
            \"codigo\": \"orden\",
            \"valor\": \"ORD-0001\"
        }
    ],
    \"client_id\": \"019d1234-0000-0000-0000-000000000001\",
    \"managed_contributor_id\": \"019d867d-0241-7288-8ece-fd64da75616d\",
    \"receiver\": {
        \"name\": \"Empresa Ejemplo S.A.\",
        \"id_type\": \"02\",
        \"id_number\": \"3101000001\",
        \"commercial_name\": \"p\",
        \"emails\": [
            \"architecto\"
        ],
        \"province\": 1,
        \"canton\": \"56\",
        \"district\": \"56\",
        \"address\": \"i\",
        \"phone_country_code\": 8,
        \"phone\": \"564255931\"
    },
    \"line_items\": [
        {
            \"item_id\": \"019d1234-0000-0000-0000-000000000002\",
            \"line_number\": 1,
            \"cabys_code\": \"5311100000000\",
            \"arancelary_partition\": \"564255931423\",
            \"quantity\": \"1.000\",
            \"unit_of_measure\": \"Unid\",
            \"detail\": \"Servicio de consultoría\",
            \"unit_price\": \"10000.00000\",
            \"total_amount\": \"10000.00000\",
            \"sub_total\": \"10000.00000\",
            \"base_imponible\": \"10000.00000\",
            \"discounts\": [
                {
                    \"monto\": 39,
                    \"codigo\": 6
                }
            ],
            \"taxes\": [
                {
                    \"codigo\": \"01\",
                    \"codigoTarifa\": \"08\",
                    \"tarifa\": \"13.00\",
                    \"factorCalculo\": 4326.41688,
                    \"monto\": \"1300.00000\",
                    \"monto_exportacion\": 77,
                    \"exoneracion\": {
                        \"tipoDocumento\": \"iy\",
                        \"numeroDocumento\": \"v\",
                        \"nombreInstitucion\": \"d\",
                        \"fechaEmision\": \"2026-08-11T21:37:46\",
                        \"tarifaExonerada\": 37,
                        \"montoExoneracion\": 9
                    }
                }
            ],
            \"impuesto_neto\": \"1300.00000\",
            \"total_line_amount\": \"11300.00000\",
            \"medicine_registration\": \"n\",
            \"pharma_form_code\": \"564\",
            \"commercial_codes\": [
                {
                    \"tipo\": 4,
                    \"codigo\": \"yvdljnikhwaykcmy\"
                }
            ],
            \"vin_numbers\": [
                \"u\"
            ]
        }
    ],
    \"references\": [
        {
            \"doc_type\": \"01\",
            \"number\": \"50613032600206270652001000010100000000001XXXXXXXX\",
            \"issued_at\": \"2026-03-01T10:00:00-06:00\",
            \"code\": \"01\",
            \"reason\": \"Anulación por error en monto\"
        }
    ],
    \"payment_methods\": [
        {
            \"tipo\": \"01\"
        }
    ],
    \"other_charges\": [
        {
            \"tipo\": \"06\",
            \"description\": \"Quidem nostrum qui commodi incidunt iure odit.\",
            \"percentage\": 10,
            \"amount\": 5000
        }
    ]
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Idempotency-Key": "Identificador único de ESTA emisión, generado por usted (recomendado: un",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "voucher_type": "01",
    "situation": "1",
    "local_code": "564",
    "terminal_code": "56425",
    "voucher_key": "56425593142326822820492192294472586671521743076933",
    "consecutive_number": "56425593142326822820",
    "issued_at": "2026-04-20T10:30:00-06:00",
    "issuer_activity_code": "6201.0",
    "receiver_activity_code": "4711.0",
    "sale_condition": "01",
    "sale_condition_other": "Acuerdo especial de intercambio",
    "credit_term": "30",
    "currency_code": "CRC",
    "exchange_rate": "1.00000",
    "external_reference": "ORD-12345",
    "xml_otros": [
        {
            "tipo": "texto",
            "codigo": "orden",
            "valor": "ORD-0001"
        }
    ],
    "client_id": "019d1234-0000-0000-0000-000000000001",
    "managed_contributor_id": "019d867d-0241-7288-8ece-fd64da75616d",
    "receiver": {
        "name": "Empresa Ejemplo S.A.",
        "id_type": "02",
        "id_number": "3101000001",
        "commercial_name": "p",
        "emails": [
            "architecto"
        ],
        "province": 1,
        "canton": "56",
        "district": "56",
        "address": "i",
        "phone_country_code": 8,
        "phone": "564255931"
    },
    "line_items": [
        {
            "item_id": "019d1234-0000-0000-0000-000000000002",
            "line_number": 1,
            "cabys_code": "5311100000000",
            "arancelary_partition": "564255931423",
            "quantity": "1.000",
            "unit_of_measure": "Unid",
            "detail": "Servicio de consultoría",
            "unit_price": "10000.00000",
            "total_amount": "10000.00000",
            "sub_total": "10000.00000",
            "base_imponible": "10000.00000",
            "discounts": [
                {
                    "monto": 39,
                    "codigo": 6
                }
            ],
            "taxes": [
                {
                    "codigo": "01",
                    "codigoTarifa": "08",
                    "tarifa": "13.00",
                    "factorCalculo": 4326.41688,
                    "monto": "1300.00000",
                    "monto_exportacion": 77,
                    "exoneracion": {
                        "tipoDocumento": "iy",
                        "numeroDocumento": "v",
                        "nombreInstitucion": "d",
                        "fechaEmision": "2026-08-11T21:37:46",
                        "tarifaExonerada": 37,
                        "montoExoneracion": 9
                    }
                }
            ],
            "impuesto_neto": "1300.00000",
            "total_line_amount": "11300.00000",
            "medicine_registration": "n",
            "pharma_form_code": "564",
            "commercial_codes": [
                {
                    "tipo": 4,
                    "codigo": "yvdljnikhwaykcmy"
                }
            ],
            "vin_numbers": [
                "u"
            ]
        }
    ],
    "references": [
        {
            "doc_type": "01",
            "number": "50613032600206270652001000010100000000001XXXXXXXX",
            "issued_at": "2026-03-01T10:00:00-06:00",
            "code": "01",
            "reason": "Anulación por error en monto"
        }
    ],
    "payment_methods": [
        {
            "tipo": "01"
        }
    ],
    "other_charges": [
        {
            "tipo": "06",
            "description": "Quidem nostrum qui commodi incidunt iure odit.",
            "percentage": 10,
            "amount": 5000
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Idempotency-Key' => 'Identificador único de ESTA emisión, generado por usted (recomendado: un',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'voucher_type' => '01',
            'situation' => '1',
            'local_code' => '564',
            'terminal_code' => '56425',
            'voucher_key' => '56425593142326822820492192294472586671521743076933',
            'consecutive_number' => '56425593142326822820',
            'issued_at' => '2026-04-20T10:30:00-06:00',
            'issuer_activity_code' => '6201.0',
            'receiver_activity_code' => '4711.0',
            'sale_condition' => '01',
            'sale_condition_other' => 'Acuerdo especial de intercambio',
            'credit_term' => '30',
            'currency_code' => 'CRC',
            'exchange_rate' => '1.00000',
            'external_reference' => 'ORD-12345',
            'xml_otros' => [
                [
                    'tipo' => 'texto',
                    'codigo' => 'orden',
                    'valor' => 'ORD-0001',
                ],
            ],
            'client_id' => '019d1234-0000-0000-0000-000000000001',
            'managed_contributor_id' => '019d867d-0241-7288-8ece-fd64da75616d',
            'receiver' => [
                'name' => 'Empresa Ejemplo S.A.',
                'id_type' => '02',
                'id_number' => '3101000001',
                'commercial_name' => 'p',
                'emails' => [
                    'architecto',
                ],
                'province' => 1,
                'canton' => '56',
                'district' => '56',
                'address' => 'i',
                'phone_country_code' => 8,
                'phone' => '564255931',
            ],
            'line_items' => [
                [
                    'item_id' => '019d1234-0000-0000-0000-000000000002',
                    'line_number' => 1,
                    'cabys_code' => '5311100000000',
                    'arancelary_partition' => '564255931423',
                    'quantity' => '1.000',
                    'unit_of_measure' => 'Unid',
                    'detail' => 'Servicio de consultoría',
                    'unit_price' => '10000.00000',
                    'total_amount' => '10000.00000',
                    'sub_total' => '10000.00000',
                    'base_imponible' => '10000.00000',
                    'discounts' => [
                        [
                            'monto' => 39,
                            'codigo' => 6,
                        ],
                    ],
                    'taxes' => [
                        [
                            'codigo' => '01',
                            'codigoTarifa' => '08',
                            'tarifa' => '13.00',
                            'factorCalculo' => 4326.41688,
                            'monto' => '1300.00000',
                            'monto_exportacion' => 77,
                            'exoneracion' => [
                                'tipoDocumento' => 'iy',
                                'numeroDocumento' => 'v',
                                'nombreInstitucion' => 'd',
                                'fechaEmision' => '2026-08-11T21:37:46',
                                'tarifaExonerada' => 37,
                                'montoExoneracion' => 9,
                            ],
                        ],
                    ],
                    'impuesto_neto' => '1300.00000',
                    'total_line_amount' => '11300.00000',
                    'medicine_registration' => 'n',
                    'pharma_form_code' => '564',
                    'commercial_codes' => [
                        [
                            'tipo' => 4,
                            'codigo' => 'yvdljnikhwaykcmy',
                        ],
                    ],
                    'vin_numbers' => [
                        'u',
                    ],
                ],
            ],
            'references' => [
                [
                    'doc_type' => '01',
                    'number' => '50613032600206270652001000010100000000001XXXXXXXX',
                    'issued_at' => '2026-03-01T10:00:00-06:00',
                    'code' => '01',
                    'reason' => 'Anulación por error en monto',
                ],
            ],
            'payment_methods' => [
                [
                    'tipo' => '01',
                ],
            ],
            'other_charges' => [
                [
                    'tipo' => '06',
                    'description' => 'Quidem nostrum qui commodi incidunt iure odit.',
                    'percentage' => 10,
                    'amount' => 5000.0,
                ],
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "voucher_key": "50620042600206270652001000010100000000011XXXXXXXX",
        "voucher_type": "01",
        "voucher_type_label": "Factura Electrónica",
        "consecutive_number": "00100001010000000001",
        "issued_at": "2026-04-20T10:30:00-06:00",
        "situation": "1",
        "situation_label": "Normal",
        "sale_condition": "01",
        "sale_condition_label": "Contado",
        "sale_condition_other": null,
        "credit_term": null,
        "receiver": {
            "id_type": "02",
            "id_number": "3101000001",
            "name": "EMPRESA EJEMPLO S.A.",
            "commercial_name": null,
            "emails": [
                "facturacion@ejemplo.cr"
            ]
        },
        "currency_code": "CRC",
        "exchange_rate": "1.00000",
        "totals": {
            "serv_gravados": "10000.00000",
            "serv_exentos": "0.00000",
            "serv_exonerado": "0.00000",
            "serv_no_sujeto": "0.00000",
            "merc_gravadas": "0.00000",
            "merc_exentas": "0.00000",
            "merc_exonerada": "0.00000",
            "merc_no_sujeta": "0.00000",
            "total_gravado": "10000.00000",
            "total_exento": "0.00000",
            "total_exonerado": "0.00000",
            "total_no_sujeto": "0.00000",
            "total_venta": "10000.00000",
            "total_descuentos": "0.00000",
            "total_venta_neta": "10000.00000",
            "total_impuesto": "1300.00000",
            "total_imp_asum_emisor_fab": "0.00000",
            "total_iva_devuelto": "0.00000",
            "total_otros_cargos": "0.00000",
            "total_comprobante": "11300.00000"
        },
        "payment_methods": [
            {
                "tipo": "01"
            }
        ],
        "status": "pending",
        "hacienda": {
            "status": null,
            "message": null,
            "sent_at": null,
            "processed_at": null
        },
        "environment": "production",
        "is_xml_available": true,
        "line_items_count": 1,
        "references_count": 0,
        "created_at": "2026-04-20T10:30:00-06:00",
        "updated_at": "2026-04-20T10:30:00-06:00"
    },
    "message": "Comprobante [50620042600206270652001000010100000000011XXXXXXXX] generado y encolado para envío a Hacienda.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "voucher_type": [
            "El campo voucher_type es obligatorio."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Validación XSD fallida para Factura Electrónica (01) | 1 error. Primer error: [45:12] Element 'CodigoCABYS': [facet 'length'] The value has a length of '12'; this differs from the allowed length of '13'.",
    "errors": {
        "voucher_type": [
            "01"
        ],
        "xsd": [
            {
                "nivel": "error",
                "codigo": 1824,
                "linea": 45,
                "columna": 12,
                "mensaje": "Element 'CodigoCABYS': [facet 'length'] The value has a length of '12'; this differs from the allowed length of '13'."
            }
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "No se pudo firmar el comprobante. El certificado digital está vencido. Renueve su certificado con el BCCR y vuelva a subirlo.",
    "errors": {
        "signature": [
            "..."
        ],
        "code": [
            "2002"
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Límite mensual de comprobantes alcanzado (50/50). Actualice a PyME para emitir más. Período: junio 2026. Precio: $29.99/mes ≈ ₡15,745.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Listar comprobantes de contingencia pendientes

requires authentication

Devuelve los comprobantes emitidos en situación de contingencia (caída del sistema) o sin internet, que aún no fueron aceptados ni rechazados por Hacienda.

La normativa establece un plazo máximo de 2 días hábiles para remitir los comprobantes de contingencia. Este endpoint le muestra cuántos están pendientes y cuántos ya superaron el plazo, para ayudarle a cumplir con el monitoreo requerido antes de incurrir en infracciones tributarias.

Estados incluidos: draft, pending, sent, error.

Los comprobantes ya resueltos (accepted, rejected, cancelled) no aparecen aquí.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/pending-contingency?situation=3&expired_only=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/pending-contingency"
);

const params = {
    "situation": "3",
    "expired_only": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/pending-contingency';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'situation' => '3',
            'expired_only' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "items": [
            {
                "voucher_key": "50617042026...",
                "voucher_type": "01",
                "voucher_type_label": "Factura Electrónica",
                "consecutive_number": "00100001010000000001",
                "status": "error",
                "situation": "3",
                "situation_label": "Sin Internet",
                "issued_at": "2026-04-10T14:30:00-06:00",
                "deadline": "2026-04-14",
                "elapsed_business_days": 3,
                "is_expired": true,
                "receiver": {
                    "id_type": "02",
                    "id_number": "3101000001",
                    "name": "Empresa S.A."
                },
                "currency_code": "CRC",
                "total_comprobante": "56500.00000"
            }
        ],
        "total": 5,
        "expired_count": 2
    },
    "message": "5 comprobante(s) de contingencia sin resolver. 2 superan el plazo de 2 días hábiles.",
    "errors": null
}
 

{
    "success": true,
    "data": {
        "items": [],
        "total": 0,
        "expired_count": 0
    },
    "message": "Sin comprobantes de contingencia pendientes.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Consultar un comprobante por clave

requires authentication

Devuelve el detalle completo de un comprobante identificado por su clave de 50 dígitos: datos del emisor y receptor, líneas, totales, estado actual y respuesta de Hacienda (si ya fue procesado).

La clave debe tener exactamente 50 dígitos numéricos | formatos inválidos retornan 404 sin procesar la consulta.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "voucher_key": "50619032600310199999900100001010000000001112345678",
        "voucher_type": "01",
        "voucher_type_label": "Factura Electrónica",
        "consecutive_number": "00100001010000000001",
        "issued_at": "2026-04-13T10:00:00-06:00",
        "situation": "1",
        "situation_label": "Normal",
        "sale_condition": "01",
        "sale_condition_label": "Contado",
        "sale_condition_other": null,
        "credit_term": null,
        "receiver": {
            "id_type": "02",
            "id_number": "3101000001",
            "name": "EMPRESA EJEMPLO S.A.",
            "commercial_name": "Ejemplo Comercial",
            "emails": [
                "facturacion@ejemplo.cr"
            ]
        },
        "currency_code": "CRC",
        "exchange_rate": "1.00000",
        "totals": {
            "serv_gravados": "10000.00000",
            "serv_exentos": "0.00000",
            "serv_exonerado": "0.00000",
            "serv_no_sujeto": "0.00000",
            "merc_gravadas": "0.00000",
            "merc_exentas": "0.00000",
            "merc_exonerada": "0.00000",
            "merc_no_sujeta": "0.00000",
            "total_gravado": "10000.00000",
            "total_exento": "0.00000",
            "total_exonerado": "0.00000",
            "total_no_sujeto": "0.00000",
            "total_venta": "10000.00000",
            "total_descuentos": "0.00000",
            "total_venta_neta": "10000.00000",
            "total_impuesto": "1300.00000",
            "total_imp_asum_emisor_fab": "0.00000",
            "total_iva_devuelto": "0.00000",
            "total_otros_cargos": "0.00000",
            "total_comprobante": "11300.00000"
        },
        "payment_methods": [
            {
                "tipo": "01"
            }
        ],
        "status": "accepted",
        "hacienda": {
            "status": "aceptado",
            "message": null,
            "sent_at": "2026-04-13T10:01:00-06:00",
            "processed_at": "2026-04-13T10:02:00-06:00"
        },
        "environment": "production",
        "is_xml_available": true,
        "line_items_count": 1,
        "references_count": 0,
        "created_at": "2026-04-13T10:00:00-06:00",
        "updated_at": "2026-04-13T10:02:00-06:00"
    },
    "message": "Comprobante obtenido correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "El recurso solicitado no existe.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Anular un comprobante (emite una Nota de Crédito)

requires authentication

En Costa Rica, la anulación de un comprobante electrónico NO es una operación directa. El mecanismo normativo es emitir una Nota de Crédito que referencia al comprobante original con el código 01 (Anula documento).

Este endpoint automatiza ese proceso:

1. Lee el comprobante original por su clave.
2. Construye automáticamente el payload de la NC (mismas líneas, mismo receptor) con la referencia correspondiente.
3. La emite por el mismo pipeline que POST /vouchers (valida XSD, firma, envía a Hacienda).
4. Retorna la NC generada con HTTP 202.

Restricciones:

• Solo comprobantes en estado accepted pueden anularse.
• Solo FE (01) y TE (04) son anulables con NC.
• Un comprobante ya cancelado no puede re-cancelarse.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/cancel" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Idempotency-Key: Identificador único de ESTA anulación, generado por usted. Es OPCIONAL," \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/cancel"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Idempotency-Key": "Identificador único de ESTA anulación, generado por usted. Es OPCIONAL,",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/cancel';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Idempotency-Key' => 'Identificador único de ESTA anulación, generado por usted. Es OPCIONAL,',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "voucher_key": "50621042600310199999900100001010000000002212345679",
        "voucher_type": "03",
        "voucher_type_label": "Nota de Crédito",
        "consecutive_number": "00100001030000000001",
        "status": "pending",
        "environment": "production",
        "created_at": "2026-04-21T11:00:00-06:00"
    },
    "message": "NC de anulación generada. Encolada para envío a Hacienda.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Solo comprobantes aceptados por Hacienda pueden anularse.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Validación XSD fallida para Nota de Crédito (03) | ...",
    "errors": {
        "voucher_type": [
            "03"
        ],
        "xsd": [
            {
                "linea": 45,
                "columna": 12,
                "mensaje": "..."
            }
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "No se pudo firmar el comprobante. El certificado digital está vencido.",
    "errors": {
        "signature": [
            "..."
        ],
        "code": [
            "2002"
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Reenviar a Hacienda un comprobante que quedó sin enviarse

requires authentication

Reintenta la emisión de un comprobante que NO llegó a Hacienda y por lo tanto NO consumió consecutivo allá: típicamente quedó en draft con su XML generado pero sin firmar (falló la firma por falta de certificado). Una vez subido el .p12, este endpoint lo firma y lo encola | reusando el mismo comprobante y consecutivo, sin generar huecos de numeración.

También cubre el estado error (Hacienda no lo procesó por un fallo temporal; ya está firmado y solo se reencola).

El ambiente del reenvío es el del comprobante original (un comprobante sandbox se firma con el certificado sandbox y se envía a sandbox).

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers/50617062600020627065200100001010000000101173247335/resend" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50617062600020627065200100001010000000101173247335/resend"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50617062600020627065200100001010000000101173247335/resend';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Descargar el XML firmado del comprobante

requires authentication

Devuelve el XML completo con firma digital XAdES-EPES, tal como fue enviado a la API de recepción de Hacienda. Este XML es el documento fiscal con validez legal.

Obligación de archivo: la normativa exige conservar este XML por 5 años. Descárguelo y archívelo de su lado dentro del período de retención de la plataforma (3 meses por defecto, hasta 5 años con el add-on de retención extendida).

Disponibilidad:

• Solo comprobantes que ya pasaron la firma digital tienen XML.
• Comprobantes en draft aún no tienen XML → 404.
• Comprobantes cuyo XML fue purgado (retención expirada) → 410 Gone.

Después de la retención, los metadatos del comprobante y el PDF siguen disponibles | solo el XML deja de estar accesible.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

[archivo binario application/xml]
 

{
    "success": false,
    "data": null,
    "message": "El XML firmado aún no está disponible. El comprobante está en estado 'draft'.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "XML purgado. Retención expirada el 2026-06-15.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Descargar el XML de respuesta de Hacienda (MensajeHacienda)

requires authentication

Devuelve el MensajeHacienda XML firmado por Hacienda que representa el resultado oficial del procesamiento del comprobante. Incluye:

• Mensaje: 1=Aceptado, 3=Rechazado.
• DetalleMensaje: descripción del error (si fue rechazado).
• MontoTotalImpuesto: monto de impuesto validado por Hacienda.

Este XML es evidencia oficial de la validación ante Hacienda. Su obligación legal de archivo es de 5 años, igual que el XML firmado.

Disponibilidad:

• Solo comprobantes que Hacienda ya procesó (estado accepted o rejected) tienen este XML.
• Comprobantes en tránsito (pending, sent) → 404.
• Si la retención expiró → 410 Gone.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml-response" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml-response"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/xml-response';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

[archivo binario application/xml]
 

{
    "success": false,
    "data": null,
    "message": "La respuesta de Hacienda aún no está disponible. El comprobante está en estado 'sent'.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "XML purgado. Retención expirada el 2026-06-15.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Descargar la representación gráfica (PDF) del comprobante

requires authentication

Genera y devuelve el PDF del comprobante usando la plantilla por defecto del contribuyente (o una específica si se indica vía template_id). El PDF incluye obligatoriamente un código QR con la clave de 50 dígitos en la esquina inferior derecha, con tamaño mínimo de 2.5 cm conforme a la normativa.

Disponibilidad:

• Solo comprobantes que ya pasaron la firma (estado ≠ draft).
• El contribuyente debe tener al menos una plantilla PDF activa marcada como default.
• El PDF permanece disponible incluso si el XML fue purgado — los metadatos y totales nunca se eliminan.

Para gestionar plantillas PDF personalizadas, vea el grupo Plantillas PDF de esta documentación.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/pdf?template_id=16" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/pdf"
);

const params = {
    "template_id": "16",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/50619032600310199999900100001010000000001112345678/pdf';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'template_id' => '16',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

[archivo binario application/pdf]
 

{
    "success": false,
    "data": null,
    "message": "El PDF no está disponible. El comprobante está en estado 'draft'.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "El contribuyente no tiene plantilla PDF default activa.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Comprobantes / Borradores

Listar borradores del contribuyente

requires authentication

Devuelve los borradores del wizard de emisión guardados por el contribuyente, ordenados del más reciente al más antiguo (por fecha de última actualización). Un borrador es el estado parcial de un comprobante en construcción; no es un comprobante fiscal ni consume consecutivo.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/drafts?per_page=15&page=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts"
);

const params = {
    "per_page": "15",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/drafts';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'per_page' => '15',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": [
        {
            "id": "019d867d-aaaa-7288-8ece-fd64da756001",
            "voucher_type": "01",
            "payload": {
                "client_id": null,
                "line_items": [],
                "currency_code": "CRC"
            },
            "totals_preview": {
                "currency_code": "CRC",
                "line_count": 0,
                "total_venta": "0.00000",
                "total_descuento": "0.00000",
                "total_gravado": "0.00000",
                "total_exento": "0.00000",
                "total_venta_neta": "0.00000",
                "total_impuesto": "0.00000",
                "total_otros_cargos": "0.00000",
                "total_comprobante": "0.00000"
            },
            "comments": "Esperando datos del cliente.",
            "validation": null,
            "created_at": "2026-04-16T10:00:00-06:00",
            "updated_at": "2026-04-16T10:30:00-06:00"
        }
    ],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 1,
        "from": 1,
        "to": 1
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": null
    }
}
 

{
    "success": true,
    "data": [],
    "message": "",
    "errors": null,
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 0,
        "from": null,
        "to": null
    },
    "links": {
        "first": "...",
        "last": "...",
        "prev": null,
        "next": null
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Crear un borrador

requires authentication

Guarda el estado parcial del wizard. NO consume consecutivo. Devuelve la validación en vivo (errores condicionales + preview de totales).

El payload es el cuerpo PARCIAL del comprobante (mismo contrato que POST /vouchers, pero puede estar incompleto entre pasos del wizard).

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"voucher_type\": \"01\",
    \"payload\": {
        \"client_id\": null,
        \"line_items\": [],
        \"currency_code\": \"CRC\"
    },
    \"comments\": \"Esperando datos del cliente.\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "voucher_type": "01",
    "payload": {
        "client_id": null,
        "line_items": [],
        "currency_code": "CRC"
    },
    "comments": "Esperando datos del cliente."
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/drafts';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'voucher_type' => '01',
            'payload' => [
                'client_id' => null,
                'line_items' => [],
                'currency_code' => 'CRC',
            ],
            'comments' => 'Esperando datos del cliente.',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-aaaa-7288-8ece-fd64da756001",
        "voucher_type": "01",
        "payload": {
            "client_id": null,
            "line_items": [],
            "currency_code": "CRC"
        },
        "totals_preview": {
            "currency_code": "CRC",
            "line_count": 0,
            "total_venta": "0.00000",
            "total_descuento": "0.00000",
            "total_gravado": "0.00000",
            "total_exento": "0.00000",
            "total_venta_neta": "0.00000",
            "total_impuesto": "0.00000",
            "total_otros_cargos": "0.00000",
            "total_comprobante": "0.00000"
        },
        "comments": "Esperando datos del cliente.",
        "validation": {
            "valid": false,
            "errors": {
                "line_items": [
                    "Agregá al menos una línea de detalle."
                ],
                "sale_condition": [
                    "Indicá la condición de venta."
                ]
            },
            "totals": {
                "currency_code": "CRC",
                "line_count": 0,
                "total_comprobante": "0.00000"
            }
        },
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Borrador guardado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "payload": [
            "El cuerpo del borrador (payload) es obligatorio."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Consultar un borrador (con validación en vivo)

requires authentication

Devuelve el detalle del borrador indicado, recalculando en el momento la validación en vivo (errores condicionales + preview de totales) sin persistirla. Solo se retornan borradores que pertenecen a su contribuyente. Un id que no sea un UUID válido retorna 404.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-aaaa-7288-8ece-fd64da756001",
        "voucher_type": "01",
        "payload": {
            "client_id": null,
            "line_items": [],
            "currency_code": "CRC"
        },
        "totals_preview": {
            "currency_code": "CRC",
            "line_count": 0,
            "total_comprobante": "0.00000"
        },
        "comments": "Esperando datos del cliente.",
        "validation": {
            "valid": false,
            "errors": {
                "line_items": [
                    "Agregá al menos una línea de detalle."
                ]
            },
            "totals": {
                "currency_code": "CRC",
                "line_count": 0,
                "total_comprobante": "0.00000"
            }
        },
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T10:30:00-06:00"
    },
    "message": "",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Guardar un paso del wizard (actualización del borrador)

requires authentication

Reemplaza el estado del borrador con lo enviado (voucher_type, payload y comments) y vuelve a calcular la validación en vivo (errores condicionales + preview de totales), persistiendo el preview. NO consume consecutivo ni firma. Un id que no sea un UUID válido retorna 404.

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"voucher_type\": \"01\",
    \"payload\": {
        \"client_id\": \"019d867d-0001-7288-8ece-fd64da756001\",
        \"sale_condition\": \"01\",
        \"line_items\": [
            {
                \"quantity\": 1,
                \"unit_price\": 1000
            }
        ]
    },
    \"comments\": \"Listo para emitir.\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "voucher_type": "01",
    "payload": {
        "client_id": "019d867d-0001-7288-8ece-fd64da756001",
        "sale_condition": "01",
        "line_items": [
            {
                "quantity": 1,
                "unit_price": 1000
            }
        ]
    },
    "comments": "Listo para emitir."
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'voucher_type' => '01',
            'payload' => [
                'client_id' => '019d867d-0001-7288-8ece-fd64da756001',
                'sale_condition' => '01',
                'line_items' => [
                    [
                        'quantity' => 1,
                        'unit_price' => 1000,
                    ],
                ],
            ],
            'comments' => 'Listo para emitir.',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-aaaa-7288-8ece-fd64da756001",
        "voucher_type": "01",
        "payload": {
            "client_id": "019d867d-0001-7288-8ece-fd64da756001",
            "sale_condition": "01",
            "line_items": [
                {
                    "quantity": 1,
                    "unit_price": 1000
                }
            ]
        },
        "totals_preview": {
            "currency_code": "CRC",
            "line_count": 1,
            "total_venta": "1000.00000",
            "total_descuento": "0.00000",
            "total_gravado": "1000.00000",
            "total_exento": "0.00000",
            "total_venta_neta": "1000.00000",
            "total_impuesto": "130.00000",
            "total_otros_cargos": "0.00000",
            "total_comprobante": "1130.00000"
        },
        "comments": "Listo para emitir.",
        "validation": {
            "valid": true,
            "errors": [],
            "totals": {
                "currency_code": "CRC",
                "line_count": 1,
                "total_comprobante": "1130.00000"
            }
        },
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T11:00:00-06:00"
    },
    "message": "Borrador actualizado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "payload": [
            "El cuerpo del borrador (payload) es obligatorio."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Emitir el comprobante a partir del borrador

requires authentication

Valida en seco (reglas condicionales); si pasa, reproduce el pipeline real de POST /vouchers (consume consecutivo, firma, valida XSD, encola el envío a Hacienda) y ELIMINA el borrador al tener éxito.

No recibe cuerpo: emite a partir del payload ya guardado en el borrador. La respuesta es liviana (no serializa el comprobante completo); el detalle se consulta en GET /vouchers/{key}. Un id que no sea un UUID válido retorna 404.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001/issue" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001/issue"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001/issue';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-bbbb-7288-8ece-fd64da756999",
        "voucher_key": "50624062600310112345600100001010000000001100000001",
        "voucher_type": "01",
        "consecutive_number": "00100001010000000001",
        "status": "pending"
    },
    "message": "Comprobante emitido.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "El borrador tiene datos incompletos para emitir.",
    "errors": {
        "line_items": [
            "Agregá al menos una línea de detalle."
        ],
        "sale_condition": [
            "Indicá la condición de venta."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "El comprobante no cumple el esquema oficial (XSD).",
    "errors": {
        "xsd": [
            "El elemento 'CodigoMoneda' no es válido."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "La sucursal/terminal indicada no existe.",
    "errors": {
        "terminal_code": [
            "Créela primero en Sucursales y terminales."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Descartar un borrador

requires authentication

Elimina el borrador indicado. No afecta a comprobantes ya emitidos (el borrador no es un comprobante fiscal). Un id que no sea un UUID válido retorna 404.

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/vouchers/drafts/019d867d-aaaa-7288-8ece-fd64da756001';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": null,
    "message": "Borrador descartado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Perfil

Estadísticas de uso mensual.

requires authentication

Retorna los conteos de comprobantes emitidos y emails enviados durante el período mensual en curso, junto con los límites de su plan.

Solo cuenta comprobantes de producción aceptados por Hacienda. Los comprobantes emitidos en sandbox no consumen el límite del plan.

Si es integrador, el conteo agrega automáticamente los comprobantes propios y los de todos sus clientes gestionados, permitiendo monitorear el consumo total del plan en una sola consulta.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/profile/usage" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/profile/usage"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/profile/usage';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "vouchers_this_month": 87,
        "vouchers_limit": 500,
        "vouchers_remaining": 413,
        "vouchers_percentage": 17.4,
        "emails_this_month": 340,
        "emails_limit": 2250,
        "period_start": "2026-04-01",
        "period_end": "2026-04-30"
    },
    "message": "Estadísticas de uso mensual.",
    "errors": null
}
 

{
    "success": true,
    "data": {
        "vouchers_this_month": 12450,
        "vouchers_limit": 50000,
        "vouchers_remaining": 37550,
        "vouchers_percentage": 24.9,
        "emails_this_month": 0,
        "emails_limit": 5000,
        "period_start": "2026-04-01",
        "period_end": "2026-04-30"
    },
    "message": "Estadísticas de uso mensual.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Consultar perfil completo del contribuyente autenticado.

requires authentication

Retorna todos los datos del contribuyente incluyendo el plan activo con sus limites y features, las actividades economicas registradas, la ubicacion y la configuracion de contacto.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/profile" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/profile"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/profile';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-0241-7288-8ece-fd64da75616d",
        "legal_name": "Empresa Ejemplo S.A.",
        "trade_name": "Ejemplo Shop",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101999999",
        "emails": [
            "facturacion@empresa.cr"
        ],
        "economic_activities": [
            "6201.0"
        ],
        "location": {
            "province": 1,
            "canton": 1,
            "district": 1
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "is_active": true,
        "production_enabled": false,
        "hacienda_environment": "sandbox",
        "plan_id": "019d0001-0000-0000-0000-000000000001",
        "is_managed": false,
        "is_integrator": false,
        "plan": {
            "id": "019d0001-0000-0000-0000-000000000001",
            "code": "pyme",
            "name": "Pyme",
            "description": "Automatice su facturación con hasta 500 comprobantes/mes.",
            "monthly_price_usd": null,
            "annual_price_usd": 96,
            "billing_mode": "annual_only",
            "annual_discount_percent": 0,
            "vouchers_per_month": 500,
            "overage_price_per_voucher": 0.03,
            "max_users": 3,
            "max_api_tokens": 2,
            "max_clients": 300,
            "max_items": 750,
            "max_pdf_templates": 1,
            "max_monthly_emails": 2250,
            "max_webhook_endpoints": 1,
            "max_branch_terminals": 2,
            "max_managed_contributors": 1,
            "api_rate_limit_per_minute": 20,
            "retention_months": 3,
            "extended_retention_eligible": true,
            "pdf_branding": "platform",
            "api_write_enabled": true,
            "api_readonly_enabled": false,
            "sandbox_access": true,
            "webhooks_enabled": false,
            "multi_contributor": false,
            "receiver_module": true,
            "bulk_emission": false,
            "sla_support": false
        },
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-13T14:30:00-06:00"
    },
    "message": "Perfil del contribuyente.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Actualizar datos editables del perfil del contribuyente.

requires authentication

Soporta actualizacion parcial: envie unicamente los campos que desea modificar. Los campos no incluidos en el payload conservan su valor actual.

Campos editables: id_number, legal_name, trade_name, emails, economic_activities, phone, phone_country_code, province, canton, district, neighborhood, address.

Campos inmutables (no se pueden cambiar desde este endpoint): id_type (tipo de identificacion), el plan activo, production_enabled (autorización DGT | gestionada por super_admin tras verificar firma BCCR y cumplimiento normativo) y el estado activo/inactivo de la cuenta.

La configuracion de email transaccional se gestiona desde su propio endpoint: PUT /email-settings.

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/profile" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"id_number\": \"3101999999\",
    \"id_type\": 2,
    \"hacienda_confirmed\": true,
    \"legal_name\": \"Empresa Ejemplo S.A.\",
    \"trade_name\": \"Ejemplo Tienda\",
    \"emails\": [
        \"facturacion@empresa.cr\"
    ],
    \"economic_activities\": [
        \"6201.0\"
    ],
    \"phone\": \"22001234\",
    \"phone_country_code\": 506,
    \"province\": 1,
    \"canton\": 1,
    \"district\": 1,
    \"neighborhood\": \"San Pedro\",
    \"address\": \"200 metros norte del parque central\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/profile"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "id_number": "3101999999",
    "id_type": 2,
    "hacienda_confirmed": true,
    "legal_name": "Empresa Ejemplo S.A.",
    "trade_name": "Ejemplo Tienda",
    "emails": [
        "facturacion@empresa.cr"
    ],
    "economic_activities": [
        "6201.0"
    ],
    "phone": "22001234",
    "phone_country_code": 506,
    "province": 1,
    "canton": 1,
    "district": 1,
    "neighborhood": "San Pedro",
    "address": "200 metros norte del parque central"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/profile';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'id_number' => '3101999999',
            'id_type' => 2,
            'hacienda_confirmed' => true,
            'legal_name' => 'Empresa Ejemplo S.A.',
            'trade_name' => 'Ejemplo Tienda',
            'emails' => [
                'facturacion@empresa.cr',
            ],
            'economic_activities' => [
                '6201.0',
            ],
            'phone' => '22001234',
            'phone_country_code' => 506,
            'province' => 1,
            'canton' => 1,
            'district' => 1,
            'neighborhood' => 'San Pedro',
            'address' => '200 metros norte del parque central',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-0241-7288-8ece-fd64da75616d",
        "legal_name": "Empresa Ejemplo S.A. Actualizada",
        "trade_name": "Ejemplo Shop Nuevo",
        "id_type": "02",
        "id_type_label": "Cédula Jurídica",
        "id_number": "3101999999",
        "emails": [
            "facturacion@empresa.cr",
            "contabilidad@empresa.cr"
        ],
        "economic_activities": [
            "6201.0",
            "4711.0"
        ],
        "location": {
            "province": 1,
            "canton": 1,
            "district": 1
        },
        "neighborhood": "San Pedro",
        "address": "200 metros norte del parque central",
        "phone": {
            "country_code": 506,
            "number": "22001234"
        },
        "is_active": true,
        "production_enabled": false,
        "hacienda_environment": "sandbox",
        "plan_id": "019d0001-0000-0000-0000-000000000001",
        "is_managed": false,
        "is_integrator": false,
        "plan": {
            "id": "019d0001-0000-0000-0000-000000000001",
            "code": "pyme",
            "name": "Pyme",
            "vouchers_per_month": 500,
            "max_clients": 300,
            "sandbox_access": true
        },
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T09:15:00-06:00"
    },
    "message": "Perfil actualizado correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "emails.0": [
            "El campo emails.0 debe ser un correo electrónico válido."
        ],
        "economic_activities.0": [
            "El formato del código de actividad económica debe ser XXXX.X (ejemplo: 6201.0)."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Usuarios de la Cuenta

Listar usuarios del contribuyente

requires authentication

Devuelve todos los usuarios (cuentas de login) asociados al contribuyente activo: los activos, los que están pendientes de establecer su contraseña y los desactivados. Los usuarios cuyo acceso fue revocado no aparecen.

Cada usuario es una cuenta de login (nombre + correo + rol), sin cédula | la cédula vive en el contribuyente, no en el usuario.

Solo el owner o un admin del contribuyente pueden consultar esta lista. Otros roles reciben HTTP 403.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/users" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/users"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/users';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": [
        {
            "id": "019d867d-0001-7288-8ece-fd64da756001",
            "name": "Ana Propietaria",
            "email": "ana@empresa.cr",
            "role": "owner",
            "is_active": true,
            "is_owner": true,
            "status": "active",
            "created_at": "2026-04-01T10:00:00-06:00"
        },
        {
            "id": "019d867d-0002-7288-8ece-fd64da756002",
            "name": "María Pérez",
            "email": "maria@empresa.cr",
            "role": "cashier",
            "is_active": true,
            "is_owner": false,
            "status": "pending",
            "created_at": "2026-04-10T14:30:00-06:00"
        }
    ],
    "message": "",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No tenés permisos para gestionar usuarios.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Invitar un usuario

requires authentication

Crea una cuenta de login (sin cédula) y la asocia al contribuyente activo. El usuario recibe un correo con un enlace para establecer su contraseña; mientras tanto queda en estado pending.

Reglas:

• El email debe ser único en toda la plataforma. Si ya existe un usuario con ese correo, responde HTTP 422.
• El role no puede ser owner; solo se admiten admin, accountant, cashier, viewer o api_user.

Solo el owner o un admin pueden invitar usuarios. Otros roles reciben HTTP 403.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/users" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"María Pérez\",
    \"email\": \"maria@empresa.cr\",
    \"role\": \"cashier\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/users"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "María Pérez",
    "email": "maria@empresa.cr",
    "role": "cashier"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/users';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'María Pérez',
            'email' => 'maria@empresa.cr',
            'role' => 'cashier',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-0002-7288-8ece-fd64da756002",
        "name": "María Pérez",
        "email": "maria@empresa.cr",
        "role": "cashier",
        "is_active": true,
        "is_owner": false,
        "status": "pending",
        "created_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Usuario invitado. Recibirá un correo para establecer su contraseña.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No tenés permisos para gestionar usuarios.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "email": [
            "Ya existe un usuario con ese correo."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "role": [
            "El rol seleccionado no es válido."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Editar un usuario

requires authentication

Permite cambiar el rol y/o el estado (activar / desactivar) de un usuario del contribuyente. Admite actualización parcial | envíe solo los campos que desea modificar.

Acción sensible: cambiar el estado is_active requiere enviar el campo password con la contraseña del usuario que opera. Si falta o es incorrecta, responde HTTP 401.

Al activar un usuario se respeta el max_users del plan: si ya se alcanzó el límite de usuarios activos, responde HTTP 422.

El propietario de la cuenta no puede modificarse (HTTP 403), y el rol owner no puede asignarse desde aquí. Solo el owner o un admin pueden editar usuarios.

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/users/019d867d-0002-7288-8ece-fd64da756002" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"role\": \"viewer\",
    \"is_active\": true,
    \"password\": \"MiClaveSegura123\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/users/019d867d-0002-7288-8ece-fd64da756002"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "role": "viewer",
    "is_active": true,
    "password": "MiClaveSegura123"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/users/019d867d-0002-7288-8ece-fd64da756002';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'role' => 'viewer',
            'is_active' => true,
            'password' => 'MiClaveSegura123',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-0002-7288-8ece-fd64da756002",
        "name": "María Pérez",
        "email": "maria@empresa.cr",
        "role": "viewer",
        "is_active": true,
        "is_owner": false,
        "status": "active",
        "created_at": "2026-04-10T14:30:00-06:00"
    },
    "message": "Usuario actualizado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Contraseña incorrecta.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No tenés permisos para gestionar usuarios.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No se puede modificar al propietario de la cuenta.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Usuario no encontrado en este contribuyente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Alcanzaste el límite de usuarios activos de tu plan (3).",
    "errors": {
        "is_active": [
            "Desactivá otro usuario o cambiá de plan."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Revocar el acceso de un usuario

requires authentication

Desvincula al usuario del contribuyente activo, liberando su asiento del plan. La cuenta de login global del usuario no se elimina: sigue viva para que pueda asociarse a otro contribuyente o facturar por su cuenta. Simplemente deja de pertenecer a esta cuenta y desaparece del listado.

Acción sensible: requiere enviar el campo password con la contraseña del usuario que opera. Si falta o es incorrecta, responde HTTP 401.

No puede revocar su propio acceso ni el del propietario de la cuenta (ambos casos responden HTTP 403). Solo el owner o un admin pueden revocar usuarios.

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/users/019d867d-0002-7288-8ece-fd64da756002" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"password\": \"MiClaveSegura123\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/users/019d867d-0002-7288-8ece-fd64da756002"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "password": "MiClaveSegura123"
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/users/019d867d-0002-7288-8ece-fd64da756002';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'password' => 'MiClaveSegura123',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": null,
    "message": "Usuario desvinculado de esta cuenta.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Contraseña incorrecta.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No tenés permisos para gestionar usuarios.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No podés revocar tu propio acceso.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No se puede revocar al propietario de la cuenta.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Usuario no encontrado en este contribuyente.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Cambio de Contribuyente

Listar contribuyentes accesibles

requires authentication

Devuelve los contribuyentes a los que el usuario autenticado tiene acceso operativo (pivote user_contributors activo y aceptado), por ejemplo como dueño de su propia empresa o como contador de varios clientes. Solo se incluyen los contribuyentes que estén activos.

El campo is_current indica cuál de ellos es el contribuyente activo de la sesión (el que lee el middleware multi-tenant). Use el endpoint POST /switch-contributor para cambiarlo.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/my-access-contributors" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/my-access-contributors"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/my-access-contributors';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": [
        {
            "contributor_id": "019d867d-0001-7288-8ece-fd64da756001",
            "legal_name": "EMPRESA EJEMPLO S.A.",
            "id_number": "3101123456",
            "role": "owner",
            "is_current": true
        },
        {
            "contributor_id": "019d867d-0002-7288-8ece-fd64da756002",
            "legal_name": "CLIENTE CONTABLE S.A.",
            "id_number": "3101987654",
            "role": "accountant",
            "is_current": false
        }
    ],
    "message": "",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Cambiar el contribuyente activo

requires authentication

Cambia el contribuyente activo de la sesión del usuario autenticado. El usuario debe tener acceso operativo (pivote user_contributors activo y aceptado) al contribuyente destino, y este debe estar activo. El mismo token sigue siendo válido tras el cambio.

Si el usuario no tiene acceso al contribuyente indicado, responde HTTP 403. Si el contribuyente no existe o está inactivo, responde HTTP 404.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/switch-contributor" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"contributor_id\": \"019d867d-0002-7288-8ece-fd64da756002\"
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/switch-contributor"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "contributor_id": "019d867d-0002-7288-8ece-fd64da756002"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/switch-contributor';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'contributor_id' => '019d867d-0002-7288-8ece-fd64da756002',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "contributor_id": "019d867d-0002-7288-8ece-fd64da756002",
        "legal_name": "CLIENTE CONTABLE S.A.",
        "role": "accountant"
    },
    "message": "Contribuyente activo cambiado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No tenés acceso a ese contribuyente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "El contribuyente no existe o está inactivo.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "contributor_id": [
            "El campo contributor id es obligatorio."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Certificados Digitales

Listar certificados digitales del contribuyente

requires authentication

Devuelve el historial completo de certificados digitales registrados por el contribuyente: el certificado actualmente activo y todos los que fueron desactivados previamente (conservados para auditoría).

Los datos sensibles del certificado (contenido del archivo .p12, contraseña y PIN de Hacienda) nunca se incluyen en la respuesta, incluso si usted mismo los cargó.

Cada registro incluye:

• Ambiente (sandbox / production).
• Estado (is_active) y fecha de desactivación si aplica.
• Vigencia del certificado (valid_from, valid_until).
• Días restantes hasta la expiración (days_remaining) | útil para monitorear renovación.
• Subject del certificado X.509 (nombre del titular).
• Número de serie del certificado.

Ordenamiento: el más reciente primero.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/certificates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": [],
    "message": "",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Consultar disponibilidad de subida de certificado por ambiente

requires authentication

Indica para cada ambiente (sandbox, production) si está disponible para subir un certificado nuevo o si ya hay uno activo que debe desactivarse primero.

Útil para mostrar el formulario de subida con el selector de ambiente correctamente deshabilitado, evitando que el usuario intente subir un .p12 que sería rechazado con HTTP 422.

Reglas:

• available = true → no hay certificado activo en ese ambiente, se puede subir uno nuevo.
• available = false → ya hay certificado activo. Para subir uno nuevo en este ambiente debe desactivar el actual con DELETE /api/v1/public/certificates/{id}.

Cuando available = false, el campo active_certificate incluye los datos del certificado vigente para que el frontend pueda mostrar al usuario qué cert está bloqueando el upload.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/certificates/availability" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates/availability"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates/availability';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "sandbox": {
            "available": true,
            "active_certificate": null
        },
        "production": {
            "available": false,
            "active_certificate": {
                "id": "019d867d-1111-7288-8ece-fd64da756001",
                "certificate_serial": "019DD6D90F43",
                "certificate_subject": "CN=ALBERT MENDEZ, serialNumber=CPF-02-0627-0652",
                "valid_from": "2025-12-15T10:30:00-06:00",
                "valid_until": "2027-12-15T10:30:00-06:00",
                "days_remaining": 596,
                "is_expired": false,
                "created_at": "2026-04-15T08:00:00-06:00"
            }
        }
    },
    "message": "",
    "errors": null
}
 

{
    "success": true,
    "data": {
        "sandbox": {
            "available": true,
            "active_certificate": null
        },
        "production": {
            "available": true,
            "active_certificate": null
        }
    },
    "message": "",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Subir y activar un certificado digital `.p12`

requires authentication

Sube un archivo .p12 (PKCS#12) con su contraseña y la contraseña del IdP de Hacienda, y lo activa como certificado para firmar comprobantes en el ambiente indicado.

Este request debe enviarse como multipart/form-data (no JSON), porque incluye un archivo binario.

Validaciones que se ejecutan ANTES de guardar:

1. Disponibilidad del ambiente: solo puede subir cert si NO hay uno activo en ese ambiente. Si ya hay uno, debe desactivarlo primero con DELETE /certificates/{id} o usar el endpoint GET /certificates/availability para chequear estado.
2. PIN del .p12: el archivo debe abrirse con la contraseña provista en p12_password.
3. Llave privada RSA: el .p12 debe contener una llave RSA válida (Hacienda CR exige RSA-SHA256 para XAdES-EPES).
4. Subject del certificado: el cert debe pertenecer al contribuyente que lo está subiendo (anti-fraude | REGLAMENTO art. 16).
5. Vigencia del certificado: el X.509 no puede estar vencido ni ser prematuro.
6. Credenciales IdP de Hacienda: el hacienda_pin debe autenticar correctamente contra el IdP del ambiente solicitado (POST grant_type=password). Si falla, el cert NO se guarda | sería inutilizable sin token OAuth2 válido.

Si CUALQUIERA de las 6 validaciones falla, se retorna HTTP 422 (o 503 si el IdP de Hacienda no responde) y NADA se guarda en DB.

Ejemplo con curl:

curl -X POST https://api.almendro.cr/api/v1/public/certificates \
  -H "Authorization: Bearer {su_token}" \
  -F "p12_file=@/ruta/a/certificado.p12" \
  -F "p12_password=PIN-del-archivo-p12" \
  -F "hacienda_pin=Contraseña-del-IdP-de-Hacienda" \
  -F "environment=sandbox"

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/certificates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "p12_password=architecto"\
    --form "hacienda_pin=architecto"\
    --form "environment=architecto"\
    --form "p12_file=@/tmp/phpbon97l1emqj1dgYHhsD" 

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('p12_password', 'architecto');
body.append('hacienda_pin', 'architecto');
body.append('environment', 'architecto');
body.append('p12_file', document.querySelector('input[name="p12_file"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'p12_password',
                'contents' => 'architecto'
            ],
            [
                'name' => 'hacienda_pin',
                'contents' => 'architecto'
            ],
            [
                'name' => 'environment',
                'contents' => 'architecto'
            ],
            [
                'name' => 'p12_file',
                'contents' => fopen('/tmp/phpbon97l1emqj1dgYHhsD', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": "019d867d-1111-7288-8ece-fd64da756001",
        "environment": "sandbox",
        "is_active": true,
        "is_expired": false,
        "days_remaining": 596,
        "valid_from": "2025-12-15T10:30:00-06:00",
        "valid_until": "2027-12-15T10:30:00-06:00",
        "certificate_subject": "CN=ALBERT MENDEZ, serialNumber=CPF-02-0627-0652",
        "certificate_serial": "019DD6C62577",
        "created_at": "2026-04-29T08:00:00-06:00"
    },
    "message": "Certificado registrado y activado correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "El PIN del archivo .p12 es incorrecto, el archivo está corrupto, o no es un PKCS#12 válido emitido por el BCCR. ...",
    "errors": {
        "p12_password": [
            "El PIN del archivo .p12 es incorrecto, ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "El certificado .p12 NO pertenece a este contribuyente. ...",
    "errors": {
        "p12_file": [
            "El certificado .p12 NO pertenece a este contribuyente. ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "El IdP de Hacienda rechazó las credenciales con HTTP 401. ...",
    "errors": {
        "hacienda_pin": [
            "El IdP de Hacienda rechazó las credenciales con HTTP 401. ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Ya existe un certificado activo en el ambiente 'sandbox'. ...",
    "errors": {
        "environment": [
            "Ya existe un certificado activo en el ambiente 'sandbox'. ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "El certificado .p12 pertenece al ambiente de sandbox (pruebas) pero usted lo está subiendo como producción. ...",
    "errors": {
        "p12_file": [
            "El certificado .p12 pertenece al ambiente de sandbox (pruebas) pero usted lo está subiendo como producción. ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "No es posible validar el certificado porque el contribuyente todavía no tiene registrada su identificación (tipo y número de cédula) en el perfil. ...",
    "errors": {
        "p12_file": [
            "No es posible validar el certificado porque el contribuyente todavía no tiene registrada su identificación ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "El certificado del contribuyente '...' no está vigente. ...",
    "errors": {
        "p12_file": [
            "El certificado del contribuyente '...' no está vigente. ..."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "El IdP de Hacienda no responde temporalmente. Intente nuevamente en unos minutos.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Desactivar un certificado digital

requires authentication

Marca el certificado como inactivo. El registro no se elimina: permanece en el histórico para auditoría de todas las firmas realizadas durante su vigencia.

Consecuencias inmediatas:

• Si el certificado desactivado era el activo de su ambiente, la emisión en ese ambiente queda bloqueada hasta que suba un nuevo certificado activo.
• Si algún integrador tenía acceso delegado a este certificado, el acceso se revoca automáticamente y se le envía una notificación.
• El conteo de accesos revocados aparece en el message de la respuesta.

Solo puede desactivar certificados propios. Si el UUID no corresponde a su contribuyente, retorna 404.

Casos típicos para desactivar:

• El certificado fue comprometido (pérdida, acceso no autorizado).
• Va a subir un certificado nuevo (debe desactivar el vigente primero | el sistema no permite dos activos en el mismo ambiente).
• Migración de un contribuyente a otra plataforma.

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/certificates/019d867d-1111-7288-8ece-fd64da756001" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/certificates/019d867d-1111-7288-8ece-fd64da756001"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/certificates/019d867d-1111-7288-8ece-fd64da756001';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": null,
    "message": "Certificado desactivado correctamente.",
    "errors": null
}
 

{
    "success": true,
    "data": null,
    "message": "Certificado desactivado correctamente. Se revocaron 2 accesos de integradores asociados.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Certificado no encontrado.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Plantillas PDF

Listar plantillas PDF del contribuyente

requires authentication

Devuelve todas las plantillas PDF activas del contribuyente, ordenadas con la plantilla por defecto primero (is_default=true) y luego por nombre alfabéticamente.

Este endpoint no pagina | el número de plantillas por contribuyente es pequeño (límite por plan entre 1 y 15), por lo que siempre se devuelve la lista completa.

Cada plantilla incluye su configuración completa (config_json) con colores, fuentes, layout y parámetros del QR, además de un flag has_logo que indica si tiene un logo cargado.

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/pdf-templates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Classic",
            "is_default": true,
            "paper_size": "letter",
            "config_json": {
                "colors": {
                    "primary": "#2d3748",
                    "secondary": "#4a5568",
                    "accent": "#3182ce"
                },
                "fonts": {
                    "family": "Helvetica",
                    "size_header": 14,
                    "size_body": 9
                },
                "layout": {
                    "show_logo": true,
                    "logo_position": "left",
                    "logo_max_height": 60
                },
                "qr": {
                    "enabled": true,
                    "size": 100,
                    "position": "bottom-right"
                }
            },
            "has_logo": true,
            "is_active": true,
            "created_at": "2026-04-01T10:00:00-06:00",
            "updated_at": "2026-04-10T14:30:00-06:00"
        },
        {
            "id": 2,
            "name": "Minimal",
            "is_default": false,
            "paper_size": "A4",
            "config_json": {
                "colors": {
                    "primary": "#000000",
                    "secondary": "#666666",
                    "accent": "#000000"
                },
                "fonts": {
                    "family": "Helvetica",
                    "size_header": 12,
                    "size_body": 8
                },
                "layout": {
                    "show_logo": false,
                    "logo_position": "left",
                    "logo_max_height": 60
                },
                "qr": {
                    "enabled": true,
                    "size": 80,
                    "position": "bottom-right"
                }
            },
            "has_logo": false,
            "is_active": true,
            "created_at": "2026-04-05T08:00:00-06:00",
            "updated_at": "2026-04-05T08:00:00-06:00"
        }
    ],
    "message": "",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Unauthenticated.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Crear una nueva plantilla PDF

requires authentication

Registra una plantilla personalizada en el catálogo del contribuyente. Si envía is_default: true, la plantilla default anterior se desmarca automáticamente.

Si no envía config_json, se aplica una configuración por defecto que cumple con todos los requisitos normativos (QR mínimo 2.5 cm en la esquina inferior derecha).

Si envía config_json, puede enviar un objeto parcial | las claves no enviadas usan los valores del template default.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/pdf-templates" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Mi Plantilla Corporativa\",
    \"is_default\": false,
    \"paper_size\": \"letter\",
    \"config_json\": {
        \"colors\": {
            \"primary\": \"#0a66c2\",
            \"secondary\": \"#333333\",
            \"accent\": \"#0a66c2\"
        },
        \"fonts\": {
            \"family\": \"Helvetica\",
            \"size_header\": 14,
            \"size_body\": 9
        },
        \"layout\": {
            \"show_logo\": true,
            \"logo_position\": \"left\",
            \"logo_max_height\": 60
        },
        \"qr\": {
            \"enabled\": true,
            \"size\": 100,
            \"position\": \"bottom-right\"
        },
        \"margins\": {
            \"top\": 15,
            \"right\": 15,
            \"bottom\": 15,
            \"left\": 15
        },
        \"style\": \"classic\",
        \"footer_text\": \"Documento generado electrónicamente | Almendro Factura Electrónica\"
    }
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Mi Plantilla Corporativa",
    "is_default": false,
    "paper_size": "letter",
    "config_json": {
        "colors": {
            "primary": "#0a66c2",
            "secondary": "#333333",
            "accent": "#0a66c2"
        },
        "fonts": {
            "family": "Helvetica",
            "size_header": 14,
            "size_body": 9
        },
        "layout": {
            "show_logo": true,
            "logo_position": "left",
            "logo_max_height": 60
        },
        "qr": {
            "enabled": true,
            "size": 100,
            "position": "bottom-right"
        },
        "margins": {
            "top": 15,
            "right": 15,
            "bottom": 15,
            "left": 15
        },
        "style": "classic",
        "footer_text": "Documento generado electrónicamente | Almendro Factura Electrónica"
    }
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Mi Plantilla Corporativa',
            'is_default' => false,
            'paper_size' => 'letter',
            'config_json' => [
                'colors' => [
                    'primary' => '#0a66c2',
                    'secondary' => '#333333',
                    'accent' => '#0a66c2',
                ],
                'fonts' => [
                    'family' => 'Helvetica',
                    'size_header' => 14,
                    'size_body' => 9,
                ],
                'layout' => [
                    'show_logo' => true,
                    'logo_position' => 'left',
                    'logo_max_height' => 60,
                ],
                'qr' => [
                    'enabled' => true,
                    'size' => 100,
                    'position' => 'bottom-right',
                ],
                'margins' => [
                    'top' => 15,
                    'right' => 15,
                    'bottom' => 15,
                    'left' => 15,
                ],
                'style' => 'classic',
                'footer_text' => 'Documento generado electrónicamente | Almendro Factura Electrónica',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": 3,
        "name": "Mi Plantilla Corporativa",
        "is_default": false,
        "paper_size": "letter",
        "config_json": {
            "colors": {
                "primary": "#0a66c2",
                "secondary": "#333333",
                "accent": "#0a66c2"
            },
            "fonts": {
                "family": "Helvetica",
                "size_header": 14,
                "size_body": 9
            },
            "layout": {
                "show_logo": true,
                "logo_position": "left",
                "logo_max_height": 60
            },
            "qr": {
                "enabled": true,
                "size": 100,
                "position": "bottom-right"
            }
        },
        "has_logo": false,
        "is_active": true,
        "created_at": "2026-04-16T10:00:00-06:00",
        "updated_at": "2026-04-16T10:00:00-06:00"
    },
    "message": "Plantilla creada correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "name": [
            "Ya existe una plantilla con este nombre para el contribuyente."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "config_json.colors.primary": [
            "El color debe ser un hexadecimal válido (ej. #1a365d)."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "config_json.qr.size": [
            "El tamaño mínimo del QR es 70 pt (≈ 2.5 cm) por normativa."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "plan": [
            "Ha alcanzado el límite de plantillas PDF de su plan. Actualice a un plan superior."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Response

Response Fields

Editar una plantilla PDF existente

requires authentication

Admite actualización parcial | envíe únicamente los campos que desea modificar. Los campos no enviados conservan su valor actual.

El campo config_json se fusiona con la configuración existente (merge profundo): las claves que envíe se actualizan y las que no envíe se mantienen intactas. Esto permite cambiar, por ejemplo, solo los colores sin afectar fuentes, layout o QR.

Si envía is_default: true y la plantilla no era la default, la default anterior se desmarca automáticamente.

Importante: editar una plantilla no afecta a los PDFs ya generados con ella. Los PDFs se congelan con la configuración vigente al momento de la emisión (inmutabilidad post-emisión).

curl --request PUT \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Profesional Actualizada\",
    \"is_default\": true,
    \"is_active\": true,
    \"paper_size\": \"letter\",
    \"config_json\": {
        \"colors\": {
            \"primary\": \"#1a365d\",
            \"secondary\": \"#4a5568\",
            \"text\": \"#2815Df\",
            \"accent\": \"#3182ce\",
            \"muted\": \"#2815Df\"
        },
        \"fonts\": {
            \"family\": \"Helvetica\",
            \"size_header\": 14,
            \"size_body\": 9,
            \"size_footer\": 7
        },
        \"layout\": {
            \"show_logo\": true,
            \"logo_position\": \"left\",
            \"logo_max_height\": 60,
            \"show_commercial_name\": true,
            \"show_address\": true,
            \"show_phone\": true,
            \"show_email\": false,
            \"show_observations\": true,
            \"show_payment_methods\": false,
            \"show_references\": false,
            \"show_other_charges\": false
        },
        \"qr\": {
            \"size\": 100,
            \"position\": \"bottom-right\"
        },
        \"margins\": {
            \"top\": 22,
            \"right\": 24,
            \"bottom\": 18,
            \"left\": 8
        },
        \"style\": \"bold\",
        \"footer_text\": \"m\"
    }
}"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Profesional Actualizada",
    "is_default": true,
    "is_active": true,
    "paper_size": "letter",
    "config_json": {
        "colors": {
            "primary": "#1a365d",
            "secondary": "#4a5568",
            "text": "#2815Df",
            "accent": "#3182ce",
            "muted": "#2815Df"
        },
        "fonts": {
            "family": "Helvetica",
            "size_header": 14,
            "size_body": 9,
            "size_footer": 7
        },
        "layout": {
            "show_logo": true,
            "logo_position": "left",
            "logo_max_height": 60,
            "show_commercial_name": true,
            "show_address": true,
            "show_phone": true,
            "show_email": false,
            "show_observations": true,
            "show_payment_methods": false,
            "show_references": false,
            "show_other_charges": false
        },
        "qr": {
            "size": 100,
            "position": "bottom-right"
        },
        "margins": {
            "top": 22,
            "right": 24,
            "bottom": 18,
            "left": 8
        },
        "style": "bold",
        "footer_text": "m"
    }
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'name' => 'Profesional Actualizada',
            'is_default' => true,
            'is_active' => true,
            'paper_size' => 'letter',
            'config_json' => [
                'colors' => [
                    'primary' => '#1a365d',
                    'secondary' => '#4a5568',
                    'text' => '#2815Df',
                    'accent' => '#3182ce',
                    'muted' => '#2815Df',
                ],
                'fonts' => [
                    'family' => 'Helvetica',
                    'size_header' => 14,
                    'size_body' => 9,
                    'size_footer' => 7,
                ],
                'layout' => [
                    'show_logo' => true,
                    'logo_position' => 'left',
                    'logo_max_height' => 60,
                    'show_commercial_name' => true,
                    'show_address' => true,
                    'show_phone' => true,
                    'show_email' => false,
                    'show_observations' => true,
                    'show_payment_methods' => false,
                    'show_references' => false,
                    'show_other_charges' => false,
                ],
                'qr' => [
                    'size' => 100,
                    'position' => 'bottom-right',
                ],
                'margins' => [
                    'top' => 22,
                    'right' => 24,
                    'bottom' => 18,
                    'left' => 8,
                ],
                'style' => 'bold',
                'footer_text' => 'm',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Profesional Actualizada",
        "is_default": true,
        "paper_size": "letter",
        "config_json": {
            "colors": {
                "primary": "#1a365d",
                "secondary": "#4a5568",
                "accent": "#3182ce"
            },
            "fonts": {
                "family": "Helvetica",
                "size_header": 14,
                "size_body": 9
            },
            "layout": {
                "show_logo": true,
                "logo_position": "left",
                "logo_max_height": 60
            },
            "qr": {
                "enabled": true,
                "size": 100,
                "position": "bottom-right"
            }
        },
        "has_logo": true,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T11:00:00-06:00"
    },
    "message": "Plantilla actualizada correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "name": [
            "Ya existe una plantilla con este nombre para el contribuyente."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Eliminar una plantilla PDF

requires authentication

Realiza un soft delete de la plantilla. Los PDFs ya generados con esta plantilla no se ven afectados | la configuración se aplica al momento de generar cada PDF y no se modifica retroactivamente.

Protección: no se puede eliminar una plantilla si es la única plantilla activa del contribuyente. En ese caso el sistema responde HTTP 409 y debe:

1. Crear otra plantilla nueva, o
2. Reactivar otra plantilla existente,

antes de eliminar la actual.

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/2" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/2"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/2';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": null,
    "message": "Plantilla eliminada correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "No se puede eliminar la única plantilla activa del contribuyente. Cree otra plantilla o marque otra como default antes de eliminar.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Generar un preview del PDF con datos reales

requires authentication

Renderiza un PDF de ejemplo usando la plantilla indicada y el comprobante más reciente emitido por el contribuyente. Permite verificar la apariencia de la plantilla antes de asignarla como default.

La respuesta es un archivo PDF (Content-Type: application/pdf) inline. Puede guardarlo localmente con -o archivo.pdf en curl o mostrarlo directamente en un iframe del navegador.

Si el contribuyente aún no ha emitido ningún comprobante, retorna HTTP 404 con un mensaje indicando que debe emitir al menos uno primero.

Nota: el comprobante usado para el preview es el más reciente (ORDER BY issued_at DESC LIMIT 1). Si quiere probar la plantilla con un comprobante específico, emita uno nuevo y use este endpoint después | o bien use el endpoint GET /vouchers/{key}/pdf con ?pdf_template_id={id}.

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/preview" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/preview"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/preview';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "Content-Type": "application/pdf",
    "Content-Disposition": "inline; filename=\"preview_Classic.pdf\"",
    "Cache-Control": "no-store",
    "body": "%PDF-1.4 ... (binario) ... %%EOF"
}
 

{
    "success": false,
    "data": null,
    "message": "No hay comprobantes emitidos para generar un preview. Emita al menos un comprobante antes de usar preview.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Recurso no encontrado.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Obtener el logo de una plantilla PDF

requires authentication

Devuelve el archivo de imagen del logo como respuesta binaria inline, con el Content-Type correcto según el formato (PNG, JPG/JPEG, SVG).

Si la plantilla no tiene logo configurado, retorna HTTP 404.

El archivo se sirve con cache privado de 1 hora y cabeceras de seguridad (X-Content-Type-Options: nosniff).

curl --request GET \
    --get "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "Content-Type": "image/png",
    "Cache-Control": "private, max-age=3600",
    "X-Content-Type-Options": "nosniff",
    "body": "(contenido binario de la imagen)"
}
 

{
    "success": false,
    "data": null,
    "message": "Esta plantilla no tiene logo.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Archivo de logo no encontrado.",
    "errors": null
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Subir o reemplazar el logo de una plantilla PDF

requires authentication

Sube un archivo de imagen que se utilizará como logo en el encabezado del PDF generado con esta plantilla. Si la plantilla ya tenía un logo, se reemplaza automáticamente (el archivo anterior se elimina del servidor).

Este request debe enviarse como multipart/form-data (no JSON), porque incluye un archivo binario.

Restricciones del archivo:

• Extensiones permitidas: png, jpg, jpeg, svg.
• Tamaño máximo: 200 KB.
• Para logos que se verán bien en el PDF, use preferentemente resolución de 300 DPI y dimensiones proporcionales a layout.logo_max_height configurado.

Ejemplo con curl:

curl -X POST https://api.almendro.cr/api/v1/public/pdf-templates/1/logo \
  -H "Authorization: Bearer {su_token}" \
  -F "logo_file=@/ruta/a/logo.png"

Ejemplo con Node.js (axios + form-data):

const FormData = require('form-data')
const fs = require('fs')
const axios = require('axios')

const form = new FormData()
form.append('logo_file', fs.createReadStream('logo.png'))

await axios.post(
  'https://api.almendro.cr/api/v1/public/pdf-templates/1/logo',
  form,
  { headers: { ...form.getHeaders(), Authorization: `Bearer ${token}` } },
)

curl --request POST \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "logo_file=@/tmp/phpfs70aiqiehda2jhlLNz" 

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('logo_file', document.querySelector('input[name="logo_file"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'multipart/form-data',
            'Accept' => 'application/json',
        ],
        'multipart' => [
            [
                'name' => 'logo_file',
                'contents' => fopen('/tmp/phpfs70aiqiehda2jhlLNz', 'r')
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Classic",
        "is_default": true,
        "paper_size": "letter",
        "config_json": {
            "colors": {},
            "fonts": {},
            "layout": {},
            "qr": {}
        },
        "has_logo": true,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T12:00:00-06:00"
    },
    "message": "Logo subido correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "logo_file": [
            "El archivo del logo es obligatorio."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "logo_file": [
            "Extensión no permitida. Use: png, jpg, jpeg, svg."
        ]
    }
}
 

{
    "success": false,
    "data": null,
    "message": "Los datos proporcionados no son válidos.",
    "errors": {
        "logo_file": [
            "El logo no puede superar 200 KB."
        ]
    }
}
 

Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Eliminar el logo de una plantilla PDF

requires authentication

Elimina el archivo de logo asociado a la plantilla. Los PDFs que ya fueron generados con este logo no se ven afectados.

Si la plantilla no tiene logo configurado, retorna HTTP 409.

curl --request DELETE \
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://fe.almendro.cr/api/v1/public/pdf-templates/1/logo';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Classic",
        "is_default": true,
        "paper_size": "letter",
        "config_json": {
            "colors": {},
            "fonts": {},
            "layout": {},
            "qr": {}
        },
        "has_logo": false,
        "is_active": true,
        "created_at": "2026-04-01T10:00:00-06:00",
        "updated_at": "2026-04-16T13:00:00-06:00"
    },
    "message": "Logo eliminado correctamente.",
    "errors": null
}
 

{
    "success": false,
    "data": null,
    "message": "Esta plantilla no tiene logo configurado.",
    "errors": null
}