Autenticación

Cabecera Authorization

Envía el token en cada solicitud, salvo en los catálogos y la especificación, que son públicos:

Authorization: Bearer glm_prod_7Qx4...

• Nunca en la URL: una solicitud con token, access_token o api_key en la consulta responde 400 TOKEN_EN_URL. Las URL quedan en registros de servidores y navegadores, así que revoca ese token y crea otro.
• Nunca en el cuerpo: los campos desconocidos se rechazan con 400 VALIDACION.
• El API no admite CORS. Llámalo desde tu servidor, no desde el navegador ni desde una aplicación móvil, donde el token quedaría expuesto.

Formato del token

El prefijo indica el ambiente en el que emite y consulta el token (ver Ambientes). Los últimos caracteres incluyen un control que permite detectar un token mal copiado.

Crear un token

Los tokens se crean en la aplicación, en Cuenta > API e integraciones. Solo los administradores de la empresa ven esa pantalla.

1. Nombre: identifica la integración, por ejemplo “ERP principal” o “Tienda en línea”.
2. Ambiente: Pruebas o Producción.
3. Punto de emisión por defecto (opcional): se usa cuando la solicitud no indica establecimiento y puntoEmision.
4. Puntos en los que puede emitir: todos los puntos de la empresa, o solo los que elijas.

Golem muestra el token una sola vez, al crearlo, y guarda solo su huella (SHA-256). Si lo pierdes, crea otro y revoca el anterior. La pantalla lista cada token con su prefijo y sus últimos 4 caracteres, quién lo creó, la fecha de creación y el último uso. Una empresa puede tener hasta 10 tokens activos.

Los tokens son de la empresa, no de la persona que los creó: si esa persona deja la empresa, el token sigue funcionando hasta que un administrador lo revoque.

Puntos de emisión del token

• Si la solicitud indica establecimiento y puntoEmision, se emite en ese punto.
• Si los omite, se usa el punto por defecto del token. Sin punto por defecto, indícalos en cada solicitud.
• Un token limitado a algunos puntos responde 403 PUNTO_NO_PERMITIDO si la solicitud usa otro punto. Si los puntos del token se eliminaron de la empresa, el token ya no puede emitir: crea otro.

GET /empresa devuelve en token.puntoPorDefecto y token.puntosPermitidos la configuración del token que hace la solicitud (puntosPermitidos es null cuando puede emitir en todos). Las consultas no dependen de los puntos: el token ve todos los comprobantes de la empresa en su ambiente.

Revocar un token

En Cuenta > API e integraciones, elige Revocar. La revocación es inmediata: la siguiente solicitud con ese token responde 401 TOKEN_REVOCADO. Los tokens revocados en los últimos 90 días siguen visibles en la pantalla.

Si un token quedó expuesto

1. Revócalo de inmediato.
2. Crea otro y reemplázalo en tu sistema.
3. Revisa los comprobantes emitidos con el listado (origen=API).
4. Si necesitas el registro de solicitudes de ese token (fecha, dirección IP, operación, resultado y comprobante), pídelo a [email protected] desde la cuenta de un administrador. Golem conserva ese registro 13 meses.

Recomendaciones

• Guarda el token en una variable de entorno o en un gestor de secretos, no en el código fuente ni en el repositorio.
• Crea un token por integración: así puedes revocar uno sin detener las demás.
• Limita a sus puntos de emisión los tokens de integraciones que emiten en un solo local.
• No escribas el token en los registros de tu sistema.

Errores de autenticación

Las respuestas 401 incluyen la cabecera WWW-Authenticate: Bearer realm="golem".

Token de la integración anterior

Si tu empresa usaba la ruta de integración anterior a la versión 1 (/api/api/v1/generate/factura), su token funciona solo en esa ruta y aparece aparte en Cuenta > API e integraciones. Cuando tu integración use el API v1, revócalo desde esa pantalla.