Pular para o conteúdo principal
Um evento é um fato: esta pessoa fez isto, neste momento, com estes detalhes. Envie um 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) e properties (detalhes). Opcionais: occurred_at, external_id e backfill.
  • 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.
Nada é cadastrado antes: nem o evento, nem as propriedades, nem o cliente.
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.name atualiza o nome do cliente.
  • customer.attributes grava 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 como skipped com no_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.
O header 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.
Uma resposta de sucesso é uma promessa: o evento está gravado, ligado a um cliente e pode ser lido pelo id na hora.
  • customer.matched_by diz qual identificador encontrou o cliente. Quando o evento criou o cliente, vem created: true e matched_by é omitido.
  • flows lista os flows ativos que escutam esse nome. Lista vazia significa que nenhum flow está escutando.
  • warnings aparece só quando há algo a avisar. Um aviso nunca substitui um erro.
  • duplicate: true aparece 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 trazer flows[].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 gatilho custom.<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, como tracking.carrier ou items[0].sku.
  • Uma propriedade ausente ou de outro tipo simplesmente não passa no filtro. O flow aparece como skipped com filter_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.
No painel, o mesmo gatilho fica em API de eventos → Evento personalizado, no bloco de gatilho do flow: escolha um evento já recebido ou digite o nome, e adicione filtros pelas propriedades. As receitas Pedido enviado e Pix gerado criam flows prontos para 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_variable no 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 com field: "event.<caminho>". A propriedade é comparada como o tipo do valor dado: número, booleano ou texto, e lista com includes.
As propriedades não têm esquema: uma propriedade de outro tipo não pode ser comparada, a condição é falsa e a execução registra o motivo. No editor, o bloco de condição oferece o grupo Evento, com as propriedades já recebidas e o tipo de cada uma.

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 chega payment_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_confirmed chega 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_on liga ao pedido certo. Sem ele, qualquer evento com esse nome do mesmo cliente conta. Com "match_on": "order_number", só conta o evento cujo order_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. 10293 e "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.
  • filters funcionam 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 de backfill nunca 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.
No painel, o bloco Aguardar evento fica na barra lateral do editor, e as regras de saída ficam no bloco de gatilho, em Encerrar quando chegar. A receita Pix gerado já vem com um lembrete que para quando chega o 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ó com events:write não pode validar.
  • Quando o envio criaria o cliente, a resposta traz "customer": { "would_create": true }.
  • O id do 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.
A resposta é 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.
  • results tem a mesma ordem e o mesmo tamanho de events. Cada event vem completo, como na resposta de POST /v1/events.
  • O param de cada erro começa pela posição do evento: events[2].name.
  • O 200 não significa que tudo foi aceito. Confira failed e reenvie só os itens com status: "error" depois de corrigi-los.
  • O lote inteiro só é recusado (422) quando events está 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.
O corpo é o mesmo objeto 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 event de GET /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[].sku inclui CAM-01, total maior que 100). Combina com as outras condições por E e OU. Eventos de teste nunca contam; eventos de backfill contam. “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[].path usa pontos para objetos e [] para itens de lista. type é string, number, boolean, date, list ou object.
  • 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 é utility ou marketing. 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 escopo events: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 403 com missing_scope.
  • A resposta do envio traz apenas customer.id. customer.matched_by e customer.created são omitidos.
  • Os avisos de identidade (ambiguous_identifier, identifier_conflict, identifier_mismatch) são omitidos. Só payload_mismatch aparece.
Assim, uma chave vazada não serve para descobrir se um e-mail ou telefone é cliente da loja.

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 skipped com reason: "test_mode".
  • Fica separado. O evento é gravado com livemode: false. Eventos, tipos de evento e a unicidade do external_id sã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.consent só é 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.
Um flow que não alcançaria o cliente por nenhum canal aparece como 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.