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

# Skill: Emitir una boleta — Faktura API

## Propósito

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

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

## 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 del ticket o venta en tu POS/tienda (p. ej. `pos-0042-000187`). Evita duplicar la boleta si reintentas. |
| `series` | Del endpoint `GET /v1/series` de Faktura (`B###`, p. ej. `B001`). |
| `customer` | De los datos del comprador en caja (`DNI`, `CE`, `PASAPORTE`, `RUC`, o `NONE` si la boleta es en soles y no supera S/ 700.00). Si el cliente da su DNI y tiene RUC 10, puedes autocompletar su nombre con `GET /v1/lookup/dni/{dni}`. |
| `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**. Los códigos de `unit_code` e `igv_type` salen de los anexos de esta skill. |
| `discount`, `service_charge` | De los descuentos o recargo al consumo aplicados en el ticket. |

## Endpoint

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

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

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