Rotas de API

Recebe: nada, sem parâmetros, sem headers de autenticação.

curl "$API_BASE/v1/ping"

Devolve:

{ "ok": true, "version": "1" }

Recebe: só o header de autenticação, sem parâmetros.

curl "$API_BASE/v1/me" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve: o e-mail, nome e o rótulo (label) da credencial usada, útil para confirmar que a credencial certa está configurada no seu sistema.

{
  "account": {
    "email": "maria@empresa.com",
    "name": "Maria Souza",
    "credId": "-Nab12cd34",
    "credLabel": "ERP Produção"
  }
}

Recebe: só o header de autenticação, sem parâmetros. É a partir daqui que você descobre os environmentID aceitos no disparo e no agendamento, os mesmos IDs que aparecem no cartão de cada ambiente na tela Ambientes.

curl "$API_BASE/v1/environments" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve: os ambientes próprios e os ambientes compartilhados pela sua empresa. online indica se o agente está conectado neste momento; offlineFlow indica se ele aceita receber execuções na fila enquanto está offline; shared marca os que pertencem a um administrador da empresa e foram publicados para todos.

{
  "environments": [
    {
      "environmentID": "3f1c9a52-77e0-4b18-9d33-8a1e2c4b6d70",
      "name": "Servidor Financeiro",
      "description": "VM do time de contas a pagar",
      "online": true, "offlineFlow": false,
      "envType": "prod", "os": "windows", "shared": false
    }
  ]
}

Recebe: só o header de autenticação, sem parâmetros. É a partir daqui que você descobre os processID disponíveis para usar nas rotas seguintes.

curl "$API_BASE/v1/processes" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve: processos próprios ("owned": true) e compartilhados com você ("owned": false, com as permissões que o dono concedeu no compartilhamento).

{
  "processes": [
    { "processID": "1042", "processName": "Importação NF-e", "agentName": "NF-Importer", "active": true, "paused": false, "owned": true },
    { "processID": "2087", "processName": "Conciliação Bancária", "agentName": "Financeiro-Bot", "active": true, "owned": false,
      "ownerName": "João Lima",
      "permissions": { "execute": true, "edit": false, "api": true, "schedule": true, "delete": false, "share": false } }
  ]
}

Repare que o item compartilhado não traz nenhum token do dono, só o nome dele (ownerName) e as permissões concedidas. Para agir sobre esse processo, use o processID normalmente: a chave do processo (gerada pelo dono) já é suficiente para a API resolver tudo.

Recebe:

curl "$API_BASE/v1/processes/1042" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "X-Process-Key: $PROCESS_KEY"

Devolve:

{
  "processID": "1042",
  "processName": "Importação NF-e",
  "description": "Lê XML de NF-e e lança no ERP",
  "agentName": "NF-Importer",
  "active": true,
  "apiEnabled": true,
  "currentVersion": 3,
  "avgHumanTime": "0:45",
  "avgOperatorCost": 12.5,
  "matrix": [
    { "name": "cnpj_fornecedor", "type": "Texto", "default": "" }
  ]
}

404 PROCESS_NOT_FOUND se o processo não existir; 403 FORBIDDEN se sua conta não for dona nem tiver compartilhamento com esse processo.

Recebe: o mesmo que GET /processes/:pid (pid na URL, Authorization e X-Process-Key nos headers).

curl "$API_BASE/v1/processes/1042/matrix" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "X-Process-Key: $PROCESS_KEY"

Devolve: os campos (name) que você vai usar depois como chave de matrix no disparo de execução ou na criação de agendamento, o mesmo nome de Variável que aparece no cadastro do processo.

{ "matrix": [ { "name": "cnpj_fornecedor", "type": "Texto", "default": "" } ] }

Recebe:

curl "$API_BASE/v1/processes/1042/executions?from=2026-06-01&to=2026-07-06&limit=20" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "X-Process-Key: $PROCESS_KEY"

Devolve:

{
  "from": "2026-06-01", "to": "2026-07-06",
  "executions": [
    { "instanceID": "a1b2c3", "processID": "1042", "processName": "Importação NF-e",
      "status": "success", "startedAt": "2026-07-06T13:02:11.000Z", "finishedAt": "2026-07-06T13:04:47.000Z",
      "durationSeconds": 156, "savingsValue": 12.5, "fteHours": 0.75 }
  ]
}

Para sistemas que empurram eventos (CRM, ERP, formulários), o caminho recomendado é o webhook do processo, sem credenciais no header e com mapeamento visual do payload. Esta rota continua sendo a opção certa quando o chamador quer controlar os valores da matrix a cada disparo, ou quando quem dispara é uma conta com quem o processo foi compartilhado.

Recebe:

A permissão de execução precisa estar concedida no compartilhamento, se o processo não for seu (ver permissions.execute em GET /processes).

Cada campo de matrix tem um type (devolvido por GET /processes/:pid/matrix), e o valor enviado é lido pelo tipo. Um valor que não cabe no tipo é recusado com INVALID_MATRIX, e a mensagem diz qual campo foi:

curl -X POST "$API_BASE/v1/processes/1042/start" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "X-Process-Key: $PROCESS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8231" \
  -d '{
    "matrix": {
      "cnpj_fornecedor": "12.345.678/0001-99",
      "numero_tentativas": 3,
      "valor_minimo": 1500.50,
      "reprocessar_pendentes": true,
      "cpfs_lista": ["111.111.111-11", "222.222.222-22", "333.333.333-33"]
    }
  }'

curl -X POST "$API_BASE/v1/processes/1042/start" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "X-Process-Key: $PROCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "environmentID": "3f1c9a52-77e0-4b18-9d33-8a1e2c4b6d70" }'

Devolve: o instanceID criado. Guarde-o para consultar o status depois em GET /instances/:iid.

{ "instanceID": "a1b2c3", "status": "started" }

{ "instanceID": "a1b2c3", "status": "queued" }

503 AGENT_OFFLINE se o ambiente estiver offline e sem fila habilitada. A mensagem traz o nome do ambiente que está fora. 400 INVALID_ENVIRONMENT se o environmentID enviado não existir ou não estiver ao alcance da sua conta, e também quando o ambiente cadastrado no próprio processo não é alcançável pelo dono dele, caso em que a mensagem traz o identificador do ambiente e a correção é no cadastro do processo, não na chamada. 403 OWNER_INACTIVE se o dono do processo estiver sem acesso ativo na plataforma: nesse caso nada é enfileirado, e a situação só muda quando o acesso dele for restabelecido. 409 PROCESS_NOT_PUBLISHED se o processo ainda não tiver versão publicada em produção: nada é enfileirado até o dono publicar a primeira versão no editor. Reenviando com o mesmo Idempotency-Key dentro de 24h, a resposta volta com "replayed": true e o instanceID da primeira chamada, em vez de criar uma nova execução.

Recebe: o instanceID devolvido pelo start, no caminho da URL. Não precisa da chave do processo, só da sua credencial de conta.

curl "$API_BASE/v1/instances/a1b2c3" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve: o formato muda conforme o estágio da execução.

{ "instanceID": "a1b2c3", "processID": "1042", "status": "running", "processName": "Importação NF-e", "userName": "ERP Produção", "startedAt": 1751818931000 }

{
  "instanceID": "a1b2c3", "processID": "1042", "processName": "Importação NF-e",
  "status": "success", "startedAt": "2026-07-06T13:02:11.000Z", "finishedAt": "2026-07-06T13:04:47.000Z",
  "durationSeconds": 156, "errorStep": null, "errorMessage": null,
  "savingsValue": 12.5, "fteHours": 0.75, "version": "3"
}

status assume queued, running, success, error, terminated, stopped ou unknown (curta janela entre sair da fila e aparecer como em execução). 404 INSTANCE_NOT_FOUND se a instância não existir ou não pertencer à sua conta.

Recebe: o instanceID no caminho, mais a ação (stop, pause ou resume) como último segmento da URL. Sem corpo.

curl -X POST "$API_BASE/v1/instances/a1b2c3/pause" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve:

{ "ok": true, "action": "pause" }

409 INSTANCE_FINISHED se a execução já terminou; 404 INSTANCE_NOT_FOUND se não existir ou não pertencer à sua conta.

Recebe: o instanceID no caminho da URL.

curl "$API_BASE/v1/instances/a1b2c3/logs" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve:

{ "logs": [ { "timestamp": "2026-09-21T10:00:01Z", "severity": "INFO", "message": "Etapa concluída: Ler XML", "stepID": "Ler XML", "userName": "ERP Produção", "version": "3", "evidence": null } ] }

São as linhas do registro oficial da execução, em ordem cronológica e até 1000 por chamada. Por isso seguem o prazo de retenção do plano, e o dado marcado como sensível aparece mascarado. O stepID é o nome da etapa, e severity vale INFO, WARNING ou ERROR. Só enxerga a instância quem a executou ou é dono do processo.

Recebe: só o header de autenticação, sem parâmetros.

curl "$API_BASE/v1/schedules" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve:

{
  "schedules": [
    { "id": "-Nab99xy", "name": "Conciliação diária", "processID": "1042", "processName": "Importação NF-e",
      "cronExpression": "0 9 * * 1-5", "active": true, "userName": "ERP Produção", "matrix": {},
      "environmentID": "3f1c9a52-77e0-4b18-9d33-8a1e2c4b6d70" }
  ]
}

Recebe:

A permissão de agendamento precisa estar concedida no compartilhamento, se o processo não for seu.

curl -X POST "$API_BASE/v1/schedules" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "X-Process-Key: $PROCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "processID": "1042",
    "name": "Conciliação diária",
    "cronExpression": "0 9 * * 1-5",
    "environmentID": "3f1c9a52-77e0-4b18-9d33-8a1e2c4b6d70",
    "matrix": {
      "numero_tentativas": 3,
      "valor_minimo": 1500.50,
      "reprocessar_pendentes": true,
      "cpfs_lista": ["111.111.111-11", "222.222.222-22", "333.333.333-33"]
    }
  }'

Devolve: o ID do agendamento criado.

{ "id": "-Nab99xy" }

Recebe: o id do agendamento no caminho, e o novo estado no corpo.

curl -X PATCH "$API_BASE/v1/schedules/-Nab99xy" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Devolve:

{ "id": "-Nab99xy", "active": false }

Erros: 402 PLAN_FEATURE_UNAVAILABLE ao enviar active: true quando o plano da empresa dona do processo não inclui agendamento de execuções. Desativar é sempre aceito: active: false continua funcionando mesmo depois de uma queda de plano, e essa é a via para desligar um agendamento que o downgrade deixou ligado.

Recebe: o id do agendamento no caminho.

curl -X DELETE "$API_BASE/v1/schedules/-Nab99xy" \
  -H "Authorization: Bearer $BM_TOKEN"

Devolve:

{ "ok": true }

Recebe:

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{ "customer": { "email": "ana@acme.com" }, "order": { "id": "PED-8812", "total": 149.90 } }'

Devolve (desenvolvimento):

{ "captured": true, "captureId": "-Nab12cd" }

Devolve (produção):

{ "instanceID": "8f3a…", "status": "started" }

Devolve (produção, origem em modo Aguardar): a conexão fica aberta até o processo responder ou o limite de espera da origem acabar (padrão 30 s, máximo 120 s). Fora desse modo, vale a resposta acima.

Nesse modo a resposta sai sempre como application/json, com o cabeçalho X-Instance-Id, e o processo não define nenhum outro header. Passou do limite de espera, não repita a chamada: a execução segue, rodando ou na fila do ambiente, e reenviar cria outra. O resultado dela se consulta por GET /v1/instances/:id, que devolve queued, running e depois o status final. Um retry com a mesma Idempotency-Key devolve o instanceID da execução original, sem o corpo da resposta.

Erros: 404 NOT_FOUND (URL não confere, sem revelar se o processo existe); 401 WEBHOOK_TOKEN_REVOKED (URL antiga após gerar uma nova); 403 WEBHOOK_DISABLED; 402 PLAN_FEATURE_UNAVAILABLE (produção, plano sem API); 409 PROCESS_NOT_PUBLISHED (produção, processo não publicado); 400 INVALID_ENVIRONMENT (produção, o ambiente cadastrado no processo não existe ou ficou fora do alcance do dono: correção é no cadastro do processo, repetir a chamada não resolve); 503 AGENT_OFFLINE; 403 OWNER_INACTIVE (dono do processo sem acesso ativo na plataforma). A execução iniciada pela produção aparece no histórico e pode ser acompanhada por GET /v1/instances/:id com as credenciais normais da API.