Automatizações

As automatizações permitem ao Tillor executar ações por si próprio, como criar tarefas ou chamar o seu sistema. A explicação para utilizadores está em Automatizações. Esta página descreve o que um integrador vê: a mensagem do passo Enviar webhook, o Pedido à API para um URL próprio ou para a API do Tillor, e como um fluxo é construído se o gerir através da API.

Enviar webhookCopiar a ligação para esta secção

O passo Enviar webhook entrega uma mensagem própria a um dos webhooks da organização. É a mesma entrega que nos eventos de webhook normais, com a mesma assinatura.

A mensagemCopiar a ligação para esta secção

O passo faz um POST com Content-Type: application/json e estes cabeçalhos:

O corpo tem o mesmo envelope que o payload do webhook:

{
  "event": "automation.invoice_unpaid",
  "data": {
    "invoice": "2026-0042",
    "amountOutstanding": 125.5
  },
  "timestamp": 1735689600000,
  "traceId": "0b0f7c0e-5d3c-4c1e-9b8a-7f1e2a3b4c5d",
  "triggeredBy": null
}

Não há spanId. O webhook não precisa de estar subscrito a uma chave de evento: uma mensagem de uma automatização é sempre entregue ao endpoint escolhido, enquanto este existir e estiver ativo.

Como verificar a assinatura está em Verificar a assinatura.

Tentativas e resultadoCopiar a ligação para esta secção

O Tillor faz até 5 tentativas dentro do passo, com 1, 2, 4 e 8 segundos de espera entre elas. Uma tentativa conta como bem-sucedida com um estado 2xx. Também um destino bloqueado, por exemplo um endereço interno, conta como tentativa falhada.

• Se uma das tentativas resultar, o fluxo continua pela saída Sucesso
• Se as cinco falharem, o fluxo continua por Falhou. A mensagem é depois ainda repetida em segundo plano segundo o calendário em Comportamento de entrega e repetições. Se uma dessas tentativas posteriores resultar, isso já não volta à execução, porque esta já seguiu em frente

Se o webhook já não existir ou estiver desativado, o passo não segue por Falhou. A execução pára então com o estado Falhou.

Pedido à API para um URL próprioCopiar a ligação para esta secção

Com Pedido à API e Enviar para em URL personalizado, uma automatização envia um pedido HTTP para o seu servidor.

Uma resposta com estado 2xx continua por Sucesso, qualquer outro estado por Falhou. Se o servidor não for alcançável ou exceder o tempo limite, a execução pára com o estado Falhou.

Pedido à API do TillorCopiar a ligação para esta secção

Com Enviar para em Tillor API, a automatização chama a API da própria organização. Indica apenas um caminho, por exemplo /tasks, e o Tillor coloca-o a seguir a /api/orgs/{orgId}. A sua referência da API está em OpenAPI.

• Identidade: o pedido é executado como o utilizador Fluxo de trabalho da organização. Esse tem todas as permissões dentro dessa organização e em mais nenhuma. As alterações ficam, por isso, em nome de Fluxo de trabalho
• Sem chave necessária: o Tillor faz a chamada por si próprio, sem chave de API e sem passar pela internet
• Caminho: tem de começar com uma única /. //, .. e \ não são permitidos. Uma query string é permitida, por exemplo /tasks?terrainId=…&limit=1. As variáveis no caminho são preenchidas codificadas
• Bloqueado: os caminhos /automations e /automation-runs são rejeitados, mesmo com query string, maiúsculas, uma / final ou codificação percentual. Uma automatização não pode gerir automatizações
• Corpo: JSON, para POST, PUT e PATCH. Em GET e DELETE não é enviado
• Menu de escolha: no editor há Escolha um endpoint da API com as operações da especificação OpenAPI. As operações internas não aparecem. Se escolher uma, o Tillor preenche o método, o caminho e um corpo de exemplo
• Falhas: uma resposta 2xx continua por Sucesso. Um estado de erro, também um 404 para um caminho que não existe, segue por Falhou

A resposta nos passos seguintesCopiar a ligação para esta secção

Depois do pedido, estas variáveis estão disponíveis:

Um segundo pedido à API no mesmo fluxo substitui response. As variáveis funcionam como em Variáveis e modelos.

A estrutura de um fluxoCopiar a ligação para esta secção

Pode também criar e alterar automatizações através da API. As operações estão no OpenAPI, na etiqueta automations. Ler exige a permissão automations:read, criar e alterar automations:write (ou todas as permissões). O próprio utilizador Fluxo de trabalho nunca as pode chamar. Pode ser mais prático construir um fluxo no editor e lê-lo como exemplo.

Uma nova automatização está sempre desativada. Ativá-la através de enabled não resulta enquanto o fluxo tiver problemas em aberto, e um fluxo ativado não pode ser guardado com problemas.

A definition é composta por passos (nodes), linhas (edges) e, opcionalmente, notas (notes). No máximo 100 passos, 200 linhas e 50 notas.

{
  "nodes": [
    {
      "id": "trigger",
      "type": "trigger",
      "label": "",
      "position": { "x": 0, "y": 0 },
      "config": { "source": "event", "eventKey": "occupation:ended" }
    },
    {
      "id": "task",
      "type": "taskCreate",
      "label": "",
      "position": { "x": 0, "y": 190 },
      "config": { "title": "Controleer {occupation.terrain.name}", "priority": "HIGH" }
    }
  ],
  "edges": [
    { "id": "trigger:out:task", "source": "trigger", "target": "task", "sourceHandle": "out" }
  ],
  "notes": [
    {
      "id": "note_1",
      "text": "Maakt na elk vertrek een controletaak.",
      "position": { "x": 340, "y": 0 },
      "width": 240,
      "height": 140
    }
  ]
}

Uma nota (notes) é uma explicação no ecrã de desenho. Nunca é executada e não tem linhas. text tem no máximo 2000 carateres, width e height são em píxeis.

Uma linha tem um sourceHandle: a saída do passo de onde parte.

Cada ação, exceto webhookSend e httpRequest, ganha uma saída extra error assim que continueOnError no config estiver em true. Sem essa definição, uma ação falhada pára a execução. Com ela, o fluxo continua por error, com {error.message} e {error.step} como variáveis para os passos seguintes. A saída skipped é usada quando um passo não tinha nada a fazer, e out é então a saída normal.

Em forEach, a saída each inicia, por item, uma execução própria para os passos seguintes, e a saída done é o caminho normal de continuação do próprio fluxo.

Uma saída pode levar a vários passos. A execução continua por si própria com a primeira linha e inicia, para cada outra linha, uma execução própria com os mesmos dados, que corre em paralelo (como a saída each de forEach). As linhas que formam um ciclo são rejeitadas no editor. Um fluxo tem exatamente um trigger.

Definições por passoCopiar a ligação para esta secção

Os campos em config são os campos do editor. Os campos de texto aceitam variáveis entre chavetas.

conditions tem a forma { "match": "all" ou "any", "rules": [...] }. Cada regra é { "id", "field", "operator", "value", "values" }. operator é is, isNot, contains, greaterThan, lessThan, isOneOf, isEmpty ou isNotEmpty. values só se usa em isOneOf. Uma lista vazia de regras deixa passar tudo.

Iniciar uma automatização com um webhookCopiar a ligação para esta secção

Uma automatização com o trigger webhook arranca com um POST para o seu próprio endereço:

curl -X POST "https://tillor.eu/api/orgs/org_abc123/automation-hooks/aut_xxx/<token>?bron=website" \
  -H "Content-Type: application/json" \
  -d '{"email":"jan@voorbeeld.nl","aankomst":"2026-07-14"}'

• O endereço completo está no editor, no trigger, ou através de GET /automations/{id}/webhook-url (com automations:read). O token é o segredo; não é necessário um cabeçalho para autenticação
• O corpo JSON passa a ser a variável body, a query string query e o momento receivedAt
• Responde 200 com { "accepted": true } assim que a execução foi iniciada. Um endereço errado, substituído ou desativado devolve 404, um corpo acima de 100 KB devolve 400
• Muitas chamadas seguidas não são rejeitadas: cada chamada válida inicia uma execução. Use Ignorar repetições no trigger se a mesma chamada puder chegar duas vezes, veja Ignorar repetições

Uma automatização não pode chamar o seu próprio webhook através de um Pedido à API à API do Tillor.

Escolher uma decisão através da APICopiar a ligação para esta secção

A tarefa de um passo Pedir uma decisão tem uma ação por opção que definiu no passo. Obtenha a tarefa para ver as actions com o seu id e escolha uma com POST /tasks/{id}/actions/{actionId}/choose. Se a opção pedir uma nota, envie-a como { "note": "..." }. A escolha é definitiva: conclui a tarefa e a automatização continua pela saída dessa opção. Os colegas atribuídos (também através de um grupo) e os administradores podem escolher. Veja o OpenAPI para os detalhes.

Ler maisCopiar a ligação para esta secção

• Webhooks para a assinatura, as repetições e a lista de eventos
• HTTP API para a autenticação e o contexto da organização
• Variáveis e modelos para a explicação para utilizadores