Autenticación

Cada llamada a la API de TrakIT indica quién llama. La API de integración usa un token que un usuario de TrakIT obtiene al iniciar sesión. La API pública usa claves de API, cada una configurada para un socio y unos pocos puntos de conexión.

API de integración: token de inicio de sesión

1. Inicie sesión con POST /api/v1/Login, con el identificador de usuario o la dirección de correo electrónico y la contraseña de un usuario que tenga acceso a la API.
2. Si tiene éxito, Info contiene el token.
3. Envíe el token en un encabezado Token con cada una de las demás llamadas:

GET /api/v1/GetJob?Num=EXBL2610045
Token: your-token

Conserve el token y úselo en todas las llamadas hasta que se rechace: no es necesario iniciar sesión para cada llamada. Cada inicio de sesión abre una nueva sesión en el historial de inicios de sesión del usuario y, tras cinco inicios de sesión fallidos en 30 minutos con el mismo identificador de usuario o la misma dirección de correo electrónico, TrakIT rechaza los inicios de sesión con ellos durante 30 minutos.

Estas respuestas significan que no se ha aceptado el token:

Info	Significado
Token missing in header	La solicitud no tiene encabezado Token.
Invalid Token, Invalid Token Split	El encabezado contiene algo que no es un token de TrakIT, por ejemplo un valor cortado o alterado.
Token invalid or expired	El token ha caducado, o su sesión ha terminado. Vuelva a iniciar sesión.
User account is locked	Se ha bloqueado al usuario desde que se emitió el token.
No such user	El usuario del token ya no existe.
API User must be SysAdmin with API Access	El usuario ya no tiene acceso a la API.
Your password has expired. Sign in to TrakIT in a web browser to change it.	La contraseña del usuario ha caducado.
Database is offline	TrakIT no está disponible en este momento, por ejemplo durante un mantenimiento. Vuelva a intentarlo más tarde.

Acceso a la API

Solo un administrador del sistema con el acceso API puede usar la API de integración. El acceso a la API es uno de los modos de acceso de la página Acceso de los usuarios, y solo el soporte de TrakIT puede activarlo o desactivarlo. Sin él, Login responde User account is not permitted to sign in from the API, y se rechaza un token emitido antes de que se desactivara.

Las llamadas actúan como ese usuario. Los expedientes, eventos, documentos y facturas de proveedor que una integración crea o modifica quedan registrados a nombre del usuario, como si el usuario lo hubiera hecho en TrakIT. Reserve un usuario para cada integración y pida al soporte de TrakIT que le dé acceso a la API, de modo que los cambios de la integración se distingan fácilmente y su acceso pueda retirarse por separado. Un usuario independiente también evita que la integración moleste a una persona: un inicio de sesión a través de la API cuenta como el último inicio de sesión del usuario, por lo que, si el mismo usuario ha iniciado sesión en TrakIT en un navegador web en otro lugar, esa sesión del navegador se cierra.

Un usuario que inicia sesión con autenticación en dos pasos, un código enviado por correo electrónico o una aplicación de autenticación, no puede obtener un token: Login no puede recibir el código, así que rechaza a ese usuario sin enviarle ninguno (Two-factor authentication is on for this user, and the API cannot take a code. Use an API user without two-factor authentication.). Use para la API un usuario sin autenticación en dos pasos.

Las reglas habituales de inicio de sesión también se aplican a Login: un usuario bloqueado no puede iniciar sesión, las contraseñas incorrectas repetidas suspenden temporalmente los inicios de sesión del usuario, y las validaciones de inicio de sesión de su empresa, si las tiene, pueden rechazarlo.

Caducidad del token

Un token sigue siendo válido mientras se use: caduca tras 7 días sin ninguna llamada. Una integración que llama a la API al menos una vez por semana no necesita volver a iniciar sesión por ese motivo. Un token también deja de ser válido antes, cuando:

• la integración cierra su sesión con Logout;
• se cambia o se restablece la contraseña del usuario, dondequiera que se haga: en TrakIT, en la aplicación de TrakIT independiente o por parte de un administrador;
• se bloquea o se desbloquea al usuario.

Cuando una llamada responda Token invalid or expired, vuelva a iniciar sesión con Login y use el nuevo token.

Cada Login proporciona un token nuevo; los tokens de inicios de sesión anteriores siguen funcionando hasta que dejan de ser válidos. Cierre con Logout la sesión de un token que la integración ya no use.

Caducidad de la contraseña

Si su empresa hace que las contraseñas caduquen (Cuando caduca su contraseña), la contraseña del usuario de la API también caduca. A partir de ese momento, Login y todas las demás llamadas responden Your password has expired. Sign in to TrakIT in a web browser to change it.; solo Logout sigue funcionando. Para continuar:

1. Inicie sesión en TrakIT en un navegador web como el usuario de la API y cambie la contraseña.
2. Vuelva a iniciar la sesión de la integración con Login y la nueva contraseña: al cambiar la contraseña, los demás tokens del usuario han dejado de ser válidos.

API pública: claves de API

El soporte de TrakIT configura las claves de la API pública. Cada clave solo tiene permitidos los puntos de conexión que necesita, y el soporte puede desactivar una clave en cualquier momento. Una clave incorrecta, desactivada o sin permiso para el punto de conexión recibe Key is disabled, not recognized or permission denied.

Los puntos de conexión reciben la clave de distintas formas:

Puntos de conexión	Envíe la clave
Facturas de proveedor, GetShipment	En un encabezado APIKey: APIKey: your-api-key.
QueryReport, AdvReport	En un parámetro APIKey de la cadena de consulta.
GetContainerPosition, ExecuteMove	En un encabezado Authorization: Authorization: Bearer your-api-key.
GetList, GetAssetLocation	La clave propia de la entidad, en un parámetro APIKey de la cadena de consulta.

Una clave de facturas de proveedor está además vinculada a un proveedor, una empresa y un usuario externo: consulte Cómo funciona una clave de proveedor.

Para obtener una clave, diríjase al soporte de TrakIT e indique para qué puntos de conexión es.

Claves de API de las entidades

GetList y GetAssetLocation responden para un solo cliente: la entidad cuya clave se envía. Esa clave no la configura el soporte de TrakIT: se muestra en la página de la entidad, como API Key, una vez que Enable API Access está activado para la entidad. Los usuarios que pueden cambiar la entidad la ven ahí y se la dan al cliente.

La clave es válida durante el año natural en curso. Al principio de cada año cambia: dé al cliente la nueva clave desde la página de la entidad. Desactivar Enable API Access para la entidad hace que su clave deje de funcionar de inmediato, en los dos puntos de conexión.

Proteger las credenciales

• Llame a la API solo por HTTPS.
• Guarde las contraseñas, los tokens y las claves en el almacén de secretos de su sistema, no en código, scripts o documentos que otros puedan leer, y no los envíe nunca por correo electrónico.
• Algunos puntos de conexión reciben la clave en la cadena de consulta, por lo que la clave forma parte de la dirección. No incluya esas direcciones en los registros ni en las capturas de pantalla que comparta.
• Si una clave puede haberse filtrado, pida al soporte de TrakIT que la desactive y emita una nueva. Si un token puede haberse filtrado, cierre su sesión con Logout. Si la contraseña del usuario de la API puede haberse filtrado, cámbiela, lo que además hace que dejen de ser válidos todos los tokens del usuario, y póngase en contacto con el soporte de TrakIT de inmediato.