Pular para o conteúdo principal

Reportar eventos do site

POST 
/site-events

É por aqui que um site conectado conta o que aconteceu nele — um pedido pago, um cadastro, um carrinho abandonado —, até 100 eventos por chamada. É o que o plugin do WordPress chama, e qualquer plataforma própria com a API key de um site conectado pode chamar também.

O site não precisa saber quais fluxos existem: ele reporta o evento pelo nome, e todo fluxo ativo e publicado com o gatilho de evento do site que escuta esse nome o recebe (no máximo 20 fluxos por evento, pela prioridade), assim como as execuções que estão esperando por ele. No fluxo, o que vier em data fica disponível como {{trigger.<caminho>}} — {{trigger.order.total}} —, ao lado de trigger.$event (id, name, occurred_at) e trigger.$site (id, url, name).

Nomes. <origem>.<objeto>.<acontecimento>, em minúsculas, de 2 a 4 segmentos e até 80 caracteres: wc.order.paid, wp.user.registered. As origens wp, wc, wcs, form e fcrc são as do catálogo do plugin; os eventos da sua própria integração vão em custom — custom.assinatura.renovada.

Contato. O bloco contact passa pela mesma sincronização de POST /contacts/sync, com os campos em snake_case e com os gatilhos ligados: um contato novo ou uma tag adicionada iniciam os fluxos de sempre. Sem um contato válido, nenhum fluxo começa — mas um bloco contact inválido não recusa o evento, que fica registrado com o motivo.

Resposta. 202 quer dizer registrado e enfileirado: nenhum fluxo roda dentro da requisição. Cada evento responde por si — um inválido volta em rejected, com a posição e o motivo, sem derrubar o lote; um id que o site já reportou conta em duplicates e não muda nada. A entrega é "pelo menos uma vez": reenviar é seguro. Cada evento tem até 64 KB entre data e contact.

Esta rota não responde 402: com a conta bloqueada, os eventos são aceitos e registrados sem rodar fluxos, para que o site não acumule reenvios.

Idempotência. Com o header Idempotency-Key, uma repetição da mesma chamada devolve a primeira resposta, com Idempotent-Replayed: true. A mesma chave com outro corpo é recusada com 422 idempotency_key_reused; enquanto a primeira requisição ainda roda, a repetição recebe 409 idempotency_in_progress.

Só a API key de um site conectado reporta eventos — ela vem com a permissão events:write. Uma API key comum recebe 404 site_not_found.

Request​

Responses​

Eventos registrados. O destino de cada um está em accepted, duplicates ou rejected.