Convenciones de la API

Formato de datos

• JSON en snake_case. Todos los campos de entrada y salida, y los query params: represented_cuit_id, total_amount, date_from.
• Montos en centavos, como enteros. 12100 son $121,00. Aplica a todos los montos: totales, bases imponibles, IVA, precios unitarios.
• Fechas en formato yyyy-mm-dd. Por ejemplo, issue_date: "2026-09-29".
• CUITs como string de 11 dígitos, sin guiones. Por ejemplo, "20111111112".
• Códigos de ARCA como números o strings, según el catálogo. Salen de GET /catalogs/*, ver Catálogos por campo.

Paginación

Los endpoints de listado aceptan page (empieza en 1, por defecto 1) y size (por defecto 20, máximo 100). Un size mayor se recorta a 100, no se rechaza.

curl "$API_URL/invoices?page=2&size=50" -H "Authorization: Bearer $TOKEN"

La respuesta separa los datos de la metadata:

{
  "data": [
    { "id": "…", "status": "APPROVED", "…": "…" }
  ],
  "meta": {
    "current_page": 2,
    "total_pages": 3,
    "page_size": 50,
    "total_elements": 142
  }
}

Los items de un listado son una versión resumida del recurso. Para el objeto completo, usá el endpoint por id (por ejemplo, GET /invoices/{id}).

Creación de recursos

Un POST que crea un recurso responde 201 con el objeto completo y un header Location con su URL:

HTTP/1.1 201 Created
Location: /invoices/5f0c8a1e-…
Content-Type: application/json

POST /invoices/{id}/retry también crea un recurso: el reintento es un comprobante nuevo, con su propio id. El original queda como estaba.

Errores

Todos los errores usan RFC 7807 (Content-Type: application/problem+json) más un campo code propio:

{
  "type": "https://errors.arca-invoicing-service.internal/api",
  "title": "Api",
  "status": 404,
  "detail": "Comprobante no encontrado",
  "instance": "/invoices/abc",
  "code": 40401015
}

• code es estable: identifica un error puntual y nunca se reutiliza. Usalo para manejar errores en tu código.
• detail es para personas: es un texto legible que puede cambiar de redacción. No lo compares como string.

El code se compone del status HTTP, un número de API y un número de error (40401015 es status 404, API 01, error 015). El listado completo está en el catálogo de errores, y cada endpoint de la referencia muestra los que puede devolver.

Los errores de validación del body (campos faltantes o con el tipo incorrecto) responden 400 sin code propio. En ese caso, el array errors trae un mensaje por cada problema encontrado:

{
  "type": "https://errors.arca-invoicing-service.internal/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "letter must be one of the following values: A, B, C, M, E, T; salesPointNumber must be an integer number",
  "instance": "/invoices",
  "errors": [
    "letter must be one of the following values: A, B, C, M, E, T",
    "salesPointNumber must be an integer number"
  ]
}

Estos mensajes están en inglés y son para diagnóstico: mostralos en tus logs, pero no los parsees.

Errores relacionados con ARCA

Hay dos situaciones distintas, y conviene tratarlas por separado:

Situación	Respuesta	Qué hacer
ARCA procesó el comprobante y lo rechazó u observó	201 con status: "REJECTED" u "OBSERVED" y el detalle en provider_errors	Corregir según provider_errors (ver Emitir comprobantes).
La operación con ARCA no se pudo completar	500 con code 50001044, 50001045 o 50001046	50001045 y 50001046 son transitorios: reintentá con backoff. 50001044 indica que ARCA rechazó la operación: revisá los datos antes de reintentar.

En los 500 el detail es siempre un texto fijo: el detalle técnico queda en los logs de Berlinesa. Si necesitás soporte, mandá el code, el instance y la hora del request.

Rate limiting

100 requests cada 60 segundos. Pasado el límite, la API responde 429 Too Many Requests: esperá y reintentá.