---
name: faktura-ver-un-comprobante
description: "Ver un comprobante con la API de Faktura (facturación electrónica SUNAT, Perú). Devuelve el comprobante con su estado actual en SUNAT. Responde 404 NotFound si el id no existe o pertenece a otro emisor o a otro entorno. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Ver un comprobante — Faktura API

## Propósito

Le da a tu asistente el contexto para **ver un comprobante** con la API de Faktura: Devuelve el comprobante con su estado actual en SUNAT. Responde 404 NotFound si el id no existe o pertenece a otro emisor o a otro entorno.

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

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/documents/{id}` |
| Producción | `GET https://faktura.cgallardo.me/v1/documents/{id}` |

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

```bash
curl https://faktura-test.cgallardo.me/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81 \
  -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK` (aceptado por SUNAT)

```json
{
  "id": "01a1d5fc-899b-720e-a6ea-03d37a346f81",
  "document_type": "03",
  "series": "B001",
  "number": 1,
  "full_number": "B001-1",
  "issue_date": "2026-11-13",
  "currency": "PEN",
  "igv_percent": "18",
  "status": "accepted",
  "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": "0",
    "description": "La Boleta numero B001-1, ha sido aceptada",
    "notes": [],
    "hash": "x/NyYaC+yItSOzJpanQWdBmcxDE=",
    "send_attempts": 1
  },
  "links": {
    "self": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81",
    "xml": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81/xml",
    "cdr": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81/cdr",
    "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=…"
  }
}
```

## El objeto comprobante

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `id` | UUID | Identificador del comprobante en Faktura. |
| `document_type` | texto | `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito. |
| `series`, `number`, `full_number` | texto, entero, texto | Serie, correlativo y ambos unidos (`B001-1`). |
| `issue_date` | fecha | Fecha de emisión (hora de Perú). |
| `currency` | texto | `PEN` o `USD`. |
| `igv_percent` | texto | Tasa de IGV aplicada al comprobante (`"18"`). |
| `status` | texto | Estado del envío a SUNAT ([Estados](https://faktura-doc.cgallardo.me/estados-y-envio/)). |
| `customer` | objeto | `doc_type` ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/)), `doc_number` (`-` si es anónimo) y `name`. |
| `totals` | objeto | Montos como texto decimal ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#totales-del-comprobante)). |
| `totals.discounts` | texto | Suma de descuentos sobre la base (por ítem y global). |
| `net_payable` | texto | Neto pendiente de pago: total menos detracción y retención. |
| `service_charge` | objeto o null | `base_amount` y `amount` cuando hay recargo al consumo. |
| `global_discount` | objeto o null | `base_amount` (gravado antes del descuento) y `amount` (descuento sobre la base). |
| `detraction` | objeto o null | `code`, `percent`, `amount` (en soles), `amount_in_document_currency`, `bank_account`, `payment_method`, `exchange_rate`. |
| `retention` | objeto o null | `percent` (`3`), `base_amount` y `amount`. |
| `purchase_order`, `despatch_references`, `observations`, `due_date` | varios | Datos comerciales enviados al emitir. |
| `amount_in_words` | texto | Total en letras (leyenda 1000 de SUNAT). |
| `payment` | objeto | `type` (`contado` o `credito`) e `installments` (`amount`, `due_date`). |
| `items[]` | lista | Por ítem: `product_code`, `sunat_product_code`, `description`, `unit_code`, `quantity`, `unit_value` (sin IGV, antes del descuento), `unit_price` (con IGV, después del descuento), `igv_type`, `discount` (sobre la base), `line_value` (base, ya descontada), `igv`, `icbper`. |
| `sunat.code` | texto o null | Código de respuesta de SUNAT (`0` aceptado). |
| `sunat.description` | texto o null | Descripción de SUNAT. |
| `sunat.notes` | lista | Observaciones de SUNAT (estado `observed`). |
| `sunat.hash` | texto o null | Valor resumen (`DigestValue`) de la firma, para la representación impresa. |
| `sunat.send_attempts` | entero | Intentos de envío realizados. |
| `note` | objeto o null | En notas: `reason_code`, `reason_description` y `affected_document` (`id`, `document_type`, `full_number`). |
| `void` | objeto o null | Si se pidió la anulación: `status` (`requested`, `voided`, `rejected`) y `reason`. Ver [Anulación](https://faktura-doc.cgallardo.me/endpoints/anulacion/). |
| `links.self` | texto | Ruta de este comprobante (`/v1/documents/{id}`). |
| `links.xml`, `links.cdr` | texto o null | Rutas de descarga de [XML](https://faktura-doc.cgallardo.me/endpoints/comprobantes/xml/) y [CDR](https://faktura-doc.cgallardo.me/endpoints/comprobantes/cdr/) cuando ya existen. |
| `links.pdf` | texto | [Representación impresa](https://faktura-doc.cgallardo.me/endpoints/pdf/) con API key (`?format=a4`, `ticket` o `ticket58`). |
| `links.public_pdf`, `links.public_ticket`, `links.public_ticket_58` | texto | Enlaces firmados (A4, ticket 80 mm y ticket 58 mm), sin API key, que vencen a los 7 días ([ver detalles](https://faktura-doc.cgallardo.me/endpoints/pdf/#enlace-público-para-el-cliente-final)). |

## Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve el objeto comprobante completo. |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup` (solo consultas de RUC/DNI). |
| `404` | `NotFound` | El `id` no existe o pertenece a otro emisor o entorno. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Anexo: Totales del comprobante (de «Cálculo de impuestos»)

| Campo en `totals` | Contenido |
| --- | --- |
| `taxed` | Suma de bases gravadas. |
| `exempt` | Suma de líneas exoneradas. |
| `unaffected` | Suma de líneas inafectas. |
| `free` | Valor referencial de las líneas gratuitas (no se cobra). |
| `igv` | IGV cobrado. |
| `icbper` | Impuesto a las bolsas. |
| `total_taxes` | `igv + icbper`. |
| `discounts` | Descuentos sobre la base (informativo, ya restados). |
| `charges` | Recargo al consumo. |
| `total` | Importe a pagar: `taxed + exempt + unaffected + total_taxes + charges`. |

`amount_in_words` trae el total en letras, tal como SUNAT exige en la representación impresa: `SON DIECISÉIS CON 60/100 SOLES`. Descuentos, detracción y retención se detallan en su [guía](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/).

## Anexo: Enlace público para el cliente final (de «Representación impresa (PDF)»)

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.

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