Emitir una boleta
Emite una boleta de venta electrónica (tipo 03) a un consumidor final. El cliente puede identificarse con DNI, CE, pasaporte o RUC, o ir sin documento (NONE) cuando la boleta es en soles y no supera S/ 700.
Método: POST
Endpoint
Sección titulada «Endpoint»POST https://faktura-test.cgallardo.me/v1/receiptsPOST https://faktura.cgallardo.me/v1/receiptsCabeceras
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 | Evita duplicados al reintentar (Idempotencia). |
Datos generales y del cliente
Sección titulada «Datos generales y del cliente»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
series |
texto | Sí | Serie de boleta creada para tu empresa en el entorno de la clave, p. ej. B001. |
currency |
texto | No | PEN (por defecto) o USD. En dólares el cliente debe identificarse siempre. |
price_includes_tax |
booleano | No | true por defecto: unit_price incluye IGV (Cálculo de impuestos). |
issue_date |
fecha | No | Fecha de emisión YYYY-MM-DD: hoy (por defecto) o hasta 3 días atrás, para ventas registradas sin conexión o en contingencia. Nunca futura (InvalidIssueDate). |
due_date |
fecha | No | Fecha de vencimiento YYYY-MM-DD, igual o posterior a la emisión. |
customer.doc_type |
texto | Sí | DNI, CE, PASAPORTE, RUC o NONE (Catálogos). |
customer.doc_number |
texto | Si no es NONE |
Número de documento. |
customer.name |
texto | Si no es NONE |
Nombre o razón social, hasta 200 caracteres. |
customer.address |
texto | No | Dirección, hasta 250 caracteres. |
Ítems (items)
Sección titulada «Ítems (items)»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
items |
lista | Sí | Entre 1 y 500 ítems. |
items[].description |
texto | Sí | Hasta 500 caracteres. |
items[].quantity |
número o texto | Sí | Mayor que 0, hasta 10 decimales. |
items[].unit_price |
número o texto | Sí | Mayor que 0, hasta 10 decimales. En ítems gratuitos es el valor referencial. |
items[].igv_type |
texto | No | gravado (por defecto), exonerado, inafecto, gratuito, gratuito_exonerado o gratuito_inafecto. |
items[].icbper |
booleano | No | true para bolsas plásticas: agrega S/ 0.50 por unidad. |
items[].unit_code |
texto | No | Unidad de medida, NIU por defecto (Catálogos). |
items[].product_code |
texto | No | Tu código interno, 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. El monto va en los mismos términos que unit_price (con o sin IGV). No se admite en ítems gratuitos. |
Descuentos, recargo y datos comerciales
Sección titulada «Descuentos, recargo y datos comerciales»| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
discount |
objeto | No | Descuento global, {"amount": 10} o {"percent": 5}. Rebaja la base de los ítems gravados: con precios con IGV, el total baja exactamente ese monto. |
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 (letras, números 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 | Hasta 500 caracteres; aparece en el XML y en el PDF. |
Sin issue_date, la fecha de emisión es el día actual en hora de Perú.
Ejemplo
Sección titulada «Ejemplo»curl -X POST https://faktura-test.cgallardo.me/v1/receipts \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: pos-0042-000187" \ -d '{ "series": "B001", "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" }, "items": [ { "product_code": "CAF-01", "description": "Cafe americano", "quantity": 2, "unit_price": 8.00 }, { "description": "Bolsa plastica", "quantity": 1, "unit_price": 0.10, "icbper": true } ] }'use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->withHeaders(['Idempotency-Key' => 'pos-0042-000187']) ->post('https://faktura-test.cgallardo.me/v1/receipts', [ 'series' => 'B001', 'customer' => [ 'doc_type' => 'DNI', 'doc_number' => '45678912', 'name' => 'MARIA PEREZ', ], 'items' => [ [ 'product_code' => 'CAF-01', 'description' => 'Cafe americano', 'quantity' => 2, 'unit_price' => 8.00, ], [ 'description' => 'Bolsa plastica', 'quantity' => 1, 'unit_price' => 0.10, 'icbper' => true, ], ], ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/receipts', { method: 'POST', headers: { Authorization: 'Bearer sk_test_...', 'Content-Type': 'application/json', 'Idempotency-Key': 'pos-0042-000187', }, body: JSON.stringify({ series: 'B001', customer: { doc_type: 'DNI', doc_number: '45678912', name: 'MARIA PEREZ' }, items: [ { product_code: 'CAF-01', description: 'Cafe americano', quantity: 2, unit_price: 8.00, }, { description: 'Bolsa plastica', quantity: 1, unit_price: 0.10, icbper: true, }, ], }),});const data = await response.json();Respuesta 201 Created
Sección titulada «Respuesta 201 Created»Con las cabeceras Location: /v1/documents/{id} y X-Request-Id. El cuerpo es el comprobante en estado pending:
{ "id": "01a1d5fc-899b-720e-a6ea-03d37a346f81", "document_type": "03", "series": "B001", "number": 1, "full_number": "B001-1", "issue_date": "2026-11-13", "currency": "PEN", "status": "pending", "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" }, "totals": { "taxed": "13.64", "exempt": "0.00", "unaffected": "0.00", "free": "0.00", "igv": "2.46", "icbper": "0.50", "total_taxes": "2.96", "discounts": "0.00", "charges": "0.00", "total": "16.60" }, "net_payable": "16.60", "amount_in_words": "SON DIECISÉIS CON 60/100 SOLES", "payment": { "type": "contado", "installments": [] }, "items": [ { "product_code": "CAF-01", "description": "Cafe americano", "unit_code": "NIU", "quantity": "2", "unit_value": "6.78", "unit_price": "8", "igv_type": "gravado", "line_value": "13.56", "igv": "2.44", "icbper": "0.00" }, { "product_code": null, "description": "Bolsa plastica", "unit_code": "NIU", "quantity": "1", "unit_value": "0.08", "unit_price": "0.1", "igv_type": "gravado", "line_value": "0.08", "igv": "0.02", "icbper": "0.50" } ], "sunat": { "code": null, "description": null, "notes": [], "hash": "x/NyYaC+yItSOzJpanQWdBmcxDE=", "send_attempts": 0 }, "links": { "self": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81", "xml": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81/xml", "cdr": null, "pdf": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81/pdf", "public_pdf": "https://faktura-test.cgallardo.me/p/01a1d52b-…/01a1d5fc-…/a4.pdf?expires=…&signature=…", "public_ticket": "https://faktura-test.cgallardo.me/p/01a1d52b-…/01a1d5fc-…/ticket.pdf?expires=…&signature=…", "public_ticket_58": "https://faktura-test.cgallardo.me/p/01a1d52b-…/01a1d5fc-…/ticket58.pdf?expires=…&signature=…" }}Unos segundos después, GET /v1/documents/{id} muestra status: "accepted", el código y la descripción de SUNAT, el hash y los enlaces al XML y al CDR.
Repetir la petición con la misma Idempotency-Key y el mismo cuerpo responde 200 OK con Idempotent-Replayed: true y el mismo comprobante.
Flujo recomendado
Sección titulada «Flujo recomendado»- Al configurar tu POS: verifica tu clave con
GET /v1/mey elige una serieBactiva conGET /v1/series. - Cliente: hasta S/ 700 en soles puedes emitir sin documento (
NONE). Si el cliente da su DNI y tiene RUC 10, puedes autocompletar su nombre con Consultar un DNI. - Emite:
POST /v1/receiptscon unaIdempotency-Keyúnica por venta (por ejemplo, caja + correlativo del ticket). - Imprime con el
full_numberde la respuesta201, sin esperar a SUNAT. - Confirma el resultado con un webhook o
GET /v1/documents/{id}, y entrega el PDF en formato ticket si el cliente lo pide.
Reglas de una boleta
Sección titulada «Reglas de una boleta»- La serie debe empezar con
B. - Si el total supera S/ 700.00, el cliente debe identificarse (
ReceiptRequiresCustomerDocument). - En dólares, el cliente debe identificarse siempre.
- Solo al contado: el crédito con cuotas es exclusivo de facturas (
CreditOnlyForInvoices). - Detracción y retención son exclusivas de facturas (
DetractionOnlyForInvoices,RetentionOnlyForInvoices). - Ejemplo con descuentos en la guía de descuentos.
Respuestas y errores
Sección titulada «Respuestas y errores»| Estado | reason |
Significado |
|---|---|---|
201 |
— | Boleta 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 boleta 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). |