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_agentaction_sourceevent_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)
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
em
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
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
anon_id
Válido apenas para eventos de app
madid
Identificação do anunciante mobile
Parâmetros de evento do servidor
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
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. 🔗 https://developers.facebook.com/docs/marketing-api/conversions-api/app-events
Parâmetros padrão
A Meta disponibiliza uma lista completa de parâmetros padrão que podem ser enviados nos eventos. Alguns exemplos:
event_nameevent_timeorder_idevent_id
Original Event Data Parameters
Os parâmetros originais de dados do evento incluem:
event_nameevent_timeorder_idevent_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.
availability
fb_availability
availability
O valor deve ser available_soon, for_rent, for_sale, off_market, recently_sold ou sale_pending.
body_style
fb_body_style
body_style
Estilo da carroçaria do veículo: CONVERTIBLE, COUPE, HATCHBACK, MINIVAN, TRUCK, SUV, SEDAN, VAN, WAGON, CROSSOVER ou OTHER.
checkin_date
fb_checkin_date
checkin_date
A 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.
city
fb_city
city
Informe a cidade da localização da intenção do usuário.
condition_of_vehicle
fb_condition_of_vehicle
condition_of_vehicle
A condição do veículo.
content_ids
fb_content_ids
content_ids
Os números de identificação do conteúdo associado ao evento, como SKUs de produtos para itens em um evento do tipo AddToCart.
content_type
fb_content_type
content_type
Deve ser definido como product ou product_group:
Use
productse as chaves enviadas por você representarem produtos. As chaves podem sercontent_idsoucontents.Use
product_groupse as chaves enviadas por você emcontent_idsrepresentarem 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.
contents
fb_contents
contents
Uma 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.
country
fb_country
country
Informe o país da localização da intenção do usuário.
currency
fb_currency
currency
Obrigató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_category
fb_delivery_category
delivery_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_date
fb_departing_arrival_date
departing_arrival_date
A data e hora de chegada ao destino da viagem de ida.
departing_departure_date
fb_departing_departure_date
departing_departure_date
A data e hora de início da viagem de ida.
destination_airport
fb_destination_airport
destination_airport
Use o código IATA oficial do aeroporto de destino.
destination_ids
fb_destination_ids
destination_ids
Se você tiver um catálogo de destinos, poderá associar um ou mais destinos desse catálogo a um evento de hotel específico.
dma_code
fb_dma_code
dma_code
O código da Designated Marketing Area (DMA) usado para direcionar ofertas aos usuários.
drivetrain
fb_drivetrain
drivetrain
Tração do veículo: 4X2, 4X4, AWD, FWD, RWD, OTHER ou NONE.
exterior_color
fb_exterior_color
exterior_color
Cor externa.
fuel_type
fb_fuel_type
fuel_type
Tipo de combustível do veículo: DIESEL, ELECTRIC, FLEX, GASOLINE, HYBRID, PETROL, PLUGIN_HYBRID, OTHER ou NONE.
hotel_score
fb_hotel_score
hotel_score
Um indicador que representa o valor relativo desse hotel para o anunciante em comparação a outros hotéis.
interior_color
fb_interior_color
interior_color
A cor interna.
lead_event_source
lead_event_source
lead_event_source
A fonte do evento de lead.
lease_end_date
fb_lease_end_date
lease_end_date
Especificado usando o formato de data da norma ISO 8601: YYYY-MM-DD.
lease_start_date
fb_lease_start_date
lease_start_date
Permite 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_type
fb_listing_type
listing_type
O 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.
make
fb_make
make
A marca ou montadora do veículo.
mileage.unit
fb_mileage.unit
mileage.unit
A unidade da quilometragem.
mileage.value
fb_mileage.value
mileage.value
O valor da quilometragem.
model
fb_model
model
O modelo do veículo.
neighborhood
fb_neighborhood
neighborhood
O bairro de interesse.
net_revenue
net_revenue
net_revenue
O valor da margem de um evento de conversão.
num_adults
fb_num_adults
num_adults
O número de adultos que ficarão hospedados.
num_children
fb_num_children
num_children
O número de crianças que ficarão hospedadas.
num_infants
fb_num_infants
num_infants
O número de bebês que ficarão hospedados.
num_items
fb_num_items
num_items
Use apenas com eventos InitiateCheckout. O número de itens que um usuário tenta comprar durante a finalização da compra.
order_id
fb_order_id
order_id
A identificação do pedido da transação como uma string.
origin_airport
fb_origin_airport
origin_airport
Use o código IATA oficial do aeroporto de partida.
postal_code
fb_postal_code
postal_code
Código postal.
predicted_ltv
predicted_ltv
predicted_ltv
O valor total previsto de um evento de conversão.
preferred_baths_range
fb_preferred_baths_range
preferred_baths_range
Número de banheiros selecionados em um intervalo.
preferred_beds_range
fb_preferred_beds_range
preferred_beds_range
Número de quartos selecionados em um intervalo.
preferred_neighborhoods
fb_preferred_neighborhoods
preferred_neighborhoods
Os bairros de preferência.
preferred_num_stops
fb_preferred_num_stops
preferred_num_stops
Indique o número de paradas que o usuário está procurando.
preferred_price_range
fb_preferred_price_range
preferred_price_range
A faixa de preço preferencial para o veículo. Mín./máx.: até 2 casas decimais.
preferred_star_ratings
fb_preferred_star_ratings
preferred_star_ratings
Uma tupla de classificação de hotel por estrelas mínima e máxima que um usuário aplica na filtragem.
price
fb_price
price
Custo 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_id
product_catalog_id
product_catalog_id
Identificação do catálogo de produtos.
property_type
fb_property_type
property_type
Deve ser apartment, condo, house, land, manufactured, other ou townhouse.
region
fb_region
region
Estado, distrito ou região de interesse.
returning_arrival_date
fb_returning_arrival_date
returning_arrival_date
A data e hora em que a viagem de retorno é concluída.
returning_departure_date
fb_returning_departure_date
returning_departure_date
A data e hora de início da viagem de retorno.
search_string
fb_search_string
search_string
Use apenas com eventos Search. Uma pesquisa feita por um usuário.
state_of_vehicle
fb_state_of_vehicle
state_of_vehicle
Estado do veículo.
suggested_destinations
fb_suggested_destinations
suggested_destinations
Os destinos sugeridos.
suggested_home_listings
fb_suggested_home_listings
suggested_home_listings
Os classificados de imóveis sugeridos.
suggested_hotels
fb_suggested_hotels
suggested_hotels
Os hotéis sugeridos.
suggested_jobs
fb_suggested_jobs
suggested_jobs
Os empregos sugeridos.
suggested_local_service_businesses
fb_suggested_local_service_businesses
suggested_local_service_businesses
Os serviços comerciais locais sugeridos.
suggested_location_based_items
fb_suggested_location_based_items
suggested_location_based_items
Os itens baseados em localização sugeridos.
suggested_vehicles
fb_suggested_vehicles
suggested_vehicles
Os veículos sugeridos.
transmission
fb_transmission
transmission
A transmissão do veículo: AUTOMATIC, MANUAL, OTHER ou NONE.
travel_class
fb_travel_class
travel_class
Deve ser economy, premium, business ou first.
travel_end
fb_travel_end
travel_end
A data de término da viagem.
travel_start
fb_travel_start
travel_start
A data de início da viagem.
trim
fb_trim
trim
Máximo de caracteres: 50.
user_bucket
fb_user_bucket
user_bucket
O grupo do usuário.
value
_valueToSum
value
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.
vin
fb_vin
vin
Número de chassi.
year
fb_year
year
O ano de lançamento do veículo no formato yyyy.
item_number
Identificador exclusivo para distinguir eventos dentro do mesmo pedido ou transação.
ad_type
O 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_id
International 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_description
Uma descrição de string.
fb_level
O nível de um jogo.
fb_max_rating_value
O limite máximo de uma escala de classificação, por exemplo, 5 em uma escala de 5 estrelas.
fb_payment_info_available
1 para sim, 0 para não.
fb_registration_method
Facebook, Email, Twitter, entre outros.
fb_success
1 para sim, 0 para não.
_valueToSum
O 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 🔗 https://developers.facebook.com/docs/marketing-api/conversions-api/parameters
Parâmetros de dados personalizados (Custom Data) 🔗 https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/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.
Atualizado