| "Validacao do fluxo falhou — nada foi salvo" | id/type vazios, ids duplicados, ou lastGeneratedStepId incorreto | Leia a lista de erros do retorno e corrija; ajuste os contadores (= ultimo id gerado + 1; o stop a999 e sentinela e nao conta) |
| JSON Schema da trigger REST nao aparece na UI | Usou requestBodySchema (campo invalido) ou passou o schema como objeto JSON | O campo correto e jsonSchema com valor como string serializada (com \r\n). Exemplo: "jsonSchema": "{\r\n \"type\": \"object\"...\r\n}\r\n". Nunca use requestBodySchema. |
| Switch apos HTTP roteia errado (vai para sucesso mesmo em erro da API) | Usou INPUT_IS_NOT_NULL no body como proxy de sucesso | Use $.aN.headers.responseStatusCode com NUMBER_DOES_NOT_MATCH "200" para detectar erro; sucesso vai para o default. |
| Passo nao executa / config "some" no save | Campos no nivel errado. Regra: acao fixed (http, triggers, stop, utility.*) → campos no TOPO do step; connector catalog (.service.actions.Action) → campos em inputData. mappingAttributes fica {} nos dois | fixed: copie o stepSkeleton de list_actions. catalog: monte inputData pelo schema de get_action_struct |
| Interpolacao nao resolve (vem literal) | Sintaxe errada ${...} | Use mustache {{$.<id>}} — ex. {{$.trigger.body}}, {{$.a0}} |
save_flow_development "retornou vazio" | Sucesso NAO traz payload | Nao e erro; confirme relendo com get_flow_development |
"Method and URL are required, check your flow configuration." no step de acao (MEMORY_STORE_SET/GET, PROJECT_STORE_SET/GET, LOGGER etc.) — mesmo com actionId/coreRouteType corretos no step | Faltou coreRouteType no objeto de link dentro do array nextSteps do step anterior. O engine usa esse campo para resolver a URL do microsservico — sem ele nao roteie e lanca o erro. Causa silenciosa: get_flow_development e save/publish aceitam sem reclamar, mas a execucao falha | Em cada item de nextSteps que aponta para um .service.actions.Action, inclua "coreRouteType" com o mesmo valor do step de destino. Ex: {"id":"a0","type":".service.actions.Action","coreRouteType":"MEMORY_STORE_GET","sourceUUID":"...","targetUUID":"..."}. Vale para TODOS os acoes de catalogo. Leia um fluxo funcional com get_flow_development para confirmar o shape correto do link. |
| Acao exige credencial mas falha | authId vazio numa acao que autentica | Defina o authId correto da conta |
| Nao sei os campos de uma acao | Tentou adivinhar | NUNCA invente — pesquise via /apipass-integrations:research-action |
login_necessario no meio de uma acao | Sem token valido | Mostre a authorizeUrl ao usuario, ele autoriza, refaca a acao |
| Operacao recusada pedindo confirm | Efeito colateral sem confirm: true | Confirme com o usuario e reenvie com confirm: true |
publish_flow da HTTP 400 IER001: Cannot read properties of undefined (reading 'map') | O step de stop (.StopV2Step, ex. a999) nao tem o array responses. O save_flow_development/create_version aceitam o stop sem responses, mas a publicacao mapeia responses para montar o contrato da API | Adicione responses ao stop (ao menos a Default 200; ideal Default + Error 400). Copie o shape exato de um fluxo publicavel via get_flow_development (ver /apipass-integrations:apipass-patterns) |
run_test_flow executa OK mas {{$.trigger.body.*}} vem null (e o body de resposta do stop que dependa dele) | Modo TEST nao popula o body do trigger como um POST HTTP real — vale para QUALQUER tipo de fluxo, nao so agentes | Nao e defeito do fluxo: o caminho funciona em requisicao real. Para validar a interpolacao do trigger, publique e chame o endpoint de verdade; use run_test_flow para validar wiring/passos com valores literais ou que nao dependam do shape do body do trigger |
run_test_flow "nao faz nada" — nenhuma execucao aparece em list_flow_execution_logs | O run_test_flow roda a versao publicada no environment; sem create_version + publish_flow antes, nada executa. Alem disso a ferramenta retorna vazio (undefined), sem executionId | Cicle a cada edicao: save_flow_development → create_version → publish_flow → run_test_flow; depois consulte list_flow_execution_logs (com startDate/endDate/page) para pegar o resultado |
Em modo TEST o payload chega em $.trigger (campos no topo), nao em $.trigger.body; webhook real as vezes usa $.trigger.body | Diferenca de shape entre TEST e POST real | Coloque um NodeJS normalizador como 1o passo apos a trigger e leia tudo dele: `let t=$.trigger |
