Business Management APIs

Primeiros passos

Aprenda a implementar o gerenciamento de ativos de criativo.

O gerenciamento de ativos de criativo está disponível apenas para parceiros selecionados. Se quiser mais informações, entre em contato com seu parceiro da Meta.

Requisitos

Para usar esta API, você precisará do seguinte:

Permissões

Durante o login no app, você precisará solicitar as seguintes permissões aos usuários:

  • business_creative_management: gerenciar pastas de criativos da empresa e ativos de negócios. Obrigatório para todos os pontos de extremidade da API de Gerenciamento de Ativos de Criativo da Empresa
  • business_creative_insights: acessar insights sobre os ativos de criativo da empresa
  • business_management: gerenciar usuários da empresa e aceitar solicitações de acordos de parceria

Limitações

  • O usuário do app (anunciante) deve ser um administrador da empresa representado pela identificação do Gerenciador de Negócios.

Etapa 1: criar uma pasta de criativos da empresa

Para criar uma pasta de criativos em nome da empresa do anunciante, envie uma solicitação POST ao ponto de extremidade {business-id}/creative_folders. Nesse caso, {business-id} é a identificação da empresa do anunciante.

É preciso ter a permissão business_creative_management para executar essa ação.

Exemplo de solicitação

curl -X POST \
  -F 'name={folder-name}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Exemplo de reposta

{ “id”: “{business-creative-folder-id}” }

Também é possível criar subpastas.

Etapa 2: adicionar criativos às pastas

Para adicionar ativos de criativo existentes a uma pasta, faça uma solicitação POST para {business-id}/images ou {business-id}/videos. Você precisará da permissão business_creative_management para executar essa ação.

Adicionar imagens

Exemplo – Para adicionar uma imagem:

curl -X POST \
  -F 'bytes={image-content-in-bytes-format}' \
  -F 'name={image-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph.facebook.com/{version}/{business-id}/images

Resposta

{
  "images":{
    "{image-name}":{
      "id":"{business-image-id}",
      "hash":"{hash}",
      "url":"{image-url}"
    }
  }
}

Carregar vídeos

Carregue um vídeo em uma única solicitação (quando ele tiver poucos megabytes) ou carregue-o em partes. Faça sua chamada de API para o carregamento do vídeo em graph-video.facebook.com em vez de graph.facebook.com.

Exemplo – Envie uma solicitação POST para {business-id}/video e inclua o nome do seu vídeo, a origem e a identificação da pasta de criativos da empresa.

curl -X POST \
  -F 'name={video-name}' \
  -F 'source='@{video-path}'' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

Resposta

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

Carregar vídeos em partes

Para vídeos maiores, envie uma solicitação start, uma ou várias solicitações transfer e uma solicitação finish.

Para fazer uma solicitação start e criar uma sessão de carregamento de vídeo, envie uma solicitação POST para /{business-id}/videos, defina o campo upload_phase como start e especifique file_size em bytes.

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={access-token}' \
  -F 'upload_phase=start' \
  -F 'file_size={video_file_size_in_bytes}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Exemplo de resposta

{
  "upload_session_id": "{session-id}",
  "business_video_id": "{business-video-id}",
  "video_id": "{video-id}",
  "start_offset": "0",
  "end_offset": "52428800"
}

Para carregar [0, 52428800] do seu vídeo, divida o arquivo em partes de acordo com os deslocamentos de início e de conclusão, depois envie essas partes com solicitações transfer. Enviaremos a você novos deslocamentos. Use-os para carregar cada parte do arquivo.

Exemplo – Envie a primeira parte:

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'upload_session_id={session-id}' \
  -F 'start_offset=0' \
  -F 'video_file_chunk=@{binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Em caso de sucesso, responderemos com deslocamentos para a próxima parte:

{
 "start_offset": "52428800",    //Start byte position of the next file chunk.
 "end_offset": "104857601"      //End byte position of the next file chunk.
}

Recorte e carregue a segunda parte com o intervalo [52428800, 104857601] do seu arquivo e faça o envio:

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'start_offset=52428801' \
  -F 'upload_session_id={your-upload-sesson-id}' \
  -F 'video_file_chunk={binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Envie todas as partes adicionais até que start_offset seja igual a end_offset:

{
  "start_offset": "152043520",
  "end_offset": "152043520"
}

Isso significa que você carregou todo o arquivo. Agora você precisa publicar esse vídeo e fechar a sessão de carregamento.

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=finish' \
  -F 'upload_session_id={session-id}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Se você receber erros durante um carregamento, poderá tentar carregar novamente essa parte. Normalmente, os erros ocorrem por problemas de resposta. Tente carregar novamente a parte que falhou. Para saber mais sobre os erros, consulte:

Depois que você carregar o criativo, os anunciantes com acesso à pasta poderão criar anúncios no Gerenciador de Anúncios ou usando a API de Marketing.

Todos os criativos carregados aparecem na interface do usuário Gerenciador de Anúncios > Seleção de mídia. Você pode usá-los na criação e na edição de anúncios. Além disso, as pastas de criativos e os ativos estão disponíveis na ferramenta Biblioteca de Mídia do Gerenciador de Negócios em Gerenciador de Negócios > Biblioteca de Mídia.

Etapa 3: fornecer uma URL de deep link para o ativo e criar um anúncio ou uma publicação

Para obter a URL do deep link para um ativo específico, consulte o campo media_library_url do ativo de vídeo ou imagem carregado:

curl -X GET \  
  -F 'access_token={partner-access-token}' \
https://graph.facebook.com/v<API_VERSION>/<asset_id>?fields=media_library_url

Se quiser usar o deep link para criar um anúncio ou uma publicação da Página, anexe &action=CREATE_AD ou &action=CREATE_POST ao final do link:

https://business.facebook.com/asset_library/business_creatives/?object_id=<OBJECT_ID>&action=CREATE_AD