---
name: faktura-emitir-una-factura
description: "Emitir una factura con la API de Faktura (facturación electrónica SUNAT, Perú). 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. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Emitir una factura — Faktura API

## Propósito

Le da a tu asistente el contexto para **emitir una factura** con la API de Faktura: 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.

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

## Modelo mental: de dónde sale cada bloque del JSON

Antes de armar el cuerpo de la petición, resuelve cada bloque desde su fuente en tu sistema o en la API de Faktura:

| Bloque / cabecera | De dónde sale |
| --- | --- |
| `Idempotency-Key` (cabecera) | Del identificador único de la venta o pedido en tu ERP/POS (p. ej. `erp-pedido-8841`). Evita duplicar la factura si se corta la conexión y reintentas. |
| `series` | Del endpoint `GET /v1/series` de Faktura (`F###`, p. ej. `F001`). |
| `customer` | De tu módulo de clientes (RUC de 11 dígitos, razón social y dirección). Si solo tienes el RUC, autocompleta razón social y domicilio fiscal con `GET /v1/lookup/ruc/{ruc}`. |
| `items` | De tu catálogo de productos o servicios. Tú envías `quantity` y `unit_price`; **Faktura calcula el IGV, el ICBPER y los totales** (no envíes impuestos calculados). Los códigos de `unit_code` (`NIU`, `ZZ`…) e `igv_type` (`gravado`, `exonerado`, `inafecto`, `gratuito`…) salen de los anexos de esta skill. |
| `payment`, `detraction`, `retention` | De las condiciones comerciales de la operación. Si es al crédito (`payment.type: "credito"`), las cuotas (`payment.installments`) deben sumar exactamente el `net_payable` (total menos detracción o retención). |

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `POST https://faktura-test.cgallardo.me/v1/invoices` |
| Producción | `POST https://faktura.cgallardo.me/v1/invoices` |

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

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

## Anexo: Moneda (currency) (de «Catálogos»)

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

## Anexo: Afectación del IGV (items[].igv_type) (de «Catálogos»)

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

## Anexo: Unidad de medida (items[].unit_code) (de «Catálogos»)

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.

## Anexo: Bienes y servicios sujetos a detracción (Catálogo 54) (de «Catálogos»)

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

## Anexo: Medio de pago de la detracción (Catálogo 59) (de «Catálogos»)

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 |

## Anexo: Recargo al consumo (de «Cálculo de impuestos»)

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

## Anexo: Guías de remisión relacionadas (despatch_references) (de «Catálogos»)

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

## Anexo: El objeto comprobante (de «Ver un 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)). |

## Anexo: Errores de emisión (POST /v1/invoices, POST /v1/receipts) (de «Errores»)

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

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