API REST: primeros pasos

La API es la forma principal de integrar Comprobado: tu sistema (tienda online, ERP, facturador propio) emite y consulta comprobantes por HTTP, sin tocar la consola. Es la misma API que usa la consola, así que todo lo que ves en pantalla se puede automatizar.

Esta guía explica cómo se usa. El detalle de cada campo y de cada endpoint está en:

Emitir comprobantes: todos los campos del pedido, la respuesta y las reglas de validación.
Referencia de endpoints: cada ruta, con sus parámetros, permisos y respuestas.
Ejemplos de integración: código completo en curl, JavaScript, Python y C#.
API keys: tipos de clave y qué puede hacer cada una.
Facturación masiva y Facturas de exportación (E).

La descripción legible por máquinas (OpenAPI 3) está siempre disponible en /openapi/v1.json: sirve para generar un cliente en el lenguaje que uses o para importarla en Postman o Insomnia. La documentación interactiva (/swagger) puede estar desactivada en producción.

Lo básico


Base	`https://TU-DOMINIO` (la misma dirección de la consola). Todas las rutas empiezan con `/v1`
Formato	JSON en UTF-8 (`Content-Type: application/json`). Los errores son `application/problem+json`
Autenticación	`Authorization: Bearer ask_live_…` en cada pedido
Ambiente	El de tu cuenta: homologación (pruebas, sin validez fiscal) o producción. No se elige por pedido: se cambia en la cuenta (ver)
Uso	De servidor a servidor. La API no habilita CORS: no la llames desde un navegador, porque expondrías la clave

Convenciones del JSON

Los nombres de las propiedades van en camelCase (puntoVenta, precioUnitario).
Los enumerados son texto en camelCase ("notaCredito", "responsableInscripto"), nunca números.
Las fechas son "aaaa-mm-dd" y las fechas con hora, ISO 8601 (2026-10-22T16:38:40+00:00).
Los importes y cantidades son números JSON (1500.5), no texto. Con punto decimal.
Los campos sin valor vienen como null (no se omiten). Al enviar, los opcionales se pueden omitir.
El tipo de comprobante (tipo) es la excepción: se manda como texto ("auto" o un código, "11").

1 · Conseguir una clave

En la consola: Integraciones → API → Nueva clave. Elegí el tipo según lo que tu sistema necesita (ver API keys): para emitir, Completa; para un tablero de consulta, Solo lectura; para importar planillas o enviar lotes, Facturación masiva.

La clave se ve una sola vez. Guardala en un gestor de secretos o en una variable de entorno del servidor.

export COMPROBADO_KEY="ask_live_XXXXXXXX"
curl https://TU-DOMINIO/v1/tenant -H "Authorization: Bearer $COMPROBADO_KEY"

Si responde con tus datos fiscales, la clave funciona.

¿Sin certificado todavía? Pasá tu cuenta al simulador (Configuración → Certificado → «Probar en el simulador») y probá todo lo de esta guía, incluidos rechazos y timeouts forzados, sin tocar ARCA.

2 · Verificar que todo está listo

Antes de emitir, un par de consultas confirman que la cuenta está bien configurada:

# ¿Hay conexión con ARCA? (certificado + autorización del servicio)
curl "https://TU-DOMINIO/v1/tenant/health?check=all" -H "Authorization: Bearer $COMPROBADO_KEY"

# ¿Qué puntos de venta tengo? (el número que va en "puntoVenta")
curl https://TU-DOMINIO/v1/points-of-sale -H "Authorization: Bearer $COMPROBADO_KEY"

# ¿Cuál fue el último número que ARCA autorizó? (punto de venta 1, Factura C = tipo 11)
curl "https://TU-DOMINIO/v1/arca/last-number?pv=1&tipo=11" -H "Authorization: Bearer $COMPROBADO_KEY"

3 · Previsualizar (sin emitir)

POST /v1/invoices/preview recibe el mismo cuerpo que emitir, valida y calcula, pero no pide CAE ni consume número. Sirve para mostrar el total al usuario y para detectar errores de datos antes de emitir. Cualquier clave puede previsualizar, incluso la de solo lectura.

curl -X POST https://TU-DOMINIO/v1/invoices/preview \
  -H "Authorization: Bearer $COMPROBADO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "puntoVenta": 1,
    "items": [{ "descripcion": "Camisa talle M", "cantidad": 2, "precioUnitario": 1500.5 }]
  }'

{
  "tipoCodigo": 11,
  "tipoNombre": "Factura C",
  "fecha": "2026-10-22",
  "importes": {
    "neto": 3001.0,
    "iva": 0,
    "tributos": 0,
    "noGravado": 0,
    "exento": 0,
    "total": 3001.0,
    "ivaPorAlicuota": []
  }
}

Notá que no mandaste el tipo de comprobante: con "tipo": "auto" (el valor por defecto) la letra se resuelve sola según tu condición frente al IVA y la del cliente (ver la tabla).

4 · Emitir

curl -X POST https://TU-DOMINIO/v1/invoices \
  -H "Authorization: Bearer $COMPROBADO_KEY" \
  -H "Idempotency-Key: pedido-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "puntoVenta": 1,
    "receptor": { "docTipo": "dni", "docNro": "30111222", "condicionIva": "consumidorFinal", "nombre": "Ana Pérez" },
    "items": [{ "descripcion": "Camisa talle M", "cantidad": 2, "precioUnitario": 1500.5 }]
  }'

Respuesta 201 Created (ARCA aprobó):

{
  "id": "inv_f7524f4f1afc4a568fa70d0c199bb4b4",
  "estado": "autorizado",
  "tipoCodigo": 11,
  "tipoNombre": "Factura C",
  "puntoVenta": 1,
  "numero": 8,
  "fecha": "2026-10-22",
  "cae": "86431017711917",
  "caeVencimiento": "2026-11-01",
  "importes": {
    "neto": 3001.0,
    "iva": 0,
    "tributos": 0,
    "noGravado": 0,
    "exento": 0,
    "total": 3001.0,
    "ivaPorAlicuota": []
  },
  "avisos": [],
  "errores": [],
  "arcaCallId": "call_ec5c3358359c492e9ae2a2a042be64e4"
}

Guardá en tu sistema el id (para consultar después), el numero y el cae. El PDF con el QR de ARCA se pide con GET /v1/invoices/{id}/pdf.

Idempotency-Key (obligatoria)

Es un texto que identifica a ese comprobante en tu sistema (el número de pedido, el id de la venta, un UUID guardado antes de emitir). Garantiza que un mismo comprobante nunca se factura dos veces, aunque tu sistema reintente por un corte de red.

Si mandás…	Pasa esto
Una clave nueva	Se emite el comprobante
La misma clave y el mismo contenido	No se emite otra vez: devuelve el resultado del primer intento (y, si estaba incierto, lo reconcilia con ARCA)
La misma clave con contenido distinto	`409` (`AS-1013`). No se emite nada
Sin la clave	`400` (`AS-1015`)

Reglas para usarla bien:

Generala antes de la primera llamada y guardala junto a tu venta. Si la generás en cada reintento, perdés la protección.
Un 400 de validación no consume la clave: corregís los datos y reintentás con la misma.
Un comprobante rechazado sí queda asociado a la clave. Repetir la misma clave devuelve el mismo rechazo. Para corregir y volver a emitir, usá una clave nueva (por ejemplo pedido-1001-2).
Un mismo número de comprobante nunca se reutiliza: un rechazo no consume número en ARCA.

5 · Interpretar el resultado

El campo estado del comprobante es lo que manda. Hay cinco:

`estado`	Qué significa	Qué hacer
`autorizado`	ARCA lo aprobó y tiene CAE	Guardar `numero` y `cae`. Listo
`rechazado`	ARCA (o la validación previa) lo rechazó. No se emitió ni se consumió el número	Leer `errores[].humano`, corregir y emitir de nuevo con una clave nueva
`incierto`	Se cortó la conexión mientras ARCA respondía: no sabemos si lo registró	No lo vuelvas a emitir con otra clave. Consultalo (`GET /v1/invoices/{id}`) o repetí el pedido con la misma clave: se resuelve consultando a ARCA
`enEspera`	Pediste `?diferir=true` y ARCA no respondía antes de enviar nada: quedó guardado, sin número ni CAE, y no es una factura válida	No lo entregues ni lo reemitas. Se emite solo cuando ARCA vuelve; seguilo con `GET /v1/invoices/{id}` o el webhook `invoice.deferred` → `invoice.authorized`. Ver Qué hacer si ARCA está caída
`pendiente`	Se está procesando (otro pedido con la misma clave está en curso, o se interrumpió)	Esperá unos segundos y consultalo. Si pasan más de 5 minutos con un número ya reservado, Comprobado lo trata como `incierto` y lo reconcilia con ARCA

Los códigos HTTP de POST /v1/invoices:

HTTP	Cuándo	Cuerpo
`201`	ARCA aprobó	El comprobante (`estado: "autorizado"`)
`202`	El pedido ya se había procesado y quedó `rechazado` o `pendiente`, o quedó `enEspera` por `?diferir=true`	El comprobante con su `estado`
`400`	Datos inválidos	Problema con `errores[].humano.campo` indicando qué corregir
`401`	Falta la clave o está revocada
`402`	Servicio suspendido por falta de pago (`AS-2024`)	Regularizá el pago: se reactiva solo
`403`	Sin permiso, cuenta suspendida o dada de baja, la API deshabilitada en tu plan, o una función que tu plan no incluye (`AS-2027`)
`409`	`Idempotency-Key` ya usada con otro contenido (`AS-1013`) o credenciales sin configurar (`AS-3004`)
`422`	ARCA rechazó el comprobante	Problema con `invoiceId`, `arcaCallId` y `errores` (`humano` + `arca`)
`424`	Falló la autenticación con ARCA (certificado vencido, servicio sin autorizar)	Problema; el comprobante no se envió
`429`	Cupo mensual agotado (`AS-2004`) o demasiados pedidos seguidos (`AS-2020`)	Ver Límites
`502` / `504`	No se pudo hablar con ARCA o ARCA falló al procesar el pedido (`SOAP:…`) / no se pudo confirmar si autorizó	En el `504` el comprobante queda incierto; el cuerpo trae su `invoiceId`
`503`	Servicio en mantenimiento (`AS-2001`), o demasiadas emisiones en curso (`AS-2030`: nada se envió a ARCA)	Reintentá más tarde; con `AS-2030` reintentá en unos segundos con la misma clave

Regla de oro: ante un 504, un timeout de tu lado o cualquier duda, no emitas con otra clave. Repetí el pedido con la misma Idempotency-Key (o consultá el invoiceId): Comprobado le pregunta a ARCA si registró el comprobante y te devuelve la verdad. Ver Comprobantes inciertos.

6 · Consultar

# Un comprobante (si estaba incierto, lo reconcilia con ARCA)
curl https://TU-DOMINIO/v1/invoices/inv_f7524f4f… -H "Authorization: Bearer $COMPROBADO_KEY"

# El PDF con el QR de verificación (solo comprobantes autorizados)
curl -o factura.pdf https://TU-DOMINIO/v1/invoices/inv_f7524f4f…/pdf -H "Authorization: Bearer $COMPROBADO_KEY"

# Listado con filtros; el total viene en el header X-Total-Count
curl "https://TU-DOMINIO/v1/invoices?desde=2026-10-01&hasta=2026-10-31&estado=autorizado&take=100&pagina=1" \
  -H "Authorization: Bearer $COMPROBADO_KEY"

Cada fila del listado trae id, estado, tipo, tipoNombre, puntoVenta, numero, fecha, total, cae, caeVencimiento, createdAt, canal, ambiente, receptor, receptorDoc, moneda (código de ARCA; PES = pesos) y cotizacion (pesos por unidad; total está siempre en la moneda del comprobante). Una exportación importada sin moneda trae sinMoneda: true y no se puede pasar a pesos hasta completarla. Para paginar con el total dentro del cuerpo, usá GET /v1/invoices/page. Todos los filtros están en la referencia.

Errores

Todo error trae dos partes: una explicación en castellano (humano) y, si vino de ARCA, el mensaje original (arca).

{
  "type": "https://comprobado.com.ar/errores/400",
  "title": "Datos inválidos",
  "status": 400,
  "detail": "El comprobante necesita al menos un ítem",
  "errores": [
    {
      "humano": {
        "codigo": "AS-1002",
        "titulo": "El comprobante necesita al menos un ítem",
        "detalle": "No se recibió ningún ítem para calcular importes.",
        "comoSolucionarlo": "Agregá al menos un ítem con precio mayor a cero.",
        "quienActua": "usuario",
        "reintentable": false,
        "campo": "/items"
      },
      "arca": null
    }
  ],
  "traceId": "d7441464"
}

errores[].humano.codigo identifica el error de forma estable: programá tu lógica contra el código (AS-1002, WSFE:10016), no contra el texto.
humano.campo apunta al campo del pedido que hay que corregir (formato JSON Pointer: /items, /receptor/docNro).
humano.quienActua dice quién lo resuelve: usuario, contador, integrador (te toca a vos, por ejemplo una clave mal armada) o soporte.
humano.reintentable indica si tiene sentido reintentar tal cual (por ejemplo, un corte de red) o si hay que cambiar algo primero.
arca trae el error crudo (origen, codigo, mensaje), por si tu contador necesita ver el texto exacto.
traceId sirve para que soporte encuentre el pedido.
Ante un código que no conozcas, mostrá humano.titulo y humano.detalle: siempre vienen.

El catálogo completo, con cada código y cómo resolverlo, está en Catálogo de errores. También se puede leer por API, sin clave: GET /v1/catalog/errors.

Límites

Pedidos por segundo: cada API key admite una ráfaga de 60 pedidos y se recarga a 3 por segundo. Si te pasás, respondemos 429 con AS-2020 y el header Retry-After (segundos). Reintentá después de esa espera y, si emitís muchos comprobantes, usá la facturación masiva en lugar de un pedido por comprobante. Además hay un tope más holgado por dirección IP (ráfaga de 300, 15 por segundo): inventar claves distintas en cada pedido no lo esquiva.
Cupo mensual: tu plan puede limitar los comprobantes por mes. Al agotarlo, emitir responde 429 con AS-2004. Consultar y previsualizar siguen funcionando. Ver el uso en GET /v1/usage, que también dice cuándo se reinicia el cupo (reiniciaEl: el día 1 de cada mes en hora de Argentina, o el día en que empezó tu período pagado, según el plan). Detalle en Plan, cupo y pagos.
Servicio suspendido por falta de pago: si el período contratado venció y pasaron los días de gracia, todo pedido responde 402 con AS-2024. Al registrarse el pago la cuenta se reactiva sola: no hace falta cambiar nada en tu integración.
Emisión secuencial: ARCA numera los comprobantes de a uno por punto de venta y tipo. Comprobado serializa las emisiones de un mismo punto de venta y tipo, así que emitir en paralelo no acelera (para volumen, los lotes).
Tiempos: emitir hace varias llamadas a ARCA (autenticación, último número, solicitud) y casi siempre tarda unos segundos; con ARCA lenta puede llegar a unos minutos. Configurá un timeout de al menos 90 segundos en tu cliente HTTP, y ante un timeout aplicá la regla de oro de arriba. Si tu conexión se corta durante la emisión, Comprobado la completa igual: consultá después con la misma clave.
Tamaño: los pedidos comunes son livianos (hasta 1 MB); los lotes aceptan hasta 25 MB y 20 000 comprobantes cada uno.

Reintentos: qué sí y qué no

Situación	Reintentar	Cómo
Timeout o corte de red de tu lado	Sí	Misma `Idempotency-Key`, mismo cuerpo
`502`, `503`, `504`	Sí, con espera creciente	Misma `Idempotency-Key`, mismo cuerpo
`429`	Sí, tras `Retry-After` (si es `AS-2020`)	Misma clave. Si es `AS-2004` (cupo), no sirve reintentar
`400` (datos inválidos)	Sí, después de corregir	Misma clave (no se consumió)
`422` / `estado: "rechazado"`	Sí, después de corregir	Clave nueva
`401` / `403`	No	Revisá la clave y los permisos
`409` (`AS-1013`)	No	Es un error de tu sistema: la clave se reutilizó con otros datos

Antes de pasar a producción

Probá todo el circuito en homologación: es idéntico, pero los comprobantes no tienen validez fiscal. Una lista para no olvidar nada:

Emití al menos una factura de cada tipo que vayas a usar, y también una nota de crédito sobre una de ellas.
Simulá un corte de red en medio de una emisión y verificá que tu sistema repite con la misma clave y no duplica.
Verificá que guardás id, numero, cae y caeVencimiento, y que podés bajar el PDF.
Manejá 429, 503 y 504 con espera creciente.
Guardá la clave en un gestor de secretos y creá una clave distinta por sistema, con el menor permiso posible.
Pasá a producción (lo pide el equipo de Comprobado o, si te registraste por tu cuenta, lo hacés vos) siguiendo el checklist de Homologación y producción. Las claves siguen siendo las mismas: solo cambia el ambiente de la cuenta.