Guía de integración — arcafactura

arcafactura emite comprobantes electrónicos de ARCA (ex AFIP) por vos: login WSAA, numeración, CAE, reintentos e idempotencia. Tu app hace un POST por comprobante y recibe el CAE.

• URL base: https://arcafactura-dev-api.dp.casalox.com
• Autenticación: Authorization: Bearer <API_KEY> (las keys se crean en el portal → API keys).
• Formato: JSON. Fechas YYYY-MM-DD. Importes en la moneda del comprobante, con hasta 2 decimales.

Inicio rápido

1. API key: portal → API keys → Crear key. Se muestra una sola vez: guardala como secreto de tu app.
2. Certificado: portal → Certificados → subí el .crt y la .key de ARCA (uno por entorno). Así tu app no maneja el certificado.
3. Probá en homologación ("entorno": "homologacion"): no genera comprobantes reales.

curl -X POST https://arcafactura-dev-api.dp.casalox.com/v1/comprobantes \
  -H "Authorization: Bearer $ARCAFACTURA_API_KEY" \
  -H "Idempotency-Key: cobro-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "cuit": 20111111112, "entorno": "homologacion", "ptoVta": 1,
    "tipoComprobante": 11, "concepto": 1,
    "receptor": { "docTipo": 99, "docNro": 0, "condicionIvaId": 5 },
    "fecha": "2026-10-17", "moneda": "PES", "cotizacion": 1,
    "importes": { "neto": 1000, "total": 1000 }
  }'

Emitir un comprobante

POST /v1/comprobantes — headers Authorization e Idempotency-Key (obligatorio, ver la sección siguiente). Responde 201.

Reglas que valida la API antes de ir a ARCA:

• total = neto + noGravado + exento + Σiva + Σtributos (tolerancia de 1 centavo).
• Factura C (monotributo): sin iva. A y M: IVA discriminado por alícuota y receptor con CUIT (docTipo 80).
• Concepto 2 o 3: fechaServicioDesde, fechaServicioHasta y fechaVtoPago.
• ARCA exige la fecha cerca de hoy (±5 días productos, ±10 servicios) y no anterior al último comprobante de la serie.

Respuesta (201):

{
  "numero": 42, "cae": "86400952208054", "caeVencimiento": "2026-10-22",
  "resultado": "A", "resultadoDescripcion": "Aprobado",
  "ptoVta": 1, "tipoComprobante": 11, "letra": "C", "clase": "factura", "descripcion": "Factura C",
  "observaciones": []
}

Factura C de servicios a un CUIT (TypeScript):

// hoyAR(): fecha de hoy en Argentina, 'YYYY-MM-DD'
const r = await fetch('https://arcafactura-dev-api.dp.casalox.com/v1/comprobantes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ARCAFACTURA_API_KEY}`,
    'Idempotency-Key': cobro.idempotencyKey, // guardada junto al cobro: la misma en cada reintento
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    cuit: 20111111112, entorno: 'produccion', ptoVta: 2, tipoComprobante: 11, concepto: 2,
    receptor: { docTipo: 80, docNro: 30712345678, condicionIvaId: 1 },
    fecha: hoyAR(), fechaServicioDesde: '2026-10-01', fechaServicioHasta: '2026-10-31', fechaVtoPago: hoyAR(),
    moneda: 'PES', cotizacion: 1,
    importes: { neto: 15000, total: 15000 },
  }),
})
if (r.status === 503 || r.status >= 500) throw new Transitorio()   // reintentar con la MISMA key
const body = await r.json()
if (!r.ok) throw new Rechazado(body.code, body.message, body.observaciones)

Nota de crédito C que anula la factura 42: igual, con "tipoComprobante": 13 y "comprobantesAsoc": [{ "tipo": 11, "ptoVta": 2, "nro": 42 }] (ver Notas de crédito).

Letras según tu condición frente al IVA

La condición frente al IVA define qué comprobantes podés emitir. Se valida la de cada CUIT: la cargada en sus datos del emisor (condicionIva en PUT /v1/emisores/{cuit}, o Perfil → Datos para la factura) o, si ese CUIT no tiene, la de tu cuenta (se elige al registrarte y se cambia en Perfil). Así una persona física monotributista y una SRL responsable inscripta conviven en la misma cuenta:

Otra letra → 400 VALIDATION_ERROR en tipoComprobante, sin ir a ARCA. Como Responsable Inscripto: A si el receptor es Responsable Inscripto o Monotributista (condicionIvaId 1, 6, 13 o 16), B para el resto (consumidor final, exento…).

Notas de crédito

Una factura emitida no se borra ni se cancela: se anula con una nota de crédito de la misma letra que la referencie en comprobantesAsoc.

• Anular = nota de crédito por el total de la factura. Acreditar parcial = nota de crédito por una parte (devolución, descuento).
• La API controla el saldo de la factura: total − notas de crédito ya emitidas (aprobadas o en curso). Una nota que lo supere → 422 SALDO_INSUFICIENTE con el saldo que queda.
• Si la factura no se emitió por arcafactura, no hay saldo que controlar: ARCA valida solo que exista.
• Reintentar una nota con la misma Idempotency-Key y otro importe se controla igual (descontando lo que ya había reservado ese intento).
• Las notas de crédito no consumen el tope de facturación de la API key.

Límites de las API keys

Cada API key es de una cuenta: la tuya, o una cuenta creada que administrás (por ejemplo, la de un cliente o tu empresa; se crean en el portal, Cuentas). Creala con esa cuenta activa en el portal: todo lo que hagas con la key queda en esa cuenta, y deja de funcionar si dejás de ser su dueño.

Cada API key puede limitarse desde el portal (API keys):

• Entornos permitidos (por ejemplo, solo homologación). Fuera de ellos → 403 ENTORNO_NO_PERMITIDO.
• Tope de facturación diario, semanal o mensual, por monto y/o cantidad de comprobantes. El tope es en pesos: un comprobante en otra moneda cuenta total × cotización (hora argentina: el día arranca a las 00:00, la semana el lunes, el mes el día 1). Cuentan facturas y notas de débito aprobadas o en curso; llegar justo al tope está permitido. Si un comprobante lo supera → 429 LIMITE_FACTURACION y no se emite: no reintentes hasta el próximo período o hasta que subas el límite.

Datos del emisor

Los datos que ARCA exige impresos en cada comprobante, por CUIT. Se copian en cada comprobante al emitirlo: si después los cambiás, los PDF ya emitidos no cambian. De dónde sacar cada uno: ver los tutoriales (en el portal, Ayuda; por MCP, tool tutoriales).

• GET /v1/emisores: los datos guardados de la cuenta.
• PUT /v1/emisores/{cuit}: guarda o reemplaza los de un CUIT con certificado cargado en la cuenta.

curl -X PUT https://arcafactura-dev-api.dp.casalox.com/v1/emisores/20111111112 \
  -H "Authorization: Bearer $ARCAFACTURA_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "razonSocial": "PEREZ JUAN", "nombreFantasia": "Mi Marca", "domicilio": "Calle 123 - Ciudad - Provincia", "iibb": "Exento", "inicioActividades": "2020-11-01", "ptoVtaProduccion": 2 }'

PDF del comprobante

GET /v1/comprobantes/pdf?idempotencyKey=…&cuit=…&entorno=… devuelve el PDF (application/pdf) de un comprobante aprobado, con todo lo que exige ARCA: letra y código, datos del emisor y del receptor, detalle, totales, CAE y su vencimiento, y el código QR oficial (RG 4892). Una página por defecto (ORIGINAL); con muchos ítems pagina sola.

• Los datos del emisor (razón social, nombre de fantasía, domicilio comercial, Ingresos Brutos, inicio de actividades) se cargan una vez por CUIT: en el portal (Perfil → Datos para la factura) o por API (ver Datos del emisor). Sin ellos → 422 DATOS_EMISOR_FALTANTES.
• El detalle sale de items (si no los mandaste, una línea según el concepto: "Servicios", "Productos"…). Nombre, domicilio y condición de venta del receptor salen de receptor.nombre, receptor.domicilio y condicionVenta.
• Factura B: incluye el Régimen de Transparencia Fiscal al Consumidor (Ley 27.743). Factura A a un monotributista: la leyenda de la Ley 27.618. En otra moneda: el total en pesos con la cotización.
• Al emitir se guarda una copia de los datos del emisor: si después los cambiás, los PDF de comprobantes ya emitidos no cambian.
• Sale con la plantilla guardada al emitir. Para reimprimirlo con otra: &plantilla=<identificador> (clasica es la hoja de siempre). El comprobante en ARCA no cambia.
• Hasta 60 por minuto por cuenta (429 RATE_LIMIT).
• 404 NO_ENCONTRADO: no hay un comprobante aprobado para esa key (o no existe la plantilla pedida).

Plantillas de factura

Cómo se ve el PDF: formato (a4, a5 media hoja, ticket80 o ticket58 para ticketeras térmicas), estilo (clasica, moderna, minimal; solo A4), color, qué va en grande (encabezado: fantasia, razon o logo), un nombre de fantasía y un logo propios, y un pie de texto. Todas llevan lo que exige ARCA.

• GET /v1/plantillas lista las de la cuenta; PUT /v1/plantillas/{identificador} crea o reemplaza; DELETE /v1/plantillas/{identificador} borra (los comprobantes ya emitidos conservan su copia).
• Al emitir, "plantilla" elige una. Sin enviarla se usa la plantilla de la API key (se elige en el portal, API keys: así cada app sale con su marca sin cambiar su código), si no la del punto de venta (puntosDeVenta de la plantilla), si no la predeterminada (predeterminada: true), si no la Clásica. Se guarda una copia con el comprobante: el PDF, el mail y la reimpresión salen igual aunque después edites la plantilla.

curl -X PUT https://arcafactura-dev-api.dp.casalox.com/v1/plantillas/mostrador \
  -H "Authorization: Bearer $ARCAFACTURA_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "nombre": "Mostrador", "formato": "ticket80", "color": "#000000", "encabezado": "fantasia",
        "pie": "¡Gracias por su compra!", "puntosDeVenta": [{ "cuit": 20111111112, "entorno": "produccion", "ptoVta": 4 }] }'

Marca por plantilla. Si vendés por varios canales con el mismo CUIT, cada plantilla puede tener su nombreFantasia (pisa el del CUIT) y su logo. Con "encabezado": "logo" el logo va en lugar del nombre (la razón social sale siempre debajo). El logo va en el mismo PUT: PNG o JPG en base64 (con o sin data:image/...;base64,), de hasta 300 KB y entre 16 y 2000 px por lado. GET /v1/plantillas devuelve su identificador: mandarlo de vuelta lo conserva, null lo quita y si no mandás logo (o nombreFantasia) queda lo que había. El nombre de fantasía se resuelve así: el nombreFantasia del pedido, si no el de la plantilla, si no el del CUIT.

curl -X PUT https://arcafactura-dev-api.dp.casalox.com/v1/plantillas/caldoc \
  -H "Authorization: Bearer $ARCAFACTURA_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "nombre": "CalDoc", "formato": "a4", "estilo": "moderna", "color": "#0f766e", "encabezado": "logo",
        "nombreFantasia": "CALDOC", "logo": "data:image/png;base64,iVBORw0KGgo…" }'

Vista previa (sin emitir)

POST /v1/comprobantes/preview con el mismo body que emitir devuelve el PDF tal como saldría, marcado BORRADOR (sin número ni CAE). Valida igual que emitir, pero no va a ARCA ni consume cuota de emisión (cuenta en los 60 PDF por minuto).

Mandar el PDF por mail

POST /v1/comprobantes/enviar con { idempotencyKey, cuit, entorno, email?, mensaje? } manda el PDF adjunto al cliente. Sin email, usa el receptor.email cargado al emitir. El remitente muestra el nombre de fantasía (o la razón social) del emisor "vía arcafactura" y las respuestas van al mail del dueño de la cuenta. El mensaje no puede llevar enlaces. Los comprobantes de homologación salen marcados como [PRUEBA]. Hasta 30 por minuto y 300 por día por cuenta.

curl -X POST https://arcafactura-dev-api.dp.casalox.com/v1/comprobantes/enviar \
  -H "Authorization: Bearer $ARCAFACTURA_API_KEY" -H 'Content-Type: application/json' \
  -d '{ "idempotencyKey": "cobro-8812", "cuit": 20111111112, "entorno": "produccion", "email": "pagos@cliente.com" }'

Padrón: datos del receptor

GET /v1/padron/{cuit}?entorno=produccion&cuitEmisor=… devuelve los datos del receptor según ARCA (constancia de inscripción): { cuit, nombre, domicilio, condicionIvaId }, con condicionIvaId 1 (responsable inscripto), 4 (exento), 6 (monotributo) o null si no se sabe. Sirven para receptor.nombre, receptor.domicilio y receptor.condicionIvaId.

• Consulta con el certificado de cuitEmisor, que tiene que estar autorizado en ARCA para el servicio ws_sr_constancia_inscripcion (ver los tutoriales). Si no → 422 CREDENTIAL_ERROR.
• 404 NO_ENCONTRADO si ARCA no tiene el CUIT; 400 si el CUIT no es válido. Hasta 60 consultas por minuto.

Webhooks

En vez de consultar, tu app puede recibir un POST cuando un comprobante queda aprobado o rechazado. Se configuran en el portal (Webhooks, en el menú de usuario): una URL https y los eventos. Al crearlo se muestra una vez el secreto de firma.

{
  "id": "6b0f…",
  "tipo": "comprobante.aprobado",
  "creado": "2026-10-14T12:00:00.000Z",
  "datos": { "cuit": 20111111112, "entorno": "produccion", "idempotencyKey": "cobro-8812", "numero": 154, "ptoVta": 2,
             "tipoComprobante": 11, "descripcion": "Factura C", "cae": "86410992198264", "caeVencimiento": "2026-10-24",
             "resultado": "A", "total": 15000, "moneda": "PES" }
}

Headers: X-Arcafactura-Evento (el tipo), X-Arcafactura-Entrega (id único de la entrega: usalo para no procesar dos veces la misma) y X-Arcafactura-Signature: t=<unix>,v1=<firma>, donde la firma es HMAC-SHA256 con tu secreto de "<t>.<cuerpo crudo>". Verificala antes de confiar en el cuerpo:

import { createHmac, timingSafeEqual } from 'node:crypto'

function firmaValida(secreto, header, cuerpoCrudo) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '')
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false
  const esperada = createHmac('sha256', secreto).update(`${m[1]}.${cuerpoCrudo}`).digest()
  return timingSafeEqual(esperada, Buffer.from(m[2], 'hex'))
}

• Respondé 2xx rápido (en menos de 10 s); si tu app tarda, encolá el trabajo y respondé.
• Cualquier otra respuesta, un timeout o un error de red se reintenta con espera creciente (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h): hasta 8 intentos. Las entregas se ven en el portal.
• Un mismo comprobante genera un solo evento aunque repitas la Idempotency-Key. Un webhook pausado no recibe nada (ni lo que tenía en cola) hasta que lo actives. Probar manda como máximo una prueba por minuto.
• Por seguridad no se entregan a direcciones internas (IP privada, localhost) ni se siguen redirecciones.

Libro de ventas (CSV)

GET /v1/comprobantes/export?desde=YYYY-MM-DD&hasta=YYYY-MM-DD&entorno=produccion[&cuit=…] devuelve los comprobantes aprobados del período (fecha del comprobante, inclusive; hasta 2 años) en un CSV que se abre directo en Excel: BOM UTF-8, separador ;, coma decimal. Las notas de crédito van en negativo.

Columnas: fecha, comprobante, punto de venta, número, CAE y su vencimiento, documento y nombre del receptor, su condición frente al IVA, neto gravado, no gravado, exento, IVA 21 %, 10,5 %, 27 %, 5 % y 2,5 %, otros tributos, total, moneda, cotización y total en pesos.

Idempotencia y reintentos

Cada comprobante lleva un Idempotency-Key que vos generás (por ejemplo un UUID guardado junto al cobro).

• Repetir el POST con la misma key devuelve el mismo comprobante: nunca emite dos veces.
• Ante 503 o timeout, reintentar SIEMPRE con la misma Idempotency-Key; nunca con una nueva. Un 503 no significa que la factura no exista: ARCA pudo aprobarla y la respuesta perderse. La API reservó el número y, al reintentar, lo verifica en ARCA: si existe, devuelve ese CAE; si no, emite una sola vez.
• Usar una key nueva después de un 503 puede generar dos facturas por el mismo cobro.
• Una key nueva solo corresponde cuando corregiste los datos tras un rechazo (400/422 de validación o COMPROBANTE_RECHAZADO).
• Backoff sugerido: 1 min → 5 min → 15 min → 1 h. La ventana de idempotencia es de 48 h.

Consultar una emisión

GET /v1/comprobantes?idempotencyKey=…&cuit=…&entorno=… — mismos cuit/entorno que el POST. No emite ni llama a ARCA.

• 200 { "estado": "final", … }: mismo cuerpo que la respuesta del POST.
• 200 { "estado": "reservado", "numero": … }: la emisión quedó sin confirmar (hubo un 503/timeout). Reintentá el POST con la misma key para resolverla.
• 404 NO_ENCONTRADO: no hay nada guardado para esa key.

POST /v1/comprobantes/reconciliar con { idempotencyKey, cuit, entorno } resuelve una emisión reservado sin reemitir: consulta el número reservado en ARCA. Usa el certificado de la bóveda; si la emisión se hizo mandando el certificado, agregá certPem y keyPem.

• 200 { "estado": "final", … }: ARCA lo tenía; se adoptó su CAE.
• 200 { "estado": "no_emitido" }: ARCA no lo tiene; reintentá el POST con la misma key.
• 404 NO_ENCONTRADO: no hay nada pendiente para esa key.

Certificados

El certificado de ARCA (.crt) y su clave privada (.key) se guardan una vez en la bóveda de tu cuenta. La clave queda cifrada y nunca se vuelve a mostrar.

• Desde el portal: Certificados → Subir certificado (el CUIT sale del certificado).
• Por API: POST /v1/credenciales con { cuit, entorno, certPem, keyPem }; GET /v1/credenciales lista alias, vencimiento y vigencia; DELETE /v1/credenciales/{cuit}/{entorno} borra.
• La API valida que la clave corresponda al certificado, que el CUIT coincida y que esté vigente.
• Renovación (~2 años): subí el nuevo; reemplaza al anterior.

Facturar por otro CUIT (delegación)

Un contador o una empresa puede facturar por otros CUIT con su certificado, si el titular de cada CUIT lo autorizó en ARCA (Administrador de Relaciones → Nueva Relación → Facturación Electrónica → Representante: el computador fiscal del certificado). Paso a paso: ver los tutoriales.

• POST /v1/credenciales/representaciones con { cuit, entorno, cuitCertificado }: cuit factura con el certificado de cuitCertificado (que tiene que estar en la cuenta).
• GET /v1/credenciales lo muestra con via = CUIT del certificado (alias y vencimiento son los de ese certificado).
• Después se emite con cuit como con cualquier otro. Si el titular no autorizó el certificado, ARCA rechaza el login → CREDENTIAL_ERROR (coe.notAuthorized).
• DELETE /v1/credenciales/{cuit}/{entorno} de un CUIT representado quita solo la relación; borrar el certificado quita también los CUIT que representaba.

Errores

Todas las respuestas de error son { "code", "message" } (más observaciones en los rechazos de ARCA).

Catálogos ARCA

Tipos de comprobante

Condición frente al IVA del receptor (condicionIvaId)

Tipos de documento (docTipo)

Alícuotas de IVA (importes.iva[].alicuotaId)

Conceptos

MCP

La API expone un servidor MCP (Model Context Protocol), el estándar abierto para conectar asistentes y agentes de IA con herramientas. Sirve para cualquier cliente compatible con MCP que permita un servidor HTTP remoto con un header de autorización (Claude, Cursor, VS Code, Windsurf, tu propio agente…): el asistente integra y opera arcafactura con tu API key.

• URL: https://arcafactura-dev-api.dp.casalox.com/mcp (transporte Streamable HTTP)
• Autenticación: header Authorization: Bearer <API_KEY>

La forma más fácil: pegale esto a tu asistente (reemplazá <TU_API_KEY> por tu key; al crear una key en el portal te lo damos ya completo):

Agregá el servidor MCP de arcafactura (facturación electrónica de ARCA, Argentina) a tu configuración de MCP:

- Nombre: arcafactura
- Tipo: HTTP (Streamable HTTP)
- URL: https://arcafactura-dev-api.dp.casalox.com/mcp
- Header: Authorization: Bearer <TU_API_KEY>

Si sos Claude Code, corré:
claude mcp add --transport http arcafactura https://arcafactura-dev-api.dp.casalox.com/mcp --header "Authorization: Bearer <TU_API_KEY>"

Si tu cliente usa un archivo JSON (mcpServers), agregá:
{ "arcafactura": { "type": "http", "url": "https://arcafactura-dev-api.dp.casalox.com/mcp", "headers": { "Authorization": "Bearer <TU_API_KEY>" } } }

Cuando esté conectado:
1. Llamá a la herramienta guia_integracion y contame en pocas líneas qué podés hacer.
2. Para probar usá siempre el entorno "homologacion". Antes de emitir en "produccion" (comprobantes reales), mostrame la vista previa con previsualizar_comprobante y esperá mi confirmación.
3. Usá una idempotencyKey distinta por comprobante y reusala si tenés que reintentar.

Desde la terminal (ejemplo con Claude Code; otros clientes tienen un comando parecido):

claude mcp add --transport http arcafactura https://arcafactura-dev-api.dp.casalox.com/mcp \
  --header "Authorization: Bearer $ARCAFACTURA_API_KEY"

Clientes con configuración JSON (la mayoría usa este formato; el nombre de la clave puede variar, por ejemplo servers en VS Code):

{
  "mcpServers": {
    "arcafactura": {
      "type": "http",
      "url": "https://arcafactura-dev-api.dp.casalox.com/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Herramientas:

Por seguridad, la clave privada no se sube por MCP (pasaría por el modelo de IA): los certificados se cargan desde el portal.