> For the complete documentation index, see [llms.txt](https://docs.sprinthub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinthub.com/estrategias/meta-business/meta-ads/parametros-da-api-de-conversoes.md). # Parâmetros da API de Conversões A **API de Conversões do Meta (CAPI)** permite o envio de eventos diretamente do servidor para a Meta, garantindo maior precisão na mensuração e na otimização de campanhas, mesmo diante de limitações como bloqueio de cookies, ad blockers ou restrições de navegadores. Os **parâmetros da API de Conversões** são essenciais para que o Meta consiga usar corretamente os eventos na **veiculação de anúncios e na atribuição de resultados**. *** ### O que são os parâmetros da API de Conversões? Os parâmetros incluem **todos os dados obrigatórios do evento** e outros dados adicionais que a API de Conversões utiliza para: * Otimização da entrega de anúncios * Atribuição correta de conversões * Melhoria da qualidade dos eventos (Event Match Quality) * Melhor desempenho das campanhas Atualmente, a API de Conversões é compatível com eventos de: * 💬 **Mensagens para empresas** * 🌐 **Web** * 📱 **Aplicativos** * 🗂 **Eventos offline** *** ### Parâmetros obrigatórios conforme o tipo de evento #### Eventos de site (Web) Eventos enviados por meio da API de Conversões para **sites** exigem obrigatoriamente: * `client_user_agent` * `action_source` * `event_source_url` Esses parâmetros ajudam a melhorar a qualidade dos eventos usados na veiculação de anúncios e podem aprimorar significativamente o desempenho da campanha. *** #### Eventos que não são da Web (App, Offline, Mensagens) Para eventos que **não são da web**, é obrigatório apenas: * `action_source` 📌 **Importante:**\ Ao utilizar a API de Conversões, você concorda que o valor informado no parâmetro `action_source` seja **preciso e condizente com a origem real do evento**, conforme seu conhecimento. *** ### Parâmetros do corpo principal (Payload) | Parâmetro | Descrição | | ----------------- | -------------------------------------------------- | | `data` | Lista de eventos enviados | | `test_event_code` | Código usado para testes no Gerenciador de Eventos | *** ### Parâmetros de informações do cliente (User Data) Esses parâmetros são usados para **identificação e correspondência do usuário**. Sempre que indicado, o **hashing SHA-256 é obrigatório**. #### Dados com hashing obrigatório | Parâmetro | Descrição | | --------- | ------------------ | | `em` | E-mail | | `ph` | Número de telefone | | `fn` | Nome | | `ln` | Sobrenome | | `ge` | Gênero | | `db` | Data de nascimento | | `ct` | Cidade | | `st` | Estado | | `zp` | Código postal | | `country` | País | *** #### Dados recomendados ou sem hashing | Parâmetro | Descrição | Hash | | --------------------- | --------------------------------- | ----------- | | `external_id` | ID externo do contato | Recomendado | | `client_ip_address` | Endereço IP do cliente | ❌ | | `client_user_agent` | Agente do usuário | ❌ | | `fbc` | ID do clique | ❌ | | `fbp` | ID do navegador | ❌ | | `subscription_id` | ID da assinatura | ❌ | | `fb_login_id` | ID de login do Facebook | ❌ | | `lead_id` | ID do lead | ❌ | | `page_id` | ID da página | ❌ | | `page_scoped_user_id` | ID do usuário no escopo da página | ❌ | | `ctwa_clid` | ID do clique para WhatsApp | ❌ | | `ig_account_id` | ID da conta do Instagram | ❌ | | `ig_sid` | ID do clique do Instagram | ❌ | #### Parâmetros exclusivos para App | Parâmetro | Observação | | --------- | ---------------------------------- | | `anon_id` | Válido apenas para eventos de app | | `madid` | Identificação do anunciante mobile | *** ### Parâmetros de evento do servidor | Parâmetro | Descrição | | --------------------------------- | ------------------------ | | `event_name` | Nome do evento | | `event_time` | Timestamp do evento | | `user_data` | Dados do cliente | | `custom_data` | Dados personalizados | | `event_source_url` | URL de origem | | `opt_out` | Consentimento do usuário | | `event_id` | ID único do evento | | `action_source` | Origem do evento | | `data_processing_options` | Opções de processamento | | `data_processing_options_country` | País | | `data_processing_options_state` | Estado | | `referrer_url` | URL de referência | | `customer_segmentation` | Segmentação do cliente | *** ### Parâmetros de dados do App | Parâmetro | | ------------------------------ | | `advertiser_tracking_enabled` | | `application_tracking_enabled` | | `extinfo` | | `campaign_ids` | | `install_referrer` | | `installer_package` | | `url_schemes` | | `windows_attribution_id` | | `anon_id` | | `madid` | | `vendor_id` | 📌 **Observação:**\ Consulte a documentação oficial da **API de Conversões do Meta para eventos de app** para obter detalhes sobre a integração correta, parâmetros suportados e boas práticas.\ 🔗 *** ### Parâmetros padrão A Meta disponibiliza uma lista completa de **parâmetros padrão** que podem ser enviados nos eventos. Alguns exemplos: * `event_name` * `event_time` * `order_id` * `event_id` *** ### Original Event Data Parameters Os parâmetros originais de dados do evento incluem: * `event_name` * `event_time` * `order_id` * `event_id` Eles são fundamentais para **deduplicação** e atribuição correta quando usados junto ao Pixel. *** ## Parâmetros-padrão Esta tabela lista todos os parâmetros-padrão que os usuários podem enviar à Meta.
SiteAppOfflineDescrição
availabilityfb_availabilityavailabilityO valor deve ser available_soon, for_rent, for_sale, off_market, recently_sold ou sale_pending.
body_stylefb_body_stylebody_styleEstilo da carroçaria do veículo: CONVERTIBLE, COUPE, HATCHBACK, MINIVAN, TRUCK, SUV, SEDAN, VAN, WAGON, CROSSOVER ou OTHER.
checkin_datefb_checkin_datecheckin_dateA data em que o usuário deseja fazer check-in no fuso horário do hotel. Aceitamos datas nos formatos YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD e YYYY-MM-DDThh:mm:ssTZD.
cityfb_citycityInforme a cidade da localização da intenção do usuário.
condition_of_vehiclefb_condition_of_vehiclecondition_of_vehicleA condição do veículo.
content_idsfb_content_idscontent_idsOs números de identificação do conteúdo associado ao evento, como SKUs de produtos para itens em um evento do tipo AddToCart.
content_typefb_content_typecontent_type

Deve ser definido como product ou product_group:

  • Use product se as chaves enviadas por você representarem produtos. As chaves podem ser content_ids ou contents.
  • Use product_group se as chaves enviadas por você em content_ids representarem grupos de produtos. Os grupos de produtos são usados para diferenciar produtos idênticos que apresentam variações, como cor, material, tamanho ou estampa.
contentsfb_contentscontentsUma lista de objetos JSON que contém os IDs dos produtos associados ao evento e informações sobre os itens. Campos disponíveis: id, quantity, item_price, delivery_category.
countryfb_countrycountryInforme o país da localização da intenção do usuário.
currencyfb_currencycurrencyObrigatório para eventos de compra. A moeda do value especificado, se aplicável. O valor deve ser um código de moeda de três dígitos válido que siga a norma ISO 4217.
delivery_categoryfb_delivery_categorydelivery_category

Opcional para eventos de compra. Tipo de entrega para um evento de compra. Valores compatíveis:

  • in_store: o cliente precisa entrar na loja para obter o produto comprado.
  • curbside: o cliente dirige até uma loja e espera dentro do veículo para pegar o pedido.
  • home_delivery: a compra é entregue na casa do cliente.
departing_arrival_datefb_departing_arrival_datedeparting_arrival_dateA data e hora de chegada ao destino da viagem de ida.
departing_departure_datefb_departing_departure_datedeparting_departure_dateA data e hora de início da viagem de ida.
destination_airportfb_destination_airportdestination_airportUse o código IATA oficial do aeroporto de destino.
destination_idsfb_destination_idsdestination_idsSe você tiver um catálogo de destinos, poderá associar um ou mais destinos desse catálogo a um evento de hotel específico.
dma_codefb_dma_codedma_codeO código da Designated Marketing Area (DMA) usado para direcionar ofertas aos usuários.
drivetrainfb_drivetraindrivetrainTração do veículo: 4X2, 4X4, AWD, FWD, RWD, OTHER ou NONE.
exterior_colorfb_exterior_colorexterior_colorCor externa.
fuel_typefb_fuel_typefuel_typeTipo de combustível do veículo: DIESEL, ELECTRIC, FLEX, GASOLINE, HYBRID, PETROL, PLUGIN_HYBRID, OTHER ou NONE.
hotel_scorefb_hotel_scorehotel_scoreUm indicador que representa o valor relativo desse hotel para o anunciante em comparação a outros hotéis.
interior_colorfb_interior_colorinterior_colorA cor interna.
lead_event_sourcelead_event_sourcelead_event_sourceA fonte do evento de lead.
lease_end_datefb_lease_end_datelease_end_dateEspecificado usando o formato de data da norma ISO 8601: YYYY-MM-DD.
lease_start_datefb_lease_start_datelease_start_datePermite a recomendação de propriedades com base na disponibilidade de datas (usando available_dates_price_config no catálogo) e a melhoria da experiência do usuário (usando tags de modelo).
listing_typefb_listing_typelisting_typeO valor deve ser for_rent_by_agent, for_rent_by_owner, for_sale_by_agent, for_sale_by_owner, foreclosed, new_construction ou new_listing.
makefb_makemakeA marca ou montadora do veículo.
mileage.unitfb_mileage.unitmileage.unitA unidade da quilometragem.
mileage.valuefb_mileage.valuemileage.valueO valor da quilometragem.
modelfb_modelmodelO modelo do veículo.
neighborhoodfb_neighborhoodneighborhoodO bairro de interesse.
net_revenuenet_revenuenet_revenueO valor da margem de um evento de conversão.
num_adultsfb_num_adultsnum_adultsO número de adultos que ficarão hospedados.
num_childrenfb_num_childrennum_childrenO número de crianças que ficarão hospedadas.
num_infantsfb_num_infantsnum_infantsO número de bebês que ficarão hospedados.
num_itemsfb_num_itemsnum_itemsUse apenas com eventos InitiateCheckout. O número de itens que um usuário tenta comprar durante a finalização da compra.
order_idfb_order_idorder_idA identificação do pedido da transação como uma string.
origin_airportfb_origin_airportorigin_airportUse o código IATA oficial do aeroporto de partida.
postal_codefb_postal_codepostal_codeCódigo postal.
predicted_ltvpredicted_ltvpredicted_ltvO valor total previsto de um evento de conversão.
preferred_baths_rangefb_preferred_baths_rangepreferred_baths_rangeNúmero de banheiros selecionados em um intervalo.
preferred_beds_rangefb_preferred_beds_rangepreferred_beds_rangeNúmero de quartos selecionados em um intervalo.
preferred_neighborhoodsfb_preferred_neighborhoodspreferred_neighborhoodsOs bairros de preferência.
preferred_num_stopsfb_preferred_num_stopspreferred_num_stopsIndique o número de paradas que o usuário está procurando.
preferred_price_rangefb_preferred_price_rangepreferred_price_rangeA faixa de preço preferencial para o veículo. Mín./máx.: até 2 casas decimais.
preferred_star_ratingsfb_preferred_star_ratingspreferred_star_ratingsUma tupla de classificação de hotel por estrelas mínima e máxima que um usuário aplica na filtragem.
pricefb_pricepriceCusto e moeda do veículo. Formate o preço como o custo, seguido pelo código de moeda ISO, com um espaço entre o valor e a moeda.
product_catalog_idproduct_catalog_idproduct_catalog_idIdentificação do catálogo de produtos.
property_typefb_property_typeproperty_typeDeve ser apartment, condo, house, land, manufactured, other ou townhouse.
regionfb_regionregionEstado, distrito ou região de interesse.
returning_arrival_datefb_returning_arrival_datereturning_arrival_dateA data e hora em que a viagem de retorno é concluída.
returning_departure_datefb_returning_departure_datereturning_departure_dateA data e hora de início da viagem de retorno.
search_stringfb_search_stringsearch_stringUse apenas com eventos Search. Uma pesquisa feita por um usuário.
state_of_vehiclefb_state_of_vehiclestate_of_vehicleEstado do veículo.
suggested_destinationsfb_suggested_destinationssuggested_destinationsOs destinos sugeridos.
suggested_home_listingsfb_suggested_home_listingssuggested_home_listingsOs classificados de imóveis sugeridos.
suggested_hotelsfb_suggested_hotelssuggested_hotelsOs hotéis sugeridos.
suggested_jobsfb_suggested_jobssuggested_jobsOs empregos sugeridos.
suggested_local_service_businessesfb_suggested_local_service_businessessuggested_local_service_businessesOs serviços comerciais locais sugeridos.
suggested_location_based_itemsfb_suggested_location_based_itemssuggested_location_based_itemsOs itens baseados em localização sugeridos.
suggested_vehiclesfb_suggested_vehiclessuggested_vehiclesOs veículos sugeridos.
transmissionfb_transmissiontransmissionA transmissão do veículo: AUTOMATIC, MANUAL, OTHER ou NONE.
travel_classfb_travel_classtravel_classDeve ser economy, premium, business ou first.
travel_endfb_travel_endtravel_endA data de término da viagem.
travel_startfb_travel_starttravel_startA data de início da viagem.
trimfb_trimtrimMáximo de caracteres: 50.
user_bucketfb_user_bucketuser_bucketO grupo do usuário.
value_valueToSumvalue

Obrigatório para eventos de compra ou quaisquer eventos que utilizem otimização de valor.

Um valor numérico associado ao evento. Precisa representar um valor monetário.

vinfb_vinvinNúmero de chassi.
yearfb_yearyearO ano de lançamento do veículo no formato yyyy.
item_numberIdentificador exclusivo para distinguir eventos dentro do mesmo pedido ou transação.
ad_typeO tipo de anúncio.
fb_content

Uma lista de objetos JSON que contém o International Article Number (EAN), quando aplicável, ou outro identificador de produto ou conteúdo, assim como as quantidades e os preços dos produtos. Obrigatório: id, quantity.


Exemplo: "[{\"id\": \"1234\", \"quantity\": 2,}, {\"id\": \"5678\", \"quantity\": 1,}]".

fb_content_idInternational Article Number (EAN), quando aplicável, ou outros identificadores de conteúdo ou produto. Para vários números de identificação do produto: por exemplo, "[\"1234\",\"5678\"]".
fb_descriptionUma descrição de string.
fb_levelO nível de um jogo.
fb_max_rating_valueO limite máximo de uma escala de classificação, por exemplo, 5 em uma escala de 5 estrelas.
fb_payment_info_available1 para sim, 0 para não.
fb_registration_methodFacebook, Email, Twitter, entre outros.
fb_success1 para sim, 0 para não.
_valueToSumO valor numérico do evento individual a ser somado nos relatórios.
*** ### Conclusão Os parâmetros da API de Conversões do Meta são essenciais para garantir **eventos confiáveis, melhor correspondência de usuários e campanhas mais eficientes**. Uma configuração correta impacta diretamente na performance dos anúncios e na qualidade dos dados analisados. *** ### Referências Este artigo foi elaborado com base na documentação oficial da Meta sobre a API de Conversões. Para informações técnicas detalhadas, atualizações e exemplos avançados, consulte as fontes abaixo: * **Parâmetros da API de Conversões**\ 🔗 * **Parâmetros de dados personalizados (Custom Data)**\ 🔗 📌 **Observação:**\ A Meta pode atualizar os parâmetros, regras de validação e requisitos a qualquer momento. Recomendamos consultar a documentação oficial sempre que houver alterações na configuração da API de Conversões ou no comportamento dos eventos. ***