Saltar al contenido principal

API REST

La documentación de la API se encuentra en la página Api Docs.

Integration API Docs

Este artículo define los recursos disponibles en la API de integración de TicTAP. Si necesitas entender el modelo de datos que usa TicTAP, puedes leer el modelo de datos.

Acceso​

Inicio de sesión de miembro del equipo​

Si necesitas autenticarte como miembro del equipo con nombre de usuario y contraseña, usa el endpoint de autenticación principal:

POST /api/login
Content-Type: application/json

Cuerpo de la petición:

{
  "username": "[email protected]",
  "password": "your-password"
}

username debe contener el correo del miembro.

También puedes incluir opcionalmente team_slug cuando el miembro pertenece a más de un equipo y quieres forzar el inicio de sesión contra un equipo concreto:

{
  "username": "[email protected]",
  "password": "your-password",
  "team_slug": "my-team"
}

Ejemplo de respuesta:

{
  "access_token": "<jwt_access_token>",
  "refresh_token": "<refresh_token>",
  "ttl": 3600,
  "team_slug": "my-team"
}

Campos:

  • access_token: JWT usado en peticiones autenticadas
  • refresh_token: token usado para solicitar un nuevo JWT
  • ttl: tiempo restante de vida del token de acceso, en segundos
  • team_slug: slug del equipo resuelto para el token emitido

Refrescar JWT​

Para obtener un nuevo token de acceso a partir de un refresh token, usa:

POST /api/refresh-token
Content-Type: application/json

Cuerpo de la petición:

{
  "token": "<refresh_token>"
}

Ejemplo de respuesta:

{
  "access_token": "<new_jwt_access_token>",
  "refresh_token": "<refresh_token>",
  "ttl": 3600,
  "team_slug": "my-team"
}

Uso del token en las peticiones​

Una vez tengas un token de acceso, inclúyelo en las peticiones como cabecera:

AccessToken: <jwt_access_token>

El autenticador actual también acepta:

Authorization: <jwt_access_token>

Token de acceso​

Para acceder a la API es necesario disponer de un accessToken. Una vez lo tengas, debes incluirlo en cada petición como cabecera HTTP.

AccessToken: "AccessToken"

Si necesitas probar distintas llamadas a la API, puedes hacerlo desde la misma página de Api Docs usando el botón "authorize".

image-1688635717307.png

Definiciones​

Al usar la API de integración, primero debes entender qué definiciones están disponibles y qué campos tiene cada una. Una vez tengas esa información, puedes usarla para crear o actualizar entidades con esas definiciones.

Listado de definiciones​

Puedes obtener la lista de definiciones disponibles llamando al endpoint:

GET /api/integration/definitions

Este endpoint devuelve una lista de definiciones disponibles en tu Enterprise. Cada definición tiene una propiedad name que la identifica, una propiedad slug que es un identificador único y una propiedad fields que es una lista de campos.

Este es un ejemplo de respuesta:

{
  "pages": 11,
  "total": 51,
  "results": [
    {
      "name": "Fire extinguisher co2 5kg",
      "slug": "fire-extinguisher-co-2-5-kg"
    },
    {
      "name": "Ventilació extractors",
      "slug": "ventilacio-extractors"
    },
    {
      "name": "Facility",
      "slug": "facility"
    },
    {
      "name": "Bie",
      "slug": "bie"
    },
    {
      "name": "Pump",
      "slug": "pump"
    }
  ]
}

En el ejemplo anterior hay una lista de 51 definiciones, pero solo se devuelven 5. Esto se debe a que el endpoint devuelve las definiciones en páginas de limit elementos. Si quieres obtener la siguiente página puedes usar el parámetro page:

?page=1&limit=5

El número total de páginas siempre se devuelve en el parámetro pages.

Detalle de una definición​

Para obtener la lista de campos que tiene una definición concreta, es necesario hacer una petición al detalle de su slug.

GET /api/integration/definitions/{slug}

Este es un ejemplo:

GET /api/integration/definitions/bie

// Response:
{
  "name": "Bie",
  "slug": "bie"
  "fields": [
    {
      "type": "text",
      "name": "Model",
      "required": false,
      "indexable": true,
      "slug": "model",
      "localized": false
    },
    {
      "type": "text",
      "name": "Product reference",
      "required": false,
      "indexable": true,
      "slug": "product-reference",
      "localized": false
    },
    {
      "type": "date",
      "name": "Date",
      "required": false,
      "indexable": false,
      "slug": "date",
      "localized": false
    },
    {
      "type": "text",
      "name": "Location",
      "required": false,
      "indexable": false,
      "slug": "location",
      "localized": false
    }
  ]
}

Cada campo tiene un slug, que lo identifica de forma única y se usará al crear o editar entidades de esa definición.

Cada campo también tiene un type que define el tipo de dato que se almacena en ese campo: text, choice, media, media_collection... Puedes encontrar una referencia de todos los tipos de campo en el modelo de datos.

Entidades​

Crear una entidad​

Una vez conocida la definición, podemos crear una entidad para esa definición:

POST /api/integration/definitions/{slug}/entities

Este es un ejemplo al crear una entidad para la definición bie:

POST /api/integration/definitions/bie/entities

// Request body:
{
    "name": "Bie 1",
    "values": { 
      "model": "Model 1",
      "product-reference": "Product reference 1",
      "date": "2020-01-01",
      "location": "Location 1"
    }
}

Cuando alguno de los campos es de tipo media o media_collection (por ejemplo documents), la petición debe usar el tipo de contenido multipart/form-data y el valor del campo debe ser un archivo.

En el siguiente ejemplo, el campo documents es de tipo media_collection y contiene una lista de archivos. El campo photo es de tipo media y es un único archivo.

POST /api/integration/definitions/bie/entities

AccessToken: {AccessToken}
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="name"

Bie 1
------WebKitFormBoundary
Content-Disposition: form-data; name="values[model]"

Model 1
------WebKitFormBoundary
Content-Disposition: form-data; name="values[photo]"
Content-Type: image/png

< /home/debian/pictures/photo.jpeg
------WebKitFormBoundary
Content-Disposition: form-data; name="values[documents][]"; filename="document1.png"
Content-Type: image/png

< /home/debian/documents/document1.pdf
------WebKitFormBoundary
Content-Disposition: form-data; name="values[documents][]"; filename="document2.pdf"
Content-Type: image/jpg

< /home/debian/documents/document2.pdf
------WebKitFormBoundary--

Actualizar una entidad​

Al actualizar una entidad, la petición es la misma que al crearla, pero el método es PUT y el endpoint es:

PUT /api/integration/definitions/{slug}/entities/{id}

Los identificadores de las entidades son UUID. Este es un ejemplo al actualizar una entidad para la definición bie:

PUT /api/integration/definitions/bie/entities/a3f4509a-6060-4526-9bae-4a2cbd8f52b5

// Request body:
{
    "name": "Bie 1 updated",
    "values": { 
      "model": "Model 1 updated",
      "product-reference": "Product reference 1",
      "date": "2023-01-02",
      "location": "Location 1"
    }
}

Eliminar una entidad​

Al eliminar una entidad, la petición es una petición DELETE al endpoint:

DELETE /api/integration/definitions/{slug}/entities/{id}

Referencia externa​

Al crear o actualizar una entidad, es posible añadir una referencia externa a la entidad. Esto resulta útil cuando quieres vincular la entidad con un sistema externo. Por ejemplo, si tienes SAP y quieres vincular la entidad con un objeto concreto de SAP, puedes añadir el identificador de ese objeto como referencia externa.

La referencia externa es un string que debe ser único para la definición dada. Esto significa que si creas una entidad con una referencia externa, no puedes crear otra con la misma referencia externa.

La referencia externa se añade a la entidad en el campo external_reference. Por ejemplo:

POST /api/integration/definitions/bie/entities

// Request body:
{
    "name": "Bie 1",
    "external_reference": "SAP-1234",
    "values": { 
      "model": "Model 1",
      "product-reference": "Product reference 1",
      "date": "2020-01-01",
      "location": "Location 1"
    }
}

La referencia externa puede actualizarse al actualizar una entidad. Por ejemplo:

PUT /api/integration/definitions/bie/entities/a3f4509a-6060-4526-9bae-4a2cbd8f52b5

// Request body:
{
    "name": "Bie 1 updated",
    "external_reference": "SAP-UPDATED-1234",
    ...
}

IMPORTANTE: al actualizar una entidad y no informar external_reference, o si está vacío, la referencia externa actual se elimina de la entidad.

"Padre" de la entidad​

Al crear o actualizar una entidad, es posible añadir un "parent" a la entidad. El padre se refiere a la entidad de nivel superior que contiene a la entidad. Por ejemplo, si tienes una definición facility y una definición room, la entidad room puede tener como padre una entidad facility. Para expresarlo a través de la API puedes añadir el campo parent_id a la entidad.

For example:

POST /api/integration/definitions/room/entities

// Request body:
{
    "name": "Room 1",
    "parent_id": "a3f4509a-6060-4526-9bae-4a2cbd8f52b5"
    ...
}

y también es posible usar la "external reference" de la entidad padre:

POST /api/integration/definitions/room/entities

// Request body:
{
    "name": "Room 1",
    "parent_id": "SAP-FACILITY-1234"
    ...
}

Esto también puede hacerse al actualizar una entidad, lo que provoca un "move" de la entidad a otro padre. Por ejemplo:

PUT /api/integration/definitions/room/entities/room-uuid

// Request body:
{
    "name": "Room 1",
    "parent_id": "SAP-ANOTHER-FACILITY"
    ...
}

IMPORTANTE: NO es posible dejar una entidad "orphan". Al actualizar una entidad y no informar parent_id, o si está vacío, el padre actual permanecerá sin cambios.