API#

Ao atualizar integrações para a versão 5.9.4, consulte as mudanças na API v1: algumas rotas antigas foram removidas, os esquemas de requisição ficaram mais rigorosos e as tarefas agora são lidas por uma fila. Confira o método, o caminho e os campos de cada requisição no Swagger da versão instalada do Sherpa Orchestrator.

A seção API contém três páginas:

1. Swagger — documentação interativa de requisições, parâmetros e respostas. Também está disponível em /api/docs/swagger no servidor da sua instalação.
2. ReDoc — outra visualização da mesma API, útil para ler esquemas e campos obrigatórios.
3. Key — tabela de tokens de API. Cada token tem nome, funções atribuídas e prazo de validade. Vários tokens podem ser usados ao mesmo tempo.

Criar um token de API#

Criar um token exige Create na linha API. Consultar a lista exige Read, alterar parâmetros exige Update e excluir exige Delete nessa linha. O token recebe as permissões das Funções selecionadas.

Para preparar um token de integração, abra Key em API e clique em "New". Os nomes correspondem à interface inglesa; a captura mostra a interface russa.

Campos obrigatórios:

• "Name" — finalidade do token;
• "Roles" — ações permitidas. Selecione pelo menos uma Função existente.

Validade:

• "Unlimited" — remove o limite de validade;
• "Expiration date" — data e hora de vencimento quando Unlimited está desmarcado.

Exemplo: informe Работа с Действиями em "Name" para uma integração de teste com Ações e selecione a Função my actions (read, write). Desmarque "Unlimited" e informe 21.10.2026 09:00 em "Expiration date". Clique em "Create" para emitir o token com essas permissões e validade.

Depois da criação, copie o valor do token ou o cabeçalho Authorization pronto na janela. O valor aparece uma única vez: guarde-o em um gerenciador seguro de segredos antes de fechar a janela. Use o cabeçalho exibido pelo Orquestrador ao chamar a API e confira os requisitos de cada rota no Swagger. Não coloque o token em URLs, logs ou arquivos desprotegidos.

A tabela permite consultar validade e funções, alterar parâmetros ou excluir um token desnecessário com as permissões correspondentes. O valor secreto de um token existente não pode ser recuperado pela tabela. A autenticação de Robô por GUID nas rotas que a aceitam é um mecanismo separado. Um GUID não é um token de API.

Autenticação Basic da API legada#

As rotas legadas protegidas /api/* que aceitam esse método permitem usar login e senha de uma Conta ou de um Usuário com autenticação local ou LDAP. O LDAP exige um serviço de diretório configurado e acessível. A conta deve estar ativa; a autenticação por senha não substitui o OAuth para contas desse tipo.

As permissões do Usuário vêm das Funções atribuídas. O acesso como Conta utiliza as permissões da Conta. A autenticação não cria uma nova sessão da interface gráfica. É necessário verificar a rota e suas permissões no Swagger da versão instalada; não se deve presumir que esse método se aplica a /api/v1/*.

Exemplo de leitura da lista de Robôs por HTTPS:

curl --user 'integration_user' 'https://orchestrator.example.com/api/robot/read'

É necessário substituir o endereço e o login. O curl solicita a senha de forma interativa. A senha não deve ser incluída na linha de comando e a verificação TLS não deve ser desativada.

A autenticação bem-sucedida por chave API ou GUID de Robô tem prioridade sobre Basic. Para obter um resultado previsível, não se devem misturar métodos na mesma solicitação.

Se o acesso for negado, é necessário verificar credenciais, tipo e estado ativo da conta e permissões da rota. Se o LDAP estiver indisponível, será retornado 503 com Directory service unavailable; deve-se verificar o diretório e a conexão, em vez de alterar a senha.

Validação de valores ao gravar Tarefas pela API legada#

Criar e atualizar Tarefas exige permissão para a operação correspondente. Os formatos das solicitações devem ser conferidos no Swagger da versão instalada.

As seguintes restrições se aplicam a POST /api/task/create, POST /api/task/createFromList e PUT /api/task/update:

• parent_task — UUID da Tarefa pai. Um valor vazio é salvo como NULL.
• priority — inteiro de 0 a 3.
• status — inteiro de 0 a 6.
• retries — inteiro não negativo.

Os métodos legados também usam nomes como ParentTask. Um valor incorreto em uma solicitação individual de criação ou atualização retorna 400 com o campo errors. Em createFromList, o erro corresponde ao item afetado, portanto o resultado de cada item deve ser verificado.

O valor incorreto deve ser corrigido no Robô ou na integração antes de repetir a solicitação. Por exemplo, ParentTask: "string" deve ser substituído pelo UUID de uma Tarefa pai existente ou um valor vazio.

Ao atualizar o banco, valores inválidos de parent_task, incluindo strings vazias, são substituídos por NULL. A migração não restaura os valores anteriores na reversão. Valores inválidos de priority, status e retries não são corrigidos automaticamente. O administrador determina os valores corretos.

Consultar a lista de Robôs#

A consulta de Robôs exige as permissões da Função correspondente. Use o cabeçalho de autorização indicado no Swagger da versão instalada.

As solicitações GET /api/v1/robots e GET /api/robot/read retornam uma lista de Robôs sem o campo machine_password. A ausência desse campo na lista não significa que a senha do Robô foi excluída. Se uma integração precisar dos parâmetros de conexão de um Robô específico, use seu guid para consultar esse Robô: GET /api/v1/robots/{guid} ou GET /api/robot/read/{guid}. As verificações de permissões existentes para essas solicitações permanecem em vigor.

Antes de atualizar, verifique se a integração não obtém a senha da lista. A edição do Robô e o visualizador VNC integrado consultam registros individuais; não é necessário inserir novamente as senhas salvas após a atualização. Não registre respostas que contenham credenciais.

Reatribuição de uma Licença Autopilot#

A reatribuição preserva o Usuário existente e utiliza o CInfo anterior para ativar a nova chave. São necessárias permissões de alteração de Licenças e acesso ao Usuário da mesma Conta. A Licença Autopilot original deve estar ativa; a nova chave deve ser do mesmo tipo, estar importada nessa Conta, disponível e ainda não ativada.

A operação está disponível pela API v1. O método, os campos e a autenticação devem ser verificados no Swagger da versão instalada.

1. É necessário identificar os GUIDs da Conta, do Usuário e da Licença atual.
2. Deve-se enviar POST /api/v1/accounts/{account_guid}/users/{user_guid}/autopilot_licenses/{license_guid}/reassignments com replacement_license_key e mode definido como automatic ou manual. A chave contém 38 letras e dígitos e deve ser diferente da atual.
3. No modo automatic, o servidor tenta ativar a nova chave. No modo manual, utiliza-se a troca habitual de solicitações e respostas por XLSX. Criar a operação não confirma a ativação: é necessário verificar status e, em caso de erro, error_code e error_message.
4. Após a ativação bem-sucedida, é necessário redefinir manualmente a chave anterior no servidor de licenciamento, excluí-la do Orchestrator e importá-la novamente antes de reutilizá-la.

Até concluir a liberação e limpeza da chave anterior, a nova Licença vinculada não pode ser excluída, redefinida ou reatribuída novamente. O aviso para liberar a chave anterior não significa falha na ativação da nova.

O cancelamento está disponível quando can_cancel=true: antes do envio da solicitação de ativação ou após uma falha definitiva de ativação. Utiliza-se DELETE na mesma rota acrescentando /{reassignment_guid}. Não está disponível enquanto se aguarda a resposta (awaiting_response) nem após a conclusão da operação. Em caso de 409, é necessário verificar o estado da operação; em caso de 422, a chave e o corpo da solicitação.

Filtrar Licenças pela API#

Na API, filters[license_key][equal] define uma correspondência exata e filters[license_key][not_contains] exclui chaves que contenham o valor. Após remover os espaços iniciais e finais, o valor não deve ultrapassar 128 caracteres. Campos desconhecidos e operadores não compatíveis retornam HTTP 422.