Documentación API

API pública para emitir comprobantes contra ARCA programáticamente. Generá un token en API Keys.

Autenticación

Todos los requests van con un header Authorization: Bearer <token>. El prefijo del token (ark_live_ / ark_test_) determina el ambiente y se valida contra el ambiente real de este deploy en cada request — un token de test nunca puede tocar producción, ni al revés.

curl https://<host>/api/v1/invoices \
  -H "Authorization: Bearer ark_test_9f2a..."

Idempotencia

Pasá un header Idempotency-Key único por comprobante en POST /api/v1/invoices y POST /api/v1/invoices/:id/credit-note. Si reintentás con la misma key, devolvemos el comprobante ya emitido en vez de volver a llamar a ARCA — evita duplicar una factura fiscal ante un timeout o un reintento automático de tu lado.

Endpoints

POST/api/v1/invoices

Emite un comprobante contra ARCA y encola el PDF

curl -X POST https://<host>/api/v1/invoices \
  -H "Authorization: Bearer ark_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8213" \
  -d '{
    "cuit": "20111111112",
    "punto_venta": 3,
    "tipo_cbte": 6,
    "concepto": 1,
    "doc_tipo": 96,
    "doc_nro": "30123456",
    "condicion_iva_receptor_id": 5,
    "items": [
      { "descripcion": "Consulta", "cantidad": 1, "precio_unitario": 1000, "alicuota_iva": 21 }
    ]
  }'

tipo_cbte: 1/6/11 = Factura A/B/C. doc_tipo: 80 CUIT, 96 DNI, 99 Consumidor Final. concepto: 1 Productos, 2 Servicios, 3 Ambos. condicion_iva_receptor_id (obligatorio desde RG 5616): 1 Responsable Inscripto, 4 Exento, 5 Consumidor Final, 6 Monotributo — el resto de los códigos en FEParamGetCondicionIvaReceptor.

{
  "id": "...",
  "status": "ISSUED",
  "cae": "74123456789012",
  "cae_vto": "2026-08-06",
  "punto_venta": 3,
  "tipo_cbte": 6,
  "nro_cbte": 1234,
  "imp_total": 1210,
  "pdf_url": "https://facturas.vivibalance.com/9f8c...",
  "pdf_status": "queued"
}

pdf_url es permanente — funciona apenas el PDF termina de generarse (normalmente unos segundos) y no vence nunca. Mientras se genera, esa URL muestra una página de espera que se actualiza sola.

GET/api/v1/invoices

Lista comprobantes (filtros: cuit, status, limit)

curl "https://<host>/api/v1/invoices?status=ISSUED&limit=20" \
  -H "Authorization: Bearer ark_test_..."

GET/api/v1/invoices/:id

Detalle de un comprobante

POST/api/v1/invoices/:id/credit-note

Emite una nota de crédito contra el comprobante

# Nota total (mismos ítems que el original)
curl -X POST https://<host>/api/v1/invoices/inv_.../credit-note \
  -H "Authorization: Bearer ark_test_..." \
  -H "Idempotency-Key: nc-8213"

# Nota parcial
curl -X POST https://<host>/api/v1/invoices/inv_.../credit-note \
  -H "Authorization: Bearer ark_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "descripcion": "Consulta", "cantidad": 1, "precio_unitario": 500, "alicuota_iva": 21 }] }'

GET/api/v1/taxpayers

CUITs alcanzados por el token

GET/api/v1/taxpayers/:cuit/next-number

Consulta el próximo número disponible (no reserva nada)

curl "https://<host>/api/v1/taxpayers/20111111112/next-number?punto_venta=3&tipo_cbte=6" \
  -H "Authorization: Bearer ark_test_..."

POST/api/v1/pdfs

Renderiza HTML arbitrario a PDF (compatible con AFIP SDK)

curl -X POST https://<host>/api/v1/pdfs \
  -H "Authorization: Bearer ark_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "html": "<html><body><h1>Hola</h1></body></html>" }'

Sin identidad permanente /d/{uuid} — no está atado a ningún comprobante, devuelve una URL de Blob directa.

Errores

Todos los errores devuelven { "error": "mensaje" } con el status HTTP correspondiente. Un rechazo de ARCA (ej. numeración fuera de secuencia, CUIT no habilitado) devuelve 422 con el detalle en arca_errors.