Descuentos, detracción y retención
Ejemplos listos para copiar y validados ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos.
Descuento por ítem y descuento global
Sección titulada «Descuento por ítem y descuento global»Con price_includes_tax: true (por defecto), los montos de descuento son con IGV: lo que deja de pagar el cliente. Faktura calcula la rebaja de la base imponible que exige SUNAT (catálogo 53: 00 por ítem, 02 global).
curl -X POST https://faktura-test.cgallardo.me/v1/invoices \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: erp-pedido-9101" \ -d '{ "series": "F001", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "items": [ { "description": "Laptop", "quantity": 1, "unit_price": 118, "discount": { "amount": 18 } }, { "description": "Mouse", "quantity": 2, "unit_price": 50, "discount": { "percent": 10 } }, { "description": "Libro", "quantity": 1, "unit_price": 20, "igv_type": "exonerado" } ], "discount": { "amount": 11.8 } }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->withHeaders(['Idempotency-Key' => 'erp-pedido-9101']) ->post('https://faktura-test.cgallardo.me/v1/invoices', [ 'series' => 'F001', 'customer' => [ 'doc_type' => 'RUC', 'doc_number' => '20100070970', 'name' => 'CLIENTE S.A.C.', ], 'items' => [ [ 'description' => 'Laptop', 'quantity' => 1, 'unit_price' => 118, 'discount' => ['amount' => 18], ], [ 'description' => 'Mouse', 'quantity' => 2, 'unit_price' => 50, 'discount' => ['percent' => 10], ], [ 'description' => 'Libro', 'quantity' => 1, 'unit_price' => 20, 'igv_type' => 'exonerado', ], ], 'discount' => ['amount' => 11.8], ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/invoices', { method: 'POST', headers: { Authorization: 'Bearer sk_test_...', 'Content-Type': 'application/json', 'Idempotency-Key': 'erp-pedido-9101', }, body: JSON.stringify({ series: 'F001', customer: { doc_type: 'RUC', doc_number: '20100070970', name: 'CLIENTE S.A.C.' }, items: [ { description: 'Laptop', quantity: 1, unit_price: 118, discount: { amount: 18 }, }, { description: 'Mouse', quantity: 2, unit_price: 50, discount: { percent: 10 }, }, { description: 'Libro', quantity: 1, unit_price: 20, igv_type: 'exonerado', }, ], discount: { amount: 11.8 }, }),});const data = await response.json();Respuesta (resumida):
{ "totals": { "taxed": "151.02", "exempt": "20.00", "unaffected": "0.00", "free": "0.00", "igv": "27.18", "icbper": "0.00", "total_taxes": "27.18", "discounts": "33.73", "charges": "0.00", "total": "198.20" }, "global_discount": { "base_amount": "161.02", "amount": "10.00" }}| Ítem | Precio de lista | Descuento con IGV | Paga | Base (line_value) |
discount (base) |
|---|---|---|---|---|---|
| Laptop | 118.00 | 18.00 | 100.00 | 84.75 | 15.25 |
| Mouse | 100.00 | 10.00 | 90.00 | 76.27 | 8.48 |
| Libro | 20.00 | — | 20.00 | 20.00 | 0.00 |
El descuento global de S/ 11.80 se aplica solo sobre los ítems gravados: su total con IGV pasa de 190.00 a 178.20. Así, la base gravada queda en 151.02, el IGV en 27.18 y el total en 198.20. La respuesta lo detalla en global_discount y en totals.discounts (33.73 sobre la base).
Reglas:
- Cada descuento es
amountopercent, nunca ambos (details: ["discount:AmountOrPercent"]). - No se admiten descuentos en ítems gratuitos.
- El descuento global exige al menos un ítem gravado.
- Una nota de crédito que anula un comprobante con descuentos copia sus líneas ya netas, con el mismo total.
- Las notas con ítems propios no admiten descuentos.
Detracción (SPOT)
Sección titulada «Detracción (SPOT)»Para servicios o bienes sujetos al Sistema de Pago de Obligaciones Tributarias. El porcentaje lo eliges según el código del bien o servicio (catálogo 54).
curl -X POST https://faktura-test.cgallardo.me/v1/invoices \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: erp-pedido-9102" \ -d '{ "series": "F001", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "items": [{ "description": "Mantenimiento de equipos", "quantity": 1, "unit_price": 1180 }], "detraction": { "code": "020", "percent": 12, "bank_account": "00-000-123456" }, "payment": { "type": "credito", "installments": [{ "amount": 1038.40, "due_date": "2026-12-15" }] } }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->withHeaders(['Idempotency-Key' => 'erp-pedido-9102']) ->post('https://faktura-test.cgallardo.me/v1/invoices', [ 'series' => 'F001', 'customer' => [ 'doc_type' => 'RUC', 'doc_number' => '20100070970', 'name' => 'CLIENTE S.A.C.', ], 'items' => [ [ 'description' => 'Mantenimiento de equipos', 'quantity' => 1, 'unit_price' => 1180, ], ], 'detraction' => ['code' => '020', 'percent' => 12, 'bank_account' => '00-000-123456'], 'payment' => [ 'type' => 'credito', 'installments' => [['amount' => 1038.40, 'due_date' => '2026-12-15']], ], ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/invoices', { method: 'POST', headers: { Authorization: 'Bearer sk_test_...', 'Content-Type': 'application/json', 'Idempotency-Key': 'erp-pedido-9102', }, body: JSON.stringify({ series: 'F001', customer: { doc_type: 'RUC', doc_number: '20100070970', name: 'CLIENTE S.A.C.' }, items: [{ description: 'Mantenimiento de equipos', quantity: 1, unit_price: 1180 }], detraction: { code: '020', percent: 12, bank_account: '00-000-123456' }, payment: { type: 'credito', installments: [{ amount: 1038.40, due_date: '2026-12-15' }], }, }),});const data = await response.json();Respuesta (resumida):
{ "totals": { "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00", "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00" }, "net_payable": "1038.40", "detraction": { "code": "020", "percent": "12", "amount": "141.60", "amount_in_document_currency": "141.60", "bank_account": "00-000-123456", "payment_method": "001", "exchange_rate": null }}- La detracción es de 12 % sobre 1180.00, es decir S/ 141.60. Tu cliente la deposita en tu cuenta del Banco de la Nación.
- El neto pendiente de pago (
net_payable) es 1038.40: las cuotas deben sumar exactamente eso. - La factura va con tipo de operación
1001y la leyenda “Operación sujeta a detracción”. - En dólares agrega
"exchange_rate": 3.75. La detracción se informa en soles (1180 × 3.75 × 12 % = S/ 531.00) y en la moneda del comprobante (US$ 141.60).
Retención del IGV
Sección titulada «Retención del IGV»Si tu cliente es agente de retención, informa el 3 % que retendrá:
curl -X POST https://faktura-test.cgallardo.me/v1/invoices \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: erp-pedido-9103" \ -d '{ "series": "F001", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "items": [{ "description": "Repuestos", "quantity": 1, "unit_price": 1180 }], "retention": true, "payment": { "type": "credito", "installments": [{ "amount": 1144.60, "due_date": "2026-12-15" }] } }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->withHeaders(['Idempotency-Key' => 'erp-pedido-9103']) ->post('https://faktura-test.cgallardo.me/v1/invoices', [ 'series' => 'F001', 'customer' => [ 'doc_type' => 'RUC', 'doc_number' => '20100070970', 'name' => 'CLIENTE S.A.C.', ], 'items' => [ [ 'description' => 'Repuestos', 'quantity' => 1, 'unit_price' => 1180, ], ], 'retention' => true, 'payment' => [ 'type' => 'credito', 'installments' => [['amount' => 1144.60, 'due_date' => '2026-12-15']], ], ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/invoices', { method: 'POST', headers: { Authorization: 'Bearer sk_test_...', 'Content-Type': 'application/json', 'Idempotency-Key': 'erp-pedido-9103', }, body: JSON.stringify({ series: 'F001', customer: { doc_type: 'RUC', doc_number: '20100070970', name: 'CLIENTE S.A.C.' }, items: [{ description: 'Repuestos', quantity: 1, unit_price: 1180 }], retention: true, payment: { type: 'credito', installments: [{ amount: 1144.60, due_date: '2026-12-15' }], }, }),});const data = await response.json();Respuesta (resumida):
{ "totals": { "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00", "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00" }, "net_payable": "1144.60", "retention": { "percent": "3", "base_amount": "1180.00", "amount": "35.40" }}- La retención es de S/ 35.40 (catálogo 53, código
62) y no cambia el total: reduce el neto pendiente de pago a 1144.60. - Requiere soles y un total mayor a S/ 700. No se combina con detracción.
Datos comerciales
Sección titulada «Datos comerciales»Fragmento con los campos; el ejemplo completo está en el recetario de facturas.
{ "purchase_order": "OC-2026-001", "despatch_references": [{ "type": "09", "number": "T001-123" }], "observations": "Entrega en almacén central", "due_date": "2026-12-15"}Viajan en el XML (OrderReference, DespatchDocumentReference, Note, DueDate) y aparecen en el PDF.