Sobre a API Pública

Esta página reúne informações que não aparecem nos endpoints de referência, mas que você provavelmente vai precisar ao consumir a API, como o significado dos códigos numéricos retornados nos campos de status e prioridade.

Autenticação

Todos os endpoints exigem o header token, com a chave de acesso da sua conta. Veja os detalhes de cada parâmetro na referência de cada endpoint.

Como gerar seu token

1. Acesse seu domínio no Trílogo e vá em Configurações > Configuração do domínio.
2. Na seção Integração, clique em Gerar Token.
3. Guarde o token gerado, ele será usado no header token de todas as requisições.

Pré-requisito: a permissão de acesso à seção Integração precisa estar habilitada em Preferências de Domínio > Integração, no perfil de acesso do usuário que for gerar o token.

Erros comuns

Código	Significado
401 Unauthorized	Token ausente ou incorreto no header.
400 Bad Request	Parâmetros ou payload da requisição inválidos.
404 Not Found	Recurso solicitado não encontrado (ex.: id inválido).

Perguntas frequentes

O token de integração tem prazo de validade ou vale até ser desativado?

O token não expira por tempo. Ele permanece válido até que um usuário com permissão o remova nas configurações do sistema. Como só é possível ter um token ativo por usuário, para gerar um novo é preciso remover o atual primeiro.
Além disso, se o nosso Time de Segurança identificar um token com uso nocivo ou suspeito, podemos revogá-lo sem aviso prévio.

No histórico do ticket, o autor de uma alteração via API aparece como integração/sistema ou como o usuário que gerou o token?

Fica registrado como o usuário de sistema "Trilogo", não como o usuário que gerou o token.

Enums de referência

Alguns campos da API retornam códigos numéricos (integer) cujo significado não é autoexplicativo. Use as tabelas abaixo para traduzi-los.

Prioridade do ticket

Campo priority no retorno de GET /api/ticket/{id} (e demais endpoints de ticket).

valor	prioridade
0	Alta
1	Média
2	Baixa

Status do ticket

Campo action dentro de currentStatus (status atual) e de cada item do array status (histórico) no retorno de GET /api/ticket/{id} (e demais endpoints de ticket).

O próprio retorno já inclui actionDescription com o texto pronto — a tabela abaixo serve para quem quer trabalhar diretamente com o código numérico.

valor	status
1	Aberto
3	Arquivado
4	Cancelado
5	Executado
6	Vistoriado
7	Em Execução

Tipos de bem, predial e procedimento

Os campos assetTypeId, buildingServiceTypeId e procedureId não seguem uma lista fixa: cada empresa cadastra e mantém seus próprios tipos de bem, de serviço predial e procedimentos, então os IDs variam de cliente para cliente. O retorno da API já inclui o nome legível junto com o id (assetTypeName, buildingServiceTypeDescription, procedureFullAddress), então normalmente você não precisa resolver o id manualmente.

Caso precise da listagem completa de tipos de bem/predial/procedimento cadastrados na sua conta, entre em contato com o Time de Sucesso do Cliente ([email protected]) que acompanha sua empresa.

Boas práticas de uso

• Trate os enums pelo valor numérico, não pelo texto (actionDescription, assetTypeName etc. podem mudar de redação sem aviso), use as tabelas acima como fonte de verdade para os códigos.
• Use includeChecklist=false (padrão) quando não precisar dos dados de checklist, o retorno fica mais leve e a consulta mais rápida.
• Guarde o token da API como segredo (variável de ambiente ou cofre), nunca em código versionado, logs ou URLs.
• Trate a resposta 204 como "ticket não encontrado ou fora do escopo do usuário", não como erro de sistema, evite cair no tratamento genérico de exceção nesse caso.
• Evite consultar o mesmo ticket repetidamente em um curto intervalo; quando o caso de uso permitir, faça cache da resposta por alguns minutos.
• GET /api/ticket (listagem) exige startDate/endDate, mas não pagina resultados. Sem outros filtros, um intervalo de datas amplo pode retornar um volume muito grande de dados e deixar a consulta lenta. Sempre que possível, combine startDate/endDate com filtros adicionais (companyId, status, tags) para reduzir o payload.
• Para manter sua base sincronizada periodicamente, não busque a base inteira a cada execução. Use GET /api/ticket/changes passando startDate/endDate como a janela desde a última sincronização, esse modo retorna tickets criados OU alterados (mudança de status/histórico) no período, e não só os criados.

Suporte

Dúvidas sobre a API, sugestões ou problemas na documentação: [email protected]