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.


POST/external/v1/events

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 sua currency. Um evento customer.created nã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 eventoO que aconteceuPropriedades permitidas
order.placedUm pedido foi feitoorderNumber, itemCount, productIds
order.paidUm pedido foi pagoorderNumber, itemCount, productIds
order.fulfilledUm pedido foi atendidoorderNumber, itemCount, productIds
order.cancelledUm pedido foi canceladoorderNumber, itemCount, productIds
order.refundedUm pedido foi reembolsadoorderNumber, itemCount, productIds
checkout.startedUm checkout foi iniciadoitemCount, productIds
cart.abandonedUm carrinho com itens foi abandonadoitemCount, productIds
product.viewedUm produto foi visualizadoproductId
customer.createdA pessoa se tornou clienteNenhuma
  • orderNumber, productId e cada identificador em productIds têm de 1 a 64 caracteres ASCII. Comece com uma letra, dígito ou #; os demais caracteres também podem incluir . _ : / -, como #1001 ou gid://shopify/Product/2.
  • itemCount é um inteiro de 0 a 10000 e productIds conté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 email e phone.

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:

  • stored conta os novos eventos salvos e duplicates aqueles já salvos por seu id, que não são salvos novamente.
  • unmatched conta 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).
RecusacdMotivo
400UNKNOWN_EVENT_TYPEO type do evento não está entre os tipos aceitos
400PERSON_REQUIREDO evento não informa email nem phone
400INVALID_VALUEUma 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
400INVALID_PROPERTIESUma propriedade não permitida para o tipo ou com formato incorreto
400INVALID_OCCURRED_AToccurredAt está mais de cinco minutos no futuro ou mais de 3650 dias no passado
400o campo correspondente, como EVENTS[0].IDevents está ausente, vazio ou excede 100 elementos, ou um campo está ausente ou malformado
403INSUFFICIENT_SCOPEA 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 id inicia 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 productIds de um pedido, checkout ou carrinho, ou ao productId visualizado. O valor deve atingir o mínimo na moeda indicada. Um evento customer.created nã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 ShopifyEvento resultante
Um pedido feito, pago, atendido ou canceladoorder.placed, order.paid, order.fulfilled, order.cancelled
Um reembolsoorder.refunded, para quem fez o pedido, no valor reembolsado
Um checkout com e-mail ou telefonecheckout.started
Um checkout inativo há uma hora, sem pedidocart.abandoned, uma vez por checkout
Um cliente inscrito no marketing que ainda não é contatocustomer.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/redact do 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.
Esta página foi útil?