API de SimpleArca
Facturá con ARCA desde tu tienda online, tu sistema de gestión o cualquier software que programes. La API usa tu misma cuenta, tu mismo CUIT y el mismo cupo de comprobantes, y está incluida en todos los planes.
Versión 1 · URL base https://simplearca.com/api/v1
1. Antes de empezar
- Creá tu cuenta en SimpleArca y elegí un plan, o usá la prueba gratis. La API está en todos los planes, sin costo extra.
- Conectá tu CUIT con ARCA desde SimpleArca (menú Conectar CUIT). La conexión se hace siempre desde la web: la API no pide ni recibe tu clave fiscal.
- Creá una clave de API en API, dentro de tu cuenta. Se muestra una sola vez: copiala y guardala en tu sistema.
Lo que emitas por la API aparece en tu cuenta de SimpleArca junto con lo que emitís desde la web, cuenta para el mismo cupo mensual y usa el mismo punto de venta.
2. Autenticación
Mandá la clave en el encabezado Authorization de cada pedido:
Authorization: Bearer sa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Para probar que funciona:
curl https://simplearca.com/api/v1/cuenta \ -H "Authorization: Bearer $SIMPLEARCA_API_KEY"
- La clave permite facturar con tu CUIT. Usala solo desde tu servidor. Nunca la pongas en el JavaScript de una página web ni en una app que se instale en el celular de tus clientes.
- Creá una clave por sistema (por ejemplo, una para la tienda y otra para el sistema de gestión). Si una deja de usarse o se filtra, la revocás sin afectar a las otras.
- Una clave revocada deja de funcionar al instante. Podés tener hasta 10 claves activas.
3. Cómo funciona la API
| Formato | JSON en los pedidos y en las respuestas. Mandá Content-Type: application/json y Accept: application/json. |
|---|---|
| Fechas | AAAA-MM-DD, por ejemplo 2026-10-15. |
| Importes | Números con punto decimal: 1500.50. Hasta 2 decimales en precios. |
| Códigos | Tipos de comprobante, documento, IVA, moneda, etc. son los mismos códigos de ARCA. Están todos en GET /parametros. |
| Entorno | Con tu cuenta, los comprobantes son reales: tienen CAE de ARCA y validez fiscal. Para probar tu integración sin emitir comprobantes reales, usá el entorno de pruebas. El campo entorno de cada comprobante dice produccion u homologacion. |
| Cupo | Cada factura y nota que emitís cuenta para el cupo de tu plan, igual que desde la web. Consultá lo que te queda en GET /cuenta. |
| Límite | 120 pedidos por minuto por clave. Si lo superás, la respuesta es 429 con el encabezado Retry-After. |
| Listados | Vienen paginados: los resultados en data, y la paginación en links y meta. Usá ?page=2 y ?por_pagina=50 (máximo 100). |
| Tiempos | La emisión es en el momento: la respuesta trae el CAE. Puede tardar algunos segundos según ARCA; usá un tiempo de espera de al menos 60 segundos. |
Entorno de pruebas (sandbox)
Mientras programás tu integración podés usar el sandbox: funciona igual que la API real, pero emite en homologación de ARCA, el entorno de pruebas oficial. Los comprobantes salen con un CAE de prueba, no tienen validez fiscal y no usan el cupo de tu plan.
| URL base | https://sandbox.simplearca.com/api/v1 |
|---|---|
| Clave | Una clave de pruebas aparte, que te damos nosotros: pedila por contacto contando qué vas a integrar. Las claves de pruebas no funcionan en la API real, ni las reales en el sandbox. |
| Emisor | Una empresa de prueba monotributista, así que se emiten Facturas C y sus notas. El resto de la API (clientes, simulación, PDF, notas, referencia externa, errores) responde igual que en la real. |
Cuando todo funcione, cambiá la URL base por https://simplearca.com/api/v1 y la clave por una creada en tu cuenta. No hace falta cambiar nada más.
4. Tu primera factura en un minuto
Una venta a un consumidor final sin identificar. El tipo de factura (A, B o C) se elige solo según tu condición frente al IVA y la del cliente:
curl https://simplearca.com/api/v1/comprobantes \
-H "Authorization: Bearer $SIMPLEARCA_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"referencia_externa": "pedido-1001",
"precios_incluyen_iva": true,
"items": [
{ "descripcion": "Remera algodón talle M", "cantidad": 2, "precio_unitario": 15000 }
]
}'
Si salió bien, la respuesta es 201 con el comprobante autorizado, su CAE y el enlace al PDF. Lo que no mandaste toma un valor por defecto: concepto Productos, fecha de hoy, condición de venta Contado y moneda pesos.
5. Emitir una factura
POST /comprobantes emite una Factura A, B o C (o una A con leyenda "Operación sujeta a retención" si ARCA te la asignó), y también la Factura de Crédito Electrónica MiPyME. Para exportación usá la ruta de Factura E.
Campos
| Campo | Qué es |
|---|---|
| referencia_externa | Opcional, hasta 100 caracteres. Tu identificador (número de pedido, de venta, etc.). Evita emitir dos veces lo mismo: ver referencia externa. Muy recomendado. |
| items | Obligatorio. De 1 a 50 ítems, cada uno con descripcion (hasta 190 caracteres), cantidad (mayor a 0), precio_unitario (mayor a 0) e iva_id (solo en A y B; por defecto 5 = 21%). |
| precios_incluyen_iva | Opcional, por defecto false. En Factura A y B el precio que va a ARCA es sin IVA. Si tus precios ya tienen el IVA incluido (lo normal en una tienda), mandá true y lo descontamos por vos. En Factura C no cambia nada. |
| cliente_id | Opcional. Id de un cliente guardado: se usan sus datos como receptor. |
| doc_tipo | 80 CUIT, 86 CUIL, 96 DNI, 99 sin identificar. Si mandás doc_nro sin tipo: con 11 números es CUIT y con menos es DNI. Sin documento, es consumidor final sin identificar. |
| doc_nro | Número de documento, con o sin guiones. |
| receptor_condicion_iva | Condición frente al IVA del cliente (5 consumidor final, 1 responsable inscripto, 6 monotributo, 4 exento… ver /parametros). Si no la mandás y el documento está en ARCA, se completa con lo que dice ARCA. Con DNI que no está en ARCA, consumidor final. |
| receptor_nombre | Nombre o razón social. Obligatorio si el cliente está identificado, salvo que ARCA lo tenga: en ese caso se usa el de ARCA. |
| receptor_domicilio, receptor_email | Opcionales. |
| concepto | 1 productos (por defecto), 2 servicios, 3 productos y servicios. |
| fecha | Por defecto, hoy. ARCA acepta hasta 5 días antes o después para productos y 10 para servicios, y nunca anterior al último comprobante del mismo tipo. |
| fch_serv_desde, fch_serv_hasta, fch_vto_pago | Obligatorias para servicios (concepto 2 o 3): período facturado y vencimiento del pago. |
| condicion_venta | Contado (por defecto), Transferencia bancaria, Tarjeta de débito, Tarjeta de crédito, Cuenta corriente, Mercado Pago u Otra. |
| moneda, cotizacion, canc_misma_moneda | Moneda con el código de ARCA (PES por defecto, DOL dólar, 060 euro…). En moneda extranjera, si no mandás cotizacion usamos la oficial de ARCA del día. canc_misma_moneda: true si te pagan en esa misma moneda. |
| tributos | Opcional, hasta 10: percepciones y otros tributos que se suman al total. Cada uno con id, desc, base_imp, alic e importe. |
| fce, fce_cbu, fce_alias, fce_transferencia, fce_referencia | Para Factura de Crédito MiPyME: fce: true, el CBU de 22 números donde te pagan, alias opcional, sistema de transferencia (SCA o ADC) y una referencia comercial opcional. Requiere receptor con CUIT y fch_vto_pago. |
| observaciones | Opcional, hasta 500 caracteres. Nota interna que se ve en tu cuenta. |
Qué tipo de factura se emite
| Tu condición | Cliente | Comprobante |
|---|---|---|
| Monotributista o exento | Cualquiera | Factura C (precios finales, sin discriminar IVA) |
| Responsable Inscripto | Responsable Inscripto o monotributista | Factura A (exige CUIT del cliente) |
| Responsable Inscripto | Consumidor final, exento y el resto | Factura B |
Antes de emitir verificamos en ARCA la condición frente al IVA del cliente identificado. Si no coincide, la respuesta es un error 422 que dice qué condición tiene según ARCA. Si ARCA rechaza la factura por los datos del cliente y con los datos actuales la letra no cambia, la emitimos con los datos corregidos y lo avisamos en el campo aviso; si la letra cambia, no la emitimos y respondemos receptor_actualizado con los datos nuevos para que la reintentes.
Ejemplos
Factura B a un consumidor final con DNI, con precios con IVA incluido y pago con Mercado Pago:
{
"referencia_externa": "pedido-1002",
"doc_nro": "30111222",
"receptor_nombre": "Ana Pérez",
"receptor_email": "ana@example.com",
"condicion_venta": "Mercado Pago",
"precios_incluyen_iva": true,
"items": [
{ "descripcion": "Zapatillas running 42", "cantidad": 1, "precio_unitario": 89990 },
{ "descripcion": "Envío", "cantidad": 1, "precio_unitario": 4500 }
]
}
Factura A a una empresa, solo con su CUIT: el nombre y la condición frente al IVA se completan con ARCA. Precios sin IVA, con un ítem al 10,5%:
{
"referencia_externa": "venta-5531",
"doc_tipo": 80,
"doc_nro": "30-71234567-1",
"condicion_venta": "Transferencia bancaria",
"items": [
{ "descripcion": "Notebook 15 pulgadas", "cantidad": 2, "precio_unitario": 650000, "iva_id": 5 },
{ "descripcion": "Libro técnico", "cantidad": 1, "precio_unitario": 30000, "iva_id": 4 }
]
}
Servicios del mes a un monotributista:
{
"doc_nro": "20304050609",
"receptor_condicion_iva": 6,
"concepto": 2,
"fch_serv_desde": "2026-10-01",
"fch_serv_hasta": "2026-10-31",
"fch_vto_pago": "2026-11-10",
"items": [ { "descripcion": "Abono mantenimiento web octubre", "cantidad": 1, "precio_unitario": 120000 } ]
}
En dólares, con la cotización oficial de ARCA y cobro en la misma moneda:
{
"doc_nro": "30712345671",
"moneda": "DOL",
"canc_misma_moneda": true,
"items": [ { "descripcion": "Licencia anual", "cantidad": 1, "precio_unitario": 1200 } ]
}
6. No facturar dos veces: referencia externa
Si mandás referencia_externa y ya existe un comprobante con esa referencia en tu cuenta (en el mismo entorno de ARCA), no se emite otro: la API devuelve el que ya existe con código 200 y "repetido": true. Una emisión nueva responde 201 y "repetido": false.
Así podés reintentar sin miedo cuando se corta la conexión, vence el tiempo de espera o tu sistema procesa dos veces el mismo pedido. Si llegan dos pedidos con la misma referencia al mismo tiempo, el segundo espera al primero.
- La referencia es única entre todos tus comprobantes, también las notas. Para la nota de crédito de un pedido usá otra, por ejemplo pedido-1001-nc.
- Si la referencia ya existe se devuelve el comprobante tal cual, aunque los datos del pedido nuevo sean distintos.
- Podés buscar por referencia con GET /comprobantes?referencia_externa=pedido-1001.
7. El comprobante que devuelve la API
{
"data": {
"id": 4821,
"tipo": 6,
"tipo_nombre": "Factura B",
"letra": "B",
"clase": "factura",
"fce": false,
"exportacion": false,
"punto_venta": 3,
"numero": 1532,
"numero_completo": "00003-00001532",
"fecha": "2026-10-15",
"cae": "76412345678901",
"cae_vencimiento": "2026-10-25",
"entorno": "produccion",
"concepto": 1,
"receptor": {
"cliente_id": 210,
"doc_tipo": 96,
"doc_nro": "30111222",
"nombre": "Ana Pérez",
"condicion_iva": 5,
"condicion_iva_nombre": "Consumidor Final",
"domicilio": null,
"email": "ana@example.com"
},
"fch_serv_desde": null,
"fch_serv_hasta": null,
"fch_vto_pago": null,
"condicion_venta": "Mercado Pago",
"moneda": "PES",
"cotizacion": 1,
"importes": {
"neto": 78090.91, "iva": 16399.09, "exento": 0, "no_gravado": 0, "tributos": 0, "total": 94490
},
"alicuotas_iva": [ { "iva_id": 5, "base": 78090.91, "importe": 16399.09 } ],
"tributos": [],
"items": [
{ "descripcion": "Zapatillas running 42", "cantidad": 1, "precio_unitario": 74371.9,
"iva_id": 5, "subtotal": 74371.9, "iva_importe": 15618.1 },
{ "descripcion": "Envío", "cantidad": 1, "precio_unitario": 3719.01,
"iva_id": 5, "subtotal": 3719.01, "iva_importe": 780.99 }
],
"exportacion_datos": null,
"observaciones": null,
"comprobante_asociado_id": null,
"saldo": {
"acreditado": 0, "debitado": 0, "disponible_para_nota_de_credito": 94490, "estado": "vigente"
},
"referencia_externa": "pedido-1002",
"origen": "api",
"aviso": null,
"qr_url": "https://www.arca.gob.ar/fe/qr/?p=eyJ2ZXIiOjEs...",
"pdf_url": "https://simplearca.com/api/v1/comprobantes/4821/pdf",
"creado": "2026-10-15T11:42:10-03:00"
},
"repetido": false
}
- Guardá en tu sistema el id, el numero_completo y el cae.
- clase es factura, nota_de_credito o nota_de_debito.
- saldo solo viene en facturas: cuánto se anuló con notas de crédito, cuánto se sumó con notas de débito y cuánto queda para anular. estado es vigente, anulada_parcialmente o anulada.
- Con precios_incluyen_iva el total puede diferir en un centavo del precio final por el redondeo de ARCA (el IVA se redondea por alícuota).
- pdf_url pide la misma clave de API: no lo compartas tal cual con tu cliente. Descargá el PDF desde tu servidor y mandalo o guardalo vos.
8. Simular sin emitir
POST /comprobantes/simular recibe lo mismo que POST /comprobantes y hace todas las validaciones, incluida la verificación del cliente en ARCA, pero no emite ni usa cupo. Devuelve el tipo de comprobante que correspondería, los datos del receptor y los importes calculados. Sirve para mostrar el detalle antes de confirmar o para probar tu integración.
{
"data": {
"tipo": 1, "tipo_nombre": "Factura A", "letra": "A",
"receptor": { "doc_tipo": 80, "doc_nro": "30712345671", "nombre": "EMPRESA SA",
"condicion_iva": 1, "domicilio": "AV. CORRIENTES 1234, CABA", "verificado_en_arca": true },
"moneda": "PES", "cotizacion": 1,
"importes": { "neto": 1330000, "iva": 276150, "exento": 0, "no_gravado": 0, "tributos": 0, "total": 1606150 },
"alicuotas_iva": [ { "iva_id": 5, "base": 1300000, "importe": 273000 }, { "iva_id": 4, "base": 30000, "importe": 3150 } ],
"items": [ ... ]
}
}
9. Consultar comprobantes y descargar el PDF
- GET /comprobantes: tus comprobantes del entorno actual, del más nuevo al más viejo. Filtros opcionales: desde y hasta (fecha del comprobante), tipo, doc_nro, cliente_id, referencia_externa, por_pagina y page.
- GET /comprobantes/{id}: un comprobante, emitido por la API o desde la web.
- GET /comprobantes/{id}/pdf: el PDF con el QR fiscal de ARCA (application/pdf).
curl "https://simplearca.com/api/v1/comprobantes?desde=2026-10-01&hasta=2026-10-31&por_pagina=100" \ -H "Authorization: Bearer $SIMPLEARCA_API_KEY" -H "Accept: application/json" curl https://simplearca.com/api/v1/comprobantes/4821/pdf \ -H "Authorization: Bearer $SIMPLEARCA_API_KEY" -o factura.pdf
10. Notas de crédito y de débito
Se emiten siempre asociadas a una factura: POST /comprobantes/{id}/nota-de-credito y POST /comprobantes/{id}/nota-de-debito. Llevan el mismo cliente, concepto, moneda y letra que la factura. Sirven para facturas comunes, FCE y Factura E.
| Campo | Qué es |
|---|---|
| items | Lo que se anula (crédito) o se suma (débito), con el mismo formato que en la factura. En Factura E, cada ítem lleva umed en vez de iva_id. |
| anular_total | Solo nota de crédito. Con true y sin items, anula la factura completa con sus mismos ítems. Solo si la factura todavía no tiene notas. |
| precios_incluyen_iva | Igual que en la factura. |
| tributos | Opcional, igual que en la factura. |
| fce_anulacion | Solo en nota de crédito de una FCE que el comprador rechazó en ARCA. |
| referencia_externa, observaciones | Igual que en la factura. |
La nota de crédito no puede superar el saldo de la factura (saldo.disponible_para_nota_de_credito). Si terminó tu prueba gratis y no te suscribiste, durante 30 días podés seguir anulando con notas de crédito lo que emitiste en la prueba.
# Se canceló el pedido 1002: anular la factura completa
curl https://simplearca.com/api/v1/comprobantes/4821/nota-de-credito \
-H "Authorization: Bearer $SIMPLEARCA_API_KEY" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{ "referencia_externa": "pedido-1002-nc", "anular_total": true }'
# Devolvieron solo el envío: nota de crédito parcial con precio con IVA
-d '{ "referencia_externa": "pedido-1002-nc-envio", "precios_incluyen_iva": true,
"items": [ { "descripcion": "Devolución envío", "cantidad": 1, "precio_unitario": 4500 } ] }'
11. Factura E de exportación
POST /comprobantes/exportacion. Primero tenés que habilitarla desde SimpleArca en Mi negocio → Comprobantes (es un trámite aparte en ARCA). No lleva IVA y usa su propio punto de venta.
| Campo | Qué es |
|---|---|
| receptor_nombre, receptor_domicilio | Obligatorios. Nombre y domicilio del cliente del exterior. receptor_email opcional. |
| pais | Obligatorio. Código de país de destino de ARCA (GET /parametros/paises). |
| cuit_pais o id_impositivo | Uno de los dos: el CUIT genérico del país (de la misma tabla) o la identificación tributaria del cliente. |
| tipo_expo | 1 bienes, 2 servicios, 4 otros. |
| permiso_existente, permisos | Solo bienes: S o N, y la lista de permisos de embarque (id de 16 caracteres y dst país de destino opcional). |
| moneda, cotizacion, canc_misma_moneda | Moneda obligatoria; si no mandás cotización, usamos la oficial de ARCA. |
| fecha, fecha_pago | Fecha por defecto hoy. fecha_pago obligatoria en servicios y otros. |
| idioma | 1 español (por defecto), 2 inglés, 3 portugués. |
| incoterms, incoterms_ds, forma_pago, obs_comerciales, observaciones | Opcionales. |
| items | Cada uno con descripcion, cantidad, umed (unidad de ARCA; 7 = unidades), precio_unitario y bonificacion opcional. |
| referencia_externa | Igual que en la factura. |
{
"referencia_externa": "expo-2026-118",
"receptor_nombre": "ACME LLC",
"receptor_domicilio": "100 Main St, Miami, FL",
"pais": 212,
"id_impositivo": "12-3456789",
"tipo_expo": 2,
"moneda": "DOL",
"canc_misma_moneda": true,
"fecha_pago": "2026-11-15",
"idioma": 2,
"items": [ { "descripcion": "Software development services", "cantidad": 1, "umed": 7, "precio_unitario": 3500 } ]
}
12. Clientes
Los clientes se guardan solos cada vez que emitís a alguien identificado. También podés manejarlos por la API:
- GET /clientes: listado, con búsqueda q (nombre o documento) o doc_nro exacto.
- POST /clientes: crea uno con doc_tipo (80, 86 o 96), doc_nro, receptor_nombre, receptor_condicion_iva y, opcionales, receptor_domicilio y receptor_email. Si ARCA tiene el documento, se guardan el nombre y domicilio de ARCA y se verifica la condición frente al IVA.
- GET /clientes/{id}, PUT /clientes/{id} (solo cambia lo que mandás) y DELETE /clientes/{id} (sus facturas no se borran).
13. Datos de ARCA: padrón y cotización
- GET /padron/{documento}: nombre, domicilio y condición frente al IVA de un CUIT, CUIL o DNI según ARCA. Con 11 números se toma como CUIT; para CUIL mandá ?doc_tipo=86. Requiere que la consulta esté habilitada para tu CUIT (se habilita al conectar o desde Mi negocio).
- GET /cotizacion/{moneda}: cotización oficial de ARCA, por ejemplo /cotizacion/DOL.
{ "data": { "cuit": "30712345671", "nombre": "EMPRESA SA", "domicilio": "AV. CORRIENTES 1234, CABA",
"condicion_iva": 1, "condicion_iva_nombre": "IVA Responsable Inscripto", "condiciones_posibles": [1] } }
{ "data": { "moneda": "DOL", "cotizacion": 1045.5, "fecha": "2026-10-14" } }
14. Facturas automáticas
Si tenés el extra Facturas automáticas, podés programar facturas que se emiten solas cada 1, 2, 3, 6 o 12 meses. Sin el extra, estas rutas responden 402 con el código extra_no_contratado.
- GET /automaticas, GET /automaticas/{id} y GET /automaticas/{id}/comprobantes (lo que ya emitió).
- POST /automaticas y PUT /automaticas/{id} (solo cambia lo que mandás).
- POST /automaticas/{id}/pausar, POST /automaticas/{id}/reanudar y DELETE /automaticas/{id}.
| Campo | Qué es |
|---|---|
| nombre | Para reconocerla, por ejemplo "Abono mensual de Juan". |
| cliente_id | Id de un cliente guardado; sin él, a consumidor final sin identificar. |
| concepto, condicion_venta | Como en la factura. |
| frecuencia_meses | 1, 2, 3, 6 o 12. |
| primera_emision | Fecha de la primera factura, de hoy a un año, con día del 1 al 28. Las siguientes salen el mismo día. |
| dias_vencimiento | Para servicios: días hasta el vencimiento del pago (0 a 60). |
| termina | {"tipo": "nunca"}, {"tipo": "cantidad", "cantidad": 12} o {"tipo": "fecha", "fecha": "2027-12-31"}. |
| items | Como en la factura; precios sin IVA si sos Responsable Inscripto. |
15. Tu cuenta y las tablas de códigos
GET /cuenta devuelve tu negocio (CUIT, razón social, condición frente al IVA, punto de venta, entorno, si la exportación y la consulta al padrón están habilitadas), tu plan y el cupo del mes. Antes de facturar, plan.puede_facturar te dice si la cuenta está lista.
{
"data": {
"usuario": { "nombre": "Juan García", "email": "juan@mitienda.com" },
"negocio": {
"cuit": "20304050609", "razon_social": "GARCIA JUAN", "nombre_fantasia": "Mi Tienda",
"condicion_iva": "responsable_inscripto", "condicion_iva_nombre": "Responsable Inscripto",
"domicilio": "Calle Falsa 123", "cuit_conectado": true, "entorno": "produccion",
"punto_venta": 3, "punto_venta_exportacion": null, "exportacion_habilitada": false,
"consulta_padron_habilitada": true, "certificado_vence": "2028-09-30"
},
"plan": { "nombre": "Pro", "estado": "Plan Pro · Activa", "puede_facturar": true, "facturas_automaticas": false },
"cupo": { "mes": "octubre 2026", "usados": 132, "limite": 500, "disponibles": 368, "prueba_gratis": false },
"clave": { "nombre": "Tienda online", "prefijo": "sa_live_Ab3x…" }
}
}
GET /parametros devuelve todas las tablas de códigos: tipos de comprobante, condiciones frente al IVA, tipos de documento, conceptos, opciones de IVA por ítem, condiciones de venta, monedas, tributos, y las de exportación (tipos, Incoterms, idiomas y unidades). GET /parametros/paises trae de ARCA los países de destino y sus CUIT genéricos.
16. Errores
Los errores responden siempre con un código HTTP y un JSON con message (un texto que se le puede mostrar al usuario) y code (para que tu sistema decida qué hacer). Los errores de datos traen además errors con los mensajes por campo:
{
"message": "Para Factura A el cliente tiene que identificarse con CUIT.",
"code": "datos_invalidos",
"errors": { "doc_tipo": ["Para Factura A el cliente tiene que identificarse con CUIT."] }
}
| HTTP | code | Qué pasó y qué hacer |
|---|---|---|
| 401 | clave_invalida | Falta la clave, está mal copiada o fue revocada. |
| 402 | suscripcion_inactiva | No hay plan activo ni prueba gratis. Se resuelve desde SimpleArca → Suscripción. |
| 402 | cupo_agotado | Se usaron todos los comprobantes del mes. Se puede sumar un pack o cambiar de plan desde SimpleArca. |
| 402 | extra_no_contratado | Facturas automáticas sin el extra contratado. |
| 403 | cuenta_suspendida | La cuenta está suspendida. Escribinos. |
| 404 | no_encontrado | El comprobante, cliente o ruta no existe o no es de tu cuenta. |
| 409 | cuit_no_conectado | Tu CUIT todavía no está conectado con ARCA. Se conecta desde SimpleArca. |
| 409 | certificado_vencido | Venció la conexión con ARCA (dura 2 años). Se renueva desde SimpleArca → Mi negocio. |
| 409 | punto_venta_pendiente | La clave tiene un punto de venta propio que todavía no está listo en ARCA. Reintentá en unos minutos. |
| 409 | emision_en_curso | Se está emitiendo otro comprobante del mismo tipo. Reintentá en unos segundos. |
| 409 | exportacion_no_habilitada, padron_no_habilitado | Falta habilitar esa función en ARCA desde SimpleArca → Mi negocio. |
| 409 | automatica_terminada | La factura automática ya terminó: cambiá el final para reanudarla. |
| 422 | datos_invalidos | Revisá errors: falta un campo, un valor no es válido o ARCA dice otra cosa del cliente. |
| 422 | rechazado_por_arca | ARCA rechazó el comprobante. El motivo está en message y los códigos de ARCA en arca_codigos. No se usó número ni cupo. |
| 422 | receptor_actualizado | ARCA tiene otros datos del cliente y con ellos cambia la letra de la factura. En receptor vienen los datos actualizados: revisalos y reintentá con ellos. |
| 422 | error_arca | No se pudo completar con ARCA: un dato que ARCA no acepta o una falla de comunicación. Leé message; si es de comunicación, reintentá con la misma referencia_externa. |
| 422 | no_admite_notas | Intentaste asociar una nota a otra nota. |
| 429 | demasiados_pedidos | Más de 120 pedidos por minuto. Esperá lo que indica Retry-After. |
| 502 | error_arca | ARCA no respondió una consulta (padrón, cotización, países). Probá de nuevo en un rato. |
| 500 | error_interno | Error nuestro. Reintentá con la misma referencia y, si sigue, escribinos. |
Si se corta la conexión mientras ARCA autoriza un comprobante, SimpleArca lo recupera de ARCA en vez de pedir otro número: reintentar con la misma referencia_externa nunca duplica.
17. Guía para tiendas online
Flujo recomendado
- Al configurar la integración, el comercio pega su clave en tu sistema. Llamá a GET /cuenta para verificarla y mostrar su razón social, CUIT, condición frente al IVA y entorno. Si plan.puede_facturar es false, explicale qué le falta.
- Cuando un pedido queda pagado (o cuando el comercio aprieta "Facturar", si prefiere hacerlo a mano), mandá POST /comprobantes con referencia_externa igual al número del pedido y precios_incluyen_iva: true.
- Mandá el documento del comprador si lo pediste en el checkout. Si no, la factura sale a consumidor final sin identificar.
- Incluí el envío como un ítem más, y los descuentos restándolos del precio de cada ítem (los ítems no admiten importes negativos).
- Guardá en el pedido el id, el numero_completo y el cae. Descargá el PDF desde pdf_url en tu servidor para mandarlo por email o mostrarlo en la cuenta del comprador.
- Si se cancela o devuelve, emití una nota de crédito con anular_total: true (o con los ítems devueltos) y una referencia propia, como pedido-1001-nc.
Qué hacer con cada error
- Reintentá solo (con la misma referencia, esperando cada vez más) cuando se corta la conexión, vence el tiempo de espera o la respuesta es 409 emision_en_curso, 429, 500 o 502.
- Avisale al comercio y no reintentes solo con 402 (plan o cupo), 409 cuit_no_conectado o 409 certificado_vencido: se resuelven desde su cuenta de SimpleArca.
- Mostrá el mensaje en el pedido con 422: casi siempre es un dato del comprador (por ejemplo, una condición frente al IVA que no coincide con ARCA) que el comercio tiene que corregir antes de reintentar.
Ejemplo en PHP
$response = Http::withToken($apiKey)->acceptJson()->timeout(90)
->retry(3, 2000, fn ($e) => $e instanceof ConnectionException
|| in_array($e->response?->status(), [409, 429, 500, 502], true), throw: false)
->post('https://simplearca.com/api/v1/comprobantes', [
'referencia_externa' => 'pedido-'.$order->id,
'doc_nro' => $order->buyer_document, // null si no lo pediste
'receptor_nombre' => $order->buyer_name,
'receptor_email' => $order->buyer_email,
'condicion_venta' => 'Mercado Pago',
'precios_incluyen_iva' => true,
'items' => $order->lines->map(fn ($line) => [
'descripcion' => $line->name,
'cantidad' => $line->quantity,
'precio_unitario' => $line->unit_price, // con IVA y con el descuento aplicado
])->push(['descripcion' => 'Envío', 'cantidad' => 1, 'precio_unitario' => $order->shipping])->all(),
]);
if ($response->successful()) {
$order->update(['invoice_id' => $response['data']['id'], 'invoice_cae' => $response['data']['cae']]);
} else {
$order->update(['invoice_error' => $response['message'], 'invoice_error_code' => $response['code']]);
}
Ejemplo en JavaScript (Node.js)
const res = await fetch('https://simplearca.com/api/v1/comprobantes', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SIMPLEARCA_API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json',
},
body: JSON.stringify({
referencia_externa: `pedido-${order.id}`,
precios_incluyen_iva: true,
items: order.items.map(i => ({ descripcion: i.title, cantidad: i.qty, precio_unitario: i.price })),
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.message}`);
console.log(body.data.numero_completo, body.data.cae);
18. Resumen de rutas
| Ruta | Para qué |
|---|---|
| GET /cuenta | Negocio, plan y cupo |
| GET /parametros | Tablas de códigos |
| GET /parametros/paises | Países y CUIT de país para exportación |
| GET /padron/{documento} | Datos de un contribuyente en ARCA |
| GET /cotizacion/{moneda} | Cotización oficial de ARCA |
| GET /comprobantes | Listar comprobantes |
| POST /comprobantes | Emitir factura A, B, C o FCE |
| POST /comprobantes/simular | Validar y calcular sin emitir |
| POST /comprobantes/exportacion | Emitir Factura E |
| GET /comprobantes/{id} | Ver un comprobante |
| GET /comprobantes/{id}/pdf | Descargar el PDF |
| POST /comprobantes/{id}/nota-de-credito | Anular total o parcialmente |
| POST /comprobantes/{id}/nota-de-debito | Sumar un importe |
| GET · POST /clientes | Listar y crear clientes |
| GET · PUT · DELETE /clientes/{id} | Ver, editar y borrar un cliente |
| GET · POST /automaticas | Listar y crear facturas automáticas |
| GET · PUT · DELETE /automaticas/{id} | Ver, editar y borrar una automática |
| POST /automaticas/{id}/pausar · /reanudar | Pausar o reanudar |
| GET /automaticas/{id}/comprobantes | Lo que emitió una automática |
¿Dudas o algo que te falta para tu integración? Escribinos a hola@simplearca.com.