Um cliente, três faturas, três jornadas

A Ana tem três faturas em aberto com você: $1.250, $480 e $2.100. Cada uma deveria receber os seus próprios lembretes no seu próprio tempo, e quando ela pagar a de $480, esse lembrete deveria parar enquanto os outros dois continuam.

Até agora uma jornada não conseguia fazer isso. Uma jornada rodava uma vez por pessoa: enquanto a execução da Ana para a primeira fatura estava ativa, o evento da segunda fatura era descartado. E um evento de saída como invoice_paid encerrava a única execução que ela tinha, fosse qual fosse a fatura.

Identifique a jornada pela fatura

Uma jornada disparada por um evento agora pode definir uma chave de execução: a propriedade do evento que identifica uma execução. No editor, abra o gatilho, escolha o evento (invoice_created) e escreva a propriedade em Uma execução por (invoice_id). Pela API ou MCP, é parallelRunsBy: "invoice_id" em journeys_set_trigger.

A partir daí, cada invoice_id diferente inicia a sua própria execução para a mesma pessoa, e cada execução leva os dados do seu próprio evento para as mensagens: o valor daquela fatura, o link de pagamento daquela fatura.

Envie um evento por fatura

Cada fatura é uma chamada ao endpoint de eventos:

curl -X POST "$BASE/events" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice_created",
    "externalId": "inv_1057_created",
    "personExternalId": "ana_torres",
    "properties": { "invoice_id": "1057", "amount": 480, "pay_url": "https://pay.example.com/1057" }
  }'

Envie a mesma chamada para a 1042 e a 1063, e a Ana fica em três execuções ao mesmo tempo. Alguns detalhes importam aqui:

• Use o endpoint de evento único. O registro de eventos em lote é tratado como carga histórica e não inicia jornadas.
• externalId é a chave de idempotência. Reenviar o mesmo devolve created: false em vez de um duplicado.
• A chave de execução tem que estar no primeiro nível de properties (invoice_id, não invoice.id). Um evento sem ela é recusado em vez de inscrito, então nenhum lembrete sai com o valor em branco.
• Um valor roda uma única vez. Um invoice_created reenviado ou repetido para a 1057 não consegue reiniciar uma sequência que já terminou.

Cancele só a fatura que foi paga

Adicione invoice_paid às Condições de parada da jornada (metadata.cancelOnEvents pela API). Numa jornada com chave de execução, o evento de saída é casado por essa mesma chave, então quando a Ana paga a fatura 1057 você envia:

curl -X POST "$BASE/events" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice_paid",
    "externalId": "inv_1057_paid",
    "personExternalId": "ana_torres",
    "properties": { "invoice_id": "1057" }
  }'

Essa execução termina. As da 1042 e da 1063 nem percebem. Casar pela chave tem duas consequências:

• Um evento de saída sem invoice_id não para nada. Parece um bug e é intencional: a alternativa é parar todas as execuções da pessoa.
• Você não pode desligar o casamento numa jornada com chave. matchRunKey: false é recusado na publicação, porque um pagamento cancelaria também as outras faturas da pessoa.

Proteja-se da corrida

O evento que dispara e o evento de saída são processados separadamente. Se a Ana paga segundos depois de a fatura ser criada, invoice_paid pode chegar antes de existir a execução que ele deveria parar, e a execução começa mesmo assim.

Então não dependa de o evento de saída chegar primeiro. Coloque uma etapa de Decisão antes de cada envio, conferindo se a fatura continua pendente. O evento de saída encerra a execução antes no caso comum, e a decisão cobre o caso raro.

A jornada

1. Envie a fatura, com o valor e o link do evento.
2. Espere um dia útil, não antes das 9:00. Ninguém recebe um lembrete de pagamento num domingo às 6 da manhã.
3. Decisão: continua em aberto?
4. Envie o lembrete.

Uma jornada com chave só pode enviar. Não há Aguardar resposta nem conversa com IA, porque uma resposta é da pessoa, não de uma execução: um "ok, obrigado" sobre a primeira fatura liberaria os lembretes das três. As execuções também só começam pelo evento; adicionar alguém manualmente ou por um segmento é recusado, porque não há fatura de onde tirar os dados.

As jornadas sem chave de execução funcionam exatamente como antes.

Relacione as execuções com o seu sistema

Cada execução informa o externalId do seu gatilho nos webhooks de jornadas, então quando chega journey_run.started ou journey_run.ended você consegue ligá-lo a inv_1057_created sem guardar nada nosso.

As execuções em paralelo são ativadas por organização. Se você não vê Uma execução por no gatilho, peça ao seu contato na Boom. A referência completa está na nossa documentação.