Abrir chamado de outro sistema

O monitoramento detecta um servidor fora do ar, o e-commerce recebe uma reclamação de entrega, o ERP registra uma não conformidade. Em vez de alguém copiar isso para o service desk, o próprio sistema abre o chamado na TAI — na fila certa, com prioridade, tipo, tags e campos preenchidos — e a equipe atende pela caixa de entrada como qualquer outro.

Quando usar	Um sistema seu precisa criar trabalho para a equipe de atendimento
Porta	REST · e-mail (alternativa) · Agente (MCP)
Você vai precisar	módulo ATENDIMENTO; permissão ATENDIMENTO; JWT de um usuário de integração

Como funciona

seu sistema ──► GET  /atendimento/fila/opcoes        (uma vez: ids das filas)
            ──► GET  /atendimento/campo/todos        (uma vez: identificadores dos campos)
            ──► GET  /atendimento/chamado/page?tag=… (já existe chamado aberto para isto?)
            ──► POST /atendimento/chamado            (abre: guarda id e numero)
            ──► POST /atendimento/chamado/{id}/nota-interna | /resolver   (acompanha)

Passo a passo

1. Descubra as filas e os campos personalizados. Faça isso uma vez e guarde no seu sistema.

   curl -s https://api.taitecnologia.com/atendimento/fila/opcoes \
     -H "Authorization: Bearer $TAI_TOKEN"
   
   curl -s https://api.taitecnologia.com/atendimento/campo/todos \
     -H "Authorization: Bearer $TAI_TOKEN"

   Das filas, guarde o id (a que tem padrao: true recebe o chamado quando você não informa fila). Dos campos, guarde o identificador, o tipo (TEXTO, NUMERO, DATA, LISTA, SIM_NAO), as opcoes das listas e quais são obrigatorio.

2. Confira se o chamado já existe. Uma tag com a chave do seu sistema evita abrir dois chamados para o mesmo alerta. Sem status, a lista traz só os chamados em aberto.

   curl -s "https://api.taitecnologia.com/atendimento/chamado/page?tag=alerta-db01-disco&size=1" \
     -H "Authorization: Bearer $TAI_TOKEN"

   Se content vier com um chamado, registre a novidade nele (passo 4) em vez de abrir outro.

3. Abra o chamado.

   curl -s -X POST https://api.taitecnologia.com/atendimento/chamado \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "assunto": "Disco acima de 90% em db01",
       "corpoHtml": "<p>O volume /data do servidor db01 chegou a 93% às 14:05.</p>",
       "solicitanteEmail": "monitoramento@suaempresa.com.br",
       "solicitanteNome": "Monitoramento",
       "filaId": 4,
       "prioridade": "ALTA",
       "tipo": "INCIDENTE",
       "tags": ["monitoramento", "alerta-db01-disco"],
       "campos": { "servidor": "db01", "uso_disco": 93 }
     }'

   O solicitante pode ser informado de três formas: solicitanteEmail + solicitanteNome (o contato é criado se ainda não existe), solicitanteId (um contato existente) ou colaboradorId (help desk interno: o pedido é de um colaborador).

   A resposta é o chamado, com status NOVO. Guarde:

   Campo	Para quê
   id	Chave para as próximas chamadas (/atendimento/chamado/{id}/…)
   numero	O protocolo que a equipe e o cliente enxergam
   fila, atendente	Onde o chamado caiu e quem recebeu, se a fila distribui sozinha
   prazoPrimeiraResposta, prazoResolucao	Prazos calculados pela política de SLA da fila

4. Acompanhe o chamado. Uma novidade do seu sistema vira nota interna — só a equipe vê:

   curl -s -X POST https://api.taitecnologia.com/atendimento/chamado/5531/nota-interna \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "corpoHtml": "<p>Uso subiu para 97% às 14:20.</p>" }'

   Quando o problema se resolve na origem, o seu sistema pode resolver o chamado:

   curl -s -X POST https://api.taitecnologia.com/atendimento/chamado/5531/resolver \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "observacao": "Normalizado: uso em 61%." }'

5. Anexe arquivos, se precisar. Suba o arquivo (multipart, parte arquivo) e ligue-o a uma nota ou resposta pelo id devolvido:

   curl -s -X POST https://api.taitecnologia.com/atendimento/chamado/5531/anexo \
     -H "Authorization: Bearer $TAI_TOKEN" \
     -F "arquivo=@grafico-disco.png"
   # → { "id": 912, ... }   depois: nota-interna com "anexoIds": [912]

Ajustar o chamado depois de aberto

Cada propriedade tem a sua rota, todas POST em /atendimento/chamado/{id}/…:

Rota	Corpo	O que faz
/fila	{"filaId": 7}	Move para outra fila (recalcula o SLA)
/prioridade	{"prioridade": "URGENTE"}	Muda a prioridade (recalcula o SLA)
/tipo	{"tipo": "PROBLEMA"}	Muda o tipo
/tags	{"tags": ["…"]}	Define as tags — a lista enviada passa a valer
/campos	{"campos": {"servidor": "db02"}}	Preenche campos personalizados; valor nulo apaga
/atribuir	{"atendenteId": 88}	Atribui a um atendente; nulo tira o atendente

Alternativa: abrir por e-mail

Se o sistema de origem só sabe mandar e-mail, use um canal de e-mail do Atendimento (Atendimento → Configurações → Canais, aba E-mail): cada e-mail que chega ao endereço do canal vira um chamado na fila de destino do canal, com o remetente como solicitante. O endereço completo do canal está em GET /atendimento/canal-email/{id}/endereco.

Cuidado

O canal de e-mail ignora mensagens automáticas: e-mails com o cabeçalho Auto-Submitted (diferente de no), Precedence: bulk, list, junk ou auto_reply, ou X-Auto-Response-Suppress com OOF, AutoReply ou All. Muitas ferramentas de alerta mandam esses cabeçalhos — nesse caso, use a API. E-mail não traz fila, prioridade nem campos: para isso, a API também é o caminho.

Automatize

• Roteie por regra. Quando o seu sistema não informa filaId, as regras de roteamento (Atendimento → Configurações → Filas) escolhem a fila pelo assunto, pelo corpo, pelo e-mail ou domínio do solicitante, pela organização ou pelo canal — e podem definir a prioridade. Pela API, POST /atendimento/regra-roteamento cria a regra e POST /atendimento/regra-roteamento/testar diz qual regra rotearia um chamado de exemplo, sem abrir nada (permissão ATENDIMENTO_PARAMETRIZAR):

  { "nome": "Alertas de disco", "campo": "ASSUNTO", "operador": "CONTEM",
    "valores": "disco, storage", "filaId": 4, "prioridade": "ALTA", "ativa": true }

• Aja depois de aberto. Um gatilho com o evento Chamado criado e uma condição (por exemplo, tag igual a monitoramento) pode mover o chamado de fila, atribuir, mudar prioridade e avisar alguém por e-mail. Configure em Atendimento → Configurações → Gatilhos.

• Feche o que parou. Automações por tempo agem sobre chamados num status há mais de N horas — por exemplo, fechar os resolvidos há quatro dias.

• Avise o seu sistema. Para saber quando a equipe resolveu o chamado que o seu sistema abriu, assine Um chamado é resolvido (CHAMADO_RESOLVIDO) num webhook: o evento traz o chamadoId, que é o id guardado no passo 3. Os outros eventos do chamado — atualizado, prazo estourado, avaliado — e o passo a passo estão em Levar os chamados para o seu sistema.

• Sem token de usuário? Se o sistema de origem só sabe fazer um POST para um endereço fixo, crie um endereço de entrada e um fluxo automatizado que começa por Quando outro sistema chamar e segue para o bloco Fazer algo na plataforma, abrindo o chamado com os dados recebidos (gatilho.corpo, em Inserir informação).

Pelo seu agente de IA

“Abra um chamado na fila Infraestrutura para monitoramento@suaempresa.com.br: disco acima de 90% no db01, prioridade alta.”

É uma escrita: o agente precisa de credencial com escopo de escrita, e o seu cliente de IA pede a sua aprovação antes de abrir. Consultas como “quantos chamados de monitoramento estão abertos?” são leitura e não pedem nada. Veja Escrita e segurança.

Cuidados

• Não há chave de idempotência. Repetir o POST abre outro chamado. Use uma tag com a chave do seu sistema e consulte antes (passo 2). Tags são gravadas em minúsculas, com até 60 caracteres, e o filtro tag compara o valor exato.
• Assunto é obrigatório. Sem ele, 400 — “Informe o assunto do chamado.”
• Campos personalizados são validados: obrigatório vazio, número que não é número, data fora de AAAA-MM-DD, valor de lista fora das opções e sim/não fora de true, false, sim, não, 1 ou 0 respondem 400 com o nome do campo. Identificador que não existe é ignorado, sem erro.
• O solicitante recebe as respostas. A abertura não manda e-mail, mas toda resposta pública da equipe vai para o e-mail do solicitante. Para alertas, use um endereço técnico (monitoramento@…) ou registre o andamento como nota interna.
• Solicitante bloqueado não abre chamado: 400.
• Sem filaId, a primeira regra de roteamento que casar escolhe a fila; sem regra, o chamado cai na fila padrão. Sem prioridade, fica a da regra ou NORMAL.
• Respostas e notas em HTML com links passam pelo firewall nas rotas /atendimento/; nas demais, veja Limites de uso.