O que é

Uma credencial para outro sistema (planilha, ERP, automação) ler dados da assistência sem usar a senha de uma pessoa. Cada chave nasce com um nome, um papel da assistência e um limite de requisições por minuto.

Para que serve

Sistemas de terceiros — um ERP que sincroniza clientes, uma automação que puxa o status das OS — precisam de um jeito de acessar o AtmusOS sem depender do login de alguém da equipe. Uma chave de API resolve isso: gera-se uma, entrega-se para quem integra, e revoga-se quando não precisar mais — sem afetar o acesso de ninguém.

Onde encontrar

Configurações → Chaves de API, ou /api-keys. Ver e revogar chave exige só acesso à assistência; gerar ou alterar uma chave exige permissão de gerenciar configurações.

Como gerar uma chave

  1. Em Configurações → Chaves de API, clique em Nova chave.
  2. Dê um nome (é só para identificar a chave na listagem — “Integração com o ERP”, por exemplo).
  3. Escolha o papel: a chave enxerga exatamente o que aquele papel enxergaria na tela, nem mais nem menos. Só é possível escolher entre Gestor, Atendente, Financeiro ou Somente leitura — Administrador e Técnico não fazem sentido para uma credencial de máquina (o primeiro tem acesso demais; o segundo depende de uma fila de trabalho que só existe para uma pessoa).
  4. Opcionalmente, ajuste o limite de requisições por minuto — em branco, usa o padrão da assistência.
  5. Confirme. A tela mostra a chave completa uma única vez, com um botão para copiar.

Copie a chave agora. Fechada essa tela, o AtmusOS só guarda uma versão embaralhada dela — nem o próprio suporte consegue recuperar o valor original. Perdida, a saída é revogar essa chave e gerar outra.

Como usar a chave

A chave entra no cabeçalho Authorization de cada requisição, como Bearer seguido da chave:

Authorization: Bearer ak_3f9a2b1c...

Documentação para quem integra

Quem for programar a integração encontra todas as rotas, campos e erros em https://api.atmusos.com.br/public-api/docs — documentação interativa, só com as rotas que uma chave de API alcança (nenhuma tela interna do AtmusOS aparece ali). Não precisa de contato com o suporte para começar a integrar.

O que uma chave alcança

  • Só leitura, por enquanto: clientes, equipamentos e ordens de serviço.
  • Nunca mais do que o papel escolhido alcançaria na tela — mesmas permissões, mesmo isolamento entre assistências. Uma chave de uma assistência jamais enxerga dado de outra.
  • Limite de requisições por minuto, por chave — cada chave tem o próprio limite; uma chave no talo não afeta nenhuma outra.

Revogar uma chave

Na listagem, clique em Revogar. O efeito é imediato: qualquer sistema usando aquela chave para de funcionar na próxima requisição. Não tem volta — revogado é definitivo; para voltar a integrar, gera-se uma chave nova.

Regras importantes

  • A chave completa aparece uma única vez, na criação. Depois disso, só a prévia (começo e fim da chave) fica visível.
  • O papel da chave é fixo entre um conjunto restrito — Gestor, Atendente, Financeiro ou Somente leitura.
  • Revogação é imediata e sem volta.
  • O limite de requisições é por chave, não compartilhado entre chaves diferentes da mesma assistência.

Problemas comuns

A integração parou de funcionar do nada Confira se a chave não foi revogada por engano na listagem de Chaves de API.

A integração recebe erro de limite excedido A chave estourou o próprio limite de requisições por minuto. Espere um minuto ou, se for uma necessidade permanente, gere uma chave nova com um limite maior (respeitando o teto da assistência).

A integração não enxerga um cliente/equipamento/OS que existe Confira o papel da chave — o mesmo recorte de visibilidade de um usuário humano com aquele papel se aplica a ela.

Funcionalidades relacionadas