dosel.lamboz.dev/v1 HACIENDA v4.4 REST · JSON · XAdES-EPES CRC · UTC-6

Presentamos tus facturas electrónicas ante Hacienda.

Enviás los datos del documento como JSON. Dosel lo arma, lo firma, lo presenta ante Hacienda, reintenta cuando el ATV falla y te devuelve el documento aceptado con su XML firmado y su PDF.

PETICIÓN
curl -X POST https://dosel.lamboz.dev/v1/documents \
  -H "Authorization: Bearer dos_sandbox_…" \
  -d '{
    "document": {
      "document_type": "invoice",
      "receiver": { "name": "...", "tax_id": { "scheme": "cedula_juridica", "value": "..." } },
      "lines": [{
        "classification_code": "8511000000000",
        "description":         "Plan Pro",
        "unit_price":           25000
      }]
    }
  }'
RESPUESTA
201 CREATED
id
018f2e4a-6b3c…
fiscal_key
50613082501031…
status
submitted
firma
✓ XAdES-EPES

Quickstart

~ 1 min
01LLAVE
dos_sandbox_9f2c7a41d8e0b3c65a1f04e7

La llave de sandbox se crea al registrarte, sin certificado ni tarjeta.

02AUTENTICAR
Authorization: Bearer dos_sandbox_…

Sumá un Idempotency-Key propio para reintentar sin duplicar.

03ENVIAR
POST /v1/documents

Devuelve la clave fiscal, el estado y el XML firmado. Webhook en cada cambio.

Endpoints

REFERENCIA COMPLETA EN /DOCS
POST /v1/documents Firma, presenta y entrega un documento
GET /v1/documents/{id} Estado actual y archivos
GET /v1/documents/{id}/xml/{variant} XML sin firmar, firmado o de respuesta de Hacienda
GET /v1/catalogs/product_classifications?q= Busca en el catálogo CABYS vigente
GET /v1/inbox Documentos de proveedor recibidos
GET /v1/status Disponibilidad del ATV que vemos

Tipos de documento

8 · HACIENDA v4.4
invoice
Factura electrónica
Venta a contribuyente registrado
simplified_invoice
Tiquete electrónico
Venta al detalle, consumidor final
credit_note
Nota de crédito
Anula o corrige un documento presentado
debit_note
Nota de débito
Aumenta el monto de un documento
purchase_invoice
Factura de compra
Compra a proveedor no inscrito
export_invoice
Factura de exportación
Venta a cliente fuera de Costa Rica
payment_receipt
REP — recibo de pago
Confirma el pago de un documento a crédito
acceptance_response
Mensaje receptor
Acepta o rechaza documento de proveedor
Mismo endpoint y misma forma de respuesta en los ocho — solo cambia document_type.
CAMPOS →

Precios

USD / MES
$0
Sandbox
Documentos de prueba ilimitados, toda la superficie del API.
$19
API Single
1.000 documentos/mes incluidos · $10.00 cada 1,000 adicionales — nunca se detiene la emisión
$79
API Platform
10.000 documentos/mes incluidos · $5.00 cada 1,000 adicionales — nunca se detiene la emisión
SIN COSTO DE SETUP CANCELÁS CUANDO QUERÁS LLAVE SANDBOX →

Eventos

HMAC-SHA256 · at-least-once
document.acceptedpresentado y aceptado
document.rejectedrechazado con motivo
document.polling_exhaustedse agotó la ventana de reintentos
authority.unavailableATV no disponible
certificate.expiring30 / 14 / 7 d antes de vencer

Errores de validación

422
{
  "error": {
    "code": "validation_failed",
    "message": "Lines classification code no existe",
    "details": { "lines.classification_code": [...] }
  }
}

Los errores de validación se devuelven antes de firmar, así que no consumen consecutivo.

REINTENTOS

Dosel acepta el documento, lo firma, asigna la clave fiscal y encola la presentación. Cuando el ATV está caído la cola reintenta con backoff exponencial hasta que Hacienda responda.

2ⁿ
Backoff de reintentos
at-least-once
Entrega de webhooks
COLA DE REINTENTOS EJEMPLO
FE-000184aceptado1x
FE-000185reintentando3x
TE-002310en cola0x
NC-000042aceptado2x
Nada que hacer de tu lado — reintentamos automáticamente.

Países

CR Costa Rica Hacienda v4.4 · ATV Diez tipos de documento, firma XAdES-EPES. EN PRODUCCIÓN
PA Panamá DGI · SFEP La misma forma de petición, con el ruteo por PAC resuelto abajo. EN DESARROLLO
EL MISMO MOTOR EN CADA PAÍS: EL RÉGIMEN FISCAL ES UN CAMPO DE LA PETICIÓN, NO UN SISTEMA APARTE.

Llave sandbox

AUTOSERVICIO · SIN LLAMADA DE VENTAS
01 Correo y contraseña
02 Nombrá tu organización — las llaves quedan bajo su alcance
03 Copiá el sk_test_ y corré el quickstart
Para producción hay que subir tu certificado de Hacienda.

Creá la cuenta, recibí tu llave dos_sandbox_… y enviá tu primer documento contra el ambiente de pruebas de Hacienda.

Crear llave sandbox →

Sin tarjeta. Al crear la llave aceptás los términos de servicio.