Guia básico de integração com API
Atualizado hoje
A API da Metricool conecta as tuas próprias ferramentas e scripts à Metricool para que possas exportar dados e criar, agendar e gerir publicações sem usar a aplicação. Este guia acompanha-te desde a obtenção de acesso até à primeira chamada à API.
Antes de começares
A API está disponível nos planos Advanced e Custom. Os planos Free e Starter não incluem acesso à API.
Acede a Definições da conta > API.
Copia o teu token de acesso à API.
Abre a documentação oficial da API através do ícone ℹ️ de informação junto ao campo do token ou acede diretamente a https://app.metricool.com/resources/apidocs/index.html. Também está disponível um guia em PDF para download: API English PDF.
Autentica todas as chamadas
Todos os endpoints requerem autenticação com três valores: o teu token no cabeçalho X-Mc-Auth, além de userId e blogId como parâmetros do pedido. Os pedidos com um corpo também usam Content-Type: application/json.
X-Mc-Auth: YOUR_API_TOKEN
Content-Type: application/jsonuserId identifica a tua conta Metricool e blogId identifica a marca. Podes consultar ambos no URL do navegador quando abres uma marca na aplicação:
https://app.metricool.com/evolution/web?blogId=00000&userId=0000000Para listar todas as marcas que geres ou que foram partilhadas contigo, chama https://app.metricool.com/api/admin/simpleProfiles?userId=YOUR_USER_ID. Cada entrada inclui o respetivo blogId. Para um guia detalhado sobre o ID da conta, consulta Como encontrar o teu ID de utilizador da Metricool.
Cria e agenda uma publicação
Envia um pedido POST para o endpoint do agendador com a data de publicação, o texto da publicação e pelo menos uma rede:
POST https://app.metricool.com/api/v2/scheduler/posts?blogId={blogId}&userId={userId}O corpo do pedido requer:
publicationDate: a data tem de ser futura e estar no formato ISO 8601 com um fuso horário, por exemplo,
Europe/Madrid.text: o conteúdo da publicação.
providers: pelo menos uma rede, por exemplo,
{ "network": "facebook" }.
Exemplo de corpo do pedido:
{
"publicationDate": {
"dateTime": "2025-07-23T10:00:00",
"timezone": "Europe/Madrid"
},
"text": "Hello! This is a scheduled post test.",
"providers": [
{ "network": "facebook" }
]
}As definições opcionais incluem draft (define como true para guardar a publicação como rascunho em vez de a agendar), autoPublish, firstCommentText e blocos específicos de cada rede, como facebookData, instagramData, twitterData, linkedinData, pinterestData, youtubeData, tiktokData, gmbData, threadsData e blueskyData, para opções por rede, como o tipo de publicação do Facebook ou a publicação automática no Instagram. A referência completa dos parâmetros está nos ficheiros Swagger .yaml e .json associados à documentação da API.
Publica automaticamente em várias redes
Define autoPublish como true para publicar sem qualquer passo manual. Sem esta opção, as publicações do Instagram e do TikTok são enviadas para o teu telemóvel como uma notificação, e tens de confirmar a publicação na aplicação nativa.
Um único pedido pode publicar o mesmo vídeo em várias redes ao mesmo tempo, reutilizando a mesma legenda. Só os campos específicos de cada rede precisam de valores separados, como o tipo de publicação para o Instagram e o Facebook, o título para o YouTube ou a opção de privacidade para o TikTok:
{
"publicationDate": { "dateTime": "2026-11-21T10:00:00", "timezone": "Europe/Madrid" },
"text": "Caption with #hashtags",
"providers": [
{ "network": "tiktok" },
{ "network": "instagram" },
{ "network": "facebook" },
{ "network": "youtube" }
],
"media": ["https://your-server.com/video.mp4"],
"saveExternalMediaFiles": true,
"autoPublish": true,
"instagramData": { "type": "REEL" },
"facebookData": { "type": "REEL" },
"youtubeData": { "type": "short", "title": "Video title" },
"tiktokData": { "privacyOption": "PUBLIC_TO_EVERYONE" }
}Com media definido como uma lista de URLs e saveExternalMediaFiles definido como true, a Metricool copia o vídeo durante este mesmo pedido. Assim, não precisas de chamar primeiro o endpoint normalize neste fluxo.
Não há um intervalo mínimo entre o pedido e a data de publicação. A Metricool verifica as publicações que já devem ser publicadas a cada minuto, por isso, normalmente, uma publicação agendada para a hora atual é publicada em poucos minutos.
Cada rede tem o seu próprio limite diário de publicações por conta de rede social, e não por conta da Metricool ou marca. Consulta Limites diários de publicação nas redes sociais para veres os limites atuais.
O que podes fazer com publicações agendadas
Os endpoints do agendador permitem realizar estas ações. Todos os caminhos são relativos ao URL base https://app.metricool.com/api.
Ação | Método e caminho |
|---|---|
Criar uma publicação agendada |
|
Listar publicações agendadas entre duas datas |
|
Obter uma publicação agendada por ID |
|
Atualizar uma publicação agendada |
|
Editar e atualizar os campos selecionados |
|
Eliminar uma publicação agendada |
|
Enviar várias publicações de uma marca para revisão em lote |
|
Aprovar ou rejeitar uma publicação agendada |
|
Obter a configuração da marca para enviar uma publicação para revisão |
|
Obter as propriedades de publicações do Instagram de uma marca |
|
Verificar o estado de publicação de uma publicação
Chama GET /v2/scheduler/posts/{id} para verificar o que aconteceu com uma publicação agendada. Cada rede incluída na publicação devolve um dos seguintes estados:
PENDING: agendada, ainda não publicada.
PUBLISHING: a publicação está em curso.
PUBLISHED: publicada. O link público está em
publicUrl.ERROR: a publicação falhou. O motivo está em
detailedStatus.AWAITING_CONFIRMATION (apenas TikTok): o TikTok aceitou a publicação, mas ainda não confirmou que foi publicada.
Uma publicação agendada sem autoPublish também aparece como PUBLISHED quando chega ao teu telemóvel para confirmação manual, embora publicUrl permaneça vazio até terminares a publicação na aplicação nativa.
Adicionar conteúdo multimédia a uma publicação agendada
Os links para conteúdo multimédia têm de ser públicos e não podem expirar: os URLs privados ou temporários são ignorados e a publicação é agendada sem conteúdo multimédia. Para anexar conteúdo multimédia, prepara-o antes de chamares o endpoint do agendador:
Normaliza o URL do conteúdo multimédia com um pedido GET para que o ficheiro seja alojado nos servidores da Metricool, quando necessário:
https://app.metricool.com/api/actions/normalize/image/url?url=<URL_OF_YOUR_MEDIA>Faz referência ao conteúdo multimédia na publicação através do respetivo
mediaId:
"media": {
"mediaId": "ID_OF_MEDIA"
}Sem o identificador do conteúdo multimédia no pedido, a publicação é agendada sem esse conteúdo. Consulta o exemplo completo em Perguntas frequentes e erros comuns ao usar a API.
Limitações de publicação
Cada rede social restringe o que as ferramentas de terceiros podem publicar através da sua própria API, por isso, nem todas as funcionalidades do planeador estão disponíveis através da API da Metricool. Para veres a lista de ações de publicação, Inbox e relatórios que não são suportadas em cada rede, consulta Limitações da API por rede social.
Os campos específicos de cada rede no corpo do pedido também variam consoante a rede. Consulta os ficheiros Swagger .yaml e .json na documentação da API para veres os campos disponíveis para cada rede antes de criares o pedido.
Implementação da API
Para exportar dados da Metricool através da nossa API para outras plataformas, como Excel, Google Sheets, MySQL e outras, segue estes passos gerais:
Obtém o token de acesso em Definições da conta > API, conforme descrito acima.
Configura o cliente HTTP: usa uma ferramenta de integração como o Postman ou uma linguagem de programação (por exemplo, Python com requests) e configura o cabeçalho
X-Mc-Authcom o teu token.Envia um pedido GET para o endpoint dos dados pretendidos (publicações, métricas, relatórios). Todas as chamadas requerem
userIdeblogId. Usa o inspetor do navegador para obter uma vista das chamadas que a Metricool faz e dos respetivos parâmetros, como se mostra em Como obter um endpoint na Metricool para fazer chamadas à API.
Formata os dados: as respostas costumam estar em JSON, por isso, associa os campos à estrutura esperada pela plataforma de destino.
Exporta os dados para a plataforma de destino.
Cada plataforma de destino tem o seu próprio método de integração, mas o fluxo geral segue este esquema.
Documentação
Aqui estão links para a documentação das APIs das plataformas mais utilizadas para a gestão de dados:
Monitoriza a utilização e renova o teu token
Definições da conta > API mostra a utilização atual da API e o histórico dos endpoints utilizados. Também podes obter estatísticas de utilização através da API com GET /v2/settings/users/{userId}/api-usage-stats, que aceita os parâmetros from, to e aggregation e devolve as chamadas feitas por endpoint.
Se precisares de substituir o teu token, podes gerar um novo em Definições da conta > API. A geração de um novo token invalida imediatamente o anterior e todas as integrações que o utilizam deixam de funcionar até o atualizares. Consulta Renovar o token de ligação à API.
Recursos adicionais
Artigos relacionados