Endpoints de API

O endpoint e a URL

Um endpoint pertence a um item e sempre roda a última versão publicada dele — não há versões de API para gerenciar. O endereço é <método> https://<seu-endereço-waiso>/exec/<id-do-projeto>/<caminho>. O id é o id público e permanente do projeto (começa com p_), não o nome, então renomear o projeto nunca quebra quem chama; o caminho padrão é o caminho da pasta e o nome do item. Um caminho errado, ou um endpoint desligado, responde 404 — igual a um projeto que não existe, para ninguém sondar nomes.

Ative um endpoint pela aba Gatilhos do item (Ativar endpoint), pelo aviso de publicação, ou na página API ligando o Status da linha (clicar numa linha inativa pergunta antes: Ativar e configurar). Um endpoint novo é POST, síncrono, protegido por token, com as entradas lidas do corpo JSON. Clicar numa linha ativa abre Configurar endpoint: Endpoint URL, HTTP Method, Execution Mode, Authentication, Parameter Passing, Limites e Active Tokens.

Sync, async e cada resposta

Um endpoint Synchronous espera a execução (até 30 segundos) e responde com o resultado. Um endpoint Asynchronous responde 202 {"runId": "…"} na hora; depois, GET /exec/<id-do-projeto>/runs/<runId> devolve o mesmo formato de uma resposta síncrona — consulte até o status deixar de ser queued ou running. Uma chamada síncrona que passa de 30 segundos responde 504 com "status": "timeout" e o runId; a execução continua e pode ser consultada do mesmo jeito.

{
  "runId": "0f9c2d4e-…",
  "status": "success",
  "flowRunId": null,
  "output": {
    "closed": true,
    "invoices": 128
  },
  "error": null,
  "errorCode": null,
  "durationMs": 412,
  "totalMs": 466
}

Consultando uma execução async

Trabalho longo fica num endpoint assíncrono. O chamador abaixo inicia uma execução e consulta a cada dois segundos. Isto roda no seu sistema — os scripts do Waiso não têm acesso à rede.

import os, time, json, urllib.request

BASE = "https://<your-waiso-address>/exec/<project-id>"
HEADERS = {"Authorization": f"Bearer {os.environ['WAISO_TOKEN']}", "Content-Type": "application/json"}

def call(path: str, args: dict) -> dict:
    req = urllib.request.Request(f"{BASE}/{path}", data=json.dumps(args).encode(), headers=HEADERS, method="POST")
    run_id = json.load(urllib.request.urlopen(req))["runId"]          # 202 {"runId": …}
    while True:
        res = json.load(urllib.request.urlopen(f"{BASE}/runs/{run_id}"))
        if res["status"] not in ("queued", "running"):
            return res
        time.sleep(2)

print(call("monthly-close", {"month": "2026-09"}))

Parâmetros

Os valores da requisição viram as entradas do item pelo nome. Com Request body (o padrão), envie um objeto JSON: {"month": "2026-09", "dryRun": true}. Com Query string, envie ?month=2026-09&dryRun=true; os valores da query chegam como texto e são entregues nos tipos declarados no script, e um corpo JSON, se também for enviado, é somado. Um valor que não vira o tipo declarado, ou um parâmetro obrigatório ausente, é recusado com 422 invalid_parameter antes de existir qualquer execução.

curl -X POST "https://<your-waiso-address>/exec/<project-id>/reports/monthly-close?month=2026-09&dryRun=true" \
  -H "Authorization: Bearer $WAISO_TOKEN"

Um flow recebe os valores como entradas do Início. Um flow com pré-processador recebe a requisição inteira, então Parameter Passing não se aplica a ele.

Tokens

1. 1
   Abra as configurações

   Na página API clique em Settings. A gaveta reúne Public Docs, Export e Tokens de API.

   Gerar token
2. 2
   Dê um nome e escolha os endpoints

   Dê um Nome do token (único no projeto), uma Validade — 1h, 1d, 7d, 30d, 1a, um valor personalizado ou Nunca — e marque os endpoints que ele pode chamar. Um token alcança só os endpoints da lista: marcar todos cobre os endpoints de hoje, e um endpoint novo exige editar o token.

3. 3
   Copie uma vez

   Clique em Generate Token. Copie o token — ele não será exibido de novo. Envie como Authorization: Bearer <token>.

Revogar token o interrompe na hora — quem chama recebe 401 token_revoked — e ele fica na lista como Revogado. Prefira um token por chamador, assim revogar um nunca quebra os outros. Um endpoint com Authentication Public não pede token; use só para dados realmente públicos.

A requisição recebida

Toda execução iniciada por um endpoint guarda a requisição que a iniciou. Abra a execução — na página Execuções ou no detalhe de um passo de flow — e Requisição recebida mostra Query, Cabeçalhos e Corpo. Copiar como cURL dá um comando que a envia de novo; Reexecutar com esta requisição inicia uma nova execução com ela na hora (Execução #… iniciada, marcada como Reexecução de #…) — sempre de forma assíncrona.

• As requisições ficam guardadas por 30 dias (A requisição expirou após 30 dias). Os corpos são guardados até 1 MB — a execução recebeu o corpo inteiro — e corpos binários não são guardados.
• Os cabeçalhos são guardados exatamente como chegaram, inclusive Authorization. Quem pode ver a execução pode lê-los.
• Uma chamada recusada pelo limite também fica guardada, sem execução.

A página API e a documentação pública

A página API lista todos os endpoints, com busca, chips Todos / Ativos / Inativos com contagens e um filtro de tipo (Scripts, Flows, Scraper). Cada linha mostra Método, Modo, Auth, Limite e o botão de Status. O painel Visão Geral da API tem quatro cartões: Endpoints (ativos, inativos, total), Uso em Hoje, 7d (padrão), 30d ou Tudo (chamadas, taxa de sucesso, tempo médio), Top endpoints por chamadas e Acesso (tokens ativos, docs públicas ou privadas). Settings → Export baixa os endpoints como JSON, uma coleção do Postman, texto simples ou comandos cURL.

Documentação pública

Todo projeto tem uma página de documentação em /api-docs/<id-do-projeto> que lista os endpoints ativos com método, URL, parâmetros, um exemplo e um formulário para testar que recebe um token Bearer. Por padrão só os membros do projeto conectados podem abri-la. Ative Settings → Public Docs → Enable public docs e qualquer pessoa com o link pode ler e testar os endpoints — ainda precisando de token para chamar um protegido.

Limites

• Um endpoint por item. Uma chamada sync espera no máximo 30 segundos.
• Chamadas por minuto (1 a 100.000) é contado por endpoint em cada minuto do relógio, somando todos os tokens. Execuções ao mesmo tempo (1 a 1.000) faz as execuções a mais esperarem, nunca falharem. Os dois vêm vazios.
• Toda chamada que inicia uma execução consome créditos como qualquer outra; uma chamada recusada (401, 404, 422 antes de rodar, 429) não consome nada.