---
name: faktura-enviar-el-comprobante-por-correo
description: "Enviar el comprobante por correo con la API de Faktura (facturación electrónica SUNAT, Perú). 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 ser… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Enviar el comprobante por correo — Faktura API

## Propósito

Le da a tu asistente el contexto para **enviar el comprobante por correo** con la API de Faktura: 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 ser…

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

## Endpoint

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

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

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

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