---
name: faktura-api
description: "Faktura API con la API de Faktura (facturación electrónica SUNAT, Perú). emitir facturas, boletas, notas y anulaciones ante SUNAT, consultar comprobantes, RUC y DNI, y recibir webhooks. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Faktura API — Faktura API

## Propósito

Le da a tu asistente el contexto para **faktura API** con la API de Faktura: emitir facturas, boletas, notas y anulaciones ante SUNAT, consultar comprobantes, RUC y DNI, y recibir webhooks.

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

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

## Introducción

### URL base y versionado

| Entorno | URL base | Clave |
| --- | --- | --- |
| Pruebas | `https://faktura-test.cgallardo.me` | `sk_test_…` (SUNAT beta) |
| Producción | `https://faktura.cgallardo.me` | `sk_live_…` (SUNAT producción) |

Todas las rutas de negocio llevan el prefijo de versión `/v1`. Dentro de `v1` solo se agregan campos o endpoints nuevos; un cambio incompatible saldría en `/v2` con aviso previo (ver [Versiones](https://faktura-doc.cgallardo.me/versiones/)).

### Entornos: prueba y producción

El entorno ante SUNAT lo decide **la API key**: el mismo código de integración sirve para ambos.

| API key | Envía a | Uso |
| --- | --- | --- |
| `sk_test_…` | SUNAT **beta** | Desarrollo y pruebas. Los comprobantes no tienen validez tributaria. |
| `sk_live_…` | SUNAT **producción** | Comprobantes reales. Requiere que tu empresa tenga certificado digital y usuario SOL configurados. Una clave de **solo consultas** (RUC y DNI) no los necesita. |

El entorno de **pruebas** (`https://faktura-test.cgallardo.me`) recibe cada versión antes de que llegue a producción y **solo acepta claves `sk_test_`**: una `sk_live_` responde `401`. Los ejemplos de esta documentación usan la URL de pruebas y una clave `sk_test_`. Para pasar a producción cambias dos cosas: la URL base por `https://faktura.cgallardo.me` y la clave por la `sk_live_`.

Una clave puede tener **fecha de vencimiento** (los accesos de prueba la tienen): al vencer responde `401` igual que una revocada, y hay que pedir otra.

Las series y la numeración son independientes por entorno: emitir en prueba nunca consume números de producción. Un comprobante emitido con una clave de prueba no es visible con una clave de producción, y viceversa.

### Formato

- Peticiones y respuestas en JSON UTF-8 (`Content-Type: application/json`).
- Nombres de campos en `snake_case`.
- **Montos en las respuestas como texto decimal** (`"16.00"`), para que ningún cliente pierda exactitud al leerlos como `float`. En las peticiones puedes enviarlos como número (`8.5`) o como texto (`"8.50"`).
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`).
- Identificadores UUID (`01a1d5fc-899b-720e-a6ea-03d37a346f81`).

### Cómo funciona una emisión

1. Envías `POST /v1/invoices` o `POST /v1/receipts`.
2. La API valida, calcula impuestos y totales, asigna el siguiente correlativo de la serie y responde de inmediato con `201` y `status: "pending"`. El número ya es tuyo y puedes imprimir el ticket.
3. En segundo plano, la API firma el XML, lo envía a SUNAT y guarda el CDR. Si SUNAT no responde, reintenta sola.
4. Consultas `GET /v1/documents/{id}` hasta ver un estado final (`accepted`, `observed`, `rejected` o `failed`).

El detalle de cada estado y la estrategia recomendada de consulta están en [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

### Correlación y soporte

Cada respuesta incluye la cabecera `X-Request-Id`. Puedes enviar tu propio identificador en esa cabecera (8 a 64 caracteres: letras, números y guiones) y la API lo reutiliza. Incluye ese valor cuando reportes un problema a soporte.

## Autenticación

Cada petición a `/v1` lleva tu API key como token Bearer:

```http
GET /v1/me HTTP/1.1
Host: faktura-test.cgallardo.me
Authorization: Bearer sk_test_ec829766c02e_bb1f99a4b8069b5657d82bff324df39b08430f47c5b730fa98cc44ec8d991cd8
```

### Formato de la API key

```text
sk_test_ec829766c02e_bb1f99a4…cd8
└─┬───┘ └────┬─────┘ └────┬─────┘
 entorno  prefijo      secreto
```

- **Entorno**: `test` (SUNAT beta) o `live` (SUNAT producción). Ver [Introducción](https://faktura-doc.cgallardo.me/introduccion/#entornos-prueba-y-producción).
- **Prefijo** (`sk_test_ec829766c02e`): identifica la clave sin revelarla. Es lo que verás en los registros y lo que usas para pedir su revocación.
- **Secreto**: solo se muestra una vez, al emitir la clave. Faktura guarda únicamente un hash; si lo pierdes, se emite una clave nueva.

### Buenas prácticas

- Guarda la clave en tu servidor (variable de entorno o gestor de secretos). **Nunca** la pongas en una app móvil, en JavaScript del navegador ni en un repositorio.
- Usa una clave por sistema o por tienda (`POS tienda 1`, `ERP central`): así puedes revocar una sin afectar a las demás.
- Si un sistema solo consulta RUC o DNI, pide una clave de **alcance `lookup`**: llega a `/v1/me` y `/v1/lookup/*` y nada más (no emite, no anula ni lee comprobantes). Una clave `lookup` que intenta otra cosa recibe `403` `ApiKeyScopeInsufficient`. `/v1/me` informa el alcance en `api_key.scope`.
- Una clave revocada deja de funcionar en la siguiente petición.

### Respuestas de autenticación

| Situación | Estado | Cuerpo |
| --- | --- | --- |
| Falta la cabecera, el esquema no es `Bearer`, la clave está mal formada, no existe, fue revocada o la empresa está desactivada | `401` | `{"reason":"Unauthenticated"}` + cabecera `WWW-Authenticate: Bearer` |
| La clave es de alcance `lookup` y la ruta exige alcance completo | `403` | `{"reason":"ApiKeyScopeInsufficient"}` |
| Superaste el límite de peticiones | `429` | `{"reason":"TooManyRequests"}` + cabecera `Retry-After` (segundos) |

Todas las causas de rechazo devuelven el mismo `401` a propósito: así nadie puede averiguar si una clave existe o fue revocada.

### Límite de peticiones

Por defecto, **120 peticiones por minuto por API key**. Al superarlo recibes `429` con `Retry-After`; espera esos segundos antes de reintentar. Si tu operación necesita más, pide que se amplíe el límite de tu clave.

### Verificar tu clave

[`GET /v1/me`](https://faktura-doc.cgallardo.me/endpoints/me/) responde con tu empresa, el entorno de la clave y si ya tienes certificado y usuario SOL configurados. Es la forma más simple de probar la integración.

## Guía: tu primera boleta en 10 minutos

Necesitas la **API key de prueba** (`sk_test_…`) que te entregó Faktura. Todo lo de esta guía va a SUNAT beta y no tiene validez tributaria.

### 1. Verifica tu clave

```bash
export FAKTURA_KEY="sk_test_..."
curl https://faktura-test.cgallardo.me/v1/me -H "Authorization: Bearer $FAKTURA_KEY"
```

Debes ver tu RUC y `"sunat_environment": "beta"`. Si recibes `401`, revisa que copiaste la clave completa ([Autenticación](https://faktura-doc.cgallardo.me/autenticacion/)).

### 2. Mira tus series

```bash
curl https://faktura-test.cgallardo.me/v1/series -H "Authorization: Bearer $FAKTURA_KEY"
```

Anota el `code` de la serie con `document_type: "03"` (por ejemplo `B001`).

### 3. Emite la boleta

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
  -H "Authorization: Bearer $FAKTURA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-primera-boleta-001" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "NONE" },
    "items": [ { "description": "Café americano", "quantity": 2, "unit_price": 8.00 } ]
  }'
```

La respuesta `201` trae el número asignado (`full_number`), los totales calculados (S/ 16.00, de los cuales S/ 2.44 son IGV), el total en letras y `status: "pending"`. Guarda el `id`.

### 4. Espera la respuesta de SUNAT

```bash
curl https://faktura-test.cgallardo.me/v1/documents/<id> -H "Authorization: Bearer $FAKTURA_KEY"
```

En uno o dos segundos verás `"status": "accepted"` y `"sunat": {"code": "0", "description": "La Boleta numero B001-1, ha sido aceptada", …}`.

### 5. Descarga el XML y el CDR

```bash
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/xml -H "Authorization: Bearer $FAKTURA_KEY"
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/cdr -H "Authorization: Bearer $FAKTURA_KEY"
```

### 6. Prueba los casos que tu POS va a encontrar

| Caso | Qué enviar | Qué esperar |
| --- | --- | --- |
| Cliente con DNI | `"customer": {"doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ"}` | `201` |
| Venta de más de S/ 700 sin cliente | `"customer": {"doc_type": "NONE"}` con un total mayor | `422 ReceiptRequiresCustomerDocument` |
| Bolsa plástica | ítem con `"icbper": true` | S/ 0.50 más por bolsa en `totals.icbper` |
| Producto exonerado | ítem con `"igv_type": "exonerado"` | IGV 0 en esa línea |
| Reintento por corte de red | la misma petición con la misma `Idempotency-Key` | `200` con el mismo comprobante |

### 7. Pasa a producción

Cuando Faktura confirme que tu empresa tiene certificado digital y usuario SOL (`GET /v1/me` muestra `has_certificate` y `has_sol_credentials` en `true`) y tus series de producción, cambia la clave por la `sk_live_…`. El código no cambia.

## Límite de peticiones

Cada API key puede hacer hasta **120 peticiones por minuto**. El límite se cuenta por clave: dos sistemas con claves distintas no se restan entre sí.

### Cabeceras

Cada respuesta de `/v1` informa el límite y lo que te queda en el minuto en curso:

| Cabecera | Descripción |
| --- | --- |
| `X-RateLimit-Limit` | Peticiones por minuto de tu clave (`120`). |
| `X-RateLimit-Remaining` | Peticiones que te quedan en este minuto. |

### Al superar el límite

La API responde `429 Too Many Requests` con la cabecera `Retry-After`, que indica los **segundos** que debes esperar antes de volver a intentar:

```json
{ "reason": "TooManyRequests" }
```

Los enlaces públicos del PDF (`links.public_pdf`, `links.public_ticket` y `links.public_ticket_58`) no descuentan del límite de tu API key: tienen su propio límite de 60 descargas por minuto.

### Cómo no llegar al límite

- **Respeta `Retry-After`** y reintenta después de ese tiempo, no en un bucle inmediato.
- **Usa [webhooks](https://faktura-doc.cgallardo.me/webhooks/)** para saber cuándo SUNAT responde, en lugar de consultar cada comprobante una y otra vez. Si consultas, espera entre intentos como indica [Estados y envío](https://faktura-doc.cgallardo.me/estados-y-envio/).
- **Consulta RUC en lote**: [hasta 1000 por llamada](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc-lote/) cuentan como una sola petición.
- **Reintenta una emisión con la misma `Idempotency-Key`** ([Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/)): no duplica el comprobante.

## Versiones

### Política

- La versión actual es **v1**. Dentro de v1 solo se agregan campos, endpoints y códigos de `reason` nuevos. Tu integración debe ignorar los campos que no conoce.
- Un cambio incompatible (quitar o renombrar un campo, cambiar un tipo) saldría en `/v2`, con al menos 6 meses de convivencia.

### Historial

| Fecha | Cambio |
| --- | --- |
| 2026-11-15 | `GET /v1/lookup/dni/{dni}`: consulta de DNI para personas naturales con negocio (RUC 10 en el padrón de SUNAT). `GET /v1/me` incorpora `api_key.scope` y `api_key.expires_at`. |
| 2026-11-14 | Firma inmediata al emitir (`sunat.hash` y `links.xml` desde la respuesta `201`), claves de alcance `lookup`, reenvío de comprobantes fallidos (`POST /v1/documents/{id}/retry`), formato `ticket58` (`links.public_ticket_58`) y `company.certificate_valid_until` en `/v1/me`. |
| 2026-11-14 | Emisión con `issue_date` (hasta 3 días atrás), tasa reducida de IGV (10.5 % para restaurantes y hoteles MYPE), recargo al consumo (`service_charge`), afectaciones `gratuito_exonerado` y `gratuito_inafecto`, motivos de nota de crédito 03, 04, 05, 08 y 13, descuentos por ítem y globales, detracción, retención del IGV, orden de compra, guías de remisión, listado `GET /v1/documents` y envío por correo (`POST /v1/documents/{id}/email`). |
| 2026-11-13 | Lanzamiento de **API v1**: facturas (`01`), boletas (`03`), notas de crédito (`07`), notas de débito (`08`), anulaciones (`RA` y `RC`), descargas de PDF (`a4` y `ticket`), XML y CDR, consultas de RUC individual y por lotes (`POST /v1/lookup/ruc`), webhooks firmados (`/v1/webhooks`), series (`/v1/series`), verificación de API key (`/v1/me`) e idempotencia. |

### Próximamente

Funcionalidades previstas en la hoja de ruta de **v1** (sin cambios incompatibles):

- Guía de remisión electrónica — remitente (`09`) y transportista (`31`).
- Facturas de exportación y operaciones con anticipos (incluidas notas de crédito de motivo `11`).
- Consulta de DNI para personas naturales sin RUC.
- Impuesto Selectivo al Consumo (ISC) e Impuesto a la Venta de Arroz Pilado (IVAP).
- Comprobantes de retención (`20`), percepción (`40`) y liquidación de compra (`04`).

## Emitir una factura

```http
POST /v1/invoices
```

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.

### Cuerpo

#### Datos generales y del cliente

| 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](https://faktura-doc.cgallardo.me/catalogos/#moneda-currency)). |
| `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](https://faktura-doc.cgallardo.me/calculo-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. |

#### Ítems (`items`)

| 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](https://faktura-doc.cgallardo.me/catalogos/#afectación-del-igv-itemsigv_type)). |
| `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](https://faktura-doc.cgallardo.me/catalogos/#unidad-de-medida-itemsunit_code). |
| `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

| 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](https://faktura-doc.cgallardo.me/catalogos/#bienes-y-servicios-sujetos-a-detracción-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](https://faktura-doc.cgallardo.me/catalogos/#medio-de-pago-de-la-detracción-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](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo)). |
| `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](https://faktura-doc.cgallardo.me/catalogos/#guías-de-remisión-relacionadas-despatch_references). |
| `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](https://faktura-doc.cgallardo.me/guias/factura-al-credito/) y en la [guía de descuentos, detracción y retención](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/).

### Ejemplo: factura al contado

```bash
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" }
    ]
  }'
```

### Respuesta `201 Created`

Devuelve las cabeceras `Location: /v1/documents/{id}` y `X-Request-Id`, y el [objeto comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) en estado `pending`:

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

### Flujo recomendado

1. **Al configurar tu sistema**: verifica tu clave con [`GET /v1/me`](https://faktura-doc.cgallardo.me/endpoints/me/) y elige una serie `F` activa con [`GET /v1/series`](https://faktura-doc.cgallardo.me/endpoints/series/).
2. **Datos del cliente**: si solo tienes su RUC, obtén razón social y dirección con [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/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](https://faktura-doc.cgallardo.me/webhooks/) `document.accepted`, o [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) con espera progresiva.
6. **Según el resultado**: con `accepted` u `observed`, entrega el [PDF](https://faktura-doc.cgallardo.me/endpoints/pdf/) o [envíalo por correo](https://faktura-doc.cgallardo.me/endpoints/comprobantes/correo/); con `rejected`, corrige y emite otra factura; con `failed`, corrige la causa y [reintenta](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/).

### Reglas de una factura

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

### Respuestas y errores

| 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](https://faktura-doc.cgallardo.me/errores/#errores-de-emisión-post-v1invoices-post-v1receipts). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto ([Límite de peticiones](https://faktura-doc.cgallardo.me/limite-de-peticiones/)). |

## Ejemplos de facturas

Recetas listas para copiar y validadas ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos. Los campos están explicados en [Emitir una factura](https://faktura-doc.cgallardo.me/endpoints/facturas/) y en [Emitir una boleta](https://faktura-doc.cgallardo.me/endpoints/boletas/#cuerpo).

Descuentos, detracción y retención tienen su propia [guía](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/), y la factura al crédito con cuotas también ([guía](https://faktura-doc.cgallardo.me/guias/factura-al-credito/)).

### Factura en dólares

Envía `"currency": "USD"` y los precios en dólares. Faktura calcula el IGV y los totales en esa moneda, y el importe en letras dice «DÓLARES AMERICANOS». No necesitas tipo de cambio, salvo que la factura lleve detracción.

```bash
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-9001" \
  -d '{
    "series": "F001",
    "currency": "USD",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Licencia de software (anual)", "quantity": 1, "unit_price": 590 } ]
  }'
```

Respuesta `201 Created` (resumida):

```json
{
  "currency": "USD",
  "totals": {
    "taxed": "500.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "90.00", "icbper": "0.00", "total_taxes": "90.00", "discounts": "0.00", "charges": "0.00", "total": "590.00"
  },
  "amount_in_words": "SON QUINIENTOS NOVENTA CON 00/100 DÓLARES AMERICANOS"
}
```

### Precios sin IGV

Si tu sistema guarda los precios sin IGV, envía `"price_includes_tax": false`: Faktura suma el 18 % encima. Con `true` (por defecto), `unit_price` ya incluye el IGV.

```bash
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-9002" \
  -d '{
    "series": "F001",
    "price_includes_tax": false,
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Servicio de consultoría", "quantity": 10, "unit_price": 100, "unit_code": "HUR" } ]
  }'
```

Diez horas de S/ 100.00 sin IGV dan una base de S/ 1000.00 y un total de S/ 1180.00:

```json
{
  "totals": {
    "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00"
  }
}
```

### Ítems gravados, exonerados e inafectos en la misma factura

Cada ítem lleva su `igv_type`. Sin él, el ítem es `gravado`. El IGV solo se calcula sobre los gravados. Qué productos están exonerados o inafectos lo decide la ley, no Faktura: consúltalo con tu contador.

```bash
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-9003" \
  -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": 30, "igv_type": "exonerado" },
      { "description": "Producto inafecto", "quantity": 1, "unit_price": 50, "igv_type": "inafecto" }
    ]
  }'
```

Cada tipo va en su propio total y el IGV sale solo de la laptop:

```json
{
  "totals": {
    "taxed": "100.00", "exempt": "60.00", "unaffected": "50.00", "free": "0.00",
    "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "228.00"
  }
}
```

### Entregas gratuitas (muestras o regalos)

Un ítem `gratuito` no se cobra: `unit_price` es su **valor referencial** (con IGV, salvo que envíes `price_includes_tax: false`). Su valor sin IGV aparece en `totals.free`, pero no suma al total. Usa `gratuito_exonerado` o `gratuito_inafecto` si el bien regalado está exonerado o inafecto. Los ítems gratuitos no admiten descuentos.

```bash
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-9004" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [
      { "description": "Caja de café 1 kg", "quantity": 5, "unit_price": 59 },
      { "description": "Taza de regalo", "quantity": 1, "unit_price": 23.60, "igv_type": "gratuito" }
    ]
  }'
```

La taza aparece en `free` por su valor sin IGV (23.60 / 1.18 = 20.00) y el cliente paga solo el café:

```json
{
  "totals": {
    "taxed": "250.00", "exempt": "0.00", "unaffected": "0.00", "free": "20.00",
    "igv": "45.00", "icbper": "0.00", "total_taxes": "45.00", "discounts": "0.00", "charges": "0.00", "total": "295.00"
  }
}
```

### Con orden de compra, guía de remisión y vencimiento

La orden de compra del cliente, las guías de remisión, las observaciones y la fecha de vencimiento viajan en el XML y aparecen en el PDF.

```bash
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-9005" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C.", "address": "AV. LOS OLIVOS 123, LIMA" },
    "items": [ { "description": "Cemento Portland tipo I (bolsa 42.5 kg)", "quantity": 100, "unit_price": 29.50, "unit_code": "BG" } ],
    "purchase_order": "OC-2026-001",
    "despatch_references": [ { "type": "09", "number": "T001-123" } ],
    "observations": "Entrega en almacén central",
    "due_date": "2026-12-15"
  }'
```

```json
{
  "totals": {
    "taxed": "2500.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "450.00", "icbper": "0.00", "total_taxes": "450.00", "discounts": "0.00", "charges": "0.00", "total": "2950.00"
  },
  "purchase_order": "OC-2026-001",
  "due_date": "2026-12-15"
}
```

### Con fecha de emisión anterior (contingencia)

Si vendiste sin conexión, emite después con la fecha real de la venta en `issue_date`: hasta **3 días atrás**, nunca una fecha futura. En este ejemplo la venta fue el 11 de noviembre y se emite el 13; usa siempre una fecha dentro de ese plazo.

```bash
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-9006" \
  -d '{
    "series": "F001",
    "issue_date": "2026-11-11",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Laptop", "quantity": 1, "unit_price": 118 } ]
  }'
```

```json
{
  "issue_date": "2026-11-11",
  "totals": {
    "taxed": "100.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "118.00"
  }
}
```

## Guía: factura al crédito con cuotas

SUNAT exige indicar en cada factura si se paga al contado o al crédito y, si es al crédito, el monto y el vencimiento de cada cuota.

### Reglas

- Solo facturas (`POST /v1/invoices`).
- De 1 a 60 cuotas.
- Cada cuota con monto mayor que cero y vencimiento **posterior** a la fecha de emisión.
- La suma de las cuotas debe ser **exactamente** el neto pendiente de pago (`net_payable`: el `totals.total` menos la detracción o la retención del IGV, si las hay).

Como la API calcula el total, conviene calcularlo antes con las mismas reglas ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/)) o, si trabajas con precios sin IGV, sumar base más 18 % redondeado por línea.

### Ejemplo: consultoría en dólares, a 2 cuotas

3 horas a USD 10.555 sin IGV → base 31.67 + IGV 5.70 = total **37.37**.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/invoices \
  -H "Authorization: Bearer $FAKTURA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-pedido-8842" \
  -d '{
    "series": "F001",
    "currency": "USD",
    "price_includes_tax": false,
    "customer": { "doc_type": "RUC", "doc_number": "20131312955", "name": "CLIENTE DE PRUEBA S.A.C." },
    "items": [ { "description": "Consultoría", "quantity": 3, "unit_price": 10.555, "unit_code": "HUR" } ],
    "payment": {
      "type": "credito",
      "installments": [
        { "amount": 20.00, "due_date": "2026-12-15" },
        { "amount": 17.37, "due_date": "2027-01-15" }
      ]
    }
  }'
```

La respuesta incluye:

```json
{
  "totals": {
    "taxed": "31.67", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "5.70", "icbper": "0.00", "total_taxes": "5.70", "discounts": "0.00", "charges": "0.00", "total": "37.37"
  },
  "amount_in_words": "SON TREINTA Y SIETE CON 37/100 DÓLARES AMERICANOS",
  "payment": {
    "type": "credito",
    "installments": [
      { "amount": "20.00", "due_date": "2026-12-15" },
      { "amount": "17.37", "due_date": "2027-01-15" }
    ]
  }
}
```

### Errores frecuentes

| `reason` | Causa |
| --- | --- |
| `InstallmentsDoNotMatchTotal` | Las cuotas suman distinto del total (revisa los redondeos). |
| `InvalidInstallments` | Una cuota vence hoy o antes, tiene monto cero, o hay más de 60. |
| `ValidationFailed` con `payment.installments:RequiredIf` | Indicaste `credito` sin cuotas. |

## Descuentos, detracción y retención

Ejemplos listos para copiar y validados ante SUNAT: solo cambia la API key, la serie y los datos del cliente por los tuyos.

### Descuento por ítem y descuento global

Con `price_includes_tax: true` (por defecto), los montos de descuento son **con IGV**: lo que deja de pagar el cliente. Faktura calcula la rebaja de la base imponible que exige SUNAT (catálogo 53: `00` por ítem, `02` global).

```bash
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-9101" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [
      { "description": "Laptop", "quantity": 1, "unit_price": 118, "discount": { "amount": 18 } },
      { "description": "Mouse", "quantity": 2, "unit_price": 50, "discount": { "percent": 10 } },
      { "description": "Libro", "quantity": 1, "unit_price": 20, "igv_type": "exonerado" }
    ],
    "discount": { "amount": 11.8 }
  }'
```

Respuesta (resumida):

```json
{
  "totals": {
    "taxed": "151.02", "exempt": "20.00", "unaffected": "0.00", "free": "0.00",
    "igv": "27.18", "icbper": "0.00", "total_taxes": "27.18", "discounts": "33.73", "charges": "0.00", "total": "198.20"
  },
  "global_discount": { "base_amount": "161.02", "amount": "10.00" }
}
```

| Ítem | Precio de lista | Descuento con IGV | Paga | Base (`line_value`) | `discount` (base) |
| --- | --- | --- | --- | --- | --- |
| Laptop | 118.00 | 18.00 | 100.00 | 84.75 | 15.25 |
| Mouse | 100.00 | 10.00 | 90.00 | 76.27 | 8.48 |
| Libro | 20.00 | — | 20.00 | 20.00 | 0.00 |

El descuento global de S/ 11.80 se aplica solo sobre los ítems gravados: su total con IGV pasa de 190.00 a 178.20. Así, la base gravada queda en 151.02, el IGV en 27.18 y el total en **198.20**. La respuesta lo detalla en `global_discount` y en `totals.discounts` (33.73 sobre la base).

Reglas:

- Cada descuento es `amount` **o** `percent`, nunca ambos (`details: ["discount:AmountOrPercent"]`).
- No se admiten descuentos en ítems gratuitos.
- El descuento global exige al menos un ítem gravado.
- Una nota de crédito que anula un comprobante con descuentos copia sus líneas **ya netas**, con el mismo total.
- Las notas con ítems propios no admiten descuentos.

### Detracción (SPOT)

Para servicios o bienes sujetos al Sistema de Pago de Obligaciones Tributarias. El porcentaje lo eliges según el código del bien o servicio (catálogo 54).

```bash
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-9102" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [{ "description": "Mantenimiento de equipos", "quantity": 1, "unit_price": 1180 }],
    "detraction": { "code": "020", "percent": 12, "bank_account": "00-000-123456" },
    "payment": { "type": "credito", "installments": [{ "amount": 1038.40, "due_date": "2026-12-15" }] }
  }'
```

Respuesta (resumida):

```json
{
  "totals": {
    "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00"
  },
  "net_payable": "1038.40",
  "detraction": { "code": "020", "percent": "12", "amount": "141.60", "amount_in_document_currency": "141.60", "bank_account": "00-000-123456", "payment_method": "001", "exchange_rate": null }
}
```

- La detracción es de 12 % sobre 1180.00, es decir S/ 141.60. Tu cliente la deposita en tu cuenta del Banco de la Nación.
- El neto pendiente de pago (`net_payable`) es 1038.40: las cuotas deben sumar exactamente eso.
- La factura va con tipo de operación `1001` y la leyenda "Operación sujeta a detracción".
- En dólares agrega `"exchange_rate": 3.75`. La detracción se informa en soles (1180 × 3.75 × 12 % = S/ 531.00) y en la moneda del comprobante (US$ 141.60).

### Retención del IGV

Si tu cliente es agente de retención, informa el 3 % que retendrá:

```bash
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-9103" \
  -d '{
    "series": "F001",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [{ "description": "Repuestos", "quantity": 1, "unit_price": 1180 }],
    "retention": true,
    "payment": { "type": "credito", "installments": [{ "amount": 1144.60, "due_date": "2026-12-15" }] }
  }'
```

Respuesta (resumida):

```json
{
  "totals": {
    "taxed": "1000.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "180.00", "icbper": "0.00", "total_taxes": "180.00", "discounts": "0.00", "charges": "0.00", "total": "1180.00"
  },
  "net_payable": "1144.60",
  "retention": { "percent": "3", "base_amount": "1180.00", "amount": "35.40" }
}
```

- La retención es de S/ 35.40 (catálogo 53, código `62`) y no cambia el total: reduce el neto pendiente de pago a 1144.60.
- Requiere soles y un total mayor a S/ 700. No se combina con detracción.

### Datos comerciales

Fragmento con los campos; el ejemplo completo está en el [recetario de facturas](https://faktura-doc.cgallardo.me/ejemplos/facturas/#con-orden-de-compra-guía-de-remisión-y-vencimiento).

```json
{
  "purchase_order": "OC-2026-001",
  "despatch_references": [{ "type": "09", "number": "T001-123" }],
  "observations": "Entrega en almacén central",
  "due_date": "2026-12-15"
}
```

Viajan en el XML (`OrderReference`, `DespatchDocumentReference`, `Note`, `DueDate`) y aparecen en el PDF.

## Emitir una boleta

```http
POST /v1/receipts
```

Emite una boleta de venta electrónica (tipo `03`) a un consumidor final. El cliente puede identificarse con DNI, CE, pasaporte o RUC, o ir sin documento (`NONE`) cuando la boleta es en soles y no supera S/ 700.

### Cuerpo

#### Datos generales y del cliente

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `series` | texto | Sí | Serie de boleta creada para tu empresa en el entorno de la clave, p. ej. `B001`. |
| `currency` | texto | No | `PEN` (por defecto) o `USD`. En dólares el cliente debe identificarse siempre. |
| `price_includes_tax` | booleano | No | `true` por defecto: `unit_price` incluye IGV ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/)). |
| `issue_date` | fecha | No | Fecha de emisión `YYYY-MM-DD`: hoy (por defecto) o hasta 3 días atrás, para ventas registradas sin conexión o en contingencia. Nunca futura (`InvalidIssueDate`). |
| `due_date` | fecha | No | Fecha de vencimiento `YYYY-MM-DD`, igual o posterior a la emisión. |
| `customer.doc_type` | texto | Sí | `DNI`, `CE`, `PASAPORTE`, `RUC` o `NONE` ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/)). |
| `customer.doc_number` | texto | Si no es `NONE` | Número de documento. |
| `customer.name` | texto | Si no es `NONE` | Nombre o razón social, hasta 200 caracteres. |
| `customer.address` | texto | No | Dirección, hasta 250 caracteres. |

#### Ítems (`items`)

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `items` | lista | Sí | Entre 1 y 500 ítems. |
| `items[].description` | texto | Sí | Hasta 500 caracteres. |
| `items[].quantity` | número o texto | Sí | Mayor que 0, hasta 10 decimales. |
| `items[].unit_price` | número o texto | Sí | Mayor que 0, hasta 10 decimales. En ítems gratuitos es el valor referencial. |
| `items[].igv_type` | texto | No | `gravado` (por defecto), `exonerado`, `inafecto`, `gratuito`, `gratuito_exonerado` o `gratuito_inafecto`. |
| `items[].icbper` | booleano | No | `true` para bolsas plásticas: agrega S/ 0.50 por unidad. |
| `items[].unit_code` | texto | No | Unidad de medida, `NIU` por defecto ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/#unidad-de-medida-itemsunit_code)). |
| `items[].product_code` | texto | No | Tu código interno, 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. El monto va en los mismos términos que `unit_price` (con o sin IGV). No se admite en ítems gratuitos. |

#### Descuentos, recargo y datos comerciales

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `discount` | objeto | No | Descuento global, `{"amount": 10}` o `{"percent": 5}`. Rebaja la base de los ítems **gravados**: con precios con IGV, el total baja exactamente ese monto. |
| `service_charge` | objeto | No | Recargo al consumo `{"percent": 10}` o `{"amount": 5}` ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo)). |
| `purchase_order` | texto | No | Orden de compra del cliente, hasta 20 caracteres (letras, números y `-/._`). |
| `despatch_references` | lista | No | Hasta 10 guías de remisión relacionadas: `{"type": "09", "number": "T001-123"}` (o `"type": "31"`). Ver [Catálogos](https://faktura-doc.cgallardo.me/catalogos/#guías-de-remisión-relacionadas-despatch_references). |
| `observations` | texto | No | Hasta 500 caracteres; aparece en el XML y en el PDF. |

Sin `issue_date`, la fecha de emisión es el día actual en hora de Perú.

### Ejemplo

```bash
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": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" },
    "items": [
      { "product_code": "CAF-01", "description": "Cafe americano", "quantity": 2, "unit_price": 8.00 },
      { "description": "Bolsa plastica", "quantity": 1, "unit_price": 0.10, "icbper": true }
    ]
  }'
```

### Respuesta `201 Created`

Con las cabeceras `Location: /v1/documents/{id}` y `X-Request-Id`. El cuerpo es el [comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) en estado `pending`:

```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",
  "status": "pending",
  "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": null, "description": null, "notes": [], "hash": "x/NyYaC+yItSOzJpanQWdBmcxDE=", "send_attempts": 0 },
  "links": {
    "self": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81",
    "xml": "/v1/documents/01a1d5fc-899b-720e-a6ea-03d37a346f81/xml",
    "cdr": null,
    "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=…"
  }
}
```

Unos segundos después, [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) muestra `status: "accepted"`, el código y la descripción de SUNAT, el `hash` y los enlaces al XML y al CDR.

Repetir la petición con la misma `Idempotency-Key` y el mismo cuerpo responde `200 OK` con `Idempotent-Replayed: true` y el mismo comprobante.

### Flujo recomendado

1. **Al configurar tu POS**: verifica tu clave con [`GET /v1/me`](https://faktura-doc.cgallardo.me/endpoints/me/) y elige una serie `B` activa con [`GET /v1/series`](https://faktura-doc.cgallardo.me/endpoints/series/).
2. **Cliente**: hasta S/ 700 en soles puedes emitir sin documento (`NONE`). Si el cliente da su DNI y tiene RUC 10, puedes autocompletar su nombre con [Consultar un DNI](https://faktura-doc.cgallardo.me/endpoints/consultas/dni/).
3. **Emite**: `POST /v1/receipts` con una `Idempotency-Key` única por venta (por ejemplo, caja + correlativo del ticket).
4. **Imprime** con el `full_number` de la respuesta `201`, sin esperar a SUNAT.
5. **Confirma** el resultado con un [webhook](https://faktura-doc.cgallardo.me/webhooks/) o [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/), y entrega el [PDF en formato ticket](https://faktura-doc.cgallardo.me/endpoints/pdf/) si el cliente lo pide.

### Reglas de una boleta

- La serie debe empezar con `B`.
- Si el total supera **S/ 700.00**, el cliente debe identificarse (`ReceiptRequiresCustomerDocument`).
- En dólares, el cliente debe identificarse siempre.
- Solo al contado: el crédito con cuotas es exclusivo de facturas (`CreditOnlyForInvoices`).
- Detracción y retención son exclusivas de facturas (`DetractionOnlyForInvoices`, `RetentionOnlyForInvoices`).
- Ejemplo con descuentos en la [guía de descuentos](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/).

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `201` | — | Boleta 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 boleta no es válido. Ver la [tabla completa de errores de emisión](https://faktura-doc.cgallardo.me/errores/#errores-de-emisión-post-v1invoices-post-v1receipts). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto ([Límite de peticiones](https://faktura-doc.cgallardo.me/limite-de-peticiones/)). |

## Ejemplos de boletas

Recetas listas para copiar y validadas ante SUNAT, igual que las de [facturas](https://faktura-doc.cgallardo.me/ejemplos/facturas/). Los campos están explicados en [Emitir una boleta](https://faktura-doc.cgallardo.me/endpoints/boletas/).

La boleta más simple, sin datos del cliente, está en la [guía de la primera boleta](https://faktura-doc.cgallardo.me/guias/primera-boleta/); la boleta con bolsa plástica (ICBPER), en el [ejemplo de boletas](https://faktura-doc.cgallardo.me/endpoints/boletas/#ejemplo).

### Venta de más de S/ 700: cliente identificado

Una boleta sin documento del cliente (`NONE`) solo se admite hasta S/ 700.00. Por encima, identifica al cliente con DNI, CE, pasaporte o RUC; si no, la API responde `422 ReceiptRequiresCustomerDocument`.

```bash
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-000301" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ" },
    "items": [ { "description": "Refrigeradora 300 L", "quantity": 1, "unit_price": 1899 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "1609.32", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "289.68", "icbper": "0.00", "total_taxes": "289.68", "discounts": "0.00", "charges": "0.00", "total": "1899.00"
  },
  "amount_in_words": "SON MIL OCHOCIENTOS NOVENTA Y NUEVE CON 00/100 SOLES"
}
```

### Restaurante: recargo al consumo

`service_charge` agrega el recargo al consumo (por ejemplo, 10 %). Se calcula sobre el valor de venta sin IGV, no forma parte de la base del IGV y se suma al total ([Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo)).

```bash
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-000302" \
  -d '{
    "series": "B001",
    "customer": { "doc_type": "NONE" },
    "items": [
      { "description": "Lomo saltado", "quantity": 2, "unit_price": 38 },
      { "description": "Chicha morada (jarra)", "quantity": 1, "unit_price": 18 }
    ],
    "service_charge": { "percent": 10 }
  }'
```

El recargo es el 10 % de la base sin IGV (79.66), va en `totals.charges` y en `service_charge`, y se suma al total:

```json
{
  "totals": {
    "taxed": "79.66", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "14.34", "icbper": "0.00", "total_taxes": "14.34", "discounts": "0.00", "charges": "7.97", "total": "101.97"
  },
  "service_charge": { "base_amount": "79.66", "amount": "7.97" }
}
```

### Boleta en dólares

En dólares el cliente debe estar identificado siempre, aunque el monto sea bajo.

```bash
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-000303" \
  -d '{
    "series": "B001",
    "currency": "USD",
    "customer": { "doc_type": "PASAPORTE", "doc_number": "X1234567", "name": "JOHN SMITH" },
    "items": [ { "description": "Tour Valle Sagrado", "quantity": 2, "unit_price": 45 } ]
  }'
```

```json
{
  "currency": "USD",
  "totals": {
    "taxed": "76.27", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "13.73", "icbper": "0.00", "total_taxes": "13.73", "discounts": "0.00", "charges": "0.00", "total": "90.00"
  },
  "amount_in_words": "SON NOVENTA CON 00/100 DÓLARES AMERICANOS"
}
```

## Emitir una nota de crédito

```http
POST /v1/credit-notes
```

Una nota modifica un comprobante **ya aceptado por SUNAT**. La nota de crédito disminuye o anula el monto (devoluciones, anulaciones, rebajas) o reprograma el cronograma de cuotas; la nota de débito lo aumenta (intereses, penalidades). La nota hereda el cliente y la moneda del comprobante afectado y se envía a SUNAT igual que una factura o boleta ([Estados](https://faktura-doc.cgallardo.me/estados-y-envio/)).

### Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `affected_document_id` | UUID | Sí | `id` del comprobante que se modifica. Debe estar `accepted` u `observed` y no estar anulado. |
| `series` | texto | Sí | Serie de nota creada para tu empresa. Debe empezar con la misma letra que el comprobante: `F` para facturas (`FC01`) y `B` para boletas (`BC01`). |
| `reason_code` | texto | Sí | Motivo SUNAT, de 2 dígitos (catálogo 09; ver la tabla abajo). |
| `reason_description` | texto | No | Sustento, hasta 250 caracteres. Por defecto, la descripción oficial del motivo. |
| `price_includes_tax` | booleano | No | Igual que al emitir: `true` por defecto. |
| `issue_date` | fecha | No | Igual que al emitir: hasta 3 días atrás y nunca antes de la fecha del comprobante afectado (`NoteIssuedBeforeAffected`). |
| `items` | lista | Según el motivo | En los motivos `01`, `02`, `03` y `06` puedes omitirlos y se copian los del comprobante; en `04`, `05`, `07`, `08`, `09` y `10` son obligatorios; en `13` no se admiten. |
| `items[].description` | texto | Sí (en ítems) | Descripción del ítem, hasta 500 caracteres. |
| `items[].quantity` | número o texto | Sí (en ítems) | Cantidad mayor que 0, hasta 10 decimales. |
| `items[].unit_price` | número o texto | Sí (en ítems) | Precio unitario mayor que 0, hasta 10 decimales. |
| `items[].igv_type` | texto | No | `gravado` (por defecto), `exonerado`, `inafecto`, `gratuito`, `gratuito_exonerado` o `gratuito_inafecto`. |
| `items[].icbper` | booleano | No | `true` si el ítem devuelto corresponde a una bolsa plástica. |
| `items[].unit_code` | texto | No | Unidad de medida (`NIU` por defecto). |
| `items[].product_code` | texto | No | Tu código interno, hasta 30 caracteres. |
| `items[].sunat_product_code` | texto | No | Código de producto SUNAT (catálogo 25, UNSPSC) de 8 dígitos. |
| `payment` | objeto | Solo motivo `13` | Nuevo cronograma: `{"type": "credito", "installments": [{"amount": 100, "due_date": "2026-12-15"}]}`. |

### Motivos admitidos (catálogo 09)

| `reason_code` | Motivo | `items` |
| --- | --- | --- |
| `01` | Anulación de la operación | Opcional: sin ítems copia el comprobante completo |
| `02` | Anulación por error en el RUC | Opcional: sin ítems copia el comprobante completo |
| `03` | Corrección por error en la descripción | Opcional: sin ítems copia el comprobante completo |
| `04` | Descuento global | Obligatorio |
| `05` | Descuento por ítem | Obligatorio |
| `06` | Devolución total | Opcional: sin ítems copia el comprobante completo |
| `07` | Devolución por ítem | Obligatorio |
| `08` | Bonificación | Obligatorio |
| `09` | Disminución en el valor | Obligatorio |
| `10` | Otros conceptos | Obligatorio |
| `13` | Ajustes: montos y/o fechas de pago | No admite ítems: va con `payment` |

Una nota de crédito no puede superar el total del comprobante (`CreditNoteExceedsAffectedTotal`), y las notas que rebajan el monto (todas menos la 03 y la 13) no pueden sumar, entre todas, más que el comprobante (`CreditNotesExceedAffectedTotal`): por ejemplo, no se anula dos veces la misma factura. No se admiten los motivos de exportación (11) ni IVAP (12).

### Motivo 13: cambiar el cronograma de una factura al crédito

Corrige el monto neto pendiente, las fechas o las cuotas de una factura al crédito. La nota va en **cero** (una línea informativa «AJUSTE DE MONTOS Y/O FECHAS DE PAGO») y lleva el nuevo cronograma; las cuotas no pueden sumar más que el neto pendiente del comprobante.

```json
{
  "affected_document_id": "01a1d5fd-…",
  "series": "FC01",
  "reason_code": "13",
  "payment": { "type": "credito", "installments": [
    { "amount": 590, "due_date": "2026-12-15" },
    { "amount": 590, "due_date": "2027-01-15" }
  ] }
}
```

Errores propios: `PaymentAdjustmentRequiresCreditInvoice` (la factura no es al crédito), `PaymentAdjustmentRequiresInstallments`, `NoteItemsNotAllowed`, `InstallmentsExceedPendingAmount` y `PaymentOnlyForAdjustmentNotes` (cronograma en otro motivo).

### Flujo recomendado

1. **Comprueba** que el comprobante esté `accepted` u `observed` con [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).
2. **Elige el motivo**: `01` para anular toda la operación, `07` para una devolución parcial, `04` para un descuento posterior.
3. **Elige la serie** de nota de la misma letra que el comprobante: `FC01` para facturas, `BC01` para boletas.
4. **Emite** `POST /v1/credit-notes` con una `Idempotency-Key` y guarda el `id` de la nota.
5. **Confirma** con SUNAT igual que una factura: [webhook](https://faktura-doc.cgallardo.me/webhooks/) o [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) de la nota.

### Ejemplo: anular una factura con nota de crédito

Anula por completo la factura `F001-1` del [ejemplo de facturas](https://faktura-doc.cgallardo.me/endpoints/facturas/#ejemplo-factura-al-contado), de S/ 129.00:

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "affected_document_id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac",
    "series": "FC01",
    "reason_code": "01"
  }'
```

Respuesta `201 Created`: un [comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) con `document_type: "07"` y el bloque `note`:

```json
{
  "document_type": "07",
  "full_number": "FC01-1",
  "status": "pending",
  "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"
  },
  "note": {
    "reason_code": "01",
    "reason_description": "ANULACION DE LA OPERACION",
    "affected_document": {
      "id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac",
      "document_type": "01",
      "full_number": "F001-1"
    }
  }
}
```

### ¿Nota de crédito o anulación?

| Situación | Usa |
| --- | --- |
| El comprobante tiene un error y está dentro del plazo de anulación | [Anulación](https://faktura-doc.cgallardo.me/endpoints/anulacion/) |
| Pasó el plazo de anulación, o el cliente devuelve todo o parte | Nota de crédito |
| Hay que cobrar algo adicional sobre una venta ya emitida | Nota de débito |

Más casos (devolución parcial, descuento posterior, nota a una boleta) en los [ejemplos de notas y anulaciones](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/).

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `201` | — | Nota de crédito 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` | `AffectedDocumentNotAccepted`, `AffectedDocumentVoided`, `IdempotencyKeyReused`, `EmitterNotReadyForProduction`, `CertificateExpired` | El comprobante afectado aún no fue aceptado por SUNAT, está anulado, o se reutilizó `Idempotency-Key` con otro cuerpo. |
| `422` | `AffectedDocumentNotFound`, `InvalidAffectedDocument`, `InvalidNoteReason`, `NoteSeriesMismatch`, `NoteItemsRequired`, `CreditNoteExceedsAffectedTotal`, `CreditNotesExceedAffectedTotal` | Error de validación o regla de negocio. Ver todos en [Errores de notas](https://faktura-doc.cgallardo.me/errores/#errores-de-notas). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Emitir una nota de débito

```http
POST /v1/debit-notes
```

La nota de débito **aumenta** el monto de un comprobante ya aceptado por SUNAT: intereses por mora, aumentos de valor o penalidades. Hereda el cliente y la moneda del comprobante afectado y se envía a SUNAT igual que una factura o boleta ([Estados](https://faktura-doc.cgallardo.me/estados-y-envio/)).

### Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `affected_document_id` | UUID | Sí | `id` del comprobante que se modifica. Debe estar `accepted` u `observed` y no estar anulado. |
| `series` | texto | Sí | Serie de nota de débito creada para tu empresa. Debe empezar con la misma letra que el comprobante: `F` para facturas (`FD01`) y `B` para boletas (`BD01`). |
| `reason_code` | texto | Sí | Motivo SUNAT, de 2 dígitos (catálogo 10; ver la tabla abajo). |
| `reason_description` | texto | No | Sustento, hasta 250 caracteres. Por defecto, la descripción oficial del motivo. |
| `price_includes_tax` | booleano | No | Igual que al emitir: `true` por defecto (`unit_price` incluye IGV). |
| `issue_date` | fecha | No | Igual que al emitir: hoy (por defecto) o hasta 3 días atrás, nunca antes de la fecha del comprobante afectado (`NoteIssuedBeforeAffected`). |
| `items` | lista | Sí | Entre 1 y 500 ítems con el cargo adicional; en las notas de débito siempre son obligatorios (`NoteItemsRequired`). |
| `items[].description` | texto | Sí | Descripción del interés, aumento de valor o penalidad, 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. |
| `items[].igv_type` | texto | No | `gravado` (por defecto), `exonerado`, `inafecto`, `gratuito`, `gratuito_exonerado` o `gratuito_inafecto`. |
| `items[].icbper` | booleano | No | `true` si el ítem corresponde a bolsas plásticas. |
| `items[].unit_code` | texto | No | Unidad de medida (`NIU` por defecto, `ZZ` para servicios). |
| `items[].product_code` | texto | No | Tu código interno, hasta 30 caracteres. |
| `items[].sunat_product_code` | texto | No | Código de producto SUNAT (catálogo 25, UNSPSC) de 8 dígitos. |

En las notas de débito no se admiten descuentos ni el bloque `payment`.

### Motivos admitidos (catálogo 10)

| `reason_code` | Motivo |
| --- | --- |
| `01` | Intereses por mora |
| `02` | Aumento en el valor |
| `03` | Penalidades / otros conceptos |

### Ejemplo: nota de débito por intereses

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/debit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "affected_document_id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac",
    "series": "FD01",
    "reason_code": "01",
    "items": [ { "description": "Intereses por mora", "quantity": 1, "unit_price": 11.80 } ]
  }'
```

### Respuesta `201 Created`

Devuelve el [comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) con `document_type: "08"` y el bloque `note`:

```json
{
  "document_type": "08",
  "full_number": "FD01-1",
  "status": "pending",
  "totals": {
    "taxed": "10.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "1.80", "icbper": "0.00", "total_taxes": "1.80", "discounts": "0.00", "charges": "0.00", "total": "11.80"
  },
  "note": {
    "reason_code": "01",
    "reason_description": "INTERESES POR MORA",
    "affected_document": {
      "id": "01a1d60a-7aa5-735b-9cf0-94b9d58a67ac",
      "document_type": "01",
      "full_number": "F001-1"
    }
  }
}
```

### Flujo recomendado

1. **Comprueba** que el comprobante original esté `accepted` u `observed` con [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).
2. **Elige el motivo** del catálogo 10 (`01` intereses por mora, `02` aumento en el valor, `03` penalidades) y la serie que corresponda a la letra del comprobante (`FD01` para facturas, `BD01` para boletas).
3. **Emite** `POST /v1/debit-notes` con `Idempotency-Key` y los `items` que detallan el cargo adicional.
4. **Confirma** la aceptación de SUNAT por [webhook](https://faktura-doc.cgallardo.me/webhooks/) o [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).

Otro caso, una penalidad contractual, está en los [ejemplos de notas y anulaciones](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#nota-de-débito-por-penalidad).

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `201` | — | Nota de débito 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` | `AffectedDocumentNotAccepted`, `AffectedDocumentVoided`, `IdempotencyKeyReused`, `EmitterNotReadyForProduction`, `CertificateExpired` | El comprobante afectado aún no fue aceptado por SUNAT, está anulado, o se reutilizó `Idempotency-Key` con otro cuerpo. |
| `422` | `AffectedDocumentNotFound`, `InvalidAffectedDocument`, `InvalidNoteReason`, `NoteSeriesMismatch`, `NoteItemsRequired` | Error de validación o regla de negocio. Ver todos en [Errores de notas](https://faktura-doc.cgallardo.me/errores/#errores-de-notas). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Ejemplos de notas y anulaciones

Recetas listas para copiar cuando necesites corregir o anular un comprobante que SUNAT ya aceptó. Usan como referencia la factura `F001-1` del [ejemplo de facturas](https://faktura-doc.cgallardo.me/endpoints/facturas/#ejemplo-factura-al-contado) (una laptop de S/ 118.00 y dos libros exonerados de S/ 5.50) y la boleta `B001-1` del [ejemplo de boletas](https://faktura-doc.cgallardo.me/endpoints/boletas/#ejemplo). Reemplaza `<id-de-la-factura>` o `<id-de-la-boleta>` por el `id` que te devolvió la API al emitirlas.

Las reglas de cada motivo están en [Emitir una nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/), [Emitir una nota de débito](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/) y [Anular un comprobante](https://faktura-doc.cgallardo.me/endpoints/anulacion/).

### ¿Nota de crédito o anulación?

| Situación | Qué usar |
| --- | --- |
| El comprobante tiene un error y no debió existir | [Anulación](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#anular-una-boleta) (comunicación de baja o resumen diario), o nota de crédito motivo `01` |
| El cliente devuelve parte de lo comprado | Nota de crédito motivo `07` (devolución por ítem) |
| Das un descuento después de emitir | Nota de crédito motivo `04` (descuento global) |
| Cobras intereses o una penalidad | Nota de débito |

### Devolver parte de una factura

El cliente devuelve los dos libros. La nota de crédito lleva solo los ítems devueltos, con su precio.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-devolucion-0001" \
  -d '{
    "affected_document_id": "<id-de-la-factura>",
    "series": "FC01",
    "reason_code": "07",
    "reason_description": "Devolución de 2 libros",
    "items": [ { "description": "Libro", "quantity": 2, "unit_price": 5.5, "igv_type": "exonerado" } ]
  }'
```

Los libros son exonerados, así que la nota no lleva IGV:

```json
{
  "totals": {
    "taxed": "0.00", "exempt": "11.00", "unaffected": "0.00", "free": "0.00",
    "igv": "0.00", "icbper": "0.00", "total_taxes": "0.00", "discounts": "0.00", "charges": "0.00", "total": "11.00"
  }
}
```

### Descuento después de emitir

Un descuento por pronto pago de S/ 11.80 (IGV incluido) sobre la factura.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-descuento-0001" \
  -d '{
    "affected_document_id": "<id-de-la-factura>",
    "series": "FC01",
    "reason_code": "04",
    "reason_description": "Descuento por pronto pago",
    "items": [ { "description": "Descuento por pronto pago", "quantity": 1, "unit_price": 11.80 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "10.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "1.80", "icbper": "0.00", "total_taxes": "1.80", "discounts": "0.00", "charges": "0.00", "total": "11.80"
  }
}
```

### Nota de crédito a una boleta

Las notas de una boleta usan una serie que empieza con `B` (`BC01`). Aquí el cliente devuelve uno de los dos cafés.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/credit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-0042-devolucion-01" \
  -d '{
    "affected_document_id": "<id-de-la-boleta>",
    "series": "BC01",
    "reason_code": "07",
    "items": [ { "description": "Cafe americano", "quantity": 1, "unit_price": 8.00 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "6.78", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "1.22", "icbper": "0.00", "total_taxes": "1.22", "discounts": "0.00", "charges": "0.00", "total": "8.00"
  }
}
```

### Nota de débito por penalidad

La nota de débito aumenta el monto del comprobante. Sus `items` son obligatorios.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/debit-notes \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-penalidad-0001" \
  -d '{
    "affected_document_id": "<id-de-la-factura>",
    "series": "FD01",
    "reason_code": "03",
    "reason_description": "Penalidad por entrega tardía",
    "items": [ { "description": "Penalidad por entrega tardía", "quantity": 1, "unit_price": 59 } ]
  }'
```

```json
{
  "totals": {
    "taxed": "50.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "9.00", "icbper": "0.00", "total_taxes": "9.00", "discounts": "0.00", "charges": "0.00", "total": "59.00"
  }
}
```

### Anular una boleta

La anulación de una boleta viaja en un resumen diario (RC). SUNAT responde con un ticket que Faktura consulta sola. El estado de la baja se ve en el bloque `void` del comprobante.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/documents/<id-de-la-boleta>/void \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Venta duplicada" }'
```

Una factura se anula igual, con su propio `id`: Faktura envía una comunicación de baja (RA) en lugar del resumen ([Anular un comprobante](https://faktura-doc.cgallardo.me/endpoints/anulacion/)).

## Listar comprobantes

```http
GET /v1/documents?document_type=03&from=2026-11-01&to=2026-11-30&page=1&page_size=50
```

Comprobantes de tu empresa en el entorno de tu API key, del más reciente al más antiguo. Sirve para cuadrar la caja del día, conciliar estados o recuperar un comprobante si perdiste la respuesta de la emisión.

### Parámetros

Todos son opcionales y se combinan entre sí.

| Parámetro | Descripción |
| --- | --- |
| `document_type` | `01`, `03`, `07` u `08`. |
| `series`, `number` | Serie (`B001`) y correlativo. |
| `status` | `pending`, `sending`, `uncertain`, `accepted`, `observed`, `rejected` o `failed`. |
| `from`, `to` | Rango de fechas de emisión `YYYY-MM-DD` (inclusive). |
| `customer_doc_number` | Documento del cliente. |
| `page`, `page_size` | Página (desde 1) y tamaño (1 a 100, 20 por defecto). |

### Ejemplo

```bash
curl "https://faktura-test.cgallardo.me/v1/documents?document_type=03&from=2026-11-01&to=2026-11-30&page=1&page_size=50" \
  -H "Authorization: Bearer sk_test_..."
```

#### Buscar por serie y correlativo

```bash
curl "https://faktura-test.cgallardo.me/v1/documents?series=B001&number=1" \
  -H "Authorization: Bearer sk_test_..."
```

### Respuesta `200 OK`

```json
{
  "items": [
    {
      "id": "01a1d5fd-…", "document_type": "03", "series": "B001", "number": 2, "full_number": "B001-2",
      "issue_date": "2026-11-14", "currency": "PEN",
      "customer": { "doc_type": "DNI", "doc_number": "45678912", "name": "MARÍA PÉREZ" },
      "total": "9.00", "status": "accepted", "void": null,
      "links": { "self": "/v1/documents/01a1d5fd-…" }
    }
  ],
  "page": 1, "page_size": 50, "total_count": 1
}
```

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `items[]` | lista | Resumen de cada comprobante de la página (`id`, `document_type`, `series`, `number`, `full_number`, `issue_date`, `currency`, `customer`, `total`, `status`, `void`, `links.self`). |
| `items[].total` | texto | Importe total del comprobante como texto decimal (`"9.00"`). El desglose completo de impuestos y líneas está en [Ver un comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/). |
| `items[].void` | objeto o null | `null` si no se pidió anulación, o `{"status": "requested", "reason": "…"}` (donde `status` es `requested`, `voided` o `rejected`). |
| `page`, `page_size` | entero | Página devuelta y tamaño de página aplicado. |
| `total_count` | entero | Total de comprobantes que cumplen los filtros enviados. |

### Respuestas y errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `200` | — | Devuelve la página de comprobantes. |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `422` | `ValidationFailed` | Un parámetro tiene un valor inválido (por ejemplo, `page_size` mayor a 100 o `to` anterior a `from`). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Ver un comprobante

```http
GET /v1/documents/{id}
```

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.

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

## Representación impresa (PDF)

```http
GET /v1/documents/{id}/pdf?format=a4|ticket|ticket58
```

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.

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

## Descargar el XML firmado

```http
GET /v1/documents/{id}/xml
```

Devuelve el XML UBL 2.1 firmado (`Content-Type: application/xml`), con el nombre oficial que exige SUNAT en la cabecera `Content-Disposition`: `<RUC>-<tipo>-<serie>-<correlativo>.xml` (p. ej. `20000000001-03-B001-1.xml`).

### Ejemplo

Guarda el archivo con el nombre que indica la API:

```bash
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/xml -H "Authorization: Bearer sk_test_..."
```

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve el XML UBL 2.1 firmado (`application/xml`). |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `404` | `NotFound` | El comprobante no existe para tu clave o aún no tiene XML firmado. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Descargar el CDR

```http
GET /v1/documents/{id}/cdr
```

Devuelve la constancia de recepción de SUNAT tal como la entregó (`Content-Type: application/zip`, p. ej. `R-20000000001-03-B001-1.zip`). Conserva este archivo: es la prueba legal de que SUNAT recibió y aceptó el comprobante.

### Ejemplo

```bash
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/cdr -H "Authorization: Bearer sk_test_..."
```

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve el archivo ZIP del CDR (`application/zip`). |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `404` | `NotFound` | El comprobante no existe para tu clave o SUNAT aún no entregó el CDR (`links.cdr` es `null`). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Enviar el comprobante por correo

```http
POST /v1/documents/{id}/email
```

Encola el envío del PDF A4, el XML firmado y el CDR a hasta 5 destinatarios. Responde `202 Accepted`; el envío ocurre en segundo plano y se reintenta si el servidor de correo falla. El remitente lleva el nombre de tu empresa. Un comprobante de prueba (clave `sk_test_`) se envía con el asunto `[PRUEBA]` y un aviso de que no tiene valor tributario.

### Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `to` | lista | Sí | De 1 a 5 correos de destino. |

### Ejemplo

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/documents/<id>/email \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": ["cliente@ejemplo.pe"] }'
```

### Respuesta `202 Accepted`

```json
{
  "id": "01a1d5fc-899b-720e-a6ea-03d37a346f81",
  "status": "queued",
  "to": ["cliente@ejemplo.pe"]
}
```

### Respuestas y errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `202` | — | Envío encolado (`status: "queued"`). |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `404` | `NotFound` | El comprobante no existe para tu clave. |
| `409` | `DocumentNotAccepted` | SUNAT aún no aceptó el comprobante: un PDF sin aceptación no tiene validez. |
| `422` | `ValidationFailed`, `InvalidRecipients` | `to` falta, tiene más de 5 destinatarios o contiene un correo inválido. |
| `429` | `EmailLimitReached`, `TooManyRequests` | Tope alcanzado: 10 envíos por comprobante y 100 por emisor por hora (o el límite de 120 peticiones/min de la clave). |
| `503` | `EmailNotConfigured` | El envío de correos no está habilitado en el servicio. |

## Reenviar un comprobante que falló

```http
POST /v1/documents/{id}/retry
```

Un comprobante en estado `failed` no llegó a SUNAT por una causa ajena a su contenido: usuario o clave SOL incorrectos, perfil sin permiso o emisor sin credenciales de producción. Una vez corregida la causa, este endpoint lo vuelve a `pending` y el envío se repite (`202 Accepted`). Todo número emitido debe llegar a SUNAT, así que no lo dejes en `failed`.

### Ejemplo

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/documents/<id>/retry -H "Authorization: Bearer sk_test_..."
```

### Respuesta `202 Accepted`

```json
{
  "id": "01a1d5fc-899b-720e-a6ea-03d37a346f81",
  "status": "pending"
}
```

### Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `409` | `DocumentNotRetryable` | El comprobante no está `failed`. Uno `rejected` no se reenvía: su contenido es inválido y corresponde emitir otro. |
| `404` | `NotFound` | El comprobante no existe para tu clave. |

## Anular un comprobante

```http
POST /v1/documents/{id}/void
```

Pide a SUNAT la anulación (baja) de un comprobante **aceptado**. Faktura elige el mecanismo según la serie:

| Serie | Comprobantes | Mecanismo SUNAT |
| --- | --- | --- |
| `F…` | Facturas y sus notas | Comunicación de baja (RA) |
| `B…` | Boletas y sus notas | Resumen diario con estado 3, anular (RC) |

SUNAT no responde en el momento: devuelve un ticket que Faktura consulta en segundo plano hasta obtener el resultado.

### Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `reason` | texto | Sí | Motivo de la baja, hasta 100 caracteres. Se guarda en mayúsculas. |

### Ejemplo

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/documents/01a1d60b-1d4e-7c8a-9f02-3b6c5d1e2f40/void \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Error en el precio" }'
```

### Respuesta `202 Accepted`

El [comprobante](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/#el-objeto-comprobante) con el bloque `void`:

```json
{
  "full_number": "F001-2",
  "status": "accepted",
  "void": { "status": "requested", "reason": "ERROR EN EL PRECIO" }
}
```

`status` sigue siendo el estado del **envío** del comprobante (`accepted`). El resultado de la baja está en `void.status`.

### Estados de la anulación (`void.status`)

| `void.status` | Significado |
| --- | --- |
| `requested` | Enviada a SUNAT; esperando la respuesta del ticket. |
| `voided` | SUNAT aceptó la baja. El comprobante ya no tiene efecto tributario. |
| `rejected` | SUNAT rechazó la baja o no pudo procesarla. El comprobante **sigue vigente**. Puedes corregir y pedirla otra vez, o emitir una nota de crédito. |

Consulta `GET /v1/documents/{id}` con la misma espera progresiva que para el envío ([Estados](https://faktura-doc.cgallardo.me/estados-y-envio/#cómo-saber-cuándo-terminó)). SUNAT suele responder en segundos, pero en ocasiones tarda bastante más.

### Flujo recomendado

1. **Decide si corresponde anular**: solo dentro de los 7 días calendario desde la emisión y si el comprobante no tiene notas. Si no, usa una [nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/).
2. **Pide la baja** con `POST /v1/documents/{id}/void` y un motivo claro.
3. **Espera el ticket de SUNAT**: el aviso `document.voided` o `document.void_rejected` por [webhook](https://faktura-doc.cgallardo.me/webhooks/), o `void.status` en [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/).
4. **Si SUNAT la rechaza**, el comprobante sigue vigente: corrige y vuelve a pedirla, o emite una nota de crédito.

### Reglas

- Solo comprobantes `accepted` u `observed` (`DocumentNotAccepted`).
- Dentro del plazo: hasta **7 días calendario** después de la fecha de emisión (`VoidWindowExpired`). Pasado el plazo, usa una [nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/).
- Una sola anulación en curso por comprobante (`VoidAlreadyRequested`); un comprobante anulado no se puede volver a anular (`AlreadyVoided`).
- Un comprobante anulado o con anulación en curso no admite notas (`AffectedDocumentVoided`).
- Un comprobante con notas de crédito o débito vigentes no se anula (`DocumentHasNotes`): primero anula sus notas.

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `202` | — | Solicitud de baja aceptada y encolada para SUNAT (`void.status: "requested"`). |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient`, `EmitterInactive` | Clave de alcance `lookup` o empresa desactivada. |
| `404` | `NotFound` | El comprobante no existe en tu empresa y entorno. |
| `409` | `DocumentNotAccepted`, `VoidAlreadyRequested`, `AlreadyVoided`, `DocumentHasNotes`, `EmitterNotReadyForProduction`, `CertificateExpired` | El comprobante aún no está aceptado, ya tiene baja en curso o confirmada, tiene notas vigentes, o faltan credenciales vigentes en producción. |
| `422` | `InvalidVoidReason`, `VoidWindowExpired`, `ValidationFailed` | Motivo vacío o de más de 100 caracteres, o venció el plazo de 7 días calendario ([Errores de anulación](https://faktura-doc.cgallardo.me/errores/#errores-de-anulación)). |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Consultar un RUC

```http
GET /v1/lookup/ruc/{ruc}
```

Sirve para autocompletar los datos del cliente en tu POS antes de emitir.

Consulta el **padrón reducido de RUC** publicado por SUNAT y actualizado diariamente en Faktura. No depende de los servicios en línea de SUNAT en el momento de la petición, por lo que responde en milisegundos incluso si SUNAT presenta intermitencias. `as_of` indica la fecha de publicación del padrón usado.

### Ejemplo

```bash
curl https://faktura-test.cgallardo.me/v1/lookup/ruc/20131312955 -H "Authorization: Bearer sk_test_..."
```

### Respuesta `200 OK`

```json
{
  "ruc": "20131312955",
  "name": "EMPRESA DE PRUEBA S.A.C.",
  "status": "ACTIVO",
  "address_condition": "HABIDO",
  "is_active_and_found": true,
  "ubigeo": "150122",
  "address": "AV. LARCO NRO. 123 INT. 402 URB. MIRAFLORES",
  "as_of": "2026-11-13"
}
```

| Campo | Descripción |
| --- | --- |
| `status` | Estado del contribuyente (`ACTIVO`, `BAJA DE OFICIO`, `SUSPENSION TEMPORAL`…). |
| `address_condition` | Condición del domicilio (`HABIDO`, `NO HALLADO`, `NO HABIDO`…). |
| `is_active_and_found` | `true` si está `ACTIVO` y `HABIDO`. Es informativo: la API no bloquea facturas a contribuyentes en otro estado. |
| `address`, `ubigeo` | Domicilio fiscal armado como lo muestra SUNAT; `null` si el padrón no lo trae. |
| `as_of` | Fecha (hora de Perú) en que SUNAT publicó el padrón consultado. |

### Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `InvalidRuc` | No tiene 11 dígitos o el dígito verificador es incorrecto (se valida antes de consultar). |
| `404` | `RucNotFound` | No figura en el padrón. |
| `503` | `RucLookupUnavailable` | El servicio de consulta no está disponible temporalmente. Reintenta más tarde. |

Para muchos RUC a la vez, usa [Consultar varios RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc-lote/).

## Consultar varios RUC a la vez

```http
POST /v1/lookup/ruc
```

Hasta **1000** RUC por llamada; los repetidos se consultan una vez. Un RUC inválido no hace fallar la llamada: se informa en `invalid`.

### Ejemplo

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/lookup/ruc \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "rucs": ["20131312955", "10467793549", "20600000005", "123"] }'
```

### Respuesta `200 OK`

```json
{
  "items": [
    { "ruc": "20131312955", "name": "EMPRESA DE PRUEBA S.A.C.", "status": "ACTIVO", "address_condition": "HABIDO", "is_active_and_found": true, "ubigeo": "150122", "address": "AV. LARCO NRO. 123" },
    { "ruc": "10467793549", "name": "PERSONA DE PRUEBA", "status": "ACTIVO", "address_condition": "HABIDO", "is_active_and_found": true, "ubigeo": "150101", "address": null }
  ],
  "not_found": ["20600000005"],
  "invalid": ["123"],
  "as_of": "2026-11-13"
}
```

`items` no sigue el orden de la petición; relaciónalos por `ruc`.

### Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `ValidationFailed` | `rucs` falta, está vacío o tiene más de 1000 elementos. |
| `503` | `RucLookupUnavailable` | El servicio de consulta no está disponible temporalmente. |

Usa el mismo padrón que [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/), con los mismos campos.

## Consultar un DNI

```http
GET /v1/lookup/dni/{dni}
```

Encuentra el nombre de una persona **que tiene RUC 10**, es decir, que se registró en SUNAT como persona natural con negocio. Su RUC es `10` + DNI + un dígito verificador. Faktura lo calcula y lo busca en el mismo padrón de SUNAT de la consulta de RUC. No consulta a RENIEC.

### Ejemplo

```bash
curl https://faktura-test.cgallardo.me/v1/lookup/dni/46779354 -H "Authorization: Bearer sk_test_..."
```

### Respuesta `200 OK`

```json
{ "dni": "46779354", "full_name": "QUISPE MAMANI JUAN CARLOS", "ruc": "10467793549", "as_of": "2026-11-15" }
```

| Campo | Descripción |
| --- | --- |
| `full_name` | Como figura en el padrón de SUNAT: apellidos y nombres. |
| `ruc` | El RUC 10 del que proviene el nombre. |
| `as_of` | Fecha del padrón de SUNAT usado. |

### Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `InvalidDni` | No son 8 dígitos. |
| `404` | `DniNotFound` | La persona **no tiene RUC 10** en el padrón. **No** significa que el DNI no exista: la mayoría de personas no tiene RUC. Pide el nombre al cliente. |
| `503` | `DniLookupUnavailable` | El servicio de consulta no está disponible temporalmente. |

Para una **boleta** no necesitas esta consulta: envía el nombre que te dé el cliente. Úsala para autocompletar cuando se pueda.

## Cómo funcionan los webhooks

En lugar de consultar `GET /v1/documents/{id}` hasta que SUNAT responda, registra una URL y Faktura te avisa con un `POST` firmado cada vez que un comprobante llega a un desenlace.

### Eventos

| Evento | Cuándo |
| --- | --- |
| `document.accepted` | SUNAT aceptó el comprobante. |
| `document.observed` | SUNAT lo aceptó con observaciones. |
| `document.rejected` | SUNAT lo rechazó. |
| `document.failed` | No se pudo procesar (credenciales, perfil SOL…). |
| `document.voided` | SUNAT aceptó la anulación. |
| `document.void_rejected` | SUNAT rechazó la anulación; el comprobante sigue vigente. |

### Cómo empezar

1. [Registra tu endpoint](https://faktura-doc.cgallardo.me/webhooks/registrar/) y guarda el `secret`.
2. Verifica la firma de cada aviso (abajo) y responde `2xx` en menos de 10 segundos.
3. [Lista](https://faktura-doc.cgallardo.me/webhooks/listar/) o [elimina](https://faktura-doc.cgallardo.me/webhooks/eliminar/) endpoints cuando lo necesites (hasta 10 por empresa).

### La petición que recibes

```http
POST /faktura/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Faktura-Webhooks/1
Faktura-Event: document.accepted
Faktura-Event-Id: 01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77
Faktura-Delivery: 01a1d6b3-0c11-72c5-a0f4-6b1e2d3c4f55
Faktura-Signature: t=1794600000,v1=5d41402abc4b2a76b9719d911017c592…

{
  "id": "01a1d6b3-0b7a-7d11-8e40-3a2f1c9d8e77",
  "type": "document.accepted",
  "created_at": "2026-11-13T22:00:01+00:00",
  "data": {
    "document_id": "01a1d5fc-899b-720e-a6ea-03d37a346f81",
    "document_type": "03",
    "full_number": "B001-1",
    "environment": "beta",
    "status": "accepted",
    "sunat_code": "0",
    "sunat_description": "La Boleta numero B001-1, ha sido aceptada",
    "void_status": null
  }
}
```

Responde con cualquier `2xx` en menos de 10 segundos. Haz el trabajo pesado después: guarda el evento y procésalo en segundo plano.

### Verificar la firma

`Faktura-Signature` contiene `t` (marca de tiempo Unix) y `v1` (HMAC-SHA256 en hexadecimal de `"<t>.<cuerpo>"` con tu `secret`). Verifica siempre sobre el **cuerpo crudo**, antes de convertirlo a JSON, y rechaza marcas de tiempo de más de 5 minutos para impedir repeticiones.

PHP:

```php
$body = file_get_contents('php://input');
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $_SERVER['HTTP_FAKTURA_SIGNATURE'] ?? '', $m);
$valid = $m
    && abs(time() - (int) $m[1]) <= 300
    && hash_equals(hash_hmac('sha256', $m[1].'.'.$body, getenv('FAKTURA_WEBHOOK_SECRET')), $m[2]);
if (! $valid) { http_response_code(400); exit; }
```

Node.js (Express):

```js
import crypto from 'node:crypto';

app.post('/faktura/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('Faktura-Signature') ?? '') ?? [];
  const expected = crypto.createHmac('sha256', process.env.FAKTURA_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex');
  const valid = t && Math.abs(Date.now() / 1000 - Number(t)) <= 300
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!valid) return res.sendStatus(400);
  res.sendStatus(204);
  // procesar JSON.parse(req.body) en segundo plano
});
```

### Reintentos y duplicados

- Si tu endpoint no responde `2xx` (error, timeout o redirección, que no se sigue), Faktura reintenta con espera creciente: 5 s, 10 s, 20 s… hasta 15 minutos entre intentos, durante unas 4 horas.
- La entrega es **al menos una vez**: puedes recibir el mismo evento más de una vez. Usa `id` (igual a `Faktura-Event-Id`) para ignorar duplicados.
- El orden de llegada no está garantizado. Si dudas, consulta `GET /v1/documents/{id}`, que siempre tiene el estado vigente.

## Registrar un webhook

```http
POST /v1/webhooks
```

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/webhooks \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://erp.miempresa.pe/faktura/webhook", "events": ["document.accepted", "document.rejected"] }'
```

### Cuerpo

| Campo | Obligatorio | Descripción |
| --- | --- | --- |
| `url` | Sí | HTTPS, accesible desde internet, sin usuario ni contraseña en la URL. |
| `events` | No | Lista de eventos; si se omite, recibe todos. |

### Respuesta `201 Created`

```json
{
  "id": "01a1d6b2-4c1e-7f30-9a2b-5d8e7c6b1a00",
  "url": "https://erp.miempresa.pe/faktura/webhook",
  "events": ["document.accepted", "document.rejected"],
  "is_active": true,
  "created_at": "2026-11-13T22:00:00+00:00",
  "secret": "whsec_3f9c…"
}
```

**Guarda el `secret`: solo se muestra esta vez.** Sirve para [verificar la firma](https://faktura-doc.cgallardo.me/webhooks/#verificar-la-firma) de cada aviso.

### Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `409` | `TooManyWebhooks` | Tu empresa ya tiene 10 endpoints, el máximo. Elimina uno antes de registrar otro. |
| `422` | `InvalidWebhookUrl` | La URL no es HTTPS, lleva usuario o contraseña, o apunta a una red privada. |
| `422` | `ValidationFailed` | Falta `url` o `events` trae un evento desconocido. |

Los eventos y el formato del aviso están en [Cómo funcionan los webhooks](https://faktura-doc.cgallardo.me/webhooks/).

## Listar webhooks

```http
GET /v1/webhooks
```

Devuelve los endpoints activos de tu empresa. El `secret` nunca vuelve a mostrarse: si lo perdiste, elimina el endpoint y regístralo de nuevo.

```bash
curl https://faktura-test.cgallardo.me/v1/webhooks -H "Authorization: Bearer sk_test_..."
```

### Respuesta `200 OK`

```json
{
  "items": [
    {
      "id": "01a1d6b2-4c1e-7f30-9a2b-5d8e7c6b1a00",
      "url": "https://erp.miempresa.pe/faktura/webhook",
      "events": ["document.accepted", "document.rejected"],
      "is_active": true,
      "created_at": "2026-11-13T22:00:00+00:00"
    }
  ]
}
```

| Campo | Descripción |
| --- | --- |
| `id` | Identificador del endpoint, para [eliminarlo](https://faktura-doc.cgallardo.me/webhooks/eliminar/). |
| `url` | URL que recibe los avisos. |
| `events` | Eventos suscritos ([lista de eventos](https://faktura-doc.cgallardo.me/webhooks/#eventos)). |
| `is_active` | `true` mientras recibe avisos. |
| `created_at` | Fecha de registro (UTC, ISO 8601). |

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve la lista de webhooks activos de tu empresa. |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Eliminar un webhook

```http
DELETE /v1/webhooks/{id}
```

Da de baja el endpoint: deja de recibir avisos y sus entregas pendientes se cancelan. Responde `204 No Content` sin cuerpo.

```bash
curl -X DELETE https://faktura-test.cgallardo.me/v1/webhooks/01a1d6b2-4c1e-7f30-9a2b-5d8e7c6b1a00 \
  -H "Authorization: Bearer sk_test_..."
```

### Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `404` | `NotFound` | El endpoint no existe o es de otra empresa. |

## Verificar la API key

```http
GET /v1/me
```

Devuelve la empresa emisora y el entorno de la API key usada. Úsalo para comprobar que tu integración se conecta bien y si tu empresa ya está lista para producción.

```bash
curl https://faktura-test.cgallardo.me/v1/me -H "Authorization: Bearer sk_test_..."
```

### Respuesta `200 OK`

```json
{
  "company": {
    "id": "01a1d52b-90eb-7207-b415-4e3f2ba3f9bd",
    "ruc": "20000000001",
    "legal_name": "FAKTURA BETA S.A.C.",
    "trade_name": null,
    "has_certificate": true,
    "has_sol_credentials": true,
    "certificate_valid_until": "2027-11-13T23:59:59+00:00"
  },
  "api_key": { "prefix": "sk_test_ec829766c02e", "environment": "test", "scope": "full", "expires_at": null },
  "sunat_environment": "beta"
}
```

| Campo | Descripción |
| --- | --- |
| `company.has_certificate` | Tu certificado digital ya está cargado. |
| `company.has_sol_credentials` | Tu usuario SOL secundario ya está configurado. Ambos son necesarios para emitir con una clave `live`. |
| `company.certificate_valid_until` | Vencimiento de tu certificado digital (`null` si no hay). Renuévalo antes: vencido, la firma deja de ser válida y SUNAT rechaza los envíos. |
| `api_key.environment` | `test` o `live`. |
| `api_key.scope` | `full` (emitir y consultar) o `lookup` (solo consultas de RUC y DNI). |
| `api_key.expires_at` | Vencimiento de la clave (`null` si no vence). Los accesos de prueba vencen: desde ese momento toda llamada responde `401` y hay que pedir otra clave. |
| `sunat_environment` | `beta` o `production`: adónde se envían los comprobantes de esta clave. |

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve los datos del emisor y de la API key. |
| `401` | `Unauthenticated` | Falta la API key, es inválida, fue revocada o venció. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Series

```http
GET /v1/series
```

Lista las series activas de tu empresa **en el entorno de tu API key**, con el siguiente correlativo que se asignará. Las series las crea el equipo de Faktura al dar de alta tu empresa; pide una nueva si abres otra caja o establecimiento.

```bash
curl https://faktura-test.cgallardo.me/v1/series -H "Authorization: Bearer sk_test_..."
```

### Respuesta `200 OK`

```json
{
  "items": [
    { "id": "01a1d52b-92d5-701b-9ee2-275218fd6f62", "document_type": "01", "code": "F001", "branch_code": "0000", "next_number": 1 },
    { "id": "01a1d52b-936e-707a-ae38-2a5f8d661979", "document_type": "03", "code": "B001", "branch_code": "0000", "next_number": 2 }
  ]
}
```

| Campo | Descripción |
| --- | --- |
| `document_type` | `01` factura, `03` boleta, `07` nota de crédito, `08` nota de débito. |
| `code` | Serie que envías en `series` al emitir (`F001`, `B001`, `FC01`, `BC01`, `FD01`, `BD01`). |
| `branch_code` | Código del establecimiento anexo ante SUNAT (`0000` es el domicilio fiscal). |
| `next_number` | Correlativo que recibirá la próxima emisión exitosa. Es informativo: con emisiones concurrentes puede avanzar entre la consulta y tu emisión. |

### Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve las series activas del emisor en el entorno de la clave. |
| `401` | `Unauthenticated` | Falta la API key, es inválida o venció. |
| `403` | `ApiKeyScopeInsufficient` | La clave es de alcance `lookup`. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Errores

### Formato

Toda falla controlada responde con un código estable en `reason` y, a veces, una lista de `details`:

```json
{
  "reason": "ValidationFailed",
  "details": ["items.0.quantity:Gt", "items.0.unit_price:Decimal"]
}
```

- `reason` es un **código estable**, en inglés y sin espacios. Tu sistema decide qué mensaje mostrar a su usuario, en su idioma. La API nunca devuelve prosa que tengas que interpretar.
- `details` (opcional) detalla la causa. En validaciones tiene la forma `campo:Regla`, con la ruta del campo en notación de puntos (`items.0.quantity` es la cantidad del primer ítem).

Los errores inesperados (`500`) no exponen detalles internos; solo devuelven el identificador de correlación:

```json
{ "traceId": "01a1d5fc-8a30-7f4b-9c1e-6d2f0b7e5a11" }
```

Ese valor coincide con la cabecera `X-Request-Id`. Repórtalo a soporte para ubicar el error exacto.

### Códigos generales

| Estado | `reason` | Qué hacer |
| --- | --- | --- |
| `400` | `BadRequest` | Revisa que el cuerpo sea JSON válido. |
| `401` | `Unauthenticated` | Revisa tu API key ([Autenticación](https://faktura-doc.cgallardo.me/autenticacion/)). |
| `403` | `Forbidden`, `EmitterInactive` | Tu empresa no puede emitir; contacta a soporte. |
| `404` | `NotFound` | El recurso no existe **o pertenece a otro emisor o entorno**. |
| `405` | `MethodNotAllowed` | Método HTTP incorrecto para esa ruta. |
| `409` | `IdempotencyKeyReused`, `EmitterNotReadyForProduction`, `CertificateExpired` | Ver la tabla de emisión. |
| `413` | `PayloadTooLarge` | El cuerpo excede el tamaño permitido. |
| `422` | `ValidationFailed` y códigos de negocio | Corrige los datos; reintentar igual no cambia el resultado. |
| `429` | `TooManyRequests`, `EmailLimitReached` | Espera `Retry-After` segundos antes de reintentar ([Límite de peticiones](https://faktura-doc.cgallardo.me/limite-de-peticiones/)). |
| `500` | — (solo `traceId`) | Reintenta con la misma `Idempotency-Key`; si persiste, reporta el `traceId`. |
| `503` | `ServiceUnavailable`, `NotReady` | Servicio temporalmente no disponible; reintenta con espera. |

### Errores de emisión (`POST /v1/invoices`, `POST /v1/receipts`)

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `ValidationFailed` | Falta un campo, el tipo no corresponde o un valor no está permitido. Ver `details`. |
| `422` | `InvalidIdempotencyKey` | La cabecera `Idempotency-Key` tiene caracteres no permitidos o más de 100. |
| `422` | `InvalidSeriesCode` | La serie no corresponde al tipo: las facturas usan `F###` y las boletas `B###`. |
| `422` | `SeriesUnavailable` | La serie no existe en el entorno de tu clave, está inactiva o agotó sus 8 dígitos. |
| `422` | `InvoiceRequiresCustomerRuc` | Una factura exige cliente con RUC. |
| `422` | `ReceiptRequiresCustomerDocument` | Boleta de más de S/ 700, o en dólares, sin documento del cliente. |
| `422` | `InvalidCustomerDocument` | DNI que no tiene 8 dígitos, RUC con dígito verificador incorrecto, CE o pasaporte con formato inválido. |
| `422` | `InvalidCustomerName` | Cliente identificado sin nombre, o nombre de más de 200 caracteres. |
| `422` | `NoItems`, `TooManyItems` | Sin ítems o con más de 500. |
| `422` | `InvalidDescription` | Ítem con descripción vacía o de más de 500 caracteres. |
| `422` | `InvalidQuantity`, `InvalidUnitPrice` | Cantidad o precio cero, negativo o con más de 10 decimales. |
| `422` | `ZeroTotal` | El total redondeado es S/ 0.00 y no hay operaciones gratuitas. |
| `422` | `CreditOnlyForInvoices` | Pago al crédito en una boleta. |
| `422` | `InvalidInstallments` | Crédito sin cuotas, más de 60 cuotas, cuota de monto cero o que vence en la fecha de emisión o antes. |
| `422` | `InstallmentsDoNotMatchTotal` | Las cuotas no suman exactamente el neto pendiente de pago (total menos detracción y retención). |
| `422` | `InvalidDiscount` | Descuento en cero, porcentaje de 100 o más, descuento global demasiado pequeño, o descuento en ítems de una nota. |
| `422` | `DiscountExceedsAmount` | El descuento iguala o supera el monto al que se aplica. |
| `422` | `DiscountNotAllowedOnFreeItem` | Descuento en un ítem gratuito. |
| `422` | `GlobalDiscountRequiresTaxedItems` | Descuento global en un comprobante sin ítems gravados. |
| `422` | `DetractionOnlyForInvoices`, `RetentionOnlyForInvoices` | Detracción o retención en una boleta. |
| `422` | `InvalidDetractionCode`, `InvalidDetractionPercent`, `InvalidDetractionAccount`, `InvalidDetractionPaymentMethod` | Código de bien o servicio, porcentaje, cuenta o medio de pago de la detracción con formato inválido. |
| `422` | `DetractionRequiresExchangeRate` | Detracción en dólares sin `exchange_rate`. |
| `422` | `RetentionRequiresPen`, `RetentionBelowThreshold` | Retención en dólares o con total de S/ 700 o menos. |
| `422` | `RetentionNotAllowedWithDetraction` | Retención y detracción a la vez. |
| `422` | `InvalidIssueDate` | `issue_date` futura o anterior al máximo permitido (3 días). |
| `422` | `InvalidServiceCharge` | Recargo al consumo sobre un valor de venta en cero. |
| `422` | `InvalidPurchaseOrder`, `InvalidDespatchReference`, `InvalidObservations`, `InvalidDueDate`, `InvalidSunatProductCode` | Dato comercial con formato inválido o vencimiento anterior a la emisión. |
| `409` | `IdempotencyKeyReused` | Usaste una `Idempotency-Key` ya usada, con otro cuerpo ([Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/)). |
| `409` | `EmitterNotReadyForProduction` | Clave `live` sin certificado digital o usuario SOL configurado. |
| `409` | `CertificateExpired` | Clave `live` y el certificado digital del emisor venció: SUNAT rechazaría el comprobante. No se consume el correlativo; renueva el certificado. |
| `403` | `EmitterInactive` | La empresa emisora está desactivada. |

### Errores de notas

Además de los de emisión:

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `AffectedDocumentNotFound` | `affected_document_id` no existe en tu empresa y entorno. |
| `422` | `InvalidAffectedDocument` | El comprobante afectado es una nota; solo se modifican facturas y boletas. |
| `409` | `AffectedDocumentNotAccepted` | El comprobante afectado aún no fue aceptado por SUNAT. |
| `409` | `AffectedDocumentVoided` | El comprobante afectado está anulado o tiene una anulación en curso. |
| `422` | `InvalidNoteReason` | `reason_code` no existe o no está soportado para ese tipo de nota. |
| `422` | `InvalidNoteDescription` | `reason_description` de más de 250 caracteres. |
| `422` | `NoteSeriesMismatch` | La serie de la nota no empieza con la misma letra que la del comprobante (`F` o `B`). |
| `422` | `NoteIssuedBeforeAffected` | `issue_date` de la nota es anterior a la fecha de emisión del comprobante afectado. |
| `422` | `NoteItemsRequired` | El motivo exige enviar `items`. |
| `422` | `NoteItemsNotAllowed` | El motivo `13` (ajuste de montos y/o fechas de pago) no admite `items`. |
| `422` | `CreditNoteExceedsAffectedTotal` | La nota de crédito supera el total del comprobante. |
| `422` | `CreditNotesExceedAffectedTotal` | Con esta nota, las notas de crédito acumuladas superarían el total del comprobante afectado. |
| `422` | `PaymentAdjustmentRequiresCreditInvoice` | El motivo `13` exige que el comprobante afectado sea una factura al crédito. |
| `422` | `PaymentAdjustmentRequiresInstallments` | El motivo `13` exige enviar el nuevo cronograma en `payment.installments`. |
| `422` | `InstallmentsExceedPendingAmount` | En el motivo `13`, las cuotas suman más que el neto pendiente (`net_payable`) de la factura afectada. |
| `422` | `PaymentOnlyForAdjustmentNotes` | Se envió `payment` en una nota cuyo motivo no es el `13`. |

### Errores de anulación

| Estado | `reason` | Causa |
| --- | --- | --- |
| `404` | `NotFound` | El comprobante no existe en tu empresa y entorno. |
| `409` | `DocumentNotAccepted` | SUNAT aún no aceptó el comprobante. |
| `409` | `VoidAlreadyRequested` | Ya hay una anulación en curso. |
| `409` | `AlreadyVoided` | El comprobante ya fue anulado. |
| `409` | `EmitterNotReadyForProduction` | Clave `live` sin certificado o usuario SOL. |
| `409` | `CertificateExpired` | Clave `live` y el certificado digital del emisor venció. |
| `422` | `InvalidVoidReason` | Motivo vacío o de más de 100 caracteres. |
| `422` | `VoidWindowExpired` | Pasó el plazo de anulación; emite una nota de crédito. |
| `409` | `DocumentHasNotes` | El comprobante tiene notas vigentes: anúlalas primero. |

### Errores de webhooks y consultas

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `InvalidWebhookUrl` | URL que no es HTTPS, con credenciales, que no resuelve o que apunta a una red privada. |
| `422` | `InvalidWebhookEvents` | Evento desconocido. |
| `422` | `InvalidRecipients` | Lista de destinatarios de correo vacía, con más de 5 correos o con formato inválido. |
| `409` | `DocumentNotAccepted` | Envío por correo de un comprobante que SUNAT aún no aceptó. |
| `409` | `DocumentNotRetryable` | Reenvío de un comprobante que no está `failed`. |
| `409` | `DocumentRejected` | PDF de un comprobante rechazado por SUNAT. |
| `403` | `ApiKeyScopeInsufficient` | Clave de alcance `lookup` en una ruta que exige alcance completo. |
| `503` | `EmailNotConfigured` | Envío por correo no habilitado en el servicio. |
| `429` | `EmailLimitReached` | Se alcanzó el tope de correos del comprobante (10) o del emisor por hora (100). |
| `409` | `TooManyWebhooks` | Ya tienes 10 endpoints activos. |
| `422` | `InvalidRuc`, `InvalidDni` | Formato inválido. |
| `404` | `RucNotFound`, `DniNotFound` | No figura en el padrón de SUNAT o en la fuente de DNI. |
| `503` | `RucLookupUnavailable`, `DniLookupUnavailable` | El servicio de consulta de RUC o DNI no está disponible temporalmente. |

### Observaciones, rechazos y fallos de envío ante SUNAT

El resultado de SUNAT **no es un error HTTP** al emitir: la emisión responde `201 Created` con `status: "pending"` y el veredicto de SUNAT se refleja después en el comprobante (por [webhook](https://faktura-doc.cgallardo.me/webhooks/) o en [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/)). Es importante distinguir los tres escenarios:

| `status` | Qué significa | ¿El comprobante es válido? | Qué debe hacer tu sistema |
| --- | --- | --- | --- |
| `observed` | SUNAT aceptó el comprobante (`sunat.code: "0"`), pero incluyó advertencias en `sunat.notes` (códigos `4000` o mayores, p. ej. `4252`). | **Sí, 100 % válido.** | Entrégalo normalmente al cliente y revisa `sunat.notes` para ajustar futuras emisiones. |
| `rejected` | SUNAT rechazó el comprobante por una regla fiscal o de datos (códigos `2000` a `3999` en `sunat.code` y detalle en `sunat.description`). | **No tiene validez tributaria.** | Corrige los datos observados y emite un comprobante nuevo (con el siguiente correlativo). |
| `failed` | No se pudo entregar a SUNAT por credenciales SOL o configuración del emisor. | Pendiente de recepción en SUNAT. | **No emitas otro comprobante.** Una vez corregida la causa, reenvíalo con [`POST /v1/documents/{id}/retry`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/). |

Ver el ciclo completo en [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

### Cómo solicitar soporte técnico

Para que podamos diagnosticar y resolver cualquier consulta con rapidez, incluye estos datos al contactar a soporte:

1. **Entorno:** indica si ocurrió en **Pruebas** (`faktura-test.cgallardo.me`) o en **Producción** (`faktura.cgallardo.me`).
2. **Empresa:** el RUC de la empresa emisora y el prefijo de la API key utilizada (p. ej. `sk_test_ec829766c02e`, nunca el secreto completo).
3. **Identificador:** el `id` del comprobante o el valor de la cabecera `X-Request-Id` (`traceId`) devuelto por la API.
4. **Petición y respuesta:** el método y ruta llamados (p. ej. `POST /v1/invoices`), el cuerpo JSON enviado (`payload`) y el código HTTP + cuerpo JSON recibido.

### Reglas de validación más comunes en `details`

| Regla | Significado |
| --- | --- |
| `Required` | Campo obligatorio ausente. |
| `In` | Valor fuera de la lista permitida (ver [Catálogos](https://faktura-doc.cgallardo.me/catalogos/)). |
| `Decimal` | No es un decimal válido o tiene más decimales de los permitidos. |
| `Gt`, `Lt` | Debe ser mayor que cero (`Gt`) o menor que el tope permitido (`Lt`, p. ej. porcentajes menores a 100). |
| `Max`, `Min`, `Size` | Excede la longitud o cantidad máxima (`Max`), no alcanza la mínima (`Min`) o no tiene la longitud exacta exigida (`Size`, p. ej. `reason_code` de 2 caracteres o `detraction.code` de 3). |
| `Regex` | No cumple el patrón del campo (p. ej. `unit_code` de 1 a 3 caracteres `A-Z0-9` o `sunat_product_code` de 8 dígitos). |
| `Boolean` | Debe ser `true` o `false`. |
| `DateFormat`, `AfterOrEqual` | Fecha que no está en formato `YYYY-MM-DD`, o fecha `to` anterior a `from`. |
| `Email` | Dirección de correo electrónico con formato inválido (en `to.*`). |
| `RequiredIf`, `RequiredWith` | Obligatorio por el valor de otro campo (por ejemplo, `installments` con `payment.type = credito`). |
| `AmountOrPercent` | Un descuento o recargo debe llevar `amount` o `percent`, uno solo. |

## Catálogos

La API usa nombres legibles y los traduce a los catálogos oficiales de SUNAT (Anexo N.° 8 de la RS N.° 097-2012/SUNAT y modificatorias).

### Tipo de documento del cliente (`customer.doc_type`)

| Valor | Catálogo 06 | Formato de `doc_number` | Permitido en |
| --- | --- | --- | --- |
| `RUC` | `6` | 11 dígitos con dígito verificador válido | Facturas y boletas |
| `DNI` | `1` | 8 dígitos | Boletas |
| `CE` | `4` | 4 a 12 letras o números (carné de extranjería) | Boletas |
| `PASAPORTE` | `7` | 4 a 12 letras o números | Boletas |
| `NONE` | `-` | Se omite; el cliente figura como «CLIENTES VARIOS» | Boletas en soles de hasta S/ 700 |

### Tipo de comprobante (`document_type` en las respuestas)

| Valor | Comprobante | Serie | Endpoint |
| --- | --- | --- | --- |
| `01` | Factura electrónica | `F` + 3 letras o números (`F001`) | [`POST /v1/invoices`](https://faktura-doc.cgallardo.me/endpoints/facturas/) |
| `03` | Boleta de venta electrónica | `B` + 3 letras o números (`B001`) | [`POST /v1/receipts`](https://faktura-doc.cgallardo.me/endpoints/boletas/) |
| `07` | Nota de crédito electrónica | Misma letra que el comprobante afectado (`FC01`, `BC01`) | [`POST /v1/credit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/) |
| `08` | Nota de débito electrónica | Misma letra que el comprobante afectado (`FD01`, `BD01`) | [`POST /v1/debit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/) |

### Afectación del IGV (`items[].igv_type`)

| Valor en la API | Catálogo 07 | Tributos en UBL 2.1 | Cuándo usarlo |
| --- | --- | --- | --- |
| `gravado` (por defecto) | `10` | `1000` (IGV 18 %) | Operación onerosa gravada con el IGV. |
| `exonerado` | `20` | `9997` (EXO 0 %) | Operación exonerada del IGV por ley (p. ej. libros o productos agrarios del Apéndice I). |
| `inafecto` | `30` | `9998` (INA 0 %) | Operación fuera del ámbito de aplicación del IGV. |
| `gratuito` | `15` | `9996` (GRA, IGV referencial 18 %) | Bonificación, muestra comercial o retiro de bienes gravados. |
| `gratuito_exonerado` | `21` | `9996` (GRA 0 %) | Entrega gratuita de un bien exonerado. |
| `gratuito_inafecto` | `31` | `9996` (GRA 0 %) | Entrega gratuita de un bien o servicio inafecto. |

Detalle de fórmulas y redondeo en [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#tipos-de-afectación-igv_type).

### Unidad de medida (`items[].unit_code`)

Código del catálogo 03 de SUNAT (UN/ECE Rec. 20). Por defecto `NIU`. Los más usados:

| Código | Unidad |
| --- | --- |
| `NIU` | Unidad (bienes) |
| `ZZ` | Unidad (servicios) |
| `KGM` | Kilogramo |
| `GRM` | Gramo |
| `LTR` | Litro |
| `MTR` | Metro |
| `MTK` | Metro cuadrado |
| `MTQ` | Metro cúbico |
| `BX` | Caja |
| `PK` | Paquete |
| `BG` | Bolsa |
| `BO` | Botella |
| `DZN` | Docena |
| `HUR` | Hora |
| `DAY` | Día |
| `MON` | Mes |

La API acepta de 1 a 3 letras mayúsculas o números; SUNAT rechaza un código que no exista en su catálogo.

### Moneda (`currency`)

| Valor | Moneda (ISO 4217) | Leyenda en letras |
| --- | --- | --- |
| `PEN` (por defecto) | Sol | `… SOLES` |
| `USD` | Dólar estadounidense | `… DÓLARES AMERICANOS` |

### Forma de pago (`payment.type`)

| Valor | Significado |
| --- | --- |
| `contado` (por defecto) | Pago al contado. |
| `credito` | Pago al crédito con cronograma de cuotas (`installments`). Solo facturas. |

### Motivos de nota de crédito (`reason_code` — Catálogo 09)

| Código | Motivo | `items` |
| --- | --- | --- |
| `01` | Anulación de la operación | Opcional (copia el comprobante) |
| `02` | Anulación por error en el RUC | Opcional (copia el comprobante) |
| `03` | Corrección por error en la descripción | Opcional (copia el comprobante) |
| `04` | Descuento global | Obligatorio |
| `05` | Descuento por ítem | Obligatorio |
| `06` | Devolución total | Opcional (copia el comprobante) |
| `07` | Devolución por ítem | Obligatorio |
| `08` | Bonificación | Obligatorio |
| `09` | Disminución en el valor | Obligatorio |
| `10` | Otros conceptos | Obligatorio |
| `13` | Ajustes — montos y/o fechas de pago | No admite `items`; usa `payment` |

Detalle y reglas en [Emitir una nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/#motivos-admitidos-catálogo-09).

### Motivos de nota de débito (`reason_code` — Catálogo 10)

| Código | Motivo | `items` |
| --- | --- | --- |
| `01` | Intereses por mora | Obligatorio |
| `02` | Aumento en el valor | Obligatorio |
| `03` | Penalidades / otros conceptos | Obligatorio |

Detalle en [Emitir una nota de débito](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/#motivos-admitidos-catálogo-10).

### Bienes y servicios sujetos a detracción (Catálogo 54)

En `detraction.code` se envía el código de 3 dígitos del catálogo 54 de SUNAT y en `detraction.percent` la tasa vigente que corresponde a la operación. Códigos frecuentes en servicios y comercio:

| Código | Bien o servicio | Tasa habitual |
| --- | --- | --- |
| `012` | Intermediación laboral y tercerización | `12` |
| `019` | Arrendamiento de bienes muebles o inmuebles | `10` |
| `020` | Mantenimiento y reparación de bienes muebles | `12` |
| `021` | Movimiento de carga | `10` |
| `022` | Otros servicios empresariales (consultoría, sistemas, contabilidad, legal, publicidad) | `12` |
| `024` | Comisión mercantil | `10` |
| `025` | Fabricación de bienes por encargo | `10` |
| `026` | Servicio de transporte de personas | `10` |
| `027` | Servicio de transporte de carga | `4` |
| `030` | Contratos de construcción | `4` |
| `037` | Demás servicios gravados con el IGV | `12` |

Ejemplo completo en la [guía de descuentos, detracción y retención](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/#detracción-spot).

### Medio de pago de la detracción (Catálogo 59)

En `detraction.payment_method` se envía un código de 3 dígitos del catálogo 59 de SUNAT (`001` por defecto):

| Código | Medio de pago |
| --- | --- |
| `001` (por defecto) | Depósito en cuenta |
| `002` | Giro |
| `003` | Transferencia de fondos |
| `004` | Orden de pago |
| `005` | Tarjeta de débito |
| `006` | Tarjeta de crédito emitida en el país por una empresa del sistema financiero |
| `999` | Otros medios de pago |

### Guías de remisión relacionadas (`despatch_references`)

Cada elemento de `despatch_references` indica el tipo de guía (Catálogo 01) y su número en formato `SERIE-NÚMERO` (4 caracteres alfanuméricos de serie, guion y de 1 a 8 dígitos):

| `type` | Tipo de guía | Ejemplo de `number` |
| --- | --- | --- |
| `09` | Guía de remisión remitente | `T001-123` o `EG07-45` |
| `31` | Guía de remisión transportista | `V001-88` |

## Cálculo de impuestos

Tú envías cantidades y precios; la API calcula IGV, ICBPER y totales como los valida SUNAT. No necesitas calcular impuestos en tu sistema.

### Precio con IGV o sin IGV

`price_includes_tax` (a nivel de comprobante, por defecto `true`) indica cómo interpretar `unit_price`.

#### Con IGV (`true`, lo habitual en un POS)

Se respeta lo que paga el cliente:

1. Total de la línea = `cantidad × precio`, redondeado a 2 decimales.
2. Valor de venta (base) = total ÷ 1.18, redondeado a 2 decimales.
3. IGV = total − base.

Ejemplo: 2 cafés a S/ 8.00 → total 16.00 → base 13.56 → IGV 2.44. La suma de las líneas coincide siempre con tu ticket.

#### Sin IGV (`false`, habitual en facturación a empresas)

1. Valor de venta (base) = `cantidad × valor unitario`, redondeado a 2 decimales.
2. IGV = base × tasa del emisor (18 %, o la reducida de la sección siguiente), redondeado a 2 decimales.
3. Total de la línea = base + IGV.

Ejemplo: 3 × 10.555 → base 31.67 → IGV 5.70 → total 37.37.

Los redondeos son *half-up* (0.005 sube a 0.01). Los valores unitarios se guardan con hasta 10 decimales.

### Tipos de afectación (`igv_type`)

| `igv_type` | Código SUNAT | IGV | Uso típico |
| --- | --- | --- | --- |
| `gravado` (por defecto) | 10 | 18 % (o la tasa reducida del emisor) | La mayoría de bienes y servicios. |
| `exonerado` | 20 | 0 % | Bienes exonerados (por ejemplo, libros, algunos alimentos primarios). |
| `inafecto` | 30 | 0 % | Operaciones fuera del ámbito del IGV. |
| `gratuito` | 15 | Informativo | Bonificaciones gravadas: no se cobran, pero se declaran con su valor referencial y el IGV que habrían tenido. |
| `gratuito_exonerado` | 21 | 0 % | Entrega gratuita de un bien exonerado (por ejemplo, un libro de regalo). |
| `gratuito_inafecto` | 31 | 0 % | Bonificación o muestra inafecta. |

Para un ítem gratuito, `unit_price` es el **valor referencial** (en `gratuito`, con o sin IGV según `price_includes_tax`; en los otros dos, sin IGV). El ítem no suma al total a pagar; aparece en `totals.free`, y el comprobante lleva la leyenda «TRANSFERENCIA GRATUITA…».

### Tasa reducida para restaurantes y hoteles MYPE

Las micro y pequeñas empresas de restaurantes, hoteles y alojamientos turísticos tienen una tasa temporal reducida (Ley 32219): en 2026, **10.5 %** (8 % de IGV más 2.5 % de IPM). La tasa se configura en la ficha de tu empresa al darte de alta o solicitándolo a soporte; no se envía en cada comprobante. La respuesta la informa en `igv_percent` y las notas usan la tasa del comprobante que modifican.

### Recargo al consumo

`service_charge` (`{"percent": 10}` o `{"amount": 5}`) agrega el recargo al consumo de restaurantes (catálogo 53, código 46): se calcula sobre el valor de venta (sin IGV), **no** forma parte de la base del IGV y se suma al total. Aparece en `totals.charges` y en `service_charge`.

### Impuesto a las bolsas plásticas (ICBPER)

Marca el ítem con `"icbper": true`. Se agrega S/ 0.50 por unidad, aparte del IGV:

```json
{ "description": "Bolsa plástica", "quantity": 2, "unit_price": 0.10, "icbper": true }
```

Resultado: base 0.17, IGV 0.03, ICBPER 1.00 → la línea suma S/ 1.20 al total.

### Totales del comprobante

| 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/).

## Estados y envío a SUNAT

La emisión responde de inmediato con el número asignado y `status: "pending"`. El envío a SUNAT ocurre en segundo plano, con reintentos automáticos, así que tu caja no se detiene si SUNAT está lenta o caída.

### Estados

| `status` | Significado | ¿Final? |
| --- | --- | --- |
| `pending` | Numerado, **ya firmado** (la respuesta de la emisión trae `sunat.hash` y `links.xml`, para imprimir el ticket de inmediato) y en cola para enviar. También vuelve aquí si SUNAT no estaba disponible y se reintentará. | No |
| `sending` | Se está enviando en este momento. | No |
| `uncertain` | Se perdió la comunicación durante el envío y no se sabe si SUNAT lo recibió. El próximo intento verifica en SUNAT antes de reenviar. | No |
| `accepted` | SUNAT lo aceptó (CDR código `0`). | Sí |
| `observed` | SUNAT lo aceptó con observaciones (CDR código 4000 o mayor). Es válido; revisa `sunat.notes` para corregir en próximas emisiones. | Sí |
| `rejected` | SUNAT lo rechazó (código 2000–3999). **No es válido**: corrige los datos y emite un comprobante nuevo con otro número. | Sí |
| `failed` | No se pudo procesar por una causa que no se resuelve reintentando, como credenciales SOL inválidas o falta de perfil. Contacta a soporte con el `sunat.code`. | Sí |

```text
pending ──► sending ──► accepted | observed | rejected | failed
   ▲           │
   └───────────┤  SUNAT no disponible (reintento con espera creciente)
               ▼
           uncertain ──► (verifica en SUNAT) ──► sending …
```

### Reintentos automáticos

- Ante caídas de SUNAT, la API reintenta con espera creciente: 5 s, 10 s, 20 s… hasta 15 minutos entre intentos, durante varias horas.
- `sunat.send_attempts` cuenta los intentos realizados.
- Un comprobante `uncertain` nunca se reenvía a ciegas: en producción primero se consulta su CDR en SUNAT, para no duplicar ni perder la constancia original.

### Cómo saber cuándo terminó

Registra un [webhook](https://faktura-doc.cgallardo.me/webhooks/) para recibir `document.accepted`, `document.rejected` y los demás desenlaces apenas ocurran, o consulta [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) con espera progresiva:

1. Primera consulta 1 segundo después de emitir. Lo normal es que ya esté en `accepted`.
2. Si sigue en `pending`, `sending` o `uncertain`, espera 2 s, 5 s, 10 s, 30 s y luego cada minuto.
3. No consultes en un bucle sin espera: cuenta para tu [límite de peticiones](https://faktura-doc.cgallardo.me/autenticacion/#límite-de-peticiones).

### ¿Puedo entregar el comprobante antes de que SUNAT lo acepte?

Sí. La normativa permite entregar la representación impresa al cliente en el momento de la venta, y enviar el comprobante a SUNAT dentro del plazo legal. La API se encarga del envío. Lo que sí debes vigilar son los comprobantes que terminen en `rejected` o `failed`.

## Idempotencia

Una red inestable puede cortar la respuesta de una emisión que **sí se registró**. Si tu POS reintenta sin protección, emite el mismo ticket dos veces y consume dos correlativos. La cabecera `Idempotency-Key` lo evita.

```http
POST /v1/receipts HTTP/1.1
Authorization: Bearer sk_live_...
Idempotency-Key: pos-0042-20261113-000187
Content-Type: application/json
```

### Comportamiento

| Situación | Respuesta |
| --- | --- |
| Primera vez que usas la clave | `201 Created`: el comprobante nuevo. |
| Misma clave y **mismo cuerpo** | `200 OK` con cabecera `Idempotent-Replayed: true`: el **mismo** comprobante, sin emitir otro ni consumir otro número. |
| Misma clave y **otro cuerpo** | `409 Conflict` con `{"reason":"IdempotencyKeyReused"}`. |
| Dos peticiones simultáneas con la misma clave | Solo una emite; la otra recibe el mismo comprobante. |

### Reglas

- De 1 a 100 caracteres: letras, números, `_`, `-`, `.` y `:`. Otro formato responde `422 InvalidIdempotencyKey`.
- La clave es única por emisor y por entorno; no caduca.
- «Mismo cuerpo» significa el mismo JSON, sin importar el orden de las claves de los objetos.
- La cabecera es opcional, pero **muy recomendada** en todo sistema que reintente.

### Cómo construir la clave

Usa algo que identifique la venta en tu sistema y que no cambie entre reintentos:

```text
<caja>-<fecha>-<número de venta interno>   →   pos-0042-20261113-000187
<id de pedido>                              →   order_8f3a2c
```

No uses un valor aleatorio nuevo en cada reintento: eso anula la protección.

## Preguntas frecuentes

### ¿Qué necesita mi empresa para emitir comprobantes reales?

Tres cosas, que se configuran una sola vez al darte de alta: el **certificado digital** de tu empresa, un **usuario SOL secundario** (nunca la clave SOL principal) y las **series** que vas a usar (`F001`, `B001`…). Con eso recibes tu clave `sk_live_`. Ver [Autenticación](https://faktura-doc.cgallardo.me/autenticacion/).

### ¿A nombre de quién salen las facturas y boletas?

Siempre a nombre de **tu empresa**: llevan tu RUC, tu razón social, tu nombre comercial, tu dirección, tu logo y la firma digital de tu propio certificado. Nunca salen a nombre de Faktura.

### ¿Desde qué lenguaje o sistema puedo conectarme?

Desde cualquier sistema capaz de hacer peticiones HTTPS con JSON: PHP (Laravel, Symfony…), Node.js, Python, C# (.NET), Java, Go, Ruby, sistemas POS de escritorio o web, ERPs y tiendas en línea. En cada endpoint del portal tienes ejemplos listos en `cURL`, `PHP (Laravel)` y `Node.js`, además de las [colecciones para Postman y Bruno](https://faktura-doc.cgallardo.me/colecciones/).

### ¿Puedo probar sin emitir comprobantes reales?

Sí. Con una clave `sk_test_` todo va a **SUNAT beta**: los comprobantes se firman y se envían igual, pero no tienen valor tributario y sus números no se cruzan con los de producción. Además, el entorno de pruebas es **privado por empresa**: ningún otro integrador puede ver los comprobantes que emitas con tu clave `sk_test_`. Ver [Introducción](https://faktura-doc.cgallardo.me/introduccion/#entornos-prueba-y-producción).

### ¿Qué cambia en mi código para pasar de pruebas a producción?

Solo dos valores de configuración (variables de entorno): la URL base (`https://faktura.cgallardo.me` en lugar de `https://faktura-test.cgallardo.me`) y la API key (`sk_live_…` en lugar de `sk_test_…`). Los endpoints, los campos del JSON y las respuestas son idénticos.

### ¿Cuánto tarda SUNAT en aceptar un comprobante?

La API responde al instante con `201` y `status: "pending"`, y el número ya es tuyo. El envío a SUNAT ocurre en segundo plano y suele resolverse en unos segundos. Ver [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

### ¿Cómo sé que SUNAT lo aceptó?

Registra un [webhook](https://faktura-doc.cgallardo.me/webhooks/) y Faktura te avisa (`document.accepted`, `document.rejected`…), o consulta [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) hasta ver un estado final.

### ¿Qué pasa si SUNAT está caído?

Faktura reintenta sola, con espera creciente, hasta obtener respuesta. Tu sistema no tiene que reenviar nada: el comprobante sigue `pending` con su número ya asignado.

### Un comprobante quedó en `failed`, ¿qué hago?

`failed` significa que no llegó a SUNAT por una causa ajena a su contenido, como un usuario SOL incorrecto. Corrige la causa y [reenvíalo](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/). Uno `rejected` no se reenvía: su contenido es inválido y corresponde emitir otro.

### ¿Puedo emitir una boleta sin pedir el DNI?

Sí, con `customer.doc_type: "NONE"`, si la boleta es en soles y no supera S/ 700.00. Por encima de ese monto, o en dólares, el cliente debe identificarse. Ver [Emitir una boleta](https://faktura-doc.cgallardo.me/endpoints/boletas/).

### ¿Puedo emitir con una fecha anterior?

Sí, con `issue_date`, hasta **3 días atrás** y nunca una fecha futura: sirve para ventas registradas sin conexión. Ver el [ejemplo de contingencia](https://faktura-doc.cgallardo.me/ejemplos/facturas/#con-fecha-de-emisión-anterior-contingencia).

### ¿Cómo anulo un comprobante?

Con [`POST /v1/documents/{id}/void`](https://faktura-doc.cgallardo.me/endpoints/anulacion/) si está dentro del plazo de anulación, o con una [nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/) si ya pasó o si el cliente devuelve solo una parte. Ver [cuál usar](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#nota-de-crédito-o-anulación).

### ¿Cómo evito emitir dos veces la misma venta si se corta la conexión?

Envía siempre la cabecera `Idempotency-Key` con un valor único por venta. Si repites la petición con la misma clave y el mismo cuerpo, la API devuelve el mismo comprobante en lugar de crear otro. Ver [Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/).

### ¿Los enlaces del PDF vencen?

Los enlaces públicos (`links.public_pdf` y `links.public_ticket`) se pueden compartir sin API key y vencen a los 7 días. El PDF con tu API key ([`GET /v1/documents/{id}/pdf`](https://faktura-doc.cgallardo.me/endpoints/pdf/)) no vence.

### ¿La consulta de RUC consulta a SUNAT en línea?

No. Consulta el padrón reducido de SUNAT actualizado diariamente en Faktura, por lo que responde en milisegundos incluso si SUNAT presenta intermitencias. `as_of` indica la fecha del padrón. Ver [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/).

## Glosario

Términos fiscales de la facturación electrónica en el Perú (SUNAT) y conceptos técnicos de la API de Faktura, ordenados alfabéticamente.

### A

#### Ambiente de pruebas (`test` / SUNAT beta)
Entorno en el que toda petición autenticada con una clave `sk_test_` firma el XML y lo envía a los servidores de homologación y pruebas de SUNAT (**SUNAT beta**). No tiene validez tributaria y su numeración es independiente de la de producción. Ver [Introducción](https://faktura-doc.cgallardo.me/introduccion/#entornos-prueba-y-producción).

#### API key
Credencial secreta que identifica a tu empresa emisora y define el ambiente al que van las llamadas: `sk_test_…` apunta a SUNAT beta y `sk_live_…` a SUNAT producción. Se envía en la cabecera `Authorization: Bearer <api key>`. Puede tener alcance `full` (emitir y consultar) o `lookup` (solo consultas de RUC y DNI). Ver [Autenticación](https://faktura-doc.cgallardo.me/autenticacion/).

### B

#### Boleta de venta electrónica (`03`)
Comprobante de pago emitido a consumidores finales ([`POST /v1/receipts`](https://faktura-doc.cgallardo.me/endpoints/boletas/)). Usa series que empiezan con `B` (`B001`). En soles y hasta S/ 700.00 admite cliente sin documento (`customer.doc_type: "NONE"`).

### C

#### CDR (Constancia de Recepción)
Archivo ZIP firmado digitalmente por SUNAT (p. ej. `R-20000000001-01-F001-1.zip`) que contiene el XML `ApplicationResponse` con el veredicto oficial sobre un comprobante (`0` aceptado, con o sin observaciones, o código de rechazo). Es el sustento legal de aceptación y se descarga en [`GET /v1/documents/{id}/cdr`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/cdr/).

#### Certificado digital
Certificado X.509 (archivo `.pfx` o `.p12`) emitido por una entidad de certificación acreditada ante INDECOPI a nombre del RUC del emisor. Faktura lo usa para firmar digitalmente (XMLDSig) cada comprobante antes de enviarlo a SUNAT.

#### Comunicación de baja (`RA`)
Resumen firmado (`RA-YYYYMMDD-#####`) mediante el cual se comunica a SUNAT la anulación de facturas y notas electrónicas con serie `F` dentro de los 7 días calendario desde su emisión. Faktura lo genera y consulta su ticket automáticamente cuando llamas a [`POST /v1/documents/{id}/void`](https://faktura-doc.cgallardo.me/endpoints/anulacion/).

#### Correlativo (`number`)
Número entero secuencial asignado por Faktura dentro de una serie (`1`, `2`, `3`…) en la misma transacción en que se registra el comprobante. Junto con la serie forma `full_number` (`F001-1`).

### D

#### Detracción (SPOT)
Sistema de Pago de Obligaciones Tributarias (leyenda `2006`, tipo de operación `1001`). En facturas de bienes o servicios afectos ([Catálogo 54](https://faktura-doc.cgallardo.me/catalogos/#bienes-y-servicios-sujetos-a-detracción-catálogo-54)), el comprador deposita un porcentaje del total en la cuenta del Banco de la Nación del emisor y paga el resto (`net_payable`). Ver la [guía de detracción](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/#detracción-spot).

### E

#### Estados del comprobante (`status`)
Ciclo de vida del envío a SUNAT:
- `pending`: creado, numerado y firmado; en cola para enviarse a SUNAT.
- `sending`: envío en curso.
- `uncertain`: la conexión se cortó sin saber si SUNAT recibió el envío; Faktura consulta el estado antes de reenviar.
- `accepted`: aceptado por SUNAT (`sunat.code: "0"`).
- `observed`: aceptado por SUNAT con advertencias en `sunat.notes`.
- `rejected`: rechazado por SUNAT (código `2000`–`3999`); no tiene validez tributaria.
- `failed`: no pudo enviarse por una causa de configuración del emisor (credenciales SOL o certificado); se reenvía con [`POST /v1/documents/{id}/retry`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/).

Detalle completo en [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

### F

#### Factura electrónica (`01`)
Comprobante de pago emitido a clientes con RUC ([`POST /v1/invoices`](https://faktura-doc.cgallardo.me/endpoints/facturas/)) que sustenta costo, gasto y crédito fiscal del IGV. Usa series que empiezan con `F` (`F001`) y admite pago al contado o al crédito con cuotas.

### G

#### Guía de remisión relacionada (`despatch_references`)
Referencia a una guía de remisión remitente (`09`) o transportista (`31`) vinculada con el traslado de los bienes facturados ([Catálogos](https://faktura-doc.cgallardo.me/catalogos/#guías-de-remisión-relacionadas-despatch_references)).

### I

#### ICBPER (Impuesto al Consumo de las Bolsas de Plástico)
Tributo de monto fijo por unidad (S/ 0.50 por bolsa) que se activa enviando `"icbper": true` en el ítem. Ver [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#impuesto-a-las-bolsas-plásticas-icbper).

#### Idempotencia (`Idempotency-Key`)
Mecanismo por el cual repetir una petición de emisión con la misma cabecera `Idempotency-Key` y el mismo cuerpo dentro de las 24 horas devuelve exactamente el mismo comprobante (`200 OK`, `Idempotent-Replayed: true`) sin crear un duplicado ni consumir otro correlativo. Ver [Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/).

#### IGV (Impuesto General a las Ventas)
Impuesto al valor agregado en el Perú (18 % general: 16 % de IGV + 2 % de IPM). Cada ítem indica su afectación en `igv_type`: `gravado`, `exonerado`, `inafecto`, `gratuito`, `gratuito_exonerado` o `gratuito_inafecto`. Ver [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/).

### N

#### Neto pendiente de pago (`net_payable`)
Monto efectivo que el cliente debe abonar al emisor tras descontar del `totals.total` la detracción o la retención del IGV. En una factura al crédito, la suma de las cuotas (`payment.installments`) debe coincidir exactamente con `net_payable`.

#### Nota de crédito electrónica (`07`)
Comprobante que disminuye o anula el valor de una factura o boleta aceptada por SUNAT, o reprograma sus cuotas con el motivo `13` ([`POST /v1/credit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/)).

#### Nota de débito electrónica (`08`)
Comprobante que incrementa el valor de una factura o boleta aceptada por SUNAT por intereses moratorios, aumento de valor o penalidades ([`POST /v1/debit-notes`](https://faktura-doc.cgallardo.me/endpoints/nota-de-debito/)).

### P

#### Padrón reducido de RUC
Archivo oficial publicado diariamente por SUNAT con el estado, condición de domicilio, ubigeo y dirección de millones de contribuyentes. Faktura lo actualiza diariamente para responder en milisegundos en [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/), [Consultar varios RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc-lote/) y [Consultar un DNI](https://faktura-doc.cgallardo.me/endpoints/consultas/dni/).

### R

#### Recargo al consumo (`service_charge`)
Cargo adicional (en porcentaje o monto fijo) que aplican establecimientos de hospedaje o restaurantes sobre el valor de venta. No forma parte de la base imponible del IGV. Ver [Cálculo de impuestos](https://faktura-doc.cgallardo.me/calculo-de-impuestos/#recargo-al-consumo).

#### Representación impresa (PDF)
Versión legible del comprobante electrónico en formato A4 o ticket térmico (80 mm y 58 mm) con código QR, valor resumen (`hash`), importe en letras y leyendas de SUNAT ([`GET /v1/documents/{id}/pdf`](https://faktura-doc.cgallardo.me/endpoints/pdf/)).

#### Resumen diario de boletas (`RC`)
Resumen firmado (`RC-YYYYMMDD-#####`) que SUNAT exige para comunicar la anulación (estado `3`) de boletas y notas con serie `B`. Faktura lo envía y consulta su ticket automáticamente al llamar a [`POST /v1/documents/{id}/void`](https://faktura-doc.cgallardo.me/endpoints/anulacion/).

#### Retención del IGV (`retention`)
Régimen aplicable cuando el comprador ha sido designado por SUNAT como Agente de Retención: retiene el 3 % del importe total de la operación (en soles y cuando supera S/ 700.00). Ver la [guía de retención](https://faktura-doc.cgallardo.me/guias/descuentos-detraccion-retencion/#retención-del-igv).

#### RUC y RUC 10
El Registro Único de Contribuyentes (11 dígitos) identifica a empresas (`20…`) y personas naturales con negocio (`10` + 8 dígitos del DNI + 1 dígito verificador).

### S

#### SEE del contribuyente
Sistema de Emisión Electrónica desde los sistemas del contribuyente: modalidad de SUNAT en la que los comprobantes se firman con el certificado digital de la empresa emisora y se transmiten con su usuario SOL secundario.

#### Serie (`series`)
Código de 4 caracteres alfanuméricos que identifica el punto de emisión y el tipo de documento: `F###` para facturas (`F001`), `B###` para boletas (`B001`), `FC##`/`BC##` para notas de crédito y `FD##`/`BD##` para notas de débito. Se consultan en [`GET /v1/series`](https://faktura-doc.cgallardo.me/endpoints/series/).

### U

#### UBL 2.1 (Universal Business Language)
Estándar XML internacional exigido por SUNAT para todos los comprobantes electrónicos. Faktura lo genera y firma automáticamente a partir del JSON que envías.

#### Usuario SOL secundario
Credencial creada dentro de SUNAT Operaciones en Línea con permisos acotados exclusivamente al envío de comprobantes electrónicos, sin acceso a declaraciones ni clave SOL principal.

### V

#### Valor resumen (`sunat.hash` / `DigestValue`)
Resumen criptográfico SHA-256 en Base64 generado al firmar el XML del comprobante. Aparece impreso en el PDF y forma parte del código QR oficial de SUNAT.

### W

#### Webhook
Notificación HTTP `POST` firmada con HMAC-SHA256 (`Faktura-Signature`) que Faktura envía a tu servidor apenas SUNAT acepta, observa, rechaza o anula un comprobante. Ver [Cómo funcionan los webhooks](https://faktura-doc.cgallardo.me/webhooks/).

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