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

  1. Creá tu cuenta en SimpleArca y elegí un plan, o usá la prueba gratis. La API está en todos los planes, sin costo extra.
  2. 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.
  3. 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

FormatoJSON en los pedidos y en las respuestas. Mandá Content-Type: application/json y Accept: application/json.
FechasAAAA-MM-DD, por ejemplo 2026-10-15.
ImportesNúmeros con punto decimal: 1500.50. Hasta 2 decimales en precios.
CódigosTipos de comprobante, documento, IVA, moneda, etc. son los mismos códigos de ARCA. Están todos en GET /parametros.
EntornoCon 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.
CupoCada 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ímite120 pedidos por minuto por clave. Si lo superás, la respuesta es 429 con el encabezado Retry-After.
ListadosVienen paginados: los resultados en data, y la paginación en links y meta. Usá ?page=2 y ?por_pagina=50 (máximo 100).
TiemposLa 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 basehttps://sandbox.simplearca.com/api/v1
ClaveUna 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.
EmisorUna 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

CampoQué es
referencia_externaOpcional, hasta 100 caracteres. Tu identificador (número de pedido, de venta, etc.). Evita emitir dos veces lo mismo: ver referencia externa. Muy recomendado.
itemsObligatorio. 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_ivaOpcional, 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_idOpcional. Id de un cliente guardado: se usan sus datos como receptor.
doc_tipo80 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_nroNúmero de documento, con o sin guiones.
receptor_condicion_ivaCondició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_nombreNombre 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_emailOpcionales.
concepto1 productos (por defecto), 2 servicios, 3 productos y servicios.
fechaPor 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_pagoObligatorias para servicios (concepto 2 o 3): período facturado y vencimiento del pago.
condicion_ventaContado (por defecto), Transferencia bancaria, Tarjeta de débito, Tarjeta de crédito, Cuenta corriente, Mercado Pago u Otra.
moneda, cotizacion, canc_misma_monedaMoneda 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.
tributosOpcional, 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_referenciaPara 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.
observacionesOpcional, hasta 500 caracteres. Nota interna que se ve en tu cuenta.

Qué tipo de factura se emite

Tu condiciónClienteComprobante
Monotributista o exentoCualquieraFactura C (precios finales, sin discriminar IVA)
Responsable InscriptoResponsable Inscripto o monotributistaFactura A (exige CUIT del cliente)
Responsable InscriptoConsumidor final, exento y el restoFactura 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.

CampoQué es
itemsLo 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_totalSolo 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_ivaIgual que en la factura.
tributosOpcional, igual que en la factura.
fce_anulacionSolo en nota de crédito de una FCE que el comprador rechazó en ARCA.
referencia_externa, observacionesIgual 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.

CampoQué es
receptor_nombre, receptor_domicilioObligatorios. Nombre y domicilio del cliente del exterior. receptor_email opcional.
paisObligatorio. Código de país de destino de ARCA (GET /parametros/paises).
cuit_pais o id_impositivoUno de los dos: el CUIT genérico del país (de la misma tabla) o la identificación tributaria del cliente.
tipo_expo1 bienes, 2 servicios, 4 otros.
permiso_existente, permisosSolo 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_monedaMoneda obligatoria; si no mandás cotización, usamos la oficial de ARCA.
fecha, fecha_pagoFecha por defecto hoy. fecha_pago obligatoria en servicios y otros.
idioma1 español (por defecto), 2 inglés, 3 portugués.
incoterms, incoterms_ds, forma_pago, obs_comerciales, observacionesOpcionales.
itemsCada uno con descripcion, cantidad, umed (unidad de ARCA; 7 = unidades), precio_unitario y bonificacion opcional.
referencia_externaIgual 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}.
CampoQué es
nombrePara reconocerla, por ejemplo "Abono mensual de Juan".
cliente_idId de un cliente guardado; sin él, a consumidor final sin identificar.
concepto, condicion_ventaComo en la factura.
frecuencia_meses1, 2, 3, 6 o 12.
primera_emisionFecha 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_vencimientoPara 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"}.
itemsComo 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."] }
}
HTTPcodeQué pasó y qué hacer
401clave_invalidaFalta la clave, está mal copiada o fue revocada.
402suscripcion_inactivaNo hay plan activo ni prueba gratis. Se resuelve desde SimpleArca → Suscripción.
402cupo_agotadoSe usaron todos los comprobantes del mes. Se puede sumar un pack o cambiar de plan desde SimpleArca.
402extra_no_contratadoFacturas automáticas sin el extra contratado.
403cuenta_suspendidaLa cuenta está suspendida. Escribinos.
404no_encontradoEl comprobante, cliente o ruta no existe o no es de tu cuenta.
409cuit_no_conectadoTu CUIT todavía no está conectado con ARCA. Se conecta desde SimpleArca.
409certificado_vencidoVenció la conexión con ARCA (dura 2 años). Se renueva desde SimpleArca → Mi negocio.
409punto_venta_pendienteLa clave tiene un punto de venta propio que todavía no está listo en ARCA. Reintentá en unos minutos.
409emision_en_cursoSe está emitiendo otro comprobante del mismo tipo. Reintentá en unos segundos.
409exportacion_no_habilitada, padron_no_habilitadoFalta habilitar esa función en ARCA desde SimpleArca → Mi negocio.
409automatica_terminadaLa factura automática ya terminó: cambiá el final para reanudarla.
422datos_invalidosRevisá errors: falta un campo, un valor no es válido o ARCA dice otra cosa del cliente.
422rechazado_por_arcaARCA rechazó el comprobante. El motivo está en message y los códigos de ARCA en arca_codigos. No se usó número ni cupo.
422receptor_actualizadoARCA 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.
422error_arcaNo 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.
422no_admite_notasIntentaste asociar una nota a otra nota.
429demasiados_pedidosMás de 120 pedidos por minuto. Esperá lo que indica Retry-After.
502error_arcaARCA no respondió una consulta (padrón, cotización, países). Probá de nuevo en un rato.
500error_internoError 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

  1. 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.
  2. 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.
  3. Mandá el documento del comprador si lo pediste en el checkout. Si no, la factura sale a consumidor final sin identificar.
  4. 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).
  5. 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.
  6. 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

RutaPara qué
GET /cuentaNegocio, plan y cupo
GET /parametrosTablas de códigos
GET /parametros/paisesPaí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 /comprobantesListar comprobantes
POST /comprobantesEmitir factura A, B, C o FCE
POST /comprobantes/simularValidar y calcular sin emitir
POST /comprobantes/exportacionEmitir Factura E
GET /comprobantes/{id}Ver un comprobante
GET /comprobantes/{id}/pdfDescargar el PDF
POST /comprobantes/{id}/nota-de-creditoAnular total o parcialmente
POST /comprobantes/{id}/nota-de-debitoSumar un importe
GET · POST /clientesListar y crear clientes
GET · PUT · DELETE /clientes/{id}Ver, editar y borrar un cliente
GET · POST /automaticasListar y crear facturas automáticas
GET · PUT · DELETE /automaticas/{id}Ver, editar y borrar una automática
POST /automaticas/{id}/pausar · /reanudarPausar o reanudar
GET /automaticas/{id}/comprobantesLo que emitió una automática

¿Dudas o algo que te falta para tu integración? Escribinos a hola@simplearca.com.