Anúncios de parceiros gerenciados: referência da API

Outras APIs de anúncios de parceiros gerenciados incluem:

• Seller Management APIs
• Gerenciamento de anúncios de parceiros
• Async API User Guide

API de Pesquisa da Empresa do Vendedor

Use esta API para pesquisar a identificação da empresa de determinado vendedor ou o vendor_id.

Tipo de token de acesso

Para fazer chamadas da API, use o token de acesso criado por um usuário administrador do sistema que pertence ao Gerenciador de Negócios (do marketplace) principal.

Exemplo de solicitação GET

curl -X GET \
  -F "child_business_external_id=<VENDOR_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/owned_businesses?access_token=<ACCESS_TOKEN>"

Exemplo de resposta

{
    "child_business_id": 3213232
}

API de Acesso aos Metadados da Empresa do Vendedor

Use essa API para recuperar os metadados do vendedor de uma empresa secundária de vendedor de anúncios de parceiros gerenciados. Os metadados da resposta da API incluem o seguinte:

• Ativos de anúncios de parceiros gerenciados: página, conta de anúncios, forma de pagamento
• Informações do modelo personalizado do vendedor
• Informações da empresa do vendedor: nome

Tipo de token de acesso

Para fazer chamadas da API, use o token de acesso criado por um usuário administrador do sistema que pertence ao Gerenciador de Negócios (do marketplace) principal.

Tipo de identificação da empresa

Use a identificação secundária do Gerenciador de Negócios na chamada de API.

Exemplo de solicitação GET

curl -X GET \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/?fields=collaborative_ads_managed_partner_business_info&access_token=<ACCESS_TOKEN>"

Exemplo de resposta

{
  "collaborative_ads_managed_partner_business_info": {
    "seller_business_status": "ready",
    "seller_business_info": {
      "seller_external_website_url": "https://www.website.com",
      "partner_facebook_page": {
        "id":"9999999"
      }
    },
    "ad_account": {
      "id": "act_11111111",
      "currency": "USD"
    },
    "page": {
      "id": "3333333"
    },
    "catalog_segment": {
      "id": "2222222"
    },
    "extended_credit": {
      "receiving_credit_allocation_config": {
        "partition_type": "FIXED",
        "id":"66666666"
      },
      "max_balance": {
        "amount":"5,000.00",
        "amount_in_hundredths":"500000",
        "currency":"USD",
        "offsetted_amount":"500000"
      },
      "id":"888888888"
    },
    "active_seller_campaign": {
      "status": "ACTIVE",
      "id": "1111111"
    },
    "template": [
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "4444444",
        "adgroup_template_ids": [
          "5555555"
        ],
        "targeting_type": "retargeting"      
      },
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "6666666",
        "adgroup_template_ids": [
          "7777777"
        ],
        "targeting_type": "prospecting"
      } 
    ]
  },
  "id": "<child_business_manager_id>"
}
    

Obter o token secundário de usuário do sistema

Em um Gerenciador de Negócios secundário integrado, use esta chamada de API para compartilhar o app e obter o respectivo token de acesso. É possível usar esse token em todas as chamadas subsequentes para criar ou gerenciar anúncios.

Exemplo de solicitação POST

curl \
  -F 'id=<CHILD_BUSINESS_MANAGER>' \
  -F 'app_id=<App_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<Parent BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  "https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token"

Exemplo de resposta

{ 
  "access_token": "<CHILD_BM_ACCESS_TOKEN>"
}

API de Atualização da Configuração da Empresa do Vendedor

Use esta API para atualizar as informações da empresa de um vendedor. Você pode atualizar as informações da empresa de um vendedor (como a URL do site externo ou o endereço de email) e/ou ativos de anúncios de parceiros gerenciados (como a conta de anúncios ativa ou um modelo personalizado de campanha de criação de anúncios). Consulte Parâmetros disponíveis para ver mais informações.

Para criar e obter a empresa de um vendedor, consulte Seller Business Creation API. Para encontrar a identificação da empresa de um vendedor existente, consulte API de Pesquisa da Empresa do Vendedor.

Tipo de token de acesso

Para fazer chamadas da API, use o token de acesso que pertence a cada Gerenciador de Negócios (do vendedor) secundário.

Parâmetros disponíveis

Exemplo de solicitação POST

curl \
  -F "seller_external_website_url='http://shop.com'" \
  -F "ad_account=<SELLER_ACTIVE_AD_ACCOUNT_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Child_Business_id>/managed_partner_business_setup?access_token=<ACCESS_TOKEN>"

Exemplo de resposta

{
    "id": 3213232, // id of child business
    "meta_data": {
        "seller_business_info": {
            "seller_email_address": "goodseller@fb.com"
            "seller_external_website_url": "www.website.com"
        },
        "ad_account": {
            "id": "434343",
            "spend_limit": "500",
        },
        "page": {
            "id": "123412341",
        },
        "template": [
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "4444444",
            "adgroup_template_ids": [
              "5555555"
            ],
            "targeting_type": "retargeting"      
          },
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "6666666",
            "adgroup_template_ids": [
              "7777777"
            ],
            "targeting_type": "prospecting"
          } 
        ]     
    }
}

Códigos de erro

Uso de modelos

Um modelo é um ativo configurado e usado pelo marketplace no serviço de anúncios de parceiros gerenciados. Os modelos contêm detalhes e configurações, ou "componentes", que impulsionam as campanhas do vendedor veiculadas pelo marketplace em nome do vendedor.

Esses componentes incluem conjuntos de anúncios e anúncios, que abrangem informações, como direcionamento, criativo do anúncio, formatos e muito mais. Existem quatro componentes necessários para cada modelo de campanha:

• Componente do conjunto de anúncios para prospecção
• Componente do anúncio
• Componente do conjunto de anúncios para redirecionamento
• Componente do anúncio

Tipos de modelo

Existem dois tipos de modelo, padrão e personalizado:

Requisitos para modelos personalizados

Antes de criar um modelo personalizado, o marketplace deve primeiro criar um Gerenciador de Negócios produtor, pois isso garante que as campanhas usadas para criar modelos estejam em conformidade com as personalizações e os requisitos dos Anúncios Colaborativos para campanhas de vendedores. Como produtor, o Gerenciador de Negócios pode ser usado para criar anúncios de origem para a criação de modelos.

Redirecionamento do conjunto de anúncios, prospecção do conjunto de anúncios e componentes de anúncios devem estar disponíveis ao adicionar e/ou configurar um modelo de campanha personalizado para um vendedor.

As campanhas usadas para a criação de modelos devem estar associadas a uma conta com Anúncios Colaborativos e ter as seguintes configurações:

• O objetivo da campanha deve ser vendas do catálogo.
• No Gerenciador de Anúncios, a otimização do orçamento precisa ser ativada ao nível da campanha, com a estratégia de lance "Menor custo".
• O formato do anúncio deve ser carrossel sem sobreposições, imagens ou vídeos estáticos.

Fluxo de modelos personalizado

Etapa 1: criar um modelo de campanha personalizado

1. Acesse a aba Ativos na Central de Colaboração. Nessa aba, a seção Inventário de modelos exibe uma coleção de modelos e componentes que podem ser usados em campanhas de vendedores.
2. Clique em Criar modelo para abrir um cartão de etapas.
3. Procure uma campanha de origem existente válida ao fornecer o conjunto de anúncios ou a identificação do anúncio.
4. Para criar o componente de modelo, selecione o conjunto de anúncios e/ou o anúncio extraído da identificação de origem. Você precisa criar os quatro componentes (2 anúncios e 2 conjuntos de anúncios) em um modelo personalizado.
5. Salve o modelo fornecendo nome e descrição.

Os detalhes específicos do vendedor (como segmento do catálogo, conjunto de produtos, Página do Facebook e URL de destino) são retirados da campanha de origem durante a criação do modelo. A campanha final criada usando o modelo tem informações específicas do vendedor para esses campos com orçamento total da campanha e estratégia de lance de menor custo.

Etapa 2: aplicar o modelo personalizado a um vendedor

Os modelos personalizados podem ser usados desta forma:

• Use no momento da integração do vendedor ao atribuir modelos específicos para novas campanhas de vendedores.
• Altere o modelo para um vendedor dar início a uma campanha de feriado ou a outra campanha especial.

Se quiser alterar o modelo de campanha para vendedores, tenha prontos os componentes do modelo que substituirão os atuais. Você pode substituir um ou todos. Se estiver criando um novo modelo para vendedores que não têm um modelo personalizado, será necessário ter os quatro componentes (2 anúncios e 2 conjuntos de anúncios) prontos para uso.

Um modelo pode ser aplicado aos vendedores usando uma das seguintes formas:

Fluxo de interface do usuário de aplicação de modelo de vendedor único

1. Acesse a aba Vendedores na Central de Colaboração e selecione um vendedor que você deseja aplicar o modelo personalizado.
2. Acesse a aba Ativos compartilhados do vendedor. No início, os vendedores não têm um modelo de campanha personalizado configurado.
3. Clique em Adicionar personalizado. Um modal será exibido; nele você pode selecionar componentes do modelo criado para aplicar ao vendedor selecionado.
4. Você pode especificar os limites de gastos para o conjunto de anúncios em prospecção e o conjunto de anúncios de redirecionamento, que são expressos como uma porcentagem do orçamento total da campanha. O orçamento será distribuído em tempo real entre os dois conjuntos de anúncios com base no desempenho. Ou seja, a porcentagem do orçamento gasto em cada conjunto de anúncios no final da campanha pode ser inferior ao gasto máximo definido. Por padrão, o limite de gastos máximo é dividido igualmente entre os dois conjuntos de anúncios, mas é possível alterar essa configuração.
5. Clique em Salvar, e os componentes do modelo selecionados serão aplicados ao vendedor.

Fluxo da interface do usuário de aplicação de modelo em massa

Esse recurso proporciona escalabilidade, permitindo que os marketplaces apliquem componentes de modelo a vários vendedores ao mesmo tempo.

1. Acesse a aba Vendedores na Central de Colaboração e selecione um conjunto de vendedores ao qual deseja aplicar os modelos usando a coluna da caixa de seleção.
2. Clique em Aplicar modelos para prosseguir com o fluxo de aplicação de modelos.
3. Um modal será exibido com base na seleção do vendedor

• Se os vendedores selecionados não tiverem modelos personalizados existentes, selecione os quatro componentes do modelo e especifique a porcentagem do limite de gastos para prospecção e redirecionamento. Por padrão, o limite de gastos é dividido igualmente entre os dois conjuntos de anúncios.
• Se os vendedores selecionados tiverem modelos personalizados aplicados anteriormente, selecione todos, um ou alguns dos componentes do modelo para substituir nos vendedores selecionados. Ao ativar o botão, você pode substituir a porcentagem do limite de gastos dos conjuntos de anúncios para os vendedores.
• Se os vendedores selecionados forem uma mistura de vendedores com e sem modelos personalizados, um modal é exibido para selecionar "Vendedores sem modelos personalizados" ou "Vendedores com modelo personalizado" para a próxima etapa. Com base nisso, um modal das duas opções anteriores é exibido.

Para finalizar o processo, clique em Salvar. Os componentes de modelo selecionados serão aplicados aos vendedores selecionados.

API de Atualização da Configuração da Empresa do Vendedor

Use a API de Atualização da Configuração da Empresa do Vendedor para aplicar um modelo personalizado a um vendedor com o seguinte parâmetro de entrada: template.

"template":[
  {
    "budget_percentage":0.5,
    "campaign_template_id":"160235235998069",
    "adgroup_template_ids":[
      "447963739637509"
    ],
    "targeting_type":"retargeting"
  },
  {
    "budget_percentage":0.5,
    "campaign_template_id":"278452090413983",
    "adgroup_template_ids":[
      "458654975391261"
    ],
    "targeting_type":"prospecting"
  }
]

Etapa 3: criar a campanha

Use as principais instruções de criação de campanhas para criar e veicular anúncios do vendedor com os parâmetros especificados e o modelo personalizado aplicado anteriormente. Para usar o modelo de campanha personalizado aplicado ao vendedor, defina use_seller_template como true.