Emitir una factura
Emite una factura electrónica (tipo 01) a un cliente con RUC. Admite pago al contado o al crédito con cuotas, detracción (SPOT) y retención del IGV.
Método: POST
Endpoint
Sección titulada «Endpoint»POST https://faktura-test.cgallardo.me/v1/invoicesPOST https://faktura.cgallardo.me/v1/invoicesCabeceras
Sección titulada «Cabeceras»| Cabecera | Obligatoria | Descripción |
|---|---|---|
Authorization |
Sí | Bearer <api key> (sk_test_ en pruebas, sk_live_ en producción). |
Content-Type |
Sí | application/json |
Idempotency-Key |
Recomendada | Clave única por venta (hasta 100 caracteres) para reintentar sin duplicar el comprobante (Idempotencia). |
Datos generales y del cliente
Sección titulada «Datos generales y del cliente»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
series |
texto | Sí | Serie activa de factura creada para tu empresa en el entorno de la clave; debe empezar con F (p. ej. F001). |
currency |
texto | No | PEN (por defecto) o USD (Catálogos). |
price_includes_tax |
booleano | No | true por defecto: unit_price incluye IGV. Si envías false, unit_price es el valor unitario sin IGV (Cálculo de impuestos). |
issue_date |
fecha | No | Fecha de emisión YYYY-MM-DD: hoy en hora de Perú (por defecto) o hasta 3 días atrás para contingencia. Nunca futura (InvalidIssueDate). |
due_date |
fecha | No | Fecha de vencimiento YYYY-MM-DD, igual o posterior a issue_date. |
customer.doc_type |
texto | Sí | Debe ser RUC (InvoiceRequiresCustomerRuc). |
customer.doc_number |
texto | Sí | RUC válido de 11 dígitos con dígito verificador oficial. |
customer.name |
texto | Sí | Razón social del cliente, hasta 200 caracteres. |
customer.address |
texto | No | Domicilio fiscal del cliente, hasta 250 caracteres; se muestra en el XML y en el PDF. |
Ítems (items)
Sección titulada «Ítems (items)»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
items |
lista | Sí | Entre 1 y 500 ítems (NoItems, TooManyItems). |
items[].description |
texto | Sí | Descripción del bien o servicio, hasta 500 caracteres. |
items[].quantity |
número o texto | Sí | Cantidad mayor que 0, hasta 10 decimales. |
items[].unit_price |
número o texto | Sí | Precio unitario mayor que 0, hasta 10 decimales (con o sin IGV según price_includes_tax). En ítems gratuitos es el valor referencial. |
items[].igv_type |
texto | No | gravado (por defecto), exonerado, inafecto, gratuito, gratuito_exonerado o gratuito_inafecto (Catálogos). |
items[].icbper |
booleano | No | true para bolsas plásticas gravadas con ICBPER (S/ 0.50 por unidad). |
items[].unit_code |
texto | No | Unidad de medida del catálogo 03 de SUNAT (NIU por defecto para bienes, ZZ para servicios). Ver Catálogos. |
items[].product_code |
texto | No | Tu código interno de producto o SKU, hasta 30 caracteres. |
items[].sunat_product_code |
texto | No | Código de producto SUNAT (catálogo 25, UNSPSC) de 8 dígitos. |
items[].discount |
objeto | No | Descuento del ítem: {"amount": 5} o {"percent": 10}, nunca ambos. No se admite en ítems gratuitos. |
Forma de pago, detracción, retención y datos comerciales
Sección titulada «Forma de pago, detracción, retención y datos comerciales»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
payment |
objeto | No | Por defecto {"type": "contado"}. |
payment.type |
texto | No | contado o credito. |
payment.installments |
lista | Si payment.type es credito |
De 1 a 60 cuotas que sumen exactamente el neto pendiente de pago (net_payable: el total menos la detracción y la retención, si las hay). |
payment.installments[].amount |
número o texto | Sí (en cuotas) | Monto de la cuota mayor que 0, hasta 2 decimales. |
payment.installments[].due_date |
fecha | Sí (en cuotas) | Vencimiento YYYY-MM-DD, posterior a issue_date. |
detraction |
objeto | No | Operación sujeta al SPOT (leyenda 2006). No se combina con retention. |
detraction.code |
texto | Sí (en detracción) | Código de bien o servicio de 3 dígitos (Catálogo 54). |
detraction.percent |
número o texto | Sí (en detracción) | Porcentaje de detracción mayor que 0 y menor que 100 (p. ej. 12). |
detraction.bank_account |
texto | Sí (en detracción) | Cuenta de detracciones del emisor en el Banco de la Nación (6 a 30 dígitos o guiones). |
detraction.payment_method |
texto | No | Medio de pago de 3 dígitos (Catálogo 59); 001 (depósito en cuenta) por defecto. |
detraction.exchange_rate |
número o texto | Si currency es USD |
Tipo de cambio para convertir el monto de la detracción a soles, como exige SUNAT. |
retention |
booleano | No | true si tu cliente es agente de retención del IGV: informa el 3 % del total (solo en PEN y para totales mayores a S/ 700). No se combina con detraction. |
discount |
objeto | No | Descuento global sobre la base gravada: {"amount": 10} o {"percent": 5}. |
service_charge |
objeto | No | Recargo al consumo: {"percent": 10} o {"amount": 5} (Cálculo de impuestos). |
purchase_order |
texto | No | Orden de compra del cliente, hasta 20 caracteres (A-Z, 0-9 y -/._). |
despatch_references |
lista | No | Hasta 10 guías de remisión relacionadas: {"type": "09", "number": "T001-123"} (o "type": "31"). Ver Catálogos. |
observations |
texto | No | Observaciones, hasta 500 caracteres; aparecen en el XML y en el PDF. |
Ejemplos completos en la guía de factura al crédito y en la guía de descuentos, detracción y retención.
Ejemplo: factura al contado
Sección titulada «Ejemplo: factura al contado»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-8841" \ -d '{ "series": "F001", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "items": [ { "description": "Laptop", "quantity": 1, "unit_price": 118 }, { "description": "Libro", "quantity": 2, "unit_price": 5.5, "igv_type": "exonerado" } ] }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->withHeaders(['Idempotency-Key' => 'erp-pedido-8841']) ->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], [ 'description' => 'Libro', 'quantity' => 2, 'unit_price' => 5.5, 'igv_type' => 'exonerado', ], ], ]);
$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-8841', }, 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 }, { description: 'Libro', quantity: 2, unit_price: 5.5, igv_type: 'exonerado', }, ], }),});const data = await response.json();Respuesta 201 Created
Sección titulada «Respuesta 201 Created»Devuelve las cabeceras Location: /v1/documents/{id} y X-Request-Id, y el objeto comprobante en estado pending:
{ "id": "01a1d5fd-1c2e-7a40-b7d5-5f3e9c0d2b18", "document_type": "01", "series": "F001", "number": 1, "full_number": "F001-1", "issue_date": "2026-11-13", "currency": "PEN", "status": "pending", "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." }, "totals": { "taxed": "100.00", "exempt": "11.00", "unaffected": "0.00", "free": "0.00", "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "129.00" }, "net_payable": "129.00", "amount_in_words": "SON CIENTO VEINTINUEVE CON 00/100 SOLES", "payment": { "type": "contado", "installments": [] }, "items": [ { "product_code": null, "description": "Laptop", "unit_code": "NIU", "quantity": "1", "unit_value": "100", "unit_price": "118", "igv_type": "gravado", "line_value": "100.00", "igv": "18.00", "icbper": "0.00" }, { "product_code": null, "description": "Libro", "unit_code": "NIU", "quantity": "2", "unit_value": "5.5", "unit_price": "5.5", "igv_type": "exonerado", "line_value": "11.00", "igv": "0.00", "icbper": "0.00" } ], "sunat": { "code": null, "description": null, "notes": [], "hash": "4k9mZpQ2vL8nR1tY7wB3cF6hJ0s=", "send_attempts": 0 }, "links": { "self": "/v1/documents/01a1d5fd-1c2e-7a40-b7d5-5f3e9c0d2b18", "xml": "/v1/documents/01a1d5fd-1c2e-7a40-b7d5-5f3e9c0d2b18/xml", "cdr": null, "pdf": "/v1/documents/01a1d5fd-1c2e-7a40-b7d5-5f3e9c0d2b18/pdf", "public_pdf": "https://faktura-test.cgallardo.me/p/01a1d52b-…/01a1d5fd-…/a4.pdf?expires=…&signature=…", "public_ticket": "https://faktura-test.cgallardo.me/p/01a1d52b-…/01a1d5fd-…/ticket.pdf?expires=…&signature=…", "public_ticket_58": "https://faktura-test.cgallardo.me/p/01a1d52b-…/01a1d5fd-…/ticket58.pdf?expires=…&signature=…" }}Flujo recomendado
Sección titulada «Flujo recomendado»- Al configurar tu sistema: verifica tu clave con
GET /v1/mey elige una serieFactiva conGET /v1/series. - Datos del cliente: si solo tienes su RUC, obtén razón social y dirección con Consultar un RUC.
- Emite:
POST /v1/invoicescon unaIdempotency-Keyúnica por venta (por ejemplo, el número de pedido de tu sistema). Si la conexión se corta, repite la misma petición con la misma clave. - Guarda
idyfull_numberde la respuesta201: el número ya es tuyo y puedes imprimir. - Espera a SUNAT: un webhook
document.accepted, oGET /v1/documents/{id}con espera progresiva. - Según el resultado: con
accepteduobserved, entrega el PDF o envíalo por correo; conrejected, corrige y emite otra factura; confailed, corrige la causa y reintenta.
Reglas de una factura
Sección titulada «Reglas de una factura»- El cliente debe tener RUC (
InvoiceRequiresCustomerRuc). - La serie debe empezar con
F(InvalidSeriesCode). - Con crédito, las cuotas deben sumar el neto pendiente de pago (
InstallmentsDoNotMatchTotal) y vencer después de la emisión (InvalidInstallments). - Detracción en dólares exige
exchange_rate(DetractionRequiresExchangeRate); la retención exige soles y un total mayor a S/ 700 (RetentionRequiresPen,RetentionBelowThreshold). - Con una clave
live, tu empresa debe tener certificado digital y usuario SOL (EmitterNotReadyForProduction), y el certificado debe estar vigente (CertificateExpired).
Respuestas y errores
Sección titulada «Respuestas y errores»| Estado | reason |
Significado |
|---|---|---|
201 |
— | Factura creada, firmada y encolada para SUNAT (status: "pending"). |
200 |
— | Petición repetida con la misma Idempotency-Key y el mismo cuerpo (Idempotent-Replayed: true). |
401 |
Unauthenticated |
Falta la API key, es inválida o venció. |
403 |
ApiKeyScopeInsufficient, EmitterInactive |
La clave es de solo consulta (lookup) o la empresa está desactivada. |
409 |
IdempotencyKeyReused, EmitterNotReadyForProduction, CertificateExpired |
La Idempotency-Key ya se usó con otro cuerpo, o faltan credenciales vigentes en producción. |
422 |
ValidationFailed y códigos de regla de negocio |
Un campo o regla de la factura no es válido. Ver la tabla completa de errores de emisión. |
429 |
TooManyRequests |
Superaste las 120 peticiones por minuto (Límite de peticiones). |