Ir al contenido

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

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

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

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=…"
}
}
  1. Al configurar tu sistema: verifica tu clave con GET /v1/me y elige una serie F activa con GET /v1/series.
  2. Datos del cliente: si solo tienes su RUC, obtén razón social y dirección con Consultar un RUC.
  3. Emite: POST /v1/invoices con una Idempotency-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.
  4. Guarda id y full_number de la respuesta 201: el número ya es tuyo y puedes imprimir.
  5. Espera a SUNAT: un webhook document.accepted, o GET /v1/documents/{id} con espera progresiva.
  6. Según el resultado: con accepted u observed, entrega el PDF o envíalo por correo; con rejected, corrige y emite otra factura; con failed, corrige la causa y reintenta.
  • 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).
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).