API de facturación electrónica para Costa Rica

Qué puede automatizar

URL base: https://app.facturadorarkea.com/api. La fuente de verdad de campos, ejemplos y errores es la especificación OpenAPI 3.1. Los precios van sin IVA; ARKEA calcula impuestos y totales.

Empresa

• GET /empresa — Nombre, identificación, ambiente (pruebas o producción), si ya puede emitir, cajas activas y plan. Úsela para comprobar la llave y obtener los id de caja.

Comprobantes

Facturas (01), tiquetes (04) y facturas de exportación (09).

• POST /comprobantes — Crear una factura o tiquete. Queda en borrador, salvo emitir: true, que la firma y la envía a Hacienda de inmediato. El cliente es un cliente_id o un objeto cliente (crea o actualiza por identificación).
• GET /comprobantes — Buscar por cliente, estado, tipo, referencia_externa o fechas.
• GET /comprobantes/{id} — Detalle: líneas, totales, estado en Hacienda y notas que lo referencian.
• DELETE /comprobantes/{id} — Eliminar un borrador. Un comprobante emitido no se elimina: se anula con una nota de crédito.
• POST /comprobantes/{id}/emitir — Firmar y enviar un borrador, o reintentar uno fallido con el mismo consecutivo. Irreversible.
• POST /comprobantes/{id}/consultar-hacienda — Preguntar ahora por un comprobante que espera respuesta. ARKEA ya consulta solo.
• POST /comprobantes/{id}/enviar — Enviar un comprobante aceptado (PDF y ambos XML) al correo del cliente o a los indicados.
• POST /comprobantes/{id}/cobrado — Marcar una factura a crédito como cobrada, o deshacer la marca.
• GET /comprobantes/{id}/pdf — Representación gráfica.
• GET /comprobantes/{id}/xml — XML firmado enviado a Hacienda.
• GET /comprobantes/{id}/respuesta-hacienda — MensajeHacienda firmado, cuando ya respondió.
• POST /comprobantes/{id}/notas-credito — Corregir un comprobante aceptado. Sin líneas acredita el documento completo; con líneas, solo esas cantidades.
• POST /comprobantes/{id}/anular — Emitir de inmediato una nota de crédito por el total. Irreversible.

Clientes

• GET /clientes — Buscar por nombre, identificación o correo.
• POST /clientes — Crear o actualizar por tipo y número de identificación. Su sistema puede enviar el cliente cada vez sin guardar el id de ARKEA.
• GET /clientes/{id} y PATCH /clientes/{id} — Consultar o cambiar solo los campos enviados.

Productos

• GET /productos — Catálogo activo, por descripción, código interno o CABYS.
• POST /productos — Crear un producto o servicio para facturarlo después con producto_id y la cantidad.
• GET /productos/{id} y PATCH /productos/{id} — Consultar o actualizar.

Recurrentes

• GET /recurrentes — Listar facturas que ARKEA emite sola en cada fecha.
• POST /recurrentes — Programar una: ARKEA la emite, la envía a Hacienda y por correo en cada fecha. La primera sale en inicia_el.
• PATCH /recurrentes/{id} — Pausar o reanudar. Al reanudar no se emiten los periodos saltados.

Reportes

• GET /reportes/ventas — Ventas netas, IVA y comprobantes aceptados en colones (las notas de crédito restan). Sin fechas, el mes en curso.
• GET /reportes/cuentas-por-cobrar — Facturas a crédito aceptadas sin cobrar, con días de atraso y el total en colones.

Hacienda

• GET /hacienda/contribuyentes/{identificacion} — Nombre, régimen, situación y actividades de una cédula, DIMEX o NITE.
• GET /hacienda/cabys — Buscar CABYS por palabras o por el inicio del código, con la tarifa de IVA sugerida.
• GET /hacienda/tipo-cambio — Tipo de cambio de venta que publica Hacienda, en colones (por defecto USD).

Ejemplo: crear y emitir una factura

El cuerpo sigue el esquema ComprobanteEntrada de la spec. tipo_documento por defecto es 01 (factura electrónica). El precio de la línea va sin IVA. Con emitir: true ARKEA firma y envía a Hacienda de inmediato; si no se puede emitir, no se guarda nada.

curl -X POST https://app.facturadorarkea.com/api/comprobantes \
  -H "Authorization: Bearer arkea_…" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_externa": "viaje-1042",
    "emitir": true,
    "cliente": {
      "nombre": "Transportes del Valle S.A.",
      "identificacion_tipo": "02",
      "identificacion_numero": "3101555555",
      "correo": "[email protected]"
    },
    "lineas": [
      {
        "detalle": "Flete San José - Limón",
        "codigo_cabys": "6511100000000",
        "es_servicio": true,
        "cantidad": 1,
        "precio_unitario": 250000
      }
    ]
  }'

Valores del ejemplo publicado en la spec. Sustitúyalos por los de su venta. Para un tiquete use tipo_documento 04; para exportación, 09.

Límites y errores

120 solicitudes por minuto por llave. El encabezado X-RateLimit-Remaining indica cuántas le quedan. Si se pasa, la respuesta es 429 con Retry-After.

Los errores siempre vienen así: {"error": {"codigo", "mensaje"}}. Con datos inválidos aparece también campos. Decida en su programa con codigo; mensaje está en español, para personas. Un error significa que no se guardó nada.

• no_autenticado — 401: falta la llave, no es válida o fue revocada, o quien la creó ya no es administrador.
• plan_sin_api — 403: la empresa no tiene el plan Pro pagado y vigente.
• llave_solo_lectura — 403: la llave es de solo lectura y la solicitud cambia datos.
• no_encontrado — 404: no existe en esta empresa.
• operacion_rechazada — 409: no se puede ahora (ya emitido, sin cajas activas, plan vencido…). El mensaje dice por qué.
• datos_invalidos — 422: datos que no cumplen las reglas; campos trae el detalle.
• demasiadas_solicitudes — 429: espere los segundos de Retry-After.
• error_interno — 500: error de ARKEA; nada quedó a medias, reintente.