Ir al contenido

Autenticación

Cada petición a /v1 lleva tu API key como token Bearer:

GET /v1/me HTTP/1.1
Host: faktura-test.cgallardo.me
Authorization: Bearer sk_test_ec829766c02e_bb1f99a4b8069b5657d82bff324df39b08430f47c5b730fa98cc44ec8d991cd8
sk_test_ec829766c02e_bb1f99a4…cd8
└─┬───┘ └────┬─────┘ └────┬─────┘
entorno prefijo secreto
  • Entorno: test (SUNAT beta) o live (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.
  • 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/me y /v1/lookup/* y nada más (no emite, no anula ni lee comprobantes). Una clave lookup que intenta otra cosa recibe 403 ApiKeyScopeInsufficient. /v1/me informa el alcance en api_key.scope.
  • Una clave revocada deja de funcionar en la siguiente petició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.

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.

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.