Convenções gerais
A API não usa prefixo/api nas rotas, e não tem versionamento hoje: não existe /v1, /v2. Respostas de erro seguem um formato padrão consistente em todos os recursos.
Autenticação
Existem dois mecanismos de autenticação, completamente separados: um para pessoas, outro para workers. Pessoas se autenticam com um par de tokens JWT. O token de acesso dura 30 minutos, vai no cabeçalhoAuthorization e carrega, entre outras informações, a identidade e o papel (administrador ou colaborador) de quem está autenticado. O token de atualização dura 7 dias e é entregue apenas como cookie protegido contra acesso por script, nunca exposto ao código do cliente; em produção esse cookie também exige conexão segura. Além da validade do token em si, cada pessoa tem um identificador de sessão conferido em toda chamada autenticada: é isso que permite que um logout revogue o acesso imediatamente em todos os lugares, mesmo que o token de acesso ainda não tenha expirado.
Workers se autenticam com uma chave própria (X-Worker-Api-Key), gerada no momento em que a máquina de uma automação é registrada e exibida uma única vez. A chave é guardada apenas como hash, nunca em texto puro, escolhido deliberadamente mais simples e rápido que o usado para senha de pessoas: uma chave de alta entropia gerada pelo sistema não precisa da mesma proteção contra tentativa e erro que uma senha escolhida por alguém precisa, e workers fazem chamadas frequentes o suficiente para que isso importe. Depois de gerada, a chave não pode ser consultada de novo. Não existe hoje um jeito de trocá-la sem desativar a automação e recriar o cadastro, então se ela for perdida ou vazar, essa é a única saída.
Automações
O recursoautomation cobre o cadastro (criar, editar, listar, detalhar), o controle de modo desenvolvimento (entrar e sair) e o registro da máquina dedicada de cada automação. Editar uma automação só é permitido enquanto ela está em modo desenvolvimento.
Jobs
O recursojob cobre a criação de uma execução, sua consulta e listagem (pessoas veem as próprias execuções; administradores veem todas), e as três rotas usadas exclusivamente por workers: reivindicar, completar e falhar. Uma execução segue um caminho linear de status, sem cancelamento e sem volta.
Outros recursos
sector é um CRUD simples para o catálogo de setores usados para classificar automações. identity cobre login, atualização de sessão, logout e o cadastro de pessoas usuárias. Nenhum dos dois expõe algo que uma integração externa normalmente precise estender além do consumo direto das rotas.