Ir al contenido

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

POST https://faktura-test.cgallardo.me/v1/receipts
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).
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.
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.
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ú.

Ventana de terminal
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 }
]
}'

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.

  1. Al configurar tu POS: verifica tu clave con GET /v1/me y elige una serie B activa con GET /v1/series.
  2. 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.
  3. Emite: POST /v1/receipts con una Idempotency-Key única por venta (por ejemplo, caja + correlativo del ticket).
  4. Imprime con el full_number de la respuesta 201, sin esperar a SUNAT.
  5. Confirma el resultado con un webhook o GET /v1/documents/{id}, y entrega el PDF en formato ticket si el cliente lo pide.
  • 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.
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).