Receber dados de outro sistema

O caminho contrário do webhook: o seu sistema chama um endereço da TAI, e uma automação de fluxo ou um fluxo automatizado decide o que fazer — abrir um card, atualizar o card de um pedido, avisar alguém, fazer algo na plataforma. Não precisa de token de usuário: o endereço já identifica a empresa.

Há dois lugares para criar o endereço:

Onde	Para quê
No fluxo (quadro), aba Automações › Receber de outro sistema	Abrir ou atualizar cards desse fluxo. Quem gere o fluxo cria o endereço
Processos › Central de Automações, aba Webhooks	Disparar um fluxo automatizado (fluxograma)

Endereço de um fluxo

1. Na configuração do fluxo, aba Automações, seção Receber de outro sistema, clique em Novo endereço. Dê um nome, marque Exigir assinatura se quiser e, se já tiver, cole um exemplo do JSON que o seu sistema envia.
2. Criar automação, na linha do endereço, abre a automação já com o evento e o endereço escolhidos.
   • Abrir um card neste fluxo: preencha os campos do card com o que chega ({{evento.corpo.cliente.nome}} aparece como Recebido: cliente.nome).
   • Agir nos cards deste fluxo que forem do mesmo assunto: diga qual campo do card corresponde a qual campo recebido (ex.: o campo Número do pedido = corpo.pedido). As ações rodam em cada card em aberto que corresponder — até 50 —, por exemplo, mover para Entregue.
3. Só as chamadas a esse endereço disparam a automação. Passe o endereço (e o segredo) a quem cuida do seu sistema.

Endereço da empresa (fluxo automatizado)

1. Em Processos › Central de Automações, aba Webhooks, seção Que outros sistemas chamam, clique em Novo endereço e dê um nome (“Pedidos da loja”).
2. Para mais segurança, marque Exigir assinatura e guarde o segredo.
3. Copiar endereço — ele tem a forma https://api.taitecnologia.com/public/webhook/entrada/<token>.
4. Crie um fluxo automatizado (Processos › Fluxos › Novo processo › Fluxo automatizado) que começa pelo bloco Quando outro sistema chamar e escolha o endereço em Endereço de entrada. Em Só quando, filtre pelo que chegou ({{gatilho.corpo.tipo}} igual a pedido); nos passos seguintes, os dados recebidos aparecem em Inserir informação. Publique o fluxo.

Chamar

curl -X POST "https://api.taitecnologia.com/public/webhook/entrada/$TOKEN_ENTRADA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-88213" \
  -d '{"pedido": 88213, "cliente": {"nome": "Mercado Bom Preço", "cnpj": "12345678000190"}, "valor": 1890.5}'

{
  "recebido": true,
  "id": "pedido-88213",
  "consultar": "https://api.taitecnologia.com/public/webhook/entrada/<token>/recebidos/pedido-88213"
}

Resposta	Significado
202	Recebido; as automações rodam em seguida
400	Corpo maior que 64 KB, ou assinatura ausente, malformada, vencida ou inválida
404	Endereço inexistente ou desligado
429	Mais de 60 chamadas por minuto neste endereço

• O corpo deve ser JSON. Um corpo que não é JSON chega ao fluxo como {"texto": "<corpo>"}.
• Idempotency-Key (até 120 caracteres): a mesma chave no mesmo endereço não dispara o fluxo de novo. Use o id do registro no seu sistema. Sem ela, cada chamada é um evento novo.
• No fluxo, os dados chegam em gatilho.corpo (o JSON enviado).
• Chamadas que chegam enquanto o fluxo roda esperam na fila e rodam uma de cada vez — nenhuma se perde.

Consultar o que a chamada fez

A chamada responde na hora e as automações rodam em seguida. Para saber o resultado — e guardar o número do card aberto no seu sistema —, faça GET no endereço de consultar:

curl "https://api.taitecnologia.com/public/webhook/entrada/$TOKEN_ENTRADA/recebidos/pedido-88213"

{
  "id": "pedido-88213",
  "status": "PROCESSADO",
  "recebidoEm": "2026-10-26 14:02:11",
  "cards": [{ "cardId": 4120, "pipeId": 87, "acao": "ABERTO", "automacaoId": 311, "status": "SUCCESS" }],
  "fluxos": []
}

status	Significado
NA_FILA	Recebido; as automações ainda não terminaram. Consulte de novo em alguns segundos
PROCESSADO	Tudo o que a chamada disparou rodou
FALHOU	Alguma automação ou fluxo falhou (veja o status de cada item)
IGNORADO	Recebido, mas nenhuma automação ou fluxo ligado escuta este endereço (ou as condições não casaram)
NAO_ENCONTRADO	O id está errado, a chamada tem mais de 90 dias, ou nada na empresa escuta endereços de entrada

• cards[].acao: ABERTO (a automação abriu o card) ou ATUALIZADO (agiu num card que já existia).
• fluxos[]: as execuções de fluxo automatizado, com execucaoId e status.
• A consulta devolve só ids e situação — nenhum dado do card. Com Exigir assinatura, assine a consulta como a chamada, com o corpo vazio (<t>.).

Assinar a chamada

Com Exigir assinatura, envie X-Tai-Assinatura: t=<segundos>,v1=<hmac> — o mesmo formato dos webhooks da TAI: HMAC-SHA256 em hexadecimal de <t>.<corpo>, com o segredo do endereço. Assinaturas com mais de 5 minutos são recusadas.

T=$(date +%s)
CORPO='{"pedido":88213}'
SIG=$(printf '%s.%s' "$T" "$CORPO" | openssl dgst -sha256 -hmac "$SEGREDO_ENTRADA" -hex | sed 's/^.* //')
curl -X POST "https://api.taitecnologia.com/public/webhook/entrada/$TOKEN_ENTRADA" \
  -H "Content-Type: application/json" -H "X-Tai-Assinatura: t=$T,v1=$SIG" -d "$CORPO"

Cuidado

O token do endereço é uma credencial: quem o tem dispara as automações. Guarde-o como senha. Trocar endereço gera um token novo e desativa o antigo na hora.