API REST v1

API de facturación electrónica para Costa Rica

Emita comprobantes desde su sistema con una llamada. Nosotros firmamos el XML, lo enviamos a Hacienda y le avisamos el resultado.

¿Ya tiene cuenta? Entre al portal para desarrolladores

POST /api/v1/documents
{
  "document_type": "01",
  "payment_method": "01",
  "currency": "CRC",
  "client": {
    "name": "Juan Pérez",
    "id_type": "01",
    "id_number": "101230456"
  },
  "lines": [{
    "name": "Servicio de consultoría",
    "quantity": 1,
    "price": 50000,
    "cabys": "8311100000000"
  }]
}

Qué incluye

Todo el ciclo del comprobante, por API

Emisión de comprobantes

Envíe facturas, tiquetes y notas de crédito y débito en JSON. Nosotros armamos el XML 4.4, lo firmamos y lo enviamos a Hacienda.

Webhooks firmados

Reciba el estado de Hacienda en su servidor, firmado con HMAC-SHA256. Si su servidor no responde, reintentamos hasta 6 veces.

Recepción de comprobantes

Acepte o rechace por API los comprobantes que le envían sus proveedores.

XML y respuesta de Hacienda

Consulte el estado, el XML firmado y el mensaje de respuesta de cada comprobante por su clave.

Varias empresas

Registre las empresas de sus clientes y emita a nombre de cada una, con su propia llave criptográfica.

Catálogos y CABYS

Consulte los catálogos de Hacienda y busque códigos CABYS desde su sistema.

Ambiente de pruebas sin costo

Pruebe toda la integración contra el ambiente de pruebas de Hacienda antes de pagar un plan.

Integración por SFTP

¿Su ERP no consume APIs REST? Deposite el XML sin firmar por SFTP y nosotros lo firmamos y lo enviamos a Hacienda.

Endpoints principales

  • POST /api/v1/auth/token Obtener un token de acceso
  • POST /api/v1/documents Emitir un comprobante
  • GET /api/v1/documents/{key} Consultar el estado de un comprobante
  • GET /api/v1/documents/{key}/xml Descargar el XML firmado
  • GET /api/v1/documents/{key}/response Descargar la respuesta de Hacienda
  • POST /api/v1/receptions Aceptar o rechazar un comprobante recibido
  • POST /api/v1/companies Registrar una empresa emisora
  • GET /api/v1/catalogs/cabys Buscar códigos CABYS
  • POST /api/v1/webhooks Registrar un webhook
  • POST /api/v1/webhooks/deliveries/{delivery}/redeliver Reenviar una notificación
Ver la referencia completa

Webhooks verificables

Cada notificación lleva una firma HMAC-SHA256 de "{timestamp}.{body}" con el secreto de su webhook. Puede rotar el secreto sin perder notificaciones.

Encabezado de la notificación
X-Ticofacturacr-Signature: t=1754997600,v1=5f2b…c91a

Eventos: document.accepted, document.rejected, document.error y más.

Cómo empezar

De la cuenta a producción en cuatro pasos

  1. 01

    Cree su cuenta

    Regístrese y entre al portal para desarrolladores. El ambiente de pruebas no tiene costo.

  2. 02

    Obtenga su token

    Pida un token de acceso con POST /api/v1/auth/token. Cada empresa tiene sus propias credenciales.

  3. 03

    Emita en pruebas

    Envíe comprobantes al ambiente de pruebas de Hacienda y registre sus webhooks.

  4. 04

    Pase a producción

    Elija un plan según su volumen de comprobantes y empiece a emitir en producción.

Precio

Pruebas sin costo. Producción desde ₡7.000 al mes.

Los planes cambian según el volumen de comprobantes y la cantidad de empresas. Vea todos los planes en el portal para desarrolladores.

Hablar con el equipo

Preguntas frecuentes

¿Cuánto cuesta probar la API?

Nada. El plan de pruebas le da acceso a la API completa contra el ambiente de pruebas de Hacienda. Para emitir en producción elige un plan pagado.

¿Necesito una llave criptográfica por empresa?

Sí. Cada empresa que emite necesita su propia llave criptográfica (.p12), su PIN y su usuario de comprobantes de Hacienda.

¿Cómo sé si Hacienda aceptó un comprobante?

Registre un webhook y reciba eventos como document.accepted o document.rejected. También puede consultar GET /api/v1/documents/{key}.

¿Qué pasa si mi servidor no responde a un webhook?

Reintentamos hasta 6 veces: a 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas. Después puede reenviar la notificación manualmente.

¿Puedo integrar un ERP que solo genera archivos XML?

Sí. Con la integración por SFTP deposita el XML sin firmar y nosotros lo firmamos y lo enviamos a Hacienda. Está incluida en los planes que indican Ingesta de XML por SFTP.

Empiece a integrar hoy

Cree su cuenta, pruebe contra el ambiente de pruebas de Hacienda y pase a producción cuando esté listo.