apipass-patterns

name	apipass-patterns
description	Estrutura de um fluxo da APIPASS — montagem incremental, contadores lastGeneratedStepId/lastGeneratedLoopId, leitura da estrutura, versoes e publicacao (environment).
disable-model-invocation	false

Padroes de Fluxo APIPASS

Montagem incremental

create_flow(name, projectId, confirm: true)   -> flowId
save_flow_development(id: flowId, steps: [...], lastGeneratedStepId, lastGeneratedLoopId, logEnabled, confirm: true)

Para alterar um fluxo existente: get_flow_development(flowId) -> ajuste os steps -> save_flow_development(...).

Contadores (regra critica)

• lastGeneratedStepId = id numerico do ultimo step gerado + 1 (NAO e apenas ">= o maior id"). Ex.: se o maior step gerado e a0, entao lastGeneratedStepId: 1.
• O step de fim e SENTINELA: a999 (.StopV2Step/.StopStep) usa um id fixo convencional e NAO conta para o calculo. Ignore-o ao achar o maior id gerado.
• Ao adicionar um step novo, use o valor atual de lastGeneratedStepId como id numerico do novo step e incremente o contador.
• lastGeneratedLoopId: idem para loops. >= 0.

Ler a estrutura

• get_flow_development(flowId) — os steps (use para aprender shapes e para editar).
• get_flow_info(flowId) — metadados do fluxo.
• export_flow_json(flowId) — exportacao completa em JSON.
• list_flow_versions(flowId) / get_version(versionId) — historico de versoes.

Publicacao (environment)

Publicar exige environmentId + historyId. Descubra-os primeiro:

• list_environments() — environments (ambientes) da conta.
• get_published_environments_for_flow(flowId) — onde o fluxo ja esta publicado. Depois:
• publish_flow(environmentId, historyId, confirm: true) — torna a versao ativa no environment (efeito real).
• unpublish_flow(environmentId, historyId, confirm: true) — despublica.

Pre-requisito do stop para publicar: o step de fim (.StopV2Step) precisa ter o array responses (ao menos a resposta Default 200). O save_flow_development/create_version aceitam o stop sem ele, mas publish_flow falha com HTTP 400 (reading 'map'). Shape minimo:

"responses": [
  { "description": "Default", "default": true, "responseData": { "status": "200" } },
  { "description": "Error", "responseData": { "status": "400", "contentType": "application/json" },
    "groups": [ { "rules": [ { "input": "{{$.flowExecution.status}}", "condition": "TEXT_DOES_NOT_MATCH", "expected": "OK" } ] } ] }
]

---

Documentacao OpenAPI (OAS) — fluxos com RestTrigger

Fluxos com trigger REST expõem um Swagger publico gerado automaticamente pela APIPASS. A documentacao e composta por dois campos:

1. jsonSchema na RestTrigger — documenta o body de entrada (requisicao).
2. oas em cada item de responses[] no StopV2Step — documenta cada resposta possivel (201, 400, 422, etc.).

Sempre preencha o campo oas ao criar ou editar fluxos com RestTrigger.

Shape completo de um item de responses[]

{
  "description": "Descricao da resposta",
  "default": true,
  "responseData": {
    "status": "201",
    "contentType": "application/json",
    "headers": [],
    "body": "{{$.aX.message}}"
  },
  "groups": [],
  "oas": {
    "mediaType": "application/json",
    "jsonSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"sucesso\": { \"type\": \"boolean\", \"example\": true }\n  }\n}",
    "headers": []
  }
}

• default: true + groups: [] — resposta padrao (fallback, sem condicao). Exatamente uma entrada com esse padrao.
• groups — regras de condicao que ativam aquela resposta. Vazio apenas na default.
• oas.jsonSchema — string JSON (serializada, igual ao jsonSchema da RestTrigger). Nunca objeto.

Exemplo com 3 respostas (201, 400, 422)

"responses": [
  {
    "description": "Default",
    "default": true,
    "responseData": { "status": "201", "contentType": "application/json", "headers": [], "body": "{{$.a8.message}}" },
    "groups": [],
    "oas": {
      "mediaType": "application/json",
      "jsonSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"sucesso\": { \"type\": \"boolean\", \"example\": true },\n    \"id\": { \"type\": \"string\", \"description\": \"Id do registro criado.\", \"example\": \"07kHZ000009tholYAA.\" }\n  }\n}",
      "headers": []
    }
  },
  {
    "description": "Requisicao invalida",
    "responseData": { "status": "400", "contentType": "application/json", "headers": [], "body": "{{$.a3.message}}" },
    "groups": [ { "rules": [ { "input": "{{$.a3.message}}", "condition": "INPUT_IS_NOT_NULL", "expected": "" } ] } ],
    "oas": {
      "mediaType": "application/json",
      "jsonSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"sucesso\": { \"type\": \"boolean\", \"example\": false },\n    \"mensagem\": { \"type\": \"string\", \"example\": \"Erro ao validar requisicao.\" },\n    \"erros\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } }\n  }\n}",
      "headers": []
    }
  },
  {
    "description": "Erro ao processar",
    "responseData": { "status": "422", "contentType": "application/json", "headers": [], "body": "{{$.a9.message}}" },
    "groups": [ { "rules": [ { "input": "{{$.flowExecution.status}}", "condition": "TEXT_DOES_NOT_MATCH", "expected": "OK" } ] } ],
    "oas": {
      "mediaType": "application/json",
      "jsonSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"sucesso\": { \"type\": \"boolean\", \"example\": false },\n    \"mensagem\": { \"type\": \"string\", \"example\": \"Erro ao processar.\" },\n    \"erros\": { \"type\": \"array\", \"items\": { \"type\": \"object\" } }\n  }\n}",
      "headers": []
    }
  }
]

Regra de condicao para respostas de erro: use INPUT_IS_NOT_NULL no logger de erro para respostas de validacao (400), e TEXT_DOES_NOT_MATCH "OK" no {{$.flowExecution.status}} para erros de processamento (422/500). A resposta default cobre o caminho feliz.

Teste de fluxo

• list_test_flows(flowId) — cenarios de teste existentes.
• create_test_flow(name, flowId, environmentId, payload, confirm: true) — cria um cenario.
• run_test_flow(flowId, environmentId, payload, confirm: true) — executa o fluxo com o payload no environment (efeito real: cria execucao e roda os passos). Sempre confirme com o usuario, nomeando o environment e o que sera disparado. Depois, investigue o resultado pelos logs (ver /apipass-integrations:apipass-gotchas).

Campos derivados no save (nao setar a mao)

O save_flow_development preenche/deriva automaticamente alguns campos — o builder NAO precisa enviar:

• usedSteps — dependencias entre steps, derivadas das interpolacoes {{$.<id>}} (confirma que as referencias resolveram).
• Defaults seguros: doc, timeout, mappingAttributesRootArray, httpProtocolVersion/httpTlsVersion, trigger: 0. Envie apenas os campos de intencao; releia com get_flow_development para conferir o que o engine completou. Ao comparar/diferenciar fluxos (ex. harness), normalize esses campos — senao geram falso-positivo de divergencia.

Validacao no save

O save_flow_development valida a estrutura antes de enviar. Se vier erro, leia a lista e corrija; nada e salvo ate passar.

Sucesso retorna vazio (sem payload de confirmacao) — isso NAO e falha. Confirme o resultado relendo com get_flow_development(flowId).

---

AMS — Apipass Message System (filas assincronas)

O AMS desacopla fluxos via filas: um fluxo publica uma mensagem; outro fluxo a consome assincronamente.

Padrao master/subfluxo com AMS

Fluxo master (trigger HTTP) → valida → monta payload → AMS_SEND_MESSAGE → retorna 200 ao caller
Subfluxo consumidor (trigger AMS) → processa a mensagem da fila → encerra

O master NUNCA espera o subfluxo — retorna imediatamente apos publicar na fila. O subfluxo e disparado automaticamente quando a mensagem chega.

Nome de fila — convencao obrigatoria

Use variaveis de stage para que o nome mude automaticamente entre ambientes:

{{$.stage.name}}-ams-{dominio}-{acao}
Ex.: {{$.stage.name}}-ams-inbound-demanda-atualizar-agendamento-trizy-multi
→ dev-ams-inbound-...  (stage dev)
→ prod-ams-inbound-... (stage prod)

NUNCA hardcode o nome da fila — use {{$.stage.name}}- como prefixo.

Trigger AMS (subfluxo consumidor)

{
  "id": "trigger",
  "trigger": true,
  "label": "Início",
  "image": "ams",
  "nodeSize": "small",
  "type": ".trigger.ams.TriggerAMSConsumeMessage",
  "queueName": "{{$.stage.name}}-ams-nome-da-fila",
  "concurrentConsumers": 10,
  "deleteStrategy": "IMMEDIATELY",
  "defaultVisibilityTimeout": null,
  "logEnabled": true,
  "previousSteps": [],
  "nextSteps": [{ "id": "a0", "type": "...", "sourceUUID": "integration-step-uuid-sourceEndpoint-trigger", "targetUUID": "integration-step-uuid-targetEndpoint-a0" }]
}

• concurrentConsumers: numero de consumidores paralelos (tipicamente 5–10).
• deleteStrategy: "IMMEDIATELY": remove a mensagem da fila assim que entregue. Usar "ON_SUCCESS" para retry automatico em caso de falha no processamento.

Step AMS_SEND_MESSAGE (publicar mensagem)

{
  "id": "a5",
  "label": "Publica na fila",
  "type": ".service.actions.Action",
  "actionId": "AMS_SEND_MESSAGE",
  "coreRouteType": "AMS_SEND_MESSAGE",
  "image": "https://s3.amazonaws.com/flow-manager-api-prd/actions/logo/ams.png",
  "additionalConfiguration": true,
  "authProvider": "",
  "logEnabled": true,
  "failOnError": true,
  "inputData": {
    "queueName": "{{$.stage.name}}-ams-nome-da-fila",
    "queueType": "STANDARD",
    "message": "{{$.a4.body}}"
  },
  "nextSteps": [{ "id": "a999", "type": ".StopV2Step", "sourceUUID": "integration-step-uuid-sourceEndpoint-a5", "targetUUID": "integration-step-uuid-targetEndpoint-a999" }]
}

• queueType: sempre "STANDARD".
• message: o payload serializado. Use "{{$.aN.body}}" para enviar o output de um step NodeJS inteiro, ou monte um NodeJS antes para formatar o payload exato.
• failOnError: true — se a fila nao existir ou a publicacao falhar, o fluxo master deve falhar (nao silenciar).

Acesso ao payload no subfluxo consumidor

A mensagem chega no trigger do subfluxo como body:

// No subfluxo consumidor:
const { campo } = $.trigger.body;
// Ex.: $.trigger.body.trizy.numeroCarga

---

AOS — Apipass Object Store (persistencia MongoDB)

O AOS e o banco de dados nativo da APIPASS, baseado em MongoDB. Permite persistir, buscar e atualizar dados diretamente nos fluxos sem infra externa.

Autorizacao AOS

O AOS usa um authProvider proprio. Descubra o authId com list_authorizations (filtre por provider APIPASS_OBJECT_STORE):

{
  "authProvider": "APIPASS_OBJECT_STORE",
  "authId": "UUID-da-autorizacao-aos"
}

Convencao de banco/colecao

• database: use {{$.stage.name}} para separar dados por ambiente (dev/prod).
• collection: nome semantico da entidade, ex.: "shipping_settings", "pedidos", "clientes".

AOS_FIND_ONE_BY_QUERY (buscar um documento)

{
  "id": "a2",
  "label": "Buscar registro",
  "type": ".service.actions.Action",
  "actionId": "AOS_FIND_ONE_BY_QUERY",
  "coreRouteType": "MONGODB_FIND_ONE_BY_QUERY",
  "authorization": "APIPASS_OBJECT_STORE",
  "image": "https://s3.amazonaws.com/flow-manager-api-prd/actions/logo/aos.png",
  "additionalConfiguration": true,
  "authProvider": "APIPASS_OBJECT_STORE",
  "authId": "UUID-da-autorizacao-aos",
  "failOnError": false,
  "inputData": {
    "database": "{{$.stage.name}}",
    "collection": "minha_colecao",
    "filter": "{\"_id\": \"{{$.trigger.queryParams.instance_id}}\"}"
  }
}

Output: $.aN.body.document — o documento encontrado (null se nao existir).

AOS_UPDATE (atualizar documento)

{
  "id": "a3",
  "label": "Atualizar registro",
  "type": ".service.actions.Action",
  "actionId": "AOS_UPDATE",
  "coreRouteType": "MONGODB_UPDATE",
  "authorization": "APIPASS_OBJECT_STORE",
  "image": "https://s3.amazonaws.com/flow-manager-api-prd/actions/logo/aos.png",
  "additionalConfiguration": true,
  "authProvider": "APIPASS_OBJECT_STORE",
  "authId": "UUID-da-autorizacao-aos",
  "failOnError": false,
  "inputData": {
    "database": "{{$.stage.name}}",
    "collection": "minha_colecao",
    "filter": "{\"_id\": \"{{$.trigger.queryParams.instance_id}}\"}",
    "upsert": false,
    "updateMany": false,
    "query": "{{$.aN.body.queryMongoDB}}"
  }
}

• query: operador MongoDB, ex.: { "$set": { campo: valor } }. Monte em um NodeJS antes e passe via "{{$.aN.body.queryMongoDB}}".
• upsert: true — cria o documento se nao existir.
• Output: $.aN.body.document.matchedCount, modifiedCount, upsertedId.

AOS_INSERT (inserir documento)

{
  "actionId": "AOS_INSERT",
  "coreRouteType": "MONGODB_INSERT",
  "inputData": {
    "database": "{{$.stage.name}}",
    "collection": "minha_colecao",
    "document": "{{$.aN.body.documentoParaInserir}}"
  }
}

• document: JSON do documento a inserir. Inclua _id customizado se quiser controle do ID (ex.: instance_id).

AOS_DELETE (remover documento)

{
  "actionId": "AOS_DELETE",
  "coreRouteType": "MONGODB_DELETE",
  "inputData": {
    "database": "{{$.stage.name}}",
    "collection": "minha_colecao",
    "filter": "{\"_id\": \"{{$.trigger.body.id}}\"}"
  }
}

Padrao CRUD com AOS (GET/POST/PATCH em um unico fluxo)

O fluxo 9d7844bf (shipping-settings) mostra o padrao de um endpoint REST que roteia pelo metodo HTTP:

Trigger REST (GET/POST/PATCH) → Valida campos → Switch por metodo
  GET  → AOS_FIND_ONE_BY_QUERY → Monta resposta → Stop
  POST → Monta documento       → AOS_INSERT     → Stop
  PATCH→ Monta query $set      → AOS_UPDATE     → re-busca → Stop

Campos _id geralmente sao o identificador do caller (instance_id, instance_id do WIX, etc.), nao o ObjectId do Mongo.

NodeJS para montar query MongoDB ($set)

const moment = require("moment");
const updated_at = moment().subtract(3, "hours").format("YYYY-MM-DDTHH:mm:ss[Z]");

const queryMongoDB = {
  "$set": {
    "campo1": $.trigger.body?.data?.campo1,
    "updated_at": updated_at
  }
};

$export(null, { queryMongoDB });

---

Regra critica — nextSteps para steps de acao (.service.actions.Action)

Quando um nextSteps aponta para um step cujo type e .service.actions.Action (MEMORY_STORE, PROJECT_STORE, LOGGER, AMS_SEND_MESSAGE, AOS_*, etc.), o objeto de link deve incluir coreRouteType com o mesmo valor do step de destino. Sem esse campo o engine nao consegue resolver a URL do microsservico e a execucao falha com "Method and URL are required, check your flow configuration." — mesmo que o step de destino esteja configurado corretamente.

Shape correto:

"nextSteps": [
  {
    "id": "a0",
    "type": ".service.actions.Action",
    "sourceUUID": "integration-step-uuid-sourceEndpoint-trigger",
    "targetUUID": "integration-step-uuid-targetEndpoint-a0",
    "coreRouteType": "MEMORY_STORE_SET"
  }
]

save_flow_development e publish_flow aceitam o specflow sem esse campo sem reclamar — o erro so aparece em execucao. Para confirmar o shape correto, leia um fluxo funcional existente com get_flow_development.