---
name: faktura-anular-un-comprobante
description: "Anular un comprobante con la API de Faktura (facturación electrónica SUNAT, Perú). Pide a SUNAT la anulación (baja) de un comprobante aceptado. Faktura elige el mecanismo según la serie: Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Anular un comprobante — Faktura API

## Propósito

Le da a tu asistente el contexto para **anular un comprobante** con la API de Faktura: Pide a SUNAT la anulación (baja) de un comprobante aceptado. Faktura elige el mecanismo según la serie:

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

## Endpoint

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

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

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

## 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: Cómo saber cuándo terminó (de «Estados y envío a SUNAT»)

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

## Anexo: Errores de anulación (de «Errores»)

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

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