Autenticación
Cada petición a /v1 lleva tu API key como token Bearer:
GET /v1/me HTTP/1.1Host: faktura-test.cgallardo.meAuthorization: Bearer sk_test_ec829766c02e_bb1f99a4b8069b5657d82bff324df39b08430f47c5b730fa98cc44ec8d991cd8Formato de la API key
Sección titulada «Formato de la API key»sk_test_ec829766c02e_bb1f99a4…cd8└─┬───┘ └────┬─────┘ └────┬─────┘ entorno prefijo secreto- Entorno:
test(SUNAT beta) olive(SUNAT producción). Ver Introducción. - Prefijo (
sk_test_ec829766c02e): identifica la clave sin revelarla. Es lo que verás en los registros y lo que usas para pedir su revocación. - Secreto: solo se muestra una vez, al emitir la clave. Faktura guarda únicamente un hash; si lo pierdes, se emite una clave nueva.
Buenas prácticas
Sección titulada «Buenas prácticas»- Guarda la clave en tu servidor (variable de entorno o gestor de secretos). Nunca la pongas en una app móvil, en JavaScript del navegador ni en un repositorio.
- Usa una clave por sistema o por tienda (
POS tienda 1,ERP central): así puedes revocar una sin afectar a las demás. - Si un sistema solo consulta RUC o DNI, pide una clave de alcance
lookup: llega a/v1/mey/v1/lookup/*y nada más (no emite, no anula ni lee comprobantes). Una clavelookupque intenta otra cosa recibe403ApiKeyScopeInsufficient./v1/meinforma el alcance enapi_key.scope. - Una clave revocada deja de funcionar en la siguiente petición.
Respuestas de autenticación
Sección titulada «Respuestas de autenticación»| Situación | Estado | Cuerpo |
|---|---|---|
Falta la cabecera, el esquema no es Bearer, la clave está mal formada, no existe, fue revocada o la empresa está desactivada |
401 |
{"reason":"Unauthenticated"} + cabecera WWW-Authenticate: Bearer |
La clave es de alcance lookup y la ruta exige alcance completo |
403 |
{"reason":"ApiKeyScopeInsufficient"} |
| Superaste el límite de peticiones | 429 |
{"reason":"TooManyRequests"} + cabecera Retry-After (segundos) |
Todas las causas de rechazo devuelven el mismo 401 a propósito: así nadie puede averiguar si una clave existe o fue revocada.
Límite de peticiones
Sección titulada «Límite de peticiones»Por defecto, 120 peticiones por minuto por API key. Al superarlo recibes 429 con Retry-After; espera esos segundos antes de reintentar. Si tu operación necesita más, pide que se amplíe el límite de tu clave.
Verificar tu clave
Sección titulada «Verificar tu clave»GET /v1/me responde con tu empresa, el entorno de la clave y si ya tienes certificado y usuario SOL configurados. Es la forma más simple de probar la integración.