Autenticación

Todas las llamadas usan un token Bearer en la cabecera Authorization. Hay dos niveles, según lo que quieras hacer.

Token de empresa — cpe:sign

Para firmar y emitir comprobantes de una empresa (RUC). Se genera en el panel, en la empresa → Tokens API. Pertenece a esa empresa.

Authorization: Bearer <token-de-empresa>

Habilita: POST /v1/cpe, consulta, reenvío y descarga de XML/CDR.

Cómo obtener el token de empresa

Dos formas — elige la que use tu integración (no tienes que cambiar tu sistema):

1. Token directo (API-first). Al crear la empresa la respuesta ya trae el token. ¿No lo guardaste? Genera otro con POST /v1/companies/{ruc}/token.

2. Login con usuario/contraseña. Si tu sistema ya inicia sesión para obtener el token, usa las credenciales de la empresa:

   curl -X POST https://api.xmlperu.dev/api/auth/cpe/token \
     -H "Content-Type: application/json" \
     -d '{ "usuario": "a1b2c3d4", "password": "e5f6g7h8" }'

   Devuelve access_token (con expiración). Las credenciales las obtienes al crear la empresa o con GET /v1/companies/{ruc}/credentials. Solo apunta tu sistema a este endpoint.

Token de cuenta — empresas:manage

Para crear y administrar empresas de tu cuenta. Se genera en el panel, en Cuenta → Tokens de API. Pertenece al usuario dueño de la cuenta, no a una empresa.

Authorization: Bearer <token-de-cuenta>

Habilita: GET/POST /v1/companies, cambiar plan y entorno.

Importante · Un token cpe:sign no puede gestionar empresas, y un token empresas:manage no puede firmar. Si usas el token equivocado, la respuesta es 403.

Errores de autenticación

Código	Significado
401	Token ausente o inválido
403	El token no tiene el permiso requerido