Introducción
URL base y versionado
Sección titulada «URL base y versionado»| Entorno | URL base | Clave |
|---|---|---|
| Pruebas | https://faktura-test.cgallardo.me |
sk_test_… (SUNAT beta) |
| Producción | https://faktura.cgallardo.me |
sk_live_… (SUNAT producción) |
Todas las rutas de negocio llevan el prefijo de versión /v1. Dentro de v1 solo se agregan campos o endpoints nuevos; un cambio incompatible saldría en /v2 con aviso previo (ver Versiones).
Entornos: prueba y producción
Sección titulada «Entornos: prueba y producción»El entorno ante SUNAT lo decide la API key: el mismo código de integración sirve para ambos.
| API key | Envía a | Uso |
|---|---|---|
sk_test_… |
SUNAT beta | Desarrollo y pruebas. Los comprobantes no tienen validez tributaria. |
sk_live_… |
SUNAT producción | Comprobantes reales. Requiere que tu empresa tenga certificado digital y usuario SOL configurados. Una clave de solo consultas (RUC y DNI) no los necesita. |
El entorno de pruebas (https://faktura-test.cgallardo.me) recibe cada versión antes de que llegue a producción y solo acepta claves sk_test_: una sk_live_ responde 401. Los ejemplos de esta documentación usan la URL de pruebas y una clave sk_test_. Para pasar a producción cambias dos cosas: la URL base por https://faktura.cgallardo.me y la clave por la sk_live_.
Una clave puede tener fecha de vencimiento (los accesos de prueba la tienen): al vencer responde 401 igual que una revocada, y hay que pedir otra.
Las series y la numeración son independientes por entorno: emitir en prueba nunca consume números de producción. Un comprobante emitido con una clave de prueba no es visible con una clave de producción, y viceversa.
Formato
Sección titulada «Formato»- Peticiones y respuestas en JSON UTF-8 (
Content-Type: application/json). - Nombres de campos en
snake_case. - Montos en las respuestas como texto decimal (
"16.00"), para que ningún cliente pierda exactitud al leerlos comofloat. En las peticiones puedes enviarlos como número (8.5) o como texto ("8.50"). - Fechas
YYYY-MM-DDen hora de Perú (America/Lima). - Identificadores UUID (
01a1d5fc-899b-720e-a6ea-03d37a346f81).
Cómo funciona una emisión
Sección titulada «Cómo funciona una emisión»- Envías
POST /v1/invoicesoPOST /v1/receipts. - La API valida, calcula impuestos y totales, asigna el siguiente correlativo de la serie y responde de inmediato con
201ystatus: "pending". El número ya es tuyo y puedes imprimir el ticket. - En segundo plano, la API firma el XML, lo envía a SUNAT y guarda el CDR. Si SUNAT no responde, reintenta sola.
- Consultas
GET /v1/documents/{id}hasta ver un estado final (accepted,observed,rejectedofailed).
El detalle de cada estado y la estrategia recomendada de consulta están en Estados y envío a SUNAT.
Correlación y soporte
Sección titulada «Correlación y soporte»Cada respuesta incluye la cabecera X-Request-Id. Puedes enviar tu propio identificador en esa cabecera (8 a 64 caracteres: letras, números y guiones) y la API lo reutiliza. Incluye ese valor cuando reportes un problema a soporte.