Versão da API: 5.0.0

Proton API

API que o código de uma automação usa durante a execução no Proton 5: saber qual componente roda agora, abrir e fechar cada passo, ler os parâmetros e o ambiente, gravar as saídas, o log e as evidências, e marcar o resultado da execução.

A Proton Cloud SDK (Python e Java) faz essas chamadas por você. Use esta referência para entender o que a SDK faz ou para integrar outra linguagem.

Autenticação

Todas as rotas exigem um token de API no cabeçalho Authorization: Bearer <token>.

• Token pessoal: criado em Meu Perfil, no Proton. O token pertence à organização ativa no momento da criação, e as chamadas valem só para ela.
• Token de usuário robô: criado pelo administrador na tela de usuários.
• Token da execução (proton_run_...): o runner atualizado o pede ao Proton para cada execução e o entrega à automação em PROTON_TOKEN. Vale só para as rotas da própria execução (as desta referência, menos as que dizem o contrário, mais o dataset e o grupo dela) e só enquanto ela roda, no máximo 24 horas. Numa rota da execução, apontar para outra execução responde 403 com {"message": "executionTokenOtherRun"}; numa rota de fora, 403 com {"message": "executionTokenRouteNotAllowed"}.

O perfil do usuário dono do token pessoal ou de robô define o que ele pode fazer. O token da execução já tem as permissões das rotas da execução:

Permissão do perfil	Rotas
Execuções: visualizar (automation.datasetRun.read)	Todas as leituras
Execuções: alterar (automation.datasetRun.update)	Abrir e fechar passo, status, saídas, log, erro e id da sessão externa

Sem a permissão, a rota responde 403 com {"message": "profileError"}. Token ausente, inválido ou vencido responde 401.

Como uma execução funciona

O runner do Proton baixa o código do repositório e inicia a automação com estas variáveis de ambiente:

Variável	Conteúdo
PROTON_HOST	Endereço da API, terminando em /api
PROTON_ID_DATASET_RUN e idDatasetRun	Id da execução
PROTON_ID_TENANT	Id da organização
PROTON_TENANT_NAME	Nome da organização
PROTON_TOKEN	Token da execução (runner atualizado)
PROTON_CORRELATION_ID	Correlation ID da execução (runner 5.0.8 em diante)

Com runner anterior, que não entrega o token da execução, a automação o lê da configuração do projeto (proton.ini ou config.properties) ou da variável PROTON_TOKEN da máquina. Nunca grave o token no repositório.

Com isso, a automação percorre os passos do dataset nesta ordem:

1. Marca a execução como Running (PUT /dataset-run/{id}/update-status).
2. Pergunta o sistema e o nome do próximo componente (component-system e component-name). Resposta vazia significa que não há mais passos.
3. Abre o passo (start-component). Só depois disso os parâmetros do passo podem ser lidos.
4. Executa o componente: lê os parâmetros (get-value), grava as saídas (set-value), escreve no log e envia as evidências.
5. Fecha o passo (end-component), que fica como Passed.
6. Volta ao item 2. Quando não há mais passos, marca a execução como Passed. Se algo falhar, marca como Failed, com o motivo da falha (reason): o passo aberto também fica Failed.

O runner só marca a execução como Failed quando o processo da automação termina com erro. Quem marca Running e Passed é a automação.

Correlation ID

Cada execução tem um Correlation ID, um UUID que a tela do Proton mostra e que o runner entrega em PROTON_CORRELATION_ID. Envie-o em toda chamada, no cabeçalho X-Correlation-Id ou em traceparent (formato W3C Trace Context, com o UUID sem hífens como trace-id): o Proton põe o id em cada linha do log do servidor e o devolve em X-Correlation-Id.

Leve o mesmo cabeçalho às chamadas que a automação faz a outros sistemas (SAP, APIs, portais). Quem achar o id num desses lugares chega na execução por GET /dataset-run/correlation/{correlationId}.

Convenções

• Datas e horas estão em UTC, no formato dd-MM-yyyy HH:mm:ss. Os marcos da execução (startedAt, finishedAt) e a hora das linhas do log (createdAt) vêm em ISO 8601.
• Os campos usam camelCase, como idDatasetRun.
• Ids de outra organização se comportam como inexistentes.

Authentication

HTTP: Bearer Auth

Token de API do Proton, no formato proton_..., criado em Meu Perfil ou para um usuário robô.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer

Contact

Atomic Solutions:

URL: https://atomicsolutions.com.br

License