Inicia o workflow para pessoas escolhidas (gatilho manual)
POST/api/workflows/{id}/run
- Auth
- Exige token
- Quem pode:
- owner
- admin
- Chave de API:
- Não aceita chave de API
- X-CommunityId
X-CommunityIdEnvie o X-CommunityId da comunidade em que a operação acontece.
**Manda e-mail** (com `confirm`). Só owner e admin, com o workflow ligado e um gatilho `manual` no desenho (senão 422 `workflows.manualTriggerMissing`; um gatilho por workflow desde a fase 5, então `triggerNodeId` não é mais preciso). As pessoas vêm de `memberIds` ou de `audience`, o mesmo público das campanhas (`all`, `groupIds`, `tags`, `memberIds`, `exclude`); quem se descadastrou, teve bounce permanente ou denunciou fica de fora. Até 20.000 pessoas (422 `workflows.manualTooMany`). Com o envio da comunidade suspenso, a contagem e a confirmação respondem 409. Sem `confirm: true`, só conta (mensagem "N pessoas entrariam…"): `{ confirmed: false, count, sample, excluded, emailsPerDay, days }` (o limite diário de e-mails da comunidade e em quantos dias os e-mails saem). Com `confirm: true`, exige `consent: true` toda vez (`workflows.consentRequired`), recusa com o envio suspenso (409) e pede `idempotencyKey` (8 a 64 letras, dígitos, `-` e `_`; 422 `workflows.idempotencyKeyInvalid`): a mesma chave de novo devolve o mesmo início com `replayed: true`, nunca uma segunda leva. As execuções começam em lotes de 2.000 por minuto (`handled`, `started`, `done`), com as regras de reentrada; os e-mails seguem o limite diário (o excedente fica para o dia seguinte). Cada início entra na auditoria da comunidade (`WORKFLOW_MANUAL_RUN`). O MCP pede confirmação antes. Até 30 chamadas por hora por pessoa (429).
Parâmetros
| Nome | Onde | Tipo | Descrição |
|---|---|---|---|
idobrigatório | path | string (uuid) |
Headers
| Nome | Tipo | Descrição |
|---|---|---|
X-CommunityIdopcional | string (uuid) | ID da comunidade em que a operação acontece. Obrigatório na maioria dos endpoints com escopo de comunidade. |
Corpo da requisição application/json
| Nome | Tipo | Descrição |
|---|---|---|
memberIdsopcional | string (uuid)[] | |
audienceopcional | object | O público das campanhas: `{ all?, groupIds?, tags?, memberIds?, exclude?: { groupIds?, tags?, memberIds? } }`. `itemAccess` (quem tem acesso a um conteúdo) só existe em campanhas: aqui volta 422. |
confirmopcional | boolean | |
consentopcional | boolean | |
idempotencyKeyopcional | string | min 8, max 64 |
Respostas
| Código | Descrição |
|---|---|
200 | A contagem, ou o início confirmado. |
401 | Token ausente, inválido ou expirado; token de outra comunidade (o `X-CommunityId` ou o `communityId` do corpo não é o do token); token antigo ou de uma sessão encerrada (troca de senha, convite aceito). Nesses casos a mensagem pede para entrar de novo (`auth.signInAgain`). |
403 | Autenticado, mas sem permissão para esta operação. |
404 | Recurso não encontrado. |
409 | Workflow desligado (`workflows.notActive`), ou o envio da comunidade está suspenso (`data.code: SENDING_SUSPENDED`). |
422 | Sem gatilho manual, público vazio ou inválido, mais de 20.000 pessoas, falta `consent` ou `idempotencyKey`. |
429 | Mais de 30 chamadas na hora; `Retry-After` diz quando tentar de novo. |
500 | Erro interno do servidor. |
Exemplo com curl
curl -X POST "https://api.memberfy.net/api/workflows/<id>/run" \
-H "Authorization: Bearer $TOKEN" \
-H "X-CommunityId: $COMMUNITY_ID" \
-H "Content-Type: application/json" \
-d '{}'