---
name: faktura-representacion-impresa-pdf
description: "Representación impresa (PDF) con la API de Faktura (facturación electrónica SUNAT, Perú). 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… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Representación impresa (PDF) — Faktura API

## Propósito

Le da a tu asistente el contexto para **representación impresa (PDF)** con la API de Faktura: 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…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-representacion-impresa-pdf/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/endpoints/pdf/

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/documents/{id}/pdf?format=a4|ticket|ticket58` |
| Producción | `GET https://faktura.cgallardo.me/v1/documents/{id}/pdf?format=a4|ticket|ticket58` |

## Autenticación y cabeceras

- `Authorization: Bearer <api key>`. En pruebas, una clave `sk_test_` (SUNAT beta, sin valor tributario); en producción, la `sk_live_`. El ambiente lo decide la clave.
- `Content-Type: application/json` en las peticiones con cuerpo.
- `Idempotency-Key` (recomendada al emitir): repetir la petición con la misma clave y el mismo cuerpo devuelve el mismo comprobante, sin duplicarlo.
- Errores: JSON `{ "reason": "<código>", "details": [...] }`. `401` clave inválida o vencida, `403` alcance insuficiente, `422` datos inválidos, `429` límite de 120 peticiones por minuto (respeta `Retry-After`), `500` solo con `traceId`.

## 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

### Formato A4

```bash
curl -o F001-1.pdf "https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=a4" \
  -H "Authorization: Bearer sk_test_..."
```

### Formato ticket (80 mm)

```bash
curl -o B001-1.pdf "https://faktura-test.cgallardo.me/v1/documents/<id>/pdf?format=ticket" \
  -H "Authorization: Bearer sk_test_..."
```

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

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:

```json
{
  "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

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

- 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 `409` con `{"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 `pending` ya está firmado: su PDF trae el valor resumen y el QR completos.

## 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. |

## Reglas generales de la API

- Montos en las respuestas como texto decimal (`"16.00"`); en las peticiones, número o texto.
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`); identificadores UUID.
- Un comprobante emitido responde `201` con `status: "pending"`: el número ya es tuyo. El resultado de SUNAT llega después (webhook o `GET /v1/documents/{id}`).
- Documentación completa: https://faktura-doc.cgallardo.me/ · Toda la API en una skill: https://faktura-doc.cgallardo.me/skills/faktura-api.md
