Autenticación

Cada petición se autentica con una clave API del workspace. Envíala en uno de estos headers:

X-API-Key: asu_live_...
# o
Authorization: Bearer asu_live_...

Si envías los dos, se usa X-API-Key.

Tipos de clave

La clave decide el modo, y cada RUC pertenece a un modo: una clave solo ve y usa los RUC de su modo. El mismo número de RUC puede registrarse una vez en cada modo. Ver Emisores.

Sandbox

Con una clave asu_test_ los comprobantes van siempre a SUNAT beta, sin validez tributaria:

• Solo ves y usas tus RUC de prueba. GET /issuers con la clave test no lista los RUC de producción, y pedir uno de ellos responde 404 ISSUER_NOT_FOUND.
• Cada RUC de prueba necesita solo su certificado y la validación en beta. SUNAT beta firma con tu certificado y el usuario genérico MODDATOS: no se piden usuario ni clave SOL.
• Usan una numeración propia que empieza en 90000001 (por ejemplo F001-90000001): no consumen los correlativos reales de tus series ni chocan con ellos en SUNAT beta.
• No descuentan operaciones de tu plan.
• GET /documents con la clave test lista solo los documentos de prueba ("test": true); con la clave live, solo los reales.
• Las lecturas por id también están separadas por modo: GET /documents/{id} y sus descargas (XML, CDR, PDF) con una clave test solo encuentran documentos de prueba, y con una clave live solo los reales. Si pides un documento del otro modo, la API responde 404 NOT_FOUND, como si no existiera.
• Una nota o una anulación de un documento de prueba se hace con la clave test, y la de un documento real con la clave live. Si las mezclas responde 403 TEST_KEY_IN_PRODUCTION.
• SUNAT no tiene beta para guías de remisión: las guías requieren clave live y un RUC con producción habilitada.

Con una clave asu_live_ se emite siempre en SUNAT real. Solo ves y usas tus RUC de producción. Si el RUC todavía no tiene producción habilitada, la API responde 403 PRODUCTION_NOT_ENABLED: usa una clave asu_test_ con un RUC de prueba para probar o completa la prueba real y la habilitación. Las operaciones que exigen una clave de producción responden 403 LIVE_KEY_REQUIRED.

Crear, rotar y revocar claves

Las claves se administran desde el panel de apisunat.net, en tu workspace en modo API. Solo el propietario y los administradores pueden hacerlo. Al rotar una clave, la anterior deja de funcionar de inmediato.

Una clave no tiene permisos parciales: da acceso completo al workspace y a todos los RUC de su modo.

Comprobar una clave

curl https://api.apisunat.net/api/v1/issuer/ping \
  -H "X-API-Key: $APISUNAT_KEY"

{
  "workspace": { "id": "8a1f...", "name": "Mi Empresa" },
  "keyType": "live",
  "plan": "pro"
}

Una clave ausente o inválida responde:

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "La API key no es válida.",
    "retryable": false,
    "fields": {},
    "requestId": "9ed9f5dd-4284-4a27-aa9f-4906b9294f24"
  }
}

Request ID

Todas las respuestas incluyen el header X-Request-Id. Si envías tu propio X-Request-Id, la API lo usa. Compártelo con soporte cuando reportes un problema.