Pular para o conteúdo
API de admissãov1OpenAPIPara IA

Autenticação e chave

Authorization: Bearer <chave>
  • A chave alcança uma empresa e só a admissão, e tem um nome dado pelo escritório (por exemplo, "ERP da matriz").
  • A admissão feita por ela é da integração da empresa, não de uma pessoa: o histórico do colaborador no Motor diz "Admitido pela chave de API ‹nome›". A chave vale enquanto não for revogada e o escritório que a gerou atender a empresa — a saída de quem a gerou não a derruba.
  • Quem gera e revoga é o administrador do escritório que opera a empresa no Motor. A chave aparece uma vez: guarde-a num cofre de segredos. O Motor guarda só o resumo dela e um prefixo para reconhecê-la.
  • Revogada, ela deixa de valer na chamada seguinte (401 CHAVE_REVOGADA).
  • Login de usuário e token OAuth do Motor são recusados nestas rotas.

Limite de uso

60 chamadas por minuto por chave. Acima disso, 429 LIMITE_EXCEDIDO com Retry-After (em segundos). Não é limite de plano: a admissão conta como colaborador ativo, como a feita pelo Motor.

O webhook

O endereço do webhook (HTTPS, nunca rede privada) e o segredo do webhook são da integração da empresa, não de cada chave: o escritório os cadastra uma vez, e o segredo também aparece uma vez. Trocar a chave não muda nenhum dos dois.

O webhook é opcional: sem ele a chave admite normalmente, e você acompanha pela consulta (GET /v1/admissoes/{id}). Ver Avisos.

Trocar a chave sem parar

A empresa pode ter até duas chaves ativas ao mesmo tempo, justamente para isto:

  1. Peça ao escritório uma chave nova. A antiga continua valendo.
  2. Troque a chave no seu sistema. As duas funcionam durante a troca, e a consulta (GET /v1/admissoes/{id}) responde com qualquer chave ativa da empresa — inclusive para admissões enviadas pela antiga.
  3. Quando não houver nada em andamento pela chave antiga (nenhuma admissão dela fora de PROCESSADA, RECUSADA ou DESCARTADA), peça a revogação dela.

Se a chave for revogada com admissão ainda não transmitida, essa admissão não é enviada sem clique: cai na fila do escritório e sai o aviso admissao.aguardando_escritorio. Revogar existe para cortar um canal que pode ter sido comprometido, e o que entrou por ele espera uma pessoa aprovar.