Autenticación
HTTP Basic con el usuario y la APIKey del cliente, y las dos formas del 401.
La API usa HTTP Basic en cada request. No hay otro mecanismo: ni tokens, ni OAuth, ni sesión.
Usuario y APIKey
- El usuario es el
UserNamedel cliente: el mismo con el que entra al portal del cliente, o sea el RUT de su empresa con guion y dígito verificador. Escríbalo igual que lo muestra el portal (conKmayúscula si corresponde). Es el RUT de usted como proveedor, no el de la empresa cliente que va en la URL. - La contraseña es su
APIKey, la «Llave de acceso» del portal.
El Quickstart explica dónde se ven las dos en el portal.
El header Authorization
El header es Authorization: Basic seguido de <usuario>:<apikey> codificado en Base64. Con
curl -u, curl lo arma por usted:
curl -u '<usuario>:<apikey>' -H 'Accept: application/json' \
https://api.enrolamiento.cl/v1/certificaciones/11111111-1/consultarArmado a mano, es lo mismo:
credencial=$(printf '%s' '<usuario>:<apikey>' | base64)
curl -H "Authorization: Basic $credencial" -H 'Accept: application/json' \
https://api.enrolamiento.cl/v1/certificaciones/11111111-1/consultarEl esquema se escribe exactamente Basic: la API distingue mayúsculas, y basic no sirve.
Base64 es una codificación, no un cifrado: cualquiera que vea el header puede leer la credencial.
Llame siempre a https://api.enrolamiento.cl.
No deje la credencial en la línea de comandos
Los ejemplos de arriba escriben la APIKey en el comando. Así queda en el historial del shell, y mientras el comando corre puede verse en la lista de procesos de la máquina. Sirve para una prueba, no para el uso diario.
-
En su aplicación, lea el usuario y la APIKey de variables de entorno o de un archivo que solo pueda leer el usuario que la ejecuta.
-
Con
curl, guárdela en un archivo de configuración con permisos restringidos y páselo con--config. Cree primero el archivo vacío, ya legible solo para su usuario, y recién después escriba la credencial: si el archivo nace con los permisos por omisión, otros usuarios de la máquina pueden leerlo hasta que se los restrinja.install -m 600 /dev/null credencial.curlEl archivo lleva una sola línea:
user = "<usuario>:<apikey>"curl --config credencial.curl -H 'Accept: application/json' \ https://api.enrolamiento.cl/v1/certificaciones/11111111-1/consultarEscriba la línea con un editor, no con un
echo, que también quedaría en el historial. Una variable de entorno puesta en el comando decurl(-u "$usuario:$apikey") se libra del historial, pero no necesariamente de la lista de procesos: el shell la reemplaza por su valor antes de lanzarcurl.
Cada request lleva la credencial
La API no abre sesión ni entrega un token que reemplace a la credencial. Mande el header
Authorization en todos los requests, también en el primero: no espere a que la API se lo pida
con un 401.
Los dos 401
La API responde 401 en dos casos, y solo uno trae cuerpo:
| Qué mandó | Cuerpo del 401 |
|---|---|
Ningún header Authorization | JSON: {"Message": "Authorization has been denied for this request."} |
El header, con un esquema que no es Basic, sin credencial, con una credencial que no se puede decodificar, o con un usuario o una APIKey inválidos | Ninguno |
No parsee el cuerpo de un 401: decida por el status. La diferencia sirve para diagnosticar:
- Con cuerpo JSON: el header no llegó. Revise que su cliente HTTP lo mande desde el primer request y que nada en el camino lo quite.
- Sin cuerpo: el header llegó, pero la API no aceptó la credencial. Revise el usuario, la APIKey
y que el esquema sea
Basic.
Repetir el request con la misma credencial da el mismo 401, así que no lo reintente en un ciclo
automático. Las respuestas 401 también traen RateLimit-Limit y RateLimit-Remaining: esos
requests pasan por el límite de la API como cualquier otro (vea Rate limits).
WWW-Authenticate
Los dos 401 traen el header WWW-Authenticate: Basic. Podría venir además otro desafío, así que no
dependa de que Basic sea el único.
Cuándo un 404 llega antes que el 401
En certificaciones_v1_actualizar_casillas_intercambio (POST /v1/certificaciones/{rut}/actualizar-casillas-intercambio),
correoContactoSii y correoContactoEmpresa son obligatorios en la query string. Si falta
cualquiera de los dos, la API responde 404 con un JSON con Message antes de revisar la
credencial: el 404 sale aunque la credencial falte o sea inválida. El detalle está en
Errores y reintentos.
Cambiar la APIKey
Usted puede cambiar su APIKey desde el portal del cliente: en Mi Cuenta, pestaña Integración, genere una nueva con el ícono que está junto al campo Llave de acceso y presione Guardar.
La cuenta tiene una sola APIKey. Al guardar la nueva, la anterior queda reemplazada, y los requests que la sigan usando reciben 401 sin cuerpo. Actualice su integración en el mismo momento en que guarda. Cámbiela también si sospecha que alguien más la conoce.