# Comprobia

> API REST para emitir comprobantes electrónicos ante SUNAT (Perú), modalidad SEE – Del Contribuyente: factura, boleta, notas de crédito y débito, guía de remisión remitente y transportista, retención, percepción y liquidación de compra. Cada emisor firma con su propio certificado. La emisión responde 202 al instante y el envío a SUNAT va en cola, con reintentos y webhooks.

Base de la API: https://comprobia.stackealabs.com/api/v1/{ruc}  ({ruc} es el RUC del emisor)
Autenticación: `Authorization: Bearer cmp_beta_…` (pruebas) o `cmp_produccion_…` (producción).

## Reglas que conviene saber antes de escribir código

- `Idempotency-Key` es OBLIGATORIA en todo lo que crea algo (POST /comprobantes, /anular…). Reintentar con la misma clave y el mismo cuerpo devuelve la misma respuesta, nunca un segundo comprobante.
- `POST /comprobantes` responde `202 Accepted` con el número ya asignado y el XML firmado. `sunat` es null hasta que SUNAT conteste. Para saber si vale, mira `tiene_validez_fiscal` (true sólo con ACEPTADO o ACEPTADO_CON_OBS), no compares `estado`.
- Importes SIEMPRE como texto decimal ("11.80"), nunca como número. Fechas `YYYY-MM-DD` en hora de Lima; la fecha de emisión no puede ser futura.
- En cada línea manda `precio_unitario` (con IGV) o `valor_unitario` (sin IGV), nunca los dos. El IGV se calcula por línea.
- Un 422 con `VALIDATION_ERROR` trae `errors[]` con `rule` y `sunat_code`: es lo que SUNAT habría rechazado, y NO gastó el número. Corrige y reintenta (la misma Idempotency-Key sirve tras un 4xx).
- Las boletas no se envían solas: van en el resumen diario. Su estado pasa a ACEPTADO a la mañana siguiente; es normal.
- Una nota (07/08) modifica un solo comprobante, que tiene que estar aceptado por SUNAT, y usa la serie de lo que corrige (F con F, B con B).
- Anular: `POST /comprobantes/{id}/anular`. El sistema elige el mecanismo (comunicación de baja o resumen); el estado pasa a ANULADO cuando SUNAT lo acepta, no al pedirlo.
- Para ver el PDF antes de emitir: `POST /comprobantes/vista-previa` con el mismo JSON (no gasta número). La historia de un comprobante: `GET /comprobantes/{id}/historial`.
- Para no teclear el cliente: `GET /clientes/ruc/{ruc}` o `GET /clientes/dni/{dni}` devuelve `razon_social`, `direccion`, `estado`, `condicion`, `avisos` y `procedencia` (padrón de SUNAT vía Acredita). Sólo autocompleta: no decide si se puede emitir.
- Errores siempre con la forma `{ "code", "message", "request_id", "errors"? }`.
- ¿Vienes de Facturalo Pro7? `/api/pro7/…` acepta su JSON y contesta con su forma.

## Sandbox

- Se crea solo en https://comprobia.stackealabs.com/desarrolladores/sandbox: confirmas el correo, eliges contraseña y creas la clave en el panel («Claves de API»). Series F001, B001 y T001.
- Lo que emite NO va a SUNAT: lo contesta un simulador con la forma de SUNAT (CDR, ticket del resumen, CDR recuperable). Cada comprobante trae `"simulado": true` y el PDF la marca PRUEBA.
- Para probar los caminos malos escribe `SIMULAR:<código>` en la descripción de una línea de una factura o nota: `SIMULAR:TIMEOUT` o `SIMULAR:0111` (transitorio, el reintento automático lo acepta), `SIMULAR:0402` (ya enviado, se recupera la CDR), `SIMULAR:1033` (se detiene), `SIMULAR:2xxx`/`3xxx` (rechazo: el número se quema), `SIMULAR:4xxx` (aceptado con observación).

## MCP

Servidor MCP (Streamable HTTP, JSON-RPC) en https://comprobia.stackealabs.com/api/mcp. Sin clave: `guia_de_integracion`, `listar_recetas`, `obtener_receta`, `consultar_endpoint`. Con `Authorization: Bearer <clave de un sandbox>`: `buscar_cliente`, `validar_comprobante`, `emitir_comprobante` (sólo sandbox, con `idempotency_key`) y `consultar_comprobante`.
Claude Code: `claude mcp add --transport http comprobia https://comprobia.stackealabs.com/api/mcp --header "Authorization: Bearer cmp_beta_…"`

## Documentación

- [Guía de inicio](https://comprobia.stackealabs.com/desarrolladores): los cinco pasos y el primer curl.
- [Recetas](https://comprobia.stackealabs.com/desarrolladores/recetas): un JSON por caso de uso (crédito, detracción, exportación, dólares, notas…).
- [Referencia de la API](https://comprobia.stackealabs.com/docs) y [contrato OpenAPI 3.1](https://comprobia.stackealabs.com/docs/openapi.yaml).
- [Texto completo para asistentes](https://comprobia.stackealabs.com/llms-full.txt): esto mismo con las recetas y el OpenAPI dentro.
- [Herramientas](https://comprobia.stackealabs.com/herramientas): validar un RUC, certificado de prueba .pfx y XML contra el XSD de SUNAT.
- Sistemas sin API: `POST /api/v1/{ruc}/planillas` emite una planilla CSV, TXT (separada por `;`, `,`, `|` o tabuladores) o XLSX, y el [conector de carpeta](https://comprobia.stackealabs.com/herramientas/conector-carpeta.ps1) para Windows la sube sola desde una carpeta. La columna `comprobante` es la clave de idempotencia de cada venta.
- [Seguridad](https://comprobia.stackealabs.com/seguridad) · [Estado del servicio](https://comprobia.stackealabs.com/estado)

## Planes (precios en soles, IGV incluido)

Se cobra por volumen: todas las funciones en todos los planes. Pasar de lo incluido nunca corta la emisión. Pagando por año, 12 meses por el precio de 10.
Plan Partner (integradores y estudios contables): una clave `cmpp_…` opera los RUC de todos tus clientes en la v1 y los da de alta por la API de partners (`/api/partner/v1`); se paga por emisor activo, con los documentos sumados entre todos.
- Libre: S/ 0.00 al mes, 100 documentos (sin costo; el excedente no se cobra ese mes).
- Inicial: S/ 39.00 al mes, 1,000 documentos, extra a S/ 0.05.
- Negocio: S/ 89.00 al mes, 3,000 documentos, extra a S/ 0.035.
- Cadena: S/ 189.00 al mes, 10,000 documentos, extra a S/ 0.022.
- Prepago: sin cuota, recargas que no vencen (500 por S/ 25.00 · 2,000 por S/ 79.00).
- A medida: a medida, se cotiza.