Representación impresa (PDF)
Devuelve la representación impresa del comprobante en PDF (Content-Type: application/pdf), lista para imprimir o enviar al cliente. Incluye todo lo que exige SUNAT: datos del emisor y del cliente, detalle, totales, monto en letras, forma de pago y cuotas, documento que modifica (en notas), código QR, valor resumen (hash) y leyendas.
Método: GET
Endpoint
Sección titulada «Endpoint»GET https://faktura-test.cgallardo.me/v1/documents/{id}/pdf?format=a4|ticket|ticket58GET https://faktura.cgallardo.me/v1/documents/{id}/pdf?format=a4|ticket|ticket58Parámetros de consulta
Sección titulada «Parámetros de consulta»| Parámetro | Valores | Descripción |
|---|---|---|
format |
a4 (por defecto), ticket, ticket58 |
a4 para facturas y envío por correo; ticket para impresoras térmicas de 80 mm (POS); ticket58 para impresoras térmicas de 58 mm (mismo contenido, letra y QR más compactos). El alto de los formatos ticket crece con la cantidad de ítems. |
Ejemplos
Sección titulada «Ejemplos»Formato A4
Sección titulada «Formato A4»curl -o F001-1.pdf "https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=a4" \ -H "Authorization: Bearer sk_test_..."use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->sink('F001-1.pdf') ->get('https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=a4');import { writeFile } from 'node:fs/promises';
const response = await fetch('https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=a4', { headers: { Authorization: 'Bearer sk_test_...', },});await writeFile('F001-1.pdf', Buffer.from(await response.arrayBuffer()));Formato ticket (80 mm)
Sección titulada «Formato ticket (80 mm)»curl -o B001-1.pdf "https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=ticket" \ -H "Authorization: Bearer sk_test_..."use Illuminate\Support\Facades\Http;
$response = Http::withToken('sk_test_...') ->sink('B001-1.pdf') ->get('https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=ticket');import { writeFile } from 'node:fs/promises';
const response = await fetch('https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=ticket', { headers: { Authorization: 'Bearer sk_test_...', },});await writeFile('B001-1.pdf', Buffer.from(await response.arrayBuffer()));El PDF está disponible apenas se emite el comprobante, aunque SUNAT aún no haya respondido. El valor resumen y el QR completo vienen desde el primer momento, porque el XML se firma al emitir.
Enlace público para el cliente final
Sección titulada «Enlace público para el cliente final»Cada comprobante trae en links.public_pdf (A4), links.public_ticket (80 mm) y links.public_ticket_58 (58 mm) un enlace firmado que apunta a GET /p/{companyId}/{documentId}/{format}.pdf y no requiere API key. Puedes enviarlo por correo o WhatsApp al cliente o abrirlo desde una tienda en línea sin exponer tu clave:
{ "links": { "public_pdf": "https://faktura-test.cgallardo.me/p/<empresa>/<id>/a4.pdf?expires=1795204800&signature=…", "public_ticket": "https://faktura-test.cgallardo.me/p/<empresa>/<id>/ticket.pdf?expires=1795204800&signature=…", "public_ticket_58": "https://faktura-test.cgallardo.me/p/<empresa>/<id>/ticket58.pdf?expires=1795204800&signature=…" }}- Vence a los 7 días de generado. Cada consulta del comprobante entrega un enlace nuevo.
- Si se altera cualquier parte (formato, identificador, expiración o firma), responde
403. - Tiene su propio límite de 60 descargas por minuto y no consume el límite de tu API key.
Código QR
Sección titulada «Código QR»El QR contiene, separados por |, lo que define SUNAT: RUC | tipo | serie | número | IGV | total | fecha | tipo doc. cliente | número doc. cliente | valor resumen |.
Comprobantes rechazados y anulados
Sección titulada «Comprobantes rechazados y anulados»- Un comprobante de prueba (clave
sk_test_, SUNAT beta) se imprime con la marca «PRUEBA - SIN VALOR TRIBUTARIO»: tiene RUC reales y por eso no debe confundirse con uno válido. - Un comprobante rechazado por SUNAT no tiene validez: su PDF responde
409con{"reason": "DocumentRejected"}, también por el enlace público. - Un comprobante anulado se sigue pudiendo imprimir, con la marca «COMPROBANTE ANULADO» bien visible.
- Un comprobante
pendingya está firmado: su PDF trae el valor resumen y el QR completos.
Respuestas y errores
Sección titulada «Respuestas y errores»| Estado | reason |
Significado |
|---|---|---|
200 |
— | Devuelve el archivo PDF (application/pdf). |
401 |
Unauthenticated |
Falta la API key, es inválida o venció (en /v1/documents/{id}/pdf). |
403 |
ApiKeyScopeInsufficient o firma inválida |
Clave de alcance lookup, o enlace público vencido/alterado. |
404 |
NotFound |
El comprobante no existe o pertenece a otro emisor o entorno. |
409 |
DocumentRejected |
El comprobante fue rechazado por SUNAT y no tiene representación impresa válida. |
422 |
ValidationFailed |
El parámetro format no es a4, ticket ni ticket58. |
429 |
TooManyRequests |
Superaste el límite de peticiones por minuto. |