Escritura

Además de leer, la API te deja crear, editar y eliminar los clientes de tu estudio.

Endpoint	Qué hace
POST /v1/cuits	Da de alta un cliente y dispara su primera sincronización
PATCH /v1/cuits/{cuit}	Actualiza los datos de un cliente ya cargado
DELETE /v1/cuits/{cuit}	Elimina un cliente

El resto de la API sigue siendo de solo lectura.

Cómo se habilita

La escritura no viene activada con el token: es parte de nuestro plan Enterprise, que se contrata del plan de tu estudio. Escribinos y armamos la propuesta con vos.

Crear un cliente

curl -X POST https://api.afippi.com/v1/cuits \
  -H "Authorization: Bearer $AFIPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "persona-fisica",
    "cuit": "20123456789",
    "nombre": "Juan",
    "apellido": "Pérez",
    "clave_arca": "la-clave-de-arca",
    "email": "juan@example.com"
  }'

Responde 201 con la identidad del cliente creado:

{
  "data": {
    "id": "cuit-public-id",
    "cuit": "20123456789",
    "displayCuit": "20-12345678-9",
    "tipo": "persona-fisica",
    "nombre": "Pérez, Juan",
    "email": "juan@example.com",
    "telefono": null
  }
}

Sociedades

Una persona jurídica lleva razon_social y representante, y no lleva clave_arca: ARCA se consulta con la clave del representante.

{
  "tipo": "persona-juridica",
  "cuit": "30123456783",
  "razon_social": "Mi Empresa SRL",
  "representante": "20123456789"
}

El representante es el CUIT de una persona física que ya tenés cargada en tu cuenta. Si no existe, o es de otra cuenta, o es otra sociedad, la respuesta es 400. Por eso, al migrar un estudio entero, cargá primero las personas físicas y después las sociedades.

La condición fiscal no se manda

monotributista y autonomo no son campos de la API: los determina la sincronización con el Sistema Registral de ARCA, que corre para toda persona física. Mandarlos responde 400, tanto en el POST como en el PATCH. Hasta que termine la primera sincronización el cliente aparece en el panel bajo Otros.

Editar un cliente

PATCH sigue RFC 7396: un campo que no mandás queda como está, y en los campos opcionales un null explícito lo borra.

curl -X PATCH https://api.afippi.com/v1/cuits/20123456789 \
  -H "Authorization: Bearer $AFIPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "nuevo@example.com", "telefono": null }'

Ese pedido cambia el email, borra el teléfono y no toca nada más: ni el nombre, ni la clave, ni las etiquetas.

Qué se puede editar

Campo	Persona física	Persona jurídica	Acepta null
nombre, apellido	sí	no	no
razon_social, representante	no	sí	no
email, telefono	sí	sí	sí
clave_arca	sí	no	no

Mandar un campo que no corresponde al tipo del cliente responde 400.

Solo email y telefono se pueden borrar: son los únicos datos opcionales de un cliente. El resto identifica al cliente o es lo que Afippi necesita para sincronizarlo, así que se cambian por otro valor pero no se vacían, y mandarlos en null responde 400.

El cuerpo tiene que traer al menos un campo: un {} responde 400 en lugar de un 200 que parecería un cambio aplicado. Y tiene que viajar con Content-Type: application/json; si no, la respuesta es 415.

Qué no se puede editar

El CUIT y el tipo no son editables: son la identidad del cliente. Mandarlos en un PATCH responde 400 en lugar de ignorarlos en silencio:

{ "error": "El CUIT y 'tipo' no se pueden modificar." }

Si te equivocaste de CUIT al cargar un cliente, eliminalo y cargalo de nuevo.

Las etiquetas se leen, no se escriben

Las etiquetas se pueden leer en GET /v1/cuits (los nombres de cada CUIT) y en GET /v1/tags (nombre y color de las de tu cuenta). No se pueden crear, editar ni borrar por API. Un PATCH nunca las toca: las que le pusiste al cliente desde el panel siguen ahí.

Eliminar un cliente

curl -X DELETE https://api.afippi.com/v1/cuits/20123456789 \
  -H "Authorization: Bearer $AFIPPI_API_TOKEN"

Responde 204 sin cuerpo.

Se borra todo y no se puede deshacer

Se va el cliente y con él todo lo que Afippi sincronizó de ARCA: comprobantes, notificaciones del DFE, estados de SCT y CCMA, reportes y la clave guardada. Las sincronizaciones que tenga pendientes se cancelan. No hay papelera ni forma de recuperarlo: para volver a tenerlo hay que cargarlo de nuevo y esperar la primera sincronización.

Un representante no se puede borrar antes que sus sociedades

Si el cliente es el representante de alguna sociedad cargada en tu cuenta, la respuesta es 409 y no se borra nada:

{ "error": "El cliente tiene sociedades asociadas, debe eliminar las sociedades primero o cambiar el representante" }

Borrá primero esas sociedades, o cambiales el representante, y reintentá.

Reintentar no es idempotente

Un CUIT que ya no está en tu cuenta responde 404, el mismo que uno que nunca estuvo o que es de otra cuenta. Después de un timeout, un GET /v1/cuits te dice si el borrado llegó a aplicarse.

Facturación

Afippi cobra por CUIT administrado, y estos endpoints no tienen tope propio: cada cliente que cargues por API cuenta igual que uno cargado desde el panel. Si vas a migrar un estudio entero, mirá antes cómo queda tu plan.