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 lista traz os runtimes que quem chama alcança, com os mesmos IDs que aparecem no cartão de cada runtime na tela Meus Runtimes. O disparo e o agendamento valem pelo alcance do dono do processo: num processo compartilhado com você, o environmentID enviado precisa ser um runtime que o dono alcança (os dele e os visíveis para toda a empresa), e um runtime seu que não é visível para a empresa é recusado mesmo aparecendo nesta lista.

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

Devolve: os runtimes próprios e os runtimes compartilhados pela sua empresa. ambientes traz uma entrada por ambiente (dev, staging e prod): null quando o runtime não tem instalação naquele ambiente, ou a situação da instalação que o atende, com online (conectada neste momento) e offlineFlow (aceita execuções na fila enquanto está offline). Dois ambientes atendidos pela mesma instalação mostram a mesma situação. shared marca os runtimes de um administrador da empresa visíveis para todos.

{
  "environments": [
    {
      "environmentID": "3f1c9a52-77e0-4b18-9d33-8a1e2c4b6d70",
      "name": "Contas a Pagar",
      "description": "Lançamentos do time financeiro",
      "ambientes": {
        "dev":     { "online": true, "offlineFlow": false },
        "staging": { "online": true, "offlineFlow": false },
        "prod":    { "online": false, "offlineFlow": true }
      },
      "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. Na variável com regra de uso vêm também usage (fixed, options ou format), scope (input ou input_flow) e, nas Opções, options: cada opção com o value, que é o que se manda, e o label que a tela mostra. No Formato vem format: o preset (cpf, cnpj, cep, email, telefone, placa, numeros ou custom, com a expressão em pattern) e a ajuda em hint, quando há. A variável obrigatória vem com "required": true, inclusive a do tipo Secreto.

{ "matrix": [
  { "name": "cnpj_fornecedor", "type": "Texto", "default": "" },
  { "name": "filial", "type": "Texto", "default": "0012", "usage": "options", "scope": "input",
    "options": [ { "value": "0012", "label": "Filial Campinas" }, { "value": "0047", "label": "" } ] }
] }

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", "stage": "staging" }'

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 runtime estiver offline e sem fila habilitada. A mensagem traz o nome do runtime que está fora. 400 INVALID_ENVIRONMENT se o environmentID enviado não existir, não estiver ao alcance do dono do processo ou não tiver instalação no ambiente da execução, se a instalação desse ambiente estiver suspensa pelo plano, se stage tiver um valor fora de dev, staging e prod, e também quando o runtime cadastrado no próprio processo não é alcançável pelo dono dele, caso em que a mensagem traz o identificador do runtime 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", "stage": "prod" }
  ]
}

environmentID e stage vêm vazios ("") quando o agendamento segue o runtime ou o ambiente do processo.

Recebe:

Ao gravar um agendamento ligado, a rota confere o par runtime e ambiente que vai valer: os enviados em environmentID e stage, ou, omitidos, os do processo publicado. Com o runtime que não existe mais, sem instalação nesse par ou com a instalação suspensa pelo plano, nada é gravado e a resposta é 400 INVALID_ENVIRONMENT, com a mesma mensagem que o Router daria no disparo. Criado com "active": false, não é conferido: a conferência acontece ao religar.

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. 400 INVALID_ENVIRONMENT ao enviar active: true quando o par runtime e ambiente do agendamento (o fixado, ou o do processo publicado) não tem instalação: religar confere o par de novo, com a mesma mensagem que o Router daria no disparo, e o agendamento continua desligado. 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 }

Ao cadastrar a URL no painel da Meta, ela chama a URL com hub.mode=subscribe e um hub.challenge e só aceita se a resposta for o desafio, como texto puro. A URL do processo responde sozinha. Não dispara o processo nem grava captura.

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 runtime, 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 (o webhook do processo está desligado no editor, nas URLs DEV e PROD); 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 runtime cadastrado no processo não existe, ficou fora do alcance do dono, não tem instalação no ambiente do agente ou tem essa instalação suspensa pelo plano: correção é no cadastro do processo, repetir a chamada não resolve; quando o runtime cadastrado não existe mais, a mensagem traz o ID dele: Runtime não encontrado na conta do dono deste agente (ID). Peça ao dono para reconfigurar o runtime do agente.); 503 AGENT_OFFLINE; 403 OWNER_INACTIVE (dono do processo sem acesso ativo na plataforma); 400 BAD_REQUEST (corpo não é um JSON válido); 415 UNSUPPORTED_CHARSET (codificação fora de UTF-8 e ISO-8859-1); 413 PAYLOAD_TOO_LARGE (corpo acima de 1 MB). 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.