# Gototem · API Gototem Partner (v1)

> Para sistemas parceiros abrirem chamados no help desk da Gototem, pela API ou por webhook. A chave é entregue pelo suporte da Gototem e identifica o seu sistema; não usa conta nem licença.

Endereço base: https://api.gototem.com.br. De onde vem a chave: a chave vem do suporte da Gototem.
Idioma da documentação: português do Brasil.

## Documentação

- [Contrato OpenAPI em JSON](https://developers.gototem.com.br/api-integracao/openapi.json): a fonte mais completa para um agente; rotas, parâmetros, respostas e erros
- [Contrato OpenAPI em YAML](https://developers.gototem.com.br/api-integracao/openapi.yaml): o mesmo contrato
- [Guia do desenvolvedor](https://developers.gototem.com.br/api-integracao/): passo a passo, erros e exemplos
- [Coleção do Postman](https://developers.gototem.com.br/api-integracao/postman.json): também abre no Insomnia

## Regras essenciais

- Toda chamada leva só o cabeçalho `Authorization: Bearer <chave>`; a chave começa com `gtes_` e vem do suporte da Gototem. Não envie nenhum outro cabeçalho de autenticação.
- Comece por `GET /v1/api-external-system/help-desk-ticket-options`. Todo chamado leva `external_id`, `company` (um `id` de `companies`) e `description`; envie também `priority` (sem ela vale o padrão da categoria, que pode ser alto), `category` e `support_level`, com os ids inteiros dessa lista, como número, nunca texto livre; os ids mudam entre homologação e produção.
- `nature` só aceita um `identifier` de `natures`, e valor fora da lista recusa o chamado (`invalid_nature`): na dúvida, omita o campo.
- Use um `external_id` único por atendimento: reenviar com o mesmo devolve `200` com `duplicate: true` e o chamado que já existe, nunca um chamado duplicado.
- Um `503 temporarily_unavailable` é a API desligada por um tempo: guarde o chamado e reenvie depois do `Retry-After`, com o mesmo `external_id`; nunca o descarte. Um `404` é sempre erro de endereço: corrija-o.
- `429` traz `Retry-After`, os segundos a esperar antes de repetir; não reenvie em laço.
- Leia `warnings` (escolhas trocadas pelo padrão, CNPJ ignorado, campos ignorados, solicitante cortado e, no reenvio, `description_differs`) e `applied` (o que foi de fato gravado) na resposta do chamado.
- Decida pelo `code` do erro ou do aviso, nunca pelo `detail` do erro nem pela `message` do aviso, e trate o `code` que não conhecer pelo status HTTP.

## Rotas no ar

- `GET /v1/api-external-system/help-desk-ticket-options`: O que o seu sistema pode escolher ao abrir um chamado
- `POST /v1/api-external-system/help-desk-ticket`: Abre um chamado no help desk
- `POST /v1/api-external-system/webhook/{system}`: Abre um chamado pelo webhook do seu sistema

## Rotas previstas (ainda não disponíveis)

- `POST /v1/api-external-system/lead`: Envio de lead (ainda não disponível)

Contrato de 15/10/2026 · versão 1.
Suporte: integracoes@gototem.com.br