Eventos
Envie as ações dos contatos nos seus sistemas: um pedido feito ou pago, um carrinho abandonado ou um produto visualizado. Cada evento é salvo uma vez, associado ao contato pelo e-mail ou telefone no espaço de trabalho padrão da organização e exibido na linha do tempo. Esta rota exige uma chave com events:write; chaves anteriores à criação dos escopos não o possuem.
Registrar eventos
O corpo contém events, uma matriz de 1 a 100 eventos. Todos são verificados antes de salvar qualquer um: se um for recusado, toda a solicitação será recusada e nada será salvo.
- Nome
id- Tipo
- string
- Descrição
Obrigatório: seu identificador do evento, de 1 a 128 caracteres sem espaços, como
order-1001-paid. Reenviar com o mesmo identificador salva o evento uma única vez, permitindo repetir a solicitação sem duplicá-lo.
- Nome
type- Tipo
- string
- Descrição
Obrigatório: o que aconteceu, entre os tipos abaixo.
- Nome
occurredAt- Tipo
- string
- Descrição
Obrigatório: quando aconteceu, em ISO 8601, como
2026-10-20T10:00:00Z. No máximo cinco minutos no futuro e 3650 dias no passado.
- Nome
email- Tipo
- string
- Descrição
O e-mail da pessoa. Informe o e-mail, o telefone ou ambos.
- Nome
phone- Tipo
- string
- Descrição
O telefone da pessoa com código do país, como
+919812345678.
- Nome
value- Tipo
- number
- Descrição
O valor do evento, a partir de 0, com no máximo 14 dígitos inteiros e quatro casas decimais, como
1299.50. Informe também suacurrency. Um eventocustomer.creatednão possui valor.
- Nome
currency- Tipo
- string
- Descrição
A moeda do valor, com código ISO 4217, como
INR.
- Nome
properties- Tipo
- object
- Descrição
Os detalhes do tipo permitidos na tabela abaixo. Qualquer outra propriedade é recusada.
| Tipo de evento | O que aconteceu | Propriedades permitidas |
|---|---|---|
order.placed | Um pedido foi feito | orderNumber, itemCount, productIds |
order.paid | Um pedido foi pago | orderNumber, itemCount, productIds |
order.fulfilled | Um pedido foi atendido | orderNumber, itemCount, productIds |
order.cancelled | Um pedido foi cancelado | orderNumber, itemCount, productIds |
order.refunded | Um pedido foi reembolsado | orderNumber, itemCount, productIds |
checkout.started | Um checkout foi iniciado | itemCount, productIds |
cart.abandoned | Um carrinho com itens foi abandonado | itemCount, productIds |
product.viewed | Um produto foi visualizado | productId |
customer.created | A pessoa se tornou cliente | Nenhuma |
orderNumber,productIde cada identificador emproductIdstêm de 1 a 64 caracteres ASCII. Comece com uma letra, dígito ou#; os demais caracteres também podem incluir. _ : / -, como#1001ougid://shopify/Product/2.itemCounté um inteiro de 0 a 10000 eproductIdscontém de 1 a 50 identificadores.- As propriedades ocupam no máximo 4 KB e aceitam apenas os identificadores e contagens acima. Não inclua dados de cartões, endereços ou texto livre; identifique a pessoa por
emailephone.
Um pedido pago e um carrinho abandonado
curl -X POST https://api.oblic.app/external/v1/events \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"id": "order-1001-paid",
"type": "order.paid",
"occurredAt": "2026-10-20T10:00:00Z",
"email": "asha@example.org",
"value": 1299.50,
"currency": "INR",
"properties": { "orderNumber": "#1001", "itemCount": 2, "productIds": ["SKU-1", "SKU-2"] }
},
{
"id": "cart-7781",
"type": "cart.abandoned",
"occurredAt": "2026-10-20T11:30:00Z",
"phone": "+919812345678",
"properties": { "itemCount": 1, "productIds": ["SKU-3"] }
}
]
}'
Resposta
{
"status": "success",
"data": { "received": 2, "stored": 2, "duplicates": 0, "unmatched": 1 },
"errors": null
}
O status da resposta é 202:
storedconta os novos eventos salvos eduplicatesaqueles já salvos por seuid, que não são salvos novamente.unmatchedconta os eventos salvos ainda sem contato. A associação escolhe o contato mais antigo do espaço padrão com o e-mail ou, na falta dele, o telefone como número telefônico ou WhatsApp. Sem correspondência, o evento aguarda. Quando habilitado, o serviço de associação normalmente roda a cada dez minutos; acúmulos ou falhas podem atrasá-lo. O serviço exclui eventos ainda não associados 30 dias após o recebimento. Um evento nunca cria um contato.- Os eventos de uma subconta usam seu
X-Oblic-On-Behalf-Of, como suas mensagens (veja Subcontas).
| Recusa | cd | Motivo |
|---|---|---|
| 400 | UNKNOWN_EVENT_TYPE | O type do evento não está entre os tipos aceitos |
| 400 | PERSON_REQUIRED | O evento não informa email nem phone |
| 400 | INVALID_VALUE | Uma value sem currency ou uma currency sem valor, um valor negativo, com mais de 14 dígitos inteiros ou quatro casas decimais, ou um valor em customer.created |
| 400 | INVALID_PROPERTIES | Uma propriedade não permitida para o tipo ou com formato incorreto |
| 400 | INVALID_OCCURRED_AT | occurredAt está mais de cinco minutos no futuro ou mais de 3650 dias no passado |
| 400 | o campo correspondente, como EVENTS[0].ID | events está ausente, vazio ou excede 100 elementos, ou um campo está ausente ou malformado |
| 403 | INSUFFICIENT_SCOPE | A chave não possui events:write |
As recusas identificam o campo ou a posição do evento na matriz, como events[2].type, sem repetir e-mail, telefone ou valores das propriedades. Nomes de propriedades desconhecidas podem aparecer na explicação: não coloque informações sensíveis nos nomes. A validação do formato precede as verificações específicas do tipo; a resposta lista os problemas encontrados nessa etapa.
Iniciar uma jornada
Uma jornada criada em Journeys pode começar com uma ação do contato quando o mecanismo de jornadas está habilitado no espaço. No editor, escolha Faz algo na sua loja e o tipo de evento. Para restringir, acrescente os identificadores de produtos enviados pela loja e o valor mínimo exigido, com sua moeda.
- Uma vez por evento: um contato que paga dois pedidos inicia a jornada duas vezes; reenviar um evento com o mesmo
idinicia uma só vez. - Somente um evento recente: inicia jornadas se for salvo com o contato, ou associado depois, em até 24 horas de
occurredAt. Um evento mais antigo, como uma carga de pedidos históricos, aparece na linha do tempo e conta para segmentos, mas não inicia jornadas. - Produtos e valor: os produtos correspondem aos
productIdsde um pedido, checkout ou carrinho, ou aoproductIdvisualizado. O valor deve atingir o mínimo na moeda indicada. Um eventocustomer.creatednão tem nenhum desses dados e não é restringido por eles.
Do Shopify
Quando a integração Shopify e o link de instalação estiverem configurados, conecte uma loja em Configurações → Integrações → Loja Shopify: instale o aplicativo Oblic no Shopify e vincule a loja à organização. Se a integração estiver indisponível, peça ao administrador que a configure primeiro. Os pedidos se tornam os eventos acima, associados por e-mail ou telefone como aqueles enviados diretamente. Clientes inscritos no marketing por e-mail ou SMS se tornam contatos com esse consentimento.
| Origem no Shopify | Evento resultante |
|---|---|
| Um pedido feito, pago, atendido ou cancelado | order.placed, order.paid, order.fulfilled, order.cancelled |
| Um reembolso | order.refunded, para quem fez o pedido, no valor reembolsado |
| Um checkout com e-mail ou telefone | checkout.started |
| Um checkout inativo há uma hora, sem pedido | cart.abandoned, uma vez por checkout |
| Um cliente inscrito no marketing que ainda não é contato | customer.created, quando o Oblic cria o contato |
- Conteúdo do evento: valor do pedido na moeda da loja, número, quantidade de itens e produtos pelos identificadores Shopify. Nenhum outro detalhe do pedido é salvo no evento.
- Clientes inscritos: o cliente inscrito no marketing por e-mail ou SMS no Shopify é procurado entre os contatos pelas regras de associação de eventos. Se não existir, é criado no espaço padrão, com e-mail ou número como nome, e o consentimento é registrado ali. Um cliente não inscrito nunca é criado como contato.
- Cancelamento da inscrição: o cliente que cancela no Shopify deixa de receber seus e-mails ou os SMS de campanhas, automações e jornadas até se inscrever novamente ali. O Shopify nunca desfaz um cancelamento de e-mail feito no Oblic, como pelo link de uma mensagem.
- Desconexão: desconecte a loja na mesma página e desinstale o Oblic no Shopify. A desconexão mantém os eventos. A loja e seus eventos são excluídos quando a posterior solicitação
shop/redactdo Shopify é processada, não apenas pela desconexão. - Privacidade dos clientes: quando o Shopify pede a exclusão de dados de um cliente, seus eventos da loja são excluídos. Se o consentimento estava registrado em um contato, os proprietários da organização são avisados no Oblic para excluí-lo. Também são avisados quando o cliente solicita seus dados.