# Referencia de la API de YoFacturo para facturación electrónica ARCA

Referencia de las operaciones que usás para facturar ante ARCA (ex AFIP) desde tu propio sistema: emitir y autorizar comprobantes, notas de crédito y débito, CAEA, FCE MiPyME y las lecturas que los acompañan. Cada operación documentada trae un ejemplo real capturado.

## Autenticación

Cada request lleva un token opaco en el header `X-API-Key: yf_live_xxx` (o `Authorization: Bearer yf_live_xxx`). Lo generás desde Configuración > API Tokens y cada token tiene scopes de lectura y escritura por recurso; si falta el scope, la respuesta es 403.

## Sandbox

Un token `yf_test_*` autentica como el mismo tenant pero lee y escribe en una base separada y nunca emite contra ARCA: el comprobante queda simulado, con un CAE sintético y `livemode: false`.

## Reintentos seguros

Las creaciones con más costo de un duplicado (ventas, productos y facturas) aceptan un header `Idempotency-Key`. Reenviar la misma clave con el mismo body devuelve la respuesta original.

## Forma de las respuestas

Toda respuesta exitosa tiene la forma `{"success": true, "data": ...}`. Todo error tiene la forma `{"success": false, "error": "...", "code": "..."}`, y `code` es estable para usarlo en un switch.

## Límites

Todos los tokens de un tenant comparten una ventana deslizante de 10 por segundo, 100 por minuto, 3000 por hora y 20000 por día. Al superarla la respuesta es 429 con los headers `X-RateLimit-*` y `Retry-After`.

## Recursos y operaciones documentadas

### [Comprobantes electrónicos](https://yo-facturo.com/dev/referencia/comprobantes/)

Acá está el circuito completo de un comprobante fiscal: crearlo como borrador, autorizarlo ante ARCA para obtener el CAE, leerlo, listarlo, anularlo y compartirlo con un link público. Todo se autentica con un token de API y respeta los scopes de facturación.

- [Emitir factura](https://yo-facturo.com/dev/referencia/comprobantes/emitir-factura/) — `POST /bill/receipts/invoice/`
- [Autorizar un comprobante y obtener el CAE](https://yo-facturo.com/dev/referencia/comprobantes/autorizar-comprobante/) — `POST /bill/receipts/authorize/{comprobante_id}/`

### [Notas de crédito y débito](https://yo-facturo.com/dev/referencia/notas-de-credito-y-debito/)

Las notas ajustan un comprobante ya aprobado. La nota de crédito anula total o parcialmente (por renglón, por monto o por porcentaje) y la de débito ajusta al alza. La vista previa calcula la nota sin persistir nada, así podés validar el resultado antes de emitirla.

- [Emitir una nota de crédito](https://yo-facturo.com/dev/referencia/notas-de-credito-y-debito/emitir-nota-de-credito/) — `POST /bill/receipts/credit-note/`

Resto de las operaciones públicas (sin página propia): https://yo-facturo.com/dev/referencia/otros-recursos/index.md
API de facturación: https://yo-facturo.com/api-facturacion/