Create Tagged File Event

Endpoint que permite indicar una o más etiquetas (y su valor) y asociarlas a una compañia (dada por el campo company_id), para registrar una acción que se ejecutará cuando un archivo de dicha compañia sea cargado al servicio Chronos y éste contenga dichas etiquetas. El conjunto de información etiquetas/acción se denomina como evento, el cual queda almacenado en el servicio y es monitoreado en segundo plano. Para que se registre adecuadamente el evento, se debe respetar la composición del cuerpo de la solicitud.

Endpoint#

Headers

Key	Value	Description
Content-Type	application/json
Authorization	Bearer {{access_token}}	access_token obtained in Atenea

Method: POST
URL: https://api.trust.lat/lighthouse/api/v1/event

caution

Recuerda que para utilizar este endpoint es necesario un access token obtenido en el servicio Atenea.

Como obtener un access token

Body#

Fields#

listener_type: Texto que indica que tipo de interacción activa al evento. En este caso, el valor de este campo debe ser tagged_file. Obligatorio.
company_id: Identificador de compañia provisto por empresa Trust. Obligatorio.
tags: Estructura que permite listar las etiquetas a ser monitoreadas. La síntaxis de esta estructura es: "<tag_name>" : "<tag_value>" y tanto la clave como su valor deben ser del tipo String. Obligatorio (Por lo menos debe existir una clave/valor).
action: Estructura que contiene la información sobre la acción a ejecutar cuando se active un evento. Obligatorio.
- external_action: Variable booleana que indica si la acción debe ser manejada por un servicio externo o por este servicio. Actualmente solo se encuentran implementadas las acciones externas, así que el valor de este campo debe ser true. Obligatorio.
- callback_type: Variable que indica que tipo de función se lleva a cabo cuando se activa un evento. Actualmente sólo se permite como valor webhook Obligatorio.
- callback_url: Dirección URL a la que se envía un aviso de la activación del evento. Obligatorio.
- delete_after_action: Valor booleano que indica si el evento debe eliminarse al finalizar su activación. Si el valor es falso, el evento se ejecutará hasta que sea eliminado de forma manual. Opcional.

Example#

{
  "listener_type": "tagged_file",
  "company_id": "1",
  "tags": {
    "foo":"bar"
  },
  "action": {
    "external_action": true,
    "callback_type": "webhook",
    "callback_url": "https://webhook.site/11111111-1111-1111-1111-111111111111",
    "delete_after_action": false
  }
}

callback_url#

Como se menciona anteriormente, este campo almacena una url que se utiliza para avisar al backend del integrador que un evento registrado ha sido detectado. Este aviso se realiza en forma de una solicitud web, llamada que se realiza en un formato similar al siguiente:

curl --location --request POST 'callback_url' \
--header 'Content-Type: application/json' \
--data-raw '{
  "event_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "room_id": "",
  "callback_url": "https://webhook.site/11111111-1111-1111-1111-111111111111",
  "callback_type": "webhook",
  "data": {
    "file_register_uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "filename":"test.txt",
    "tags":{
      "foo":"bar"
    }
  }
}'

caution

El endpoint que se asigne en el campo callback_url debe ser capaz de tolerar un alto nivel de llamadas paralelas

Code Examples#

Curl
JavaScript
Python

curl --location --request POST 'https://api-tst.trust.lat/lighthouse/api/v1/event' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "listener_type": "tagged_file",
  "company_id": "1",
  "tags": {
    "foo":"bar"
  },
  "action": {
    "external_action": true,
    "callback_type": "webhook",
    "callback_url": "https://webhook.site/11111111-1111-1111-1111-111111111111",
    "delete_after_action": false
  }
}'

Responses#

HTTP Code: 201 Created#

Event registered successfully#

{
    "status": "Created",
    "value": {
        "event_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "listener_type": "tagged_file",
        "company_id": "1",
        "tags": {
            "foo": "bar"
        }
    }
}

HTTP Code: 422 Unprocessable Entity#

Listener type missing#

{
    "code": 422,
    "message": "Invalid listener_type, check with the admin for the valid types"
}

Missing company_id in request body#

{
    "code": 422,
    "message": "Validation fail",
    "errors": {
        "text": "Problem with tagged_file event type",
        "data": null,
        "data2": null,
        "validations": {
            "company_id": "company_id not present"
        }
    }
}

Missing tags in request body#

{
    "code": 422,
    "message": "Validation fail",
    "errors": {
        "text": "Problem with tagged_file event type",
        "data": null,
        "data2": null,
        "validations": {
            "tags": "tags not present"
        }
    }
}

Bad formatted tags#

{
    "code": 422,
    "message": "Validation fail",
    "errors": {
        "text": "Problem with tagged_file event type",
        "data": null,
        "data2": null,
        "validations": {
            "tags": "tags must be formatted as a Map<String:String>",
            "tags.foo": "true is not formatted as a string"
        }
    }
}