Autenticación

En esta sección aprenderás a generar un token de autorización para poder enviar peticiones al API.

Stage, Producción y Producción UE son entornos independientes. Usuarios, API keys y datos no se comparten: una credencial de un entorno da 401 en los demás. Integra primero en Stage y, al pasar a producción, cambia solo la URL base y la credencial. Ver entornos.

Las credenciales (usuario, contraseña y API key) son de un entorno concreto: las de Stage solo sirven en Stage, las de Producción solo en Producción y las de Producción UE solo en Producción UE. El selector de la cabecera cambia las URL de esta documentación.

Obtener tu API key en la app del entorno seleccionado
POSThttps://enterprise-stage.api.trato.io/api/authentication/token

Generar JWT

Para generar el token de acceso, deberás enviar el usuario y password asociados a tu cuenta de TRATO a través de la siguiente llamada.


  • Name
    email
    Type
    string
    Description

    Usuario para acceder al panel de TRATO.

  • Name
    password
    Type
    string
    Description

    Contraseña para acceder a TRATO. mínimo 11 caracteres.


Response attributes

  • Name
    success
    Type
    string
    Description

    Indica si la configuración del contrato fue exitosa (true/false).

  • Name
    jwt
    Type
    string
    Description

    El JSON Web Token generado por el api.

  • Name
    ttl
    Type
    integer
    Description

    Tiempo de vigencia del token en segundos.

  • Name
    error
    Type
    string
    Description

    En caso de existir algún error, se indicará en este parámetro.

Petición

POST
/api/authentication/token
curl -X POST https://enterprise-stage.api.trato.io/api/authentication/token \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "********"}'

Respuesta

{
  "success": true,
  "jwt": "iOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2",
  "ttl": 300,
  "error": ""
}

Api Key

Para usar el api key, deberás enviarlo a traves de un Header llamado 'apikey'. Si mandas el apikey en un header no es necesario generar el JWT

Ejemplo de petición usando apikey

curl https://enterprise-stage.api.trato.io/api/list/templates \
  -H "apikey: {apikey}"

Mantén siempre su token ó apikey seguro para que no sea comprometido.


Error 401: credencial de otro entorno

Si la API key o el token no existen en el entorno al que llamas, la API responde 401 con el código INVALID_CREDENTIALS, el entorno que ha respondido (environment) y una pista (hint).

401

{
  "success": false,
  "statusCode": 401,
  "error": "InvalidApiKey",
  "environment": "production",
  "code": "INVALID_CREDENTIALS",
  "hint": "Credencial ausente o no válida en este entorno (Producción). Cada entorno tiene sus propios usuarios y API keys. Si la obtuviste en clm-stage.trato.io (Stage), usa https://enterprise-stage.api.trato.io. Más información: https://developer.trato.io/entornos",
  "docs": "https://developer.trato.io/entornos"
}

Comprueba que la URL base y la credencial son del mismo entorno: credencial de clm-stage.trato.io con la URL de Stage; credencial de clm.trato.io con la URL de Producción. Si el error sigue, genera de nuevo la API key en Perfil > Seguridad.


Protección de las urls de los archivos

En caso de tener habilitada dicha protección en el TENANT, lo que cambia es como se obtiene el contenido de los archivos, por lo que con esto es necesario tener una sesión válida, por lo que nadie que no este autorizado podrá obtener el archivo.

Ejemplo

https://upload.trato.io/332fcb56-da8f-432f-879a-8ddee565c289.pdf
-> https://enterprise-stage.api.trato.io/uploads/624b726200a14793dfb01cde