Documentación de la API
Faktura emite comprobantes electrónicos ante SUNAT (facturas, boletas, notas de crédito y débito, y sus anulaciones) desde cualquier sistema —POS, ERP, e-commerce— con un JSON simple. Tú envías el cliente, los ítems y los precios; la API calcula el IGV y los totales, numera el comprobante, genera y firma el XML UBL 2.1, lo envía a SUNAT y guarda la constancia de recepción (CDR).
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":"NONE"},"items":[{"description":"Café americano","quantity":2,"unit_price":8.00}]}'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' => 'NONE'], 'items' => [ [ 'description' => 'Café americano', 'quantity' => 2, 'unit_price' => 8.00, ], ], ]);
$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: 'NONE' }, items: [{ description: 'Café americano', quantity: 2, unit_price: 8.00 }], }),});const data = await response.json();EmpezarURL base, ambientes, autenticación y tu primera boleta en 10 minutos.
FacturasEmitir facturas al contado, al crédito, en dólares, con detracción o retención.
BoletasBoletas con o sin documento del cliente, bolsas plásticas y recargo al consumo.
Notas de crédito y débitoDevoluciones, descuentos, anulaciones, intereses y penalidades.
ComprobantesListar, ver, descargar PDF, XML y CDR, enviar por correo, reintentar y anular.
Consultas de RUC y DNIDatos del cliente desde el padrón de SUNAT, uno a uno o en lote.
WebhooksAvisos firmados cuando SUNAT acepta, observa, rechaza o anula.
Ejemplos listos para copiarRecetas probadas: dólares, gratuitos, restaurante, devoluciones…
Tablas, errores y glosarioCatálogos SUNAT, cálculo de impuestos, códigos de error y glosario.
Colecciones y skillsPostman, Bruno, archivo .http y skills para asistentes de IA.
Empieza aquí
Sección titulada «Empieza aquí»| Si quieres… | Lee |
|---|---|
| Entender cómo funciona la API, URL base y entornos | Introducción |
| Obtener y usar tu API key | Autenticación |
| Emitir tu primera boleta en 10 minutos | Guía: primera boleta |
| Emitir una factura al crédito con cuotas | Guía: factura al crédito |
| Emitir con descuentos, detracción (SPOT) o retención del IGV | Guía: descuentos, detracción y retención |
| Copiar un ejemplo para tu caso: factura en dólares, precios sin IGV, gratuitos, restaurante, devoluciones, anulaciones… | Ejemplos de facturas, boletas y notas y anulaciones |
| Probar desde Postman, Bruno, VS Code o instalar skills para IA | Colecciones y skills |
| Saber cuándo un comprobante ya fue aceptado por SUNAT | Estados y envío a SUNAT y Webhooks |
| Imprimir o enviar el comprobante al cliente | Representación impresa (PDF) y Enviar por correo |
| Reintentar sin duplicar comprobantes | Idempotencia |
| Interpretar un error o código de estado | Errores |
| Entender cómo se calculan IGV, ICBPER y totales | Cálculo de impuestos |
Valores válidos de doc_type, igv_type, unit_code, detracción… |
Catálogos |
| Consultar términos fiscales de SUNAT y de la API | Glosario y Preguntas frecuentes |
Referencia de endpoints
Sección titulada «Referencia de endpoints»Emisión: facturas, boletas y notas
Sección titulada «Emisión: facturas, boletas y notas»| Método | Ruta | Descripción |
|---|---|---|
POST |
/v1/invoices |
Emitir una factura electrónica (01) |
POST |
/v1/receipts |
Emitir una boleta de venta electrónica (03) |
POST |
/v1/credit-notes |
Emitir una nota de crédito electrónica (07) |
POST |
/v1/debit-notes |
Emitir una nota de débito electrónica (08) |
Comprobantes emitidos
Sección titulada «Comprobantes emitidos»| Método | Ruta | Descripción |
|---|---|---|
GET |
/v1/documents |
Listar y filtrar comprobantes |
GET |
/v1/documents/{id} |
Ver un comprobante y su estado en SUNAT |
GET |
/v1/documents/{id}/pdf |
Descargar la representación impresa en PDF (a4, ticket, ticket58) |
GET |
/p/{companyId}/{documentId}/{format}.pdf |
Enlace público firmado del PDF para el cliente final (sin API key) |
GET |
/v1/documents/{id}/xml |
Descargar el XML UBL 2.1 firmado |
GET |
/v1/documents/{id}/cdr |
Descargar la constancia de recepción (CDR) de SUNAT |
POST |
/v1/documents/{id}/email |
Enviar el comprobante por correo (PDF, XML y CDR) |
POST |
/v1/documents/{id}/retry |
Reenviar un comprobante failed tras corregir la causa |
POST |
/v1/documents/{id}/void |
Anular un comprobante (comunicación de baja RA o resumen diario RC) |
Consultas de RUC y DNI
Sección titulada «Consultas de RUC y DNI»| Método | Ruta | Descripción |
|---|---|---|
GET |
/v1/lookup/ruc/{ruc} |
Consultar un RUC en el padrón de SUNAT |
POST |
/v1/lookup/ruc |
Consultar hasta 1000 RUC en una sola petición |
GET |
/v1/lookup/dni/{dni} |
Consultar un DNI (personas con RUC 10 en el padrón de SUNAT) |
Webhooks
Sección titulada «Webhooks»| Método | Ruta | Descripción |
|---|---|---|
POST |
/v1/webhooks |
Registrar un webhook (cómo funcionan) |
GET |
/v1/webhooks |
Listar los webhooks activos |
DELETE |
/v1/webhooks/{id} |
Eliminar un webhook |
Cuenta y series
Sección titulada «Cuenta y series»| Método | Ruta | Descripción |
|---|---|---|
GET |
/v1/me |
Verificar tu API key, el entorno y el estado de tu emisor |
GET |
/v1/series |
Listar tus series activas y su siguiente correlativo |
Historial de cambios del contrato y lo que viene: Versiones. Límites de uso: Límite de peticiones. Dudas comunes: Preguntas frecuentes y Glosario. Para probar sin código: Colecciones.