> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Rastrear eventos personalizados > Defina eventos de negócios e envie atividades de clientes para a YCloud. ## O que é Eventos Personalizados representam atividades do seu aplicativo, site, loja ou sistema de backend. Defina o esquema do evento uma única vez e, em seguida, envie ocorrências que podem ser utilizadas pelos fluxos de trabalho de clientes da YCloud. ## Antes de começar * Escolha um nome estável para o evento que não mude com o texto de exibição. * Identifique o contato associado a cada evento. * Defina as propriedades do evento e seus tipos de dados. * Decida qual timestamp do sistema representa quando a atividade ocorreu. ## Como funciona 1. Crie uma definição de evento. 2. Adicione ou atualize definições de propriedades conforme o esquema evolui. 3. Envie ocorrências de eventos usando exatamente o nome da definição. 4. Associe cada ocorrência a um ID de contato, número de telefone ou nome de usuário da Meta. 5. Monitore eventos rejeitados e incompatibilidades de esquema. Definições de eventos são contratos. Alterar um rótulo ou descrição é mais seguro do que alterar o significado de um nome ou propriedade existente. ## Requisição ### Criar uma definição de evento `POST /event/definitions` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/definitions \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "order_completed", "label": "Order completed", "description": "A customer completed an order.", "objectType": "CONTACT", "properties": [ { "name": "order_value", "label": "Order value", "type": "NUMBER" } ] }' ``` ### Escolher um identificador de contato Para um evento definido com `objectType: CONTACT`, forneça um destes identificadores: | Campo | Como a YCloud identifica o contato | | - | - | | `objectId` | Usa o ID numérico de um contato existente em sua conta. Se o contato não existir, a requisição falha. | | `contactPhoneNumber` | Busca um número de telefone no formato E.164 em sua conta e cria um contato caso não haja correspondência. | | `contactUsername` | Corresponde ao nome de usuário da Meta salvo de um contato existente em sua conta. Se não houver correspondência, a requisição falha sem criar um contato. | Apenas um identificador é usado para cada evento. Se você fornecer múltiplos identificadores, um `objectId` numérico tem precedência, seguido por um `contactPhoneNumber` não vazio e, depois, `contactUsername`. Se um ID de contato numérico não for encontrado, a YCloud rejeita a requisição sem tentar o número de telefone ou o nome de usuário. Use o nome de usuário da Meta salvo no contato, sem o `@` inicial. `contactUsername` é um campo de requisição de nível superior, separado de `properties`. Não é necessário adicioná-lo às definições de propriedades do evento. ### Enviar um evento por número de telefone `POST /event/events` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/events \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "eventName": "order_completed", "occurTime": "2026-07-16T12:00:00.000Z", "contactPhoneNumber": "+16315551111", "properties": { "order_value": 99.9 } }' ``` ### Enviar um evento por nome de usuário Se você souber o nome de usuário da Meta do contato, poderá enviar o mesmo evento sem um número de telefone ou ID de contato. Neste exemplo, `customer_demo` já deve estar salvo em um contato na sua conta. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/events \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "eventName": "order_completed", "occurTime": "2026-07-16T12:00:00.000Z", "contactUsername": "customer_demo", "properties": { "order_value": 99.9 } }' ``` ## Resposta A criação de uma definição retorna a definição salva. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "order_completed", "label": "Order completed", "objectType": "CONTACT", "properties": [ { "name": "order_value", "label": "Order value", "type": "NUMBER" } ] } ``` Uma ocorrência de evento aceita com sucesso retorna HTTP `200` com um objeto JSON vazio. ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK Content-Type: application/json {} ``` ## Evolução do esquema * Adicione novas propriedades opcionais sempre que possível. * Não reutilize o nome de uma propriedade existente para um significado diferente. * Valide os tipos antes de enviar eventos. * Mantenha os nomes de eventos e de propriedades estáveis entre ambientes. * Crie versões para o nome do evento quando uma alteração semântica significativa for inevitável. ## Limites e solução de problemas * A definição do evento deve existir antes que uma ocorrência seja enviada. * Os nomes e valores das propriedades devem corresponder à definição. * Use RFC 3339 para `occurTime`. * Certifique-se de que o identificador de contato corresponda ao cliente desejado em sua conta. * Para `contactUsername`, verifique se o contato já existe e se o nome de usuário corresponde ao valor salvo sem o `@` inicial. * Omita identificadores que você não deseja que a YCloud use. Um número de telefone fornecido tem precedência sobre um nome de usuário. * Uma resposta `200` confirma o aceite, não que uma automação posterior foi concluída. Inspecione os esquemas de definição e propriedades. Inspecione o contrato de requisição da ocorrência. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.