Guía para integradores

Si tu software factura en nombre de tus propios clientes —un sistema de gestión, un estudio contable, una plataforma—, cada contribuyente nuevo necesita su CUIT dado de alta y su certificado de ARCA cargado antes de poder emitir. Con estos endpoints hacés todo ese recorrido desde tu propio panel: ni vos ni tu cliente tienen que entrar a nuestro dashboard.

El modelo es el mismo que el del dashboard: un certificado por CUIT y por entorno, generado a partir de un CSR que armamos nosotros. La clave privada se genera de nuestro lado y queda guardada cifrada: nunca viaja, ni hacia vos ni hacia tu cliente.

Una vez que el CUIT está listo, emitís para él con la misma API key, mandando su número en representada.

El flujo completo

  Tu sistema                            Tu cliente, en ARCA (con su Clave Fiscal)
  ──────────                            ─────────────────────────────────────────
  1. POST /api/cuits
     → 201 con el CSR (csrPendiente.csrPem)
                          ──── le mostrás el CSR ────▶
                                        2. Crea el certificado pegando el CSR
                                           y descarga el .crt
                                        3. Autoriza los web services
                                           (Administrador de Relaciones)
                                        4. Da de alta un punto de venta
                                           para Web Services
                          ◀──── te pasa el .crt ────
  5. POST /api/cuits/{cuit}/{environment}/certificado  { "crtPem": "..." }
     → estado "vigente"
  6. GET /api/cuits/{cuit}/{environment}
     → pasosPendientes vacío: ya puede emitir
     (si figura algo, se lo mostrás y después
      POST .../verificar cuando avise que lo hizo)

Los pasos 2 a 4 ocurren dentro de ARCA y no se pueden automatizar: requieren la Clave Fiscal del contribuyente y ARCA no ofrece una API para eso. Lo que sí podés hacer es guiarlo con los textos de más abajo, que salen directo del campo pasosPendientes.

1. Alta del CUIT. POST /api/cuits con el número, el entorno, un alias y la razón social. En la misma operación generamos el CSR y lo devolvemos en csrPendiente.csrPem. El CUIT queda en estado pendiente.
2. Tu cliente tramita el certificado en ARCA con ese CSR, y te devuelve el .crt que ARCA le emitió.
3. Carga del certificado. POST .../certificado con { "crtPem": "..." }. Lo validamos contra el CSR, lo activamos y —si ARCA responde— detectamos su punto de venta. El CUIT pasa a vigente.
4. Lo que falte. Consultá el CUIT y, si pasosPendientes no está vacío, mostrale a tu cliente el texto de cada paso. Cuando te avise que lo hizo, POST .../verificar vuelve a preguntarle a ARCA y actualiza la lista.

Pasos pendientes

Cada CUIT viene con pasosPendientes: la lista, ordenada por prioridad, de lo que falta para que pueda emitir sin avisos. Una lista vacía significa que no queda nada pendiente que conozcamos. Los textos de esta sección están pensados para que los copies a tu panel tal cual, o adaptados.

generar_csr

El CSR se genera solo en el alta. Este paso aparece si esa generación falló, o si el CSR se canceló. Lo resolvés vos: POST .../csr y seguí con cargar_certificado.

cargar_certificado

Texto para tu cliente, en producción:

1. Entrá a arca.gob.ar con tu Clave Fiscal.
2. Abrí Administración de Certificados Digitales, elegí agregar un alias y pegá este CSR.
3. Descargá el certificado (.crt) que te devuelve ARCA y envianoslo.

En homologación el trámite es en el WSASS (autogestión de certificados de homologación): Crear certificado, pegar el CSR y descargar el .crt.

Cuando tengas el .crt, cargalo con POST .../certificado. Si el CUIT estaba en activo_renovando, el certificado anterior sigue funcionando hasta ese momento.

renovar_certificado

Los certificados de ARCA vencen. Iniciá la renovación con POST .../csr: el CUIT pasa a activo_renovando, sigue emitiendo con el certificado actual y te devolvemos un CSR nuevo para que tu cliente repita el trámite de cargar_certificado.

Para saber qué renovar sin recorrer toda la cuenta: GET /api/cuits?estado=por_vencer,vencido.

delegar_constancia

Sin este servicio no podemos leer del padrón el domicilio fiscal ni la razón social del contribuyente, y el comprobante impreso sale con el bloque del emisor incompleto. Texto para tu cliente:

1. Entrá a arca.gob.ar con tu Clave Fiscal.
2. Abrí Administrador de Relaciones de Clave Fiscal → Nueva Relación.
3. Buscá el servicio ws_sr_constancia_inscripcion (constancia de inscripción).
4. En Representante, elegí el computador fiscal «{alias}» —el alias del certificado—, no una persona, y confirmá.

El alias es el certificado.subjectCn del CUIT. Cuando tu cliente te avise, llamá a POST .../verificar: si ARCA ya lo autoriza, el paso desaparece.

habilitar_punto_venta

El punto de venta guardado para el CUIT (ptoVta) no figura entre los que ARCA habilita para Web Services: la primera factura con ese número la va a rechazar. Texto para tu cliente:

1. Entrá a arca.gob.ar con tu Clave Fiscal.
2. Abrí Administración de Puntos de Venta y Domicilios y dá de alta un punto de venta con sistema de facturación Web Services.

El punto de venta que usás en Comprobantes en línea no sirve para facturar por API: son modalidades distintas y se declaran por separado.

Después tenés dos caminos: si tu cliente habilitó ese mismo número, POST .../verificar; si habilitó otro, fijalo con PATCH { "ptoVta": <número> }, o mandá { "ptoVta": null } para que lo resolvamos contra ARCA al emitir.

Operaciones disponibles

El recurso se identifica por número de CUIT (11 dígitos, sin guiones) y entorno (homologacion o produccion), igual que representada al emitir: el mismo CUIT en los dos entornos son dos recursos distintos, cada uno con su certificado, su CSR y su punto de venta.

Las lecturas también están disponibles como tools del servidor MCP (cuits_listar, cuits_obtener), para que un agente pueda consultar qué le falta a cada CUIT.

No consume cuota

Nada de lo que hagas en /api/cuits descuenta comprobantes ni consultas de padrón, ni cuenta como consumo en el dashboard: tampoco la reverificación, aunque consulte a ARCA.

Lo que sí aplica es el cupo de CUITs de tu plan: si la cuenta ya lo completó, el alta responde 402. Dar de baja un CUIT libera su lugar.

Autenticación

Todos los endpoints requieren una API key válida en el header Authorization: Bearer <key>. Las escrituras requieren scope read_write; con una key de solo lectura responden 403. Ver Scopes de API key.

Errores

Todos los errores responden { "error": "<mensaje en español>" }, más los campos que se indican en cada caso.