POST e a Bevits grava o evento, liga-o a um cliente e inicia os flows
que escutam esse nome.
- URL:
POST https://api.bevits.com/v1/events - Formato:
name(o que aconteceu),customer(com quem) eproperties(detalhes). Opcionais:occurred_at,external_idebackfill. - Como liga ao cliente: envie os identificadores que tiver (
external_id,tax_id,email,phone). O primeiro que casar, nessa ordem, decide. Se nenhum casar, o cliente é criado. A resposta diz qual cliente foi e por qual identificador.
A chave precisa do escopo
write ou events:write. Veja
Chave só de envio.Envio completo
Campos desconhecidos são recusados com
unknown_field, em vez de ignorados.
Um customerId no lugar de customer.id falha na primeira chamada.
O nome é estrito para que Order Shipped, order shipped e order_shipped
não virem três eventos diferentes. Um nome inválido já falha na primeira
chamada e sugere o correto:
Como o evento liga ao cliente
A regra: os identificadores são testados nesta ordem,id, external_id,
tax_id, email, phone, e o primeiro que pertencer a um cliente ativo
decide. Se nenhum pertencer, o cliente é criado com tudo que foi enviado.
external_id e tax_id são identificadores fortes: identificam uma
pessoa. email e phone são fracos: podem ser compartilhados ou trocar de
dono. Cada identificador pertence a um único cliente, e é isso que torna o
resultado previsível.
Um evento nunca funde dois clientes. Quando algo não bate, a API mantém o que
já existia e avisa em warnings:
Cada aviso traz
code, message e param (por exemplo customer.email).
Dados do cliente na mesma chamada
customer.nameatualiza o nome do cliente.customer.attributesgrava atributos do cliente. Só as chaves enviadas mudam. Os valores podem ser texto (até 256 caracteres), número ou booleano, e as chaves têm até 64 caracteres.- Um atributo que ainda não existe é criado com o tipo inferido do valor: texto, número, booleano ou data (texto em ISO 8601).
- Um valor que não cabe no tipo de um atributo existente recusa o evento com
attribute_type_mismatch. Nada é gravado. - Um cliente só com
external_id, sem e-mail nem telefone, é válido. O evento é gravado, e um flow que não consegue alcançá-lo por nenhum canal aparece comoskippedcomno_contact_channel.
Repetir com segurança
external_id é o ID do fato no seu sistema, como ship_10293. Ele é único por
nome de evento durante 90 dias. Reenviar o mesmo name e external_id
nesse período responde 200 com o evento original e duplicate: true.
- Nada acontece de novo. O reenvio não dispara flows e não toca no cliente: atributos e identificadores não são reaplicados.
- Corpo diferente no reenvio. O primeiro envio continua valendo, e a
resposta traz o aviso
payload_mismatch. Não é um upsert. - Sem
external_id. Cada chamada é um evento novo. A API nunca deduplica por conta própria.
Idempotency-Key também é aceito nos envios (POST /v1/events e
POST /v1/events/bulk). Durante 24 horas, repetir a mesma chave com o mesmo
corpo devolve a resposta guardada, com o header Idempotent-Replayed: true. A
mesma chave com outro corpo responde 409 conflict.
Use os dois: external_id protege o fato, Idempotency-Key protege a
requisição. No lote, o Idempotency-Key é o que impede um timeout de duplicar
os itens sem external_id.
Propriedades e limites
properties é um objeto JSON livre e é todo seu: não há chave reservada. Os
valores podem ser texto, número, booleano, data (texto em ISO 8601), lista e
objeto. Não existe esquema a cadastrar. O tipo de cada propriedade é inferido
dos eventos recebidos e aparece em Tipos de evento.
O que não cabe é recusado com 422 e um error.code. Nada é truncado.
O limite de nomes existe para pegar cedo o erro de colocar dado no nome, como
order_10293_shipped. O nome diz o que aconteceu; IDs e valores vão em
properties. Tipos de evento arquivados não contam no limite, e um evento com
nome arquivado é recusado com event_type_archived.
Tempo
occurred_at diz quando o fato aconteceu. Sem ele, vale o momento do
recebimento.
Use
backfill: true para importar histórico. A regra das 72 horas protege
contra uma fila reprocessada despejar mensagens antigas nos seus clientes.
O que a resposta diz
201 Created quando o evento é novo. 200 OK com o evento original quando o
external_id já existia.
id na hora.
customer.matched_bydiz qual identificador encontrou o cliente. Quando o evento criou o cliente, vemcreated: trueematched_byé omitido.flowslista os flows ativos que escutam esse nome. Lista vazia significa que nenhum flow está escutando.warningsaparece só quando há algo a avisar. Um aviso nunca substitui um erro.duplicate: trueaparece quando a chamada devolveu um evento que já existia.
flows[].status e flows[].reason
Para saber o que aconteceu com um flow
queued,
consulte o evento.
Avisos de um flow
Um flow iniciado pode trazerflows[].warnings: o que ele não conseguiu fazer e
você pode corrigir no envio. O campo só aparece quando há algo a avisar.
Avisos
Disparar um flow com o evento
Um flow escuta um evento personalizado pelo gatilhocustom.<nome_do_evento>.
Crie o flow por POST /v1/flows com platform: "custom" e o nome do evento em
event:
trigger.filtersé opcional e aceita até 10 filtros. O flow só inicia quando todos casam com as propriedades do evento.propertyé o caminho da propriedade, comotracking.carrierouitems[0].sku.- Uma propriedade ausente ou de outro tipo simplesmente não passa no filtro. O
flow aparece como
skippedcomfilter_not_matched. - As mensagens usam as propriedades do evento como variáveis, e
os blocos de condição as comparam com
field: "event.<caminho>"(condições). - O flow é criado como rascunho. Ele só recebe eventos depois de ativado
(
POST /v1/flows/{flow_id}/activate). - O flow pode ser criado antes de o primeiro evento com esse nome chegar.
order_shipped e pix_generated.
Variáveis
As mensagens do flow (e-mail, SMS e WhatsApp) leem as propriedades do evento como variáveis:- Uma variável sem valor e sem texto alternativo faz a mensagem ser pulada, em
qualquer canal (e-mail, SMS e WhatsApp), para o cliente nunca receber a
variável como foi escrita. O evento registra
missing_variableno flow (avisos de um flow). Nos templates oficiais do WhatsApp, use uma variável dinâmica para dar um texto alternativo. - Uma lista ou um objeto inteiro é escrito como JSON. No e-mail, o bloco de
itens do pedido mostra
items[]quando os itens seguem o formato do catálogo (name,quantity,price_in_cents,image_url,url). - No editor, as propriedades já recebidas aparecem no grupo Evento do seletor de variáveis.
Condições
Um bloco de condição compara uma propriedade do evento comfield: "event.<caminho>". A propriedade é comparada como o tipo do valor dado:
número, booleano ou texto, e lista com includes.
Aguardar e encerrar por evento
Um flow também pode escutar eventos do mesmo cliente enquanto está em execução. São dois usos do mesmo mecanismo:- Aguardar evento: um bloco que pausa a execução até o evento chegar, com um
tempo máximo de até 90 dias. Tem duas saídas: chegou (
if_arrived) e tempo esgotado (if_timed_out). - Encerrar quando chegar: no gatilho, eventos que encerram a execução assim
que chegam (
trigger.exit_on, até 5). Ex.: a cobrança de um Pix termina quando chegapayment_confirmed.
- Um evento que chega antes também conta. Tudo o que o flow escuta é
registrado quando a execução começa. Se o
payment_confirmedchega antes de a execução alcançar o bloco de espera (ou antes até de o flow começar), o bloco segue na hora pela saída chegou, e uma regra de saída encerra a execução antes do primeiro envio. match_onliga ao pedido certo. Sem ele, qualquer evento com esse nome do mesmo cliente conta. Com"match_on": "order_number", só conta o evento cujoorder_numberé igual ao do evento que iniciou o flow, para um cliente com dois pedidos abertos não ter os dois encerrados por um pagamento.10293e"10293"são o mesmo valor. Só vale em flows iniciados por evento personalizado; se o evento inicial não tiver a propriedade, nada casa.filtersfuncionam como os do gatilho: só conta o evento que passa em todos.- Encerrar é cancelar. A execução é cancelada e nenhum envio seguinte sai: todo envio confere o cancelamento antes de sair.
- Eventos de teste (
bvt_test_) e debackfillnunca contam: um não acontece de verdade, o outro é histórico importado. - O bloco de espera conta o tempo máximo a partir de quando a execução chega nele.
- Os blocos seguintes leem o evento recebido como
{{events.<nome>.<caminho>}}, por exemplo{{events.payment_confirmed.payment_method}}. Se o tempo esgotar, essas variáveis não têm valor: use um texto alternativo ({{events.payment_confirmed.payment_method | default: "Pix"}}). - Flows do Instagram não aguardam nem encerram por evento.
payment_confirmed do mesmo order_number.
Validar sem gravar
POST /v1/events/validate recebe o mesmo corpo e devolve o que
POST /v1/events devolveria, sem gravar nada e sem alterar clientes. Use
durante o desenvolvimento para ver qual cliente casaria, quais flows seriam
enfileirados e quais avisos surgiriam.
- Exige o escopo
read. Uma chave só comevents:writenão pode validar. - Quando o envio criaria o cliente, a resposta traz
"customer": { "would_create": true }. - O
iddo evento devolvido é provisório: não existe um evento para consultar depois. - Os erros são os mesmos do envio.
Envio em lote
POST /v1/events/bulk aceita até 100 eventos e 1 MB por chamada. Cada item tem
o mesmo formato de POST /v1/events.
200 com um resultado por evento:
- Não é atômico. Cada evento vale por si. Um evento inválido falha sozinho e os outros seguem.
resultstem a mesma ordem e o mesmo tamanho deevents. Cadaeventvem completo, como na resposta dePOST /v1/events.- O
paramde cada erro começa pela posição do evento:events[2].name. - O
200não significa que tudo foi aceito. Confirafailede reenvie só os itens comstatus: "error"depois de corrigi-los. - O lote inteiro só é recusado (
422) quandoeventsestá vazio, tem mais de 100 itens ou passa de 1 MB (batch_too_large). - Ordem: os eventos são gravados na ordem enviada. A ordem em que os flows de eventos diferentes executam não é garantida.
Ler um evento
GET /v1/events/{event_id} devolve o evento, o cliente a que foi ligado e o
que aconteceu com cada flow. Funciona logo depois do envio.
event do envio. Nele, cada flow que estava queued
passa a started ou a skipped com o motivo.
No painel, Configurações → Eventos mostra os eventos recebidos ao vivo, com
o cliente encontrado e o resultado de cada flow, e permite enviar um evento de
teste. É lá também que um tipo de evento ganha rótulo e natureza, ou é
arquivado.
Um evento pode ser lido pelo ID durante os 13 meses de histórico, com
properties e o resultado de cada flow. Depois disso, a rota responde 404.
Listar eventos
GET /v1/events lista os eventos da loja, do recebido mais recentemente ao
mais antigo. GET /v1/customers/{customer_id}/events é a linha do tempo de um
cliente, incluindo os eventos de clientes que foram fundidos a ele.
- Cada item é o mesmo objeto
eventdeGET /v1/events/{event_id}. - Um evento aparece na listagem assim que é aceito, sem esperar.
- A listagem cobre os 13 meses de histórico. Uma chave de teste lista os eventos de teste; uma chave de produção, os de produção.
- O histórico vive em um armazenamento analítico. Se ele estiver indisponível,
as listagens respondem
503;GET /v1/events/{event_id}continua respondendo para eventos recentes.
No painel
- Configurações → Eventos → Chamadas recusadas mostra, por 7 dias, cada
chamada que a API recusou: o erro, o campo, o
request_id, a chave usada e o corpo exatamente como foi enviado. Num lote, cada evento recusado aparece com o próprio corpo. Depois de 7 dias, o registro é apagado. - A aba Eventos do cliente, no CRM, mostra a linha do tempo dele. Proprietários e administradores podem apagar ali o histórico de eventos de um cliente (LGPD): as propriedades saem da Bevits na hora e o histórico é removido em até um dia. O cliente continua no CRM.
- Segmentos por evento. No filtro de clientes, a condição Evento
personalizado seleciona quem fez um evento ao menos, no máximo ou
exatamente N vezes, ou nunca, em todo o histórico, nos últimos N dias ou entre
duas datas, com até 5 filtros por propriedade (
items[].skuincluiCAM-01,totalmaior que 100). Combina com as outras condições por E e OU. Eventos de teste nunca contam; eventos debackfillcontam. “Nunca” vale dentro dos 13 meses de histórico.
Tipos de evento
GET /v1/event-types lista os nomes de evento que a loja já enviou, com as
propriedades inferidas dos eventos recebidos.
properties[].pathusa pontos para objetos e[]para itens de lista.typeéstring,number,boolean,date,listouobject.- As propriedades são uma ajuda, não uma restrição: um evento com outro formato continua sendo aceito. Elas aparecem pouco depois de o evento ser recebido.
natureéutilityoumarketing. Os nomes do catálogo de eventos recomendados já nascem com a natureza do catálogo; os outros nascem sem esse campo.- A lista vem inteira, sem paginação. Tipos arquivados só aparecem com
?include_archived=true.
Chave só de envio
O escopoevents:write pode existir sozinho em uma chave. É a chave indicada
para o backend que só alimenta eventos: ela envia, e não consegue ler a base de
clientes.
Com uma chave só de envio:
- Qualquer outra rota responde
403commissing_scope. - A resposta do envio traz apenas
customer.id.customer.matched_byecustomer.createdsão omitidos. - Os avisos de identidade (
ambiguous_identifier,identifier_conflict,identifier_mismatch) são omitidos. Sópayload_mismatchaparece.
Limites de requisição
As rotas de envio têm um limite próprio, por segundo, separado do limite geral de 600 requisições por minuto.
As respostas trazem
X-RateLimit-Limit, X-RateLimit-Remaining e
X-RateLimit-Reset. Ao receber 429, aguarde os segundos indicados em
Retry-After. As rotas de leitura (GET /v1/events, GET /v1/events/{event_id},
GET /v1/customers/{customer_id}/events e GET /v1/event-types) usam o limite
geral.
Modo de teste
Com uma chave de teste (bvt_test_…), o evento passa por toda a validação e
resolução, mas não muda nada em produção:
- Nunca cria nem altera clientes. A resposta devolve o cliente que casaria,
ou
"customer": { "would_create": true }quando o envio criaria um. - Nunca envia mensagem. Os flows aparecem como
skippedcomreason: "test_mode". - Fica separado. O evento é gravado com
livemode: false. Eventos, tipos de evento e a unicidade doexternal_idsão separados entre teste e produção, e cada chave só lê os eventos do seu modo. Nomes vistos só em teste não contam no limite de 500.
Consentimento na criação do cliente
- Um evento nunca altera o opt-in ou o opt-out de um cliente que já existe.
- Um cliente criado por um evento nasce sem opt-in de marketing, a menos
que a chamada traga
customer.consent. customer.consentsó é lido quando o evento cria o cliente.
consent.whatsapp vale para WhatsApp e SMS. consent.email vale para e-mail.
Quem recebe as mensagens do flow
O que um flow pode enviar depende da natureza do evento que o iniciou e do consentimento do cliente em cada canal:- Utilidade é sobre algo que o cliente fez, como o rastreio de um pedido ou o código de um Pix. Por isso alcança quem não aceitou marketing.
- No WhatsApp oficial, o template também precisa ser de utilidade. Uma mensagem só conta como utilidade quando o evento é de utilidade e a Meta aprovou o template na categoria de utilidade. Um template de marketing segue a regra de marketing, mesmo num flow iniciado por um evento de utilidade.
- Eventos sem natureza seguem a regra de marketing. A natureza de cada tipo de evento pode ser alterada em Configurações → Eventos.
- E-mail e WhatsApp são independentes.
consent: { "email": true, "whatsapp": false }recebe e-mails de marketing e só WhatsApp e SMS de utilidade. Quem pediu para sair de todas as mensagens não recebe e-mail.
skipped
com no_consent.
Referência de erros
Todo erro segue o envelope da API. Nos eventos,error.code nomeia o motivo,
error.param traz o caminho completo do campo (customer.email,
events[3].name) e error.suggestion, quando existe, traz um valor que seria
aceito. Um evento recusado não grava nada e não toca em nenhum cliente.
Outros erros de validação, como um e-mail mal formado ou um
occurred_at sem
offset, respondem 422 validation_error com param e sem code. Os demais
erros seguem os fundamentos:
Próximos passos
Eventos recomendados
Nomes e propriedades sugeridos para os eventos mais comuns de e-commerce.
Autenticação
Crie uma chave só de envio com o escopo
events:write.