Emitir una nota de crédito por API: POST /bill/receipts/credit-note/
Revierte total o parcialmente el importe de un comprobante autorizado. Elegís cómo acreditar: por renglón, por monto, por porcentaje o, si no indicás nada, por el cien por ciento del comprobante original. Los ejemplos de esta página se capturaron en sandbox (token yf_test_): el CAE y el número son simulados, ARCA no los emitió y no valen como comprobante fiscal; lo reconocés por simulated: true y livemode: false.
Qué hace
Revierte total o parcialmente el importe de un comprobante autorizado: por renglón (lineas), por monto (importe_a_acreditar), por porcentaje (porcentaje_aplicar) o, sin ninguno, el 100%. Con un token yf_test_* (sandbox) este endpoint no llama a AFIP: persiste un comprobante simulado (simulated: true, livemode: false, un CAE sintético) en la base sandbox aislada del tenant. Requiere scope invoices:write. En un tenant que factura con SIFEN (Paraguay) responde 409 con error_code: use_sifen_routes: emití con POST /sales/ y las notas con POST /sales/{sale_id}/credit_note/. Notas de crédito y débito sobre comprobantes de un CUIT dado de baja: se permiten mientras ese CUIT no lo haya registrado otra cuenta; si lo registró otra responde 409 API_PARTNER_NOTE_ISSUER_CLAIMED_ELSEWHERE, y si ARCA ya no lista la delegación la nota queda pendiente con API_PARTNER_NOTE_ISSUER_DELEGATION_MISSING.
Parámetros
| Parámetro | Dónde | Requerido | Tipo | Descripción |
|---|---|---|---|---|
Idempotency-Key | header | no | string | Clave elegida por el cliente (hasta 255 caracteres) para hacer este POST seguro de reintentar. Un segundo request con la MISMA clave y el MISMO body reproduce la respuesta original (200/201, header Idempotency-Replayed: true) en vez de crear un segundo recurso. La misma clave con un body DISTINTO devuelve 422. La clave está scopeada al token exacto (yf_live_*/yf_test_*) que la usó — dos tokens nunca colisionan aunque manden la misma clave. TTL: 24 horas. |
Cuerpo del request
Formato application/json.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
comprobante_asociado_id | string | sí | Id del comprobante (factura) aprobado que esta nota acredita. |
motivo | string | no | |
lineas | array de object | no | Devolución por renglón. |
lineas[].linea | integer | sí | Índice (desde 0) del renglón del comprobante original. |
lineas[].cantidad | number | sí | Unidades que se devuelven (no puede superar la cantidad original). |
importe_a_acreditar | number | no | Monto a acreditar, IVA incluido (no puede superar el total del comprobante). |
porcentaje_aplicar | number | no | Porcentaje del comprobante a acreditar. |
items | array de object | no | Ya no se usa para devoluciones parciales: usá lineas, importe_a_acreditar o porcentaje_aplicar. |
importe_total | number | no | |
ambiente | string | no | Ignorado: el ambiente sale de la configuración de la cuenta. Valores: production, testing. Por defecto: production. |
autorizar | boolean | no | Por defecto: false. |
Ejemplo real capturado
Los ejemplos se generaron en el entorno de pruebas: el CAE es simulado y no tiene validez fiscal.
Capturado el 2026-11-10 en el entorno de pruebas con un token yf_test_*: los datos personales están anonimizados y el CAE de un comprobante de prueba es sintético.
Request
{
"comprobante_asociado_id": "6af28fe59d98ce51ca3bc5c7",
"motivo": "Devolucion de mercaderia",
"lineas": [
{
"linea": 1,
"cantidad": 1
}
],
"autorizar": true
}Respuesta (HTTP 200)
{
"success": true,
"data": {
"motivo": "Devolucion de mercaderia",
"lineas": [
{
"linea": 1,
"cantidad": 1
}
],
"tipo_comprobante": 8,
"punto_venta": 1,
"numero_comprobante": 4261715,
"cae": "05561320376600",
"cae_vencimiento": "20261120",
"fecha_comprobante": "20261110",
"comprobante_asociado_id": "6af28fe59d98ce51ca3bc5c7",
"estado": "autorizado",
"ambiente": "sandbox",
"livemode": false,
"simulated": true,
"simulated_note": "Sandbox test-mode document: no ARCA call was made. This CAE is synthetic and is not valid for a real fiscal document. For a real homologation CAE use a live token with \"ambiente\": \"testing\".",
"created_at": "2026-11-10T03:30:46.939211+00:00",
"email": "[email protected]",
"id": "6af28fe69d98ce51ca3bc5cd",
"sandbox": true
},
"message": "Simulated credit note created in sandbox mode (no real ARCA CAE)"
}Campos de la respuesta 200
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
success | boolean | no | |
data | object | no | |
data.id | string | no | |
data.tipo_comprobante | integer | no | |
data.punto_venta | integer | no | |
data.numero_comprobante | integer | no | |
data.cae | string | no | Código de Autorización Electrónico de AFIP (o sintético en sandbox). |
data.cae_vencimiento | string | no | |
data.fecha_comprobante | string | no | |
data.estado | string | no | |
data.ambiente | string | no | |
data.livemode | boolean | no | false cuando el comprobante fue emitido por un token yf_test_* (simulado, sin AFIP real). |
data.simulated | boolean | no | true en modo sandbox: el CAE tiene el formato correcto pero NO es válido para un comprobante fiscal real. |
data.iva_handling | object | no | |
data.iva_handling.incluye_iva_discriminado | boolean | no | |
data.iva_handling.tipo_comprobante_nombre | string | no | |
data.iva_handling.condicion_fiscal_emisor | string | no | |
data.idempotent_replay | boolean | no | true si esta respuesta es la reproducción de un request anterior idéntico. |
data.items | array de object | no | |
data.items[].Descripcion | string | no | |
data.items[].Cantidad | number | no | |
data.items[].Precio | number | no | Precio unitario (neto de IVA cuando el tipo discrimina IVA). |
data.items[].Bonificacion | number | no | |
data.items[].IvaId | integer | no | Alícuota AFIP (3=0%, 4=10.5%, 5=21%, 6=27%, 8=5%, 9=2.5%). |
data.items[].importe_neto_linea | number | no | Neto de la línea: Precio x Cantidad - Bonificacion, redondeado a 2 decimales (ROUND_HALF_UP). Calculado por el backend. |
data.items[].importe_iva_linea | number | no | IVA de la línea (0 si el tipo no discrimina IVA, 0% o exento). Calculado por el backend. |
data.items[].importe_total_linea | number | no | importe_neto_linea + importe_iva_linea. La suma de las líneas puede diferir de importe_total por el redondeo por línea y no incluye tributos. |
message | string | no | |
_links | object | no | Mapa HATEOAS: cada valor es un link accionable relativo a este recurso. |
Respuestas de error
Todo error tiene la forma {"success": false, "error": "...", "code": "..."}.
| Estado | Descripción | Código |
|---|---|---|
| 400 | Solicitud inválida (body ausente o con formato incorrecto). | VALIDATION_ERROR |
| 401 | Falta autenticación o el token es inválido/expiró. | UNAUTHORIZED |
| 403 | El token no tiene el/los scope(s) requeridos, o el plan del tenant no habilita el módulo. | FORBIDDEN |
| 409 | Conflicto de estado (p. ej. editar un recurso en un estado que no lo permite). | CONFLICT |
| 422 | Semánticamente inválido — incluye la reutilización de un Idempotency-Key con un body distinto. | UNPROCESSABLE_ENTITY |
| 429 | Se superó el rate limit del endpoint o del tenant. Ver headers X-RateLimit-* y Retry-After. | RATE_LIMITED |
Código para probarlo
Estos ejemplos corren contra el entorno de pruebas con un token yf_test_* en la variable $YF_TEST_TOKEN. En producción la base es https://api.yo-facturo.com/api/v1.
curl -sS -X POST "https://api.yo-facturo.com/api/v1/bill/receipts/credit-note/" \
-H "X-API-Key: $YF_TEST_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"comprobante_asociado_id": "6af28fe59d98ce51ca3bc5c7",
"motivo": "Devolucion de mercaderia",
"lineas": [
{
"linea": 1,
"cantidad": 1
}
],
"autorizar": true
}'