Ir al contenido

Introducción

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

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.

  • 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 como float. En las peticiones puedes enviarlos como número (8.5) o como texto ("8.50").
  • Fechas YYYY-MM-DD en hora de Perú (America/Lima).
  • Identificadores UUID (01a1d5fc-899b-720e-a6ea-03d37a346f81).
  1. Envías POST /v1/invoices o POST /v1/receipts.
  2. La API valida, calcula impuestos y totales, asigna el siguiente correlativo de la serie y responde de inmediato con 201 y status: "pending". El número ya es tuyo y puedes imprimir el ticket.
  3. En segundo plano, la API firma el XML, lo envía a SUNAT y guarda el CDR. Si SUNAT no responde, reintenta sola.
  4. Consultas GET /v1/documents/{id} hasta ver un estado final (accepted, observed, rejected o failed).

El detalle de cada estado y la estrategia recomendada de consulta están en Estados y envío a SUNAT.

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.