Introdução
A API do Reportei Connect permite que você integre dados de diversas plataformas de redes sociais e marketing diretamente em sua aplicação. Com endpoints simples e bem documentados, você pode acessar métricas, criar relatórios personalizados e automatizar processos de análise de dados.
Base URL
https://connect.reportei.com/apiEndpoints que retornam listas de recursos suportam paginação através dos parâmetros page e per_page.
Parâmetros de Paginação:
page- Número da página (padrão: 1)per_page- Itens por página (padrão: 15, máximo: 100)
Exemplo de Requisição:
curl -X GET "https://connect.reportei.com/api/customers?page=2&per_page=20" \
-H "Authorization: Bearer YOUR_API_TOKEN"Resposta Paginada:
{
"data": [...],
"meta": {
"current_page": 2,
"per_page": 20,
"total": 150,
"total_pages": 8
}
}Todas as respostas da API seguem um formato JSON consistente para facilitar o processamento dos dados.
Resposta de Sucesso:
{
"data": {
"id": "uuid",
"type": "resource_type",
"attributes": {
// Resource attributes
}
}
}Resposta de Lista:
{
"data": [
{
"id": "uuid",
"type": "resource_type",
"attributes": { ... }
}
],
"meta": {
"current_page": 1,
"per_page": 15,
"total": 100
}
}Resposta de Erro:
{
"error": {
"code": "error_code",
"message": "Human readable error message",
"details": {
// Additional error information
}
}
}A API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição.
200 OK
Requisição bem-sucedida
201 Created
Recurso criado com sucesso
400 Bad Request
Requisição inválida ou malformada
401 Unauthorized
Token de autenticação ausente ou inválido
403 Forbidden
Sem permissão para acessar o recurso
404 Not Found
Recurso não encontrado
422 Unprocessable Entity
Validação falhou nos dados enviados
429 Too Many Requests
Limite de taxa excedido
500 Internal Server Error
Erro no servidor
Exemplo de Erro:
{
"error": {
"code": "validation_error",
"message": "The given data was invalid",
"details": {
"email": ["The email field is required"],
"name": ["The name must be at least 3 characters"]
}
}
}Autenticação
Para autenticar requisições relacionadas à sua conta de merchant, inclua seu token de acesso no cabeçalho Authorization.
Authorization: Bearer YOUR_ACCESS_TOKENPara acessar dados de um cliente específico, use o token gerado para ele. Este token deve ser enviado no cabeçalho x-customer-token, juntamente com o Bearer Token.
x-customer-token: CUSTOMER_API_TOKENImportante: O customer token é gerado apenas uma vez na criação do cliente. Certifique-se de armazená-lo com segurança, pois ele não pode ser recuperado posteriormente.
Merchants
Gerencie as configurações do seu merchant e visualize as integrações disponíveis.
Retorna informações sobre o seu merchant, incluindo limites de taxa (rate limiting) e a lista de integrações disponíveis para conexão.
{
"merchant": {
"uuid": "c1e6c85a-6441-4107-ab36-b8bf581b40e0",
"name": "Reportei",
"app_url": "https://reportei.com",
"redirect_url": "https://reportei.com",
"created_at": "2024-09-24 17:07:26",
"updated_at": "2024-09-24 17:07:26",
"rate_limit_per_minute": "999",
"rate_limit_per_second": "999",
"total_customers": 2,
"available_integrations": [
{
"name": "Instagram Business",
"slug": "instagram_business"
},
{
"name": "Facebook",
"slug": "facebook"
}
]
}
}Customers
Gerencie os clientes associados ao seu merchant. Clientes representam os usuários finais que utilizarão as integrações.
Ao criar um novo cliente, um período de trial de 7 dias é iniciado automaticamente. Durante este período, o cliente pode acessar todas as funcionalidades da API. Após o término do trial, o acesso será restrito (retornando erro 401 Unauthorized) até que o status de pagamento seja atualizado.
Para remover a restrição, atualize o status de pagamento do cliente utilizando o endpoint /customers/{uuid}/update-payment-status.
Retorna uma lista paginada de todos os clientes associados ao seu merchant.
{
"data": [
{
"uuid": "caedbbbe-7d93-476f-b965-bf97cd7ce874",
"name": "Reportei Customer 1",
"created_at": "2024-09-24 17:07:34",
"updated_at": "2024-09-24 17:07:34",
"trial_ends_at": "2024-10-08 17:15:12",
"is_paying": false,
"merchant": "Reportei"
}
],
"meta": {
"current_page": 1,
"per_page": 15,
"total": 2,
"total_pages": 1
}
}Retorna os detalhes de um cliente específico através do seu UUID.
{
"customer": {
"uuid": "caedbbbe-7d93-476f-b965-bf97cd7ce874",
"name": "Reportei Customer 1",
"created_at": "2024-09-24 17:07:34",
"updated_at": "2024-09-24 17:07:34",
"trial_ends_at": "2024-10-08 17:15:12",
"is_paying": false,
"merchant": "Reportei"
}
}Cria um novo cliente associado ao seu merchant. O api_token gerado neste momento é crucial e não será recuperado.
{
"name": "Nome do Novo Cliente"
}Atualiza o nome de um cliente existente.
{
"name": "Novo Nome do Cliente"
}Remove um cliente e todas as suas integrações associadas.
{
"success": true,
"message": "Record successfully removed"
}Marca um cliente como pagante ou não pagante, afetando o acesso a recursos após o período de trial.
{
"is_paying": true
}Retorna as configurações e integrações ativas de um cliente específico, utilizando o x-customer-token no header.
{
"customer": {
"uuid": "073c1e15-94d0-49b3-9861-a0e9b7ffb06c",
"name": "Reportei Customer 1",
"created_at": "2024-09-24 19:06:08",
"updated_at": "2024-09-24 19:06:08",
"trial_ends_at": "2024-10-08 17:15:12",
"is_paying": false,
"merchant": "Reportei",
"integrations": [
{
"uuid": "6110b666-0327-4a81-b48e-9feb34d72f78",
"integration": "Instagram Business",
"name": "reportei",
"slug": "instagram_business",
"status": "active"
}
]
}
}Customer Integrations
Gerencie as conexões das plataformas de redes sociais e marketing dos seus clientes. Utilize ox-customer-token para acessar estes endpoints.
Cada integração de cliente possui um status que indica sua validade e conexão. Verifique o campo status para entender o estado da conexão.
Inicia um fluxo para que o cliente possa conectar novas contas de redes sociais ou gerenciar as existentes. Retorna um link único para a interface de integração.
Todos os campos são opcionais.
{
"redirect_url": "https://sua-aplicacao.com/dashboard",
"locale": "pt_BR",
"limits": {},
"limit_reached_url": "https://sua-aplicacao.com/limite",
"expires_in_minutes": 30,
"close_on_finish": true,
"enable_multi_account_selection": false
}Descrição dos campos:
redirect_url— URL de redirecionamento após a integraçãolocale— Idioma da interface de integração (ex:pt_BR,en,es,fr)limits— Array de objetos para controlar o comportamento da sessão (veja detalhes abaixo)limit_reached_url— URL para redirecionar quando o limite de integrações for atingidoexpires_in_minutes— Tempo de expiração da sessão em minutos (mínimo: 1)close_on_finish— Setrue, fecha a janela ao finalizar a integraçãoenable_multi_account_selection— Permite que o usuário selecione múltiplas contas na mesma sessão
Limits disponíveis:
O campo limits recebe um array de objetos, cada um com name e value. É possível combinar múltiplos limites na mesma sessão.
integration_count integerbloqueia
Limita o número total de integrações que o customer pode conectar nesta sessão.
{ "name": "integration_count", "value": 5 }same_type_integration integerbloqueia
Limita quantas integrações do mesmo tipo (ex: Instagram Business) o customer pode conectar.
{ "name": "same_type_integration", "value": 2 }same_integration_across_customers integerbloqueia
Limita quantos customers (non-paying) do mesmo merchant podem conectar a mesma conta. Útil para evitar abuso de trial — customers pagantes são sempre permitidos.
{ "name": "same_integration_across_customers", "value": 1 }available_integrations array de slugsfiltro de UI
Filtra quais integrações são exibidas na tela de conexão. Não bloqueia — apenas controla a visibilidade. Se omitido, todas as integrações do merchant são exibidas.
{ "name": "available_integrations", "value": ["instagram_business", "facebook_ads", "google_analytics_4"] }Exemplo combinando múltiplos limites:
{
"redirect_url": "https://sua-aplicacao.com/dashboard",
"limits": [
{ "name": "integration_count", "value": 3 },
{ "name": "available_integrations", "value": ["instagram_business", "facebook_ads"] }
],
"limit_reached_url": "https://sua-aplicacao.com/upgrade"
}Sessão Expirável: O link da sessão é válido por 5 minutos. Acesse o session_link para iniciar o processo de integração do cliente.
Retorna detalhes de uma integração específica do cliente.
{
"customer_integration": {
"uuid": "4addc0da-8583-4dbb-a0e9-c7e2e8470f50",
"source_name": "reportei",
"status": "active",
"created_at": "2024-09-24 17:08:08",
"updated_at": "2024-09-24 17:08:08",
"integration": {
"name": "Instagram Business",
"slug": "instagram_business"
}
}
}Remove uma integração específica do cliente. Requer o UUID da integração e o UUID de uma sessão ativa.
{
"success": true,
"message": "Record successfully removed"
}Metrics
Consulte métricas de integrações conectadas. Utilize o Connect Explorer para testar a coleta de dados e visualizar as métricas disponíveis para cada integração, ou use os endpoints abaixo para obter os dados programaticamente.
O Connect Explorer é uma ferramenta interativa que permite validar seus tokens, explorar as métricas disponíveis por integração e testar consultas à API — tudo sem escrever código. Ideal para descobrir quais métricas e dimensões estão disponíveis antes de implementar a integração.
Valide seus tokens
Acesse o Explorer, insira seu Bearer Token (merchant) e x-customer-token (customer) para validar a conexão e carregar as integrações disponíveis.
Explore métricas disponíveis
Selecione uma integração e navegue pelo catálogo completo de métricas, organizadas por tipo (Numbers, Charts, Tables). Customize métricas e dimensões conforme necessário.
Teste a consulta e copie o payload
Defina o período desejado, execute a consulta e visualize a resposta da API em tempo real. Copie o payload gerado para usar diretamente nos endpoints /metrics/get-data ou /metrics/get-data-async.
Cada métrica no array metrics possui a seguinte estrutura:
id
Identificador único para a métrica. Use qualquer UUID ou string única.
reference_key
Nome geral da métrica, ex: ig:story_replies (respostas de stories do Instagram).
metrics
Array com os valores específicos de métricas solicitados, ex: ["replies"].
dimensions Opcional
Detalhamento adicional da métrica, ex: ["stories", "date", "device"].
component
Tipo da métrica, que altera a estrutura da resposta final:
- •
number_v1- Retorna um único valor numérico - •
datatable_v1- Retorna dados tabulares - •
chart_v1- Retorna dados formatados para gráficos
entity_id e entity_type Opcional
ID e tipo da entidade para filtrar resultados (ad, campaign ou adset).
Importante: Dependendo da rede da integração do cliente, algumas combinações de métricas e dimensões podem não ser compatíveis.
Retorna um objeto com os valores das métricas solicitadas de uma integração de cliente.
Parâmetros Obrigatórios:
customer_integration- UUID da integração do clientestart- Data de início da análise (ISO 8601)end- Data de fim da análise (ISO 8601)metrics- Array contendo a estrutura de métricas
Parâmetros Opcionais:
comparison_start- Data de início da comparação (ISO 8601)comparison_end- Data de fim da comparação (ISO 8601)
Este exemplo inclui 3 métricas diferentes: ig:story_replies (number_v1), ig:followers_gender (chart_v1), e ig:clicks_breakdown (datatable_v1).
{
"customer_integration": "4addc0da-8583-4dbb-a0e9-c7e2e8470f50",
"start": "2024-01-01",
"end": "2024-09-01",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "ig:story_replies",
"component": "number_v1",
"metrics": ["replies"],
"dimensions": ["stories"]
},
{
"id": "3051ed66-a05c-462a-aece-e1d900e78b02",
"reference_key": "ig:followers_gender",
"component": "chart_v1",
"metrics": ["followers"],
"dimensions": ["gender"]
},
{
"id": "b3a949ac-f6ae-4bd1-bb90-1e8e0cbe8ed5",
"reference_key": "ig:clicks_breakdown",
"component": "datatable_v1",
"metrics": ["count", "ctr"],
"dimensions": ["clicks_breakdown"]
}
]
}Inicia um processo para coletar os dados de métricas solicitados e envia os resultados de forma assíncrona para a metrics_webhook_url fornecida.
Parâmetros Obrigatórios:
metrics_webhook_url- URL que receberá o payload de métricascustomer_integration- UUID da integração do clientestart- Data de início da análise (ISO 8601)end- Data de fim da análise (ISO 8601)metrics- Array contendo a estrutura de métricas (veja o endpoint Get metrics data para mais informações)
Parâmetros Opcionais:
comparison_start- Data de início da comparação (ISO 8601)comparison_end- Data de fim da comparação (ISO 8601)
Nota: A estrutura do corpo da requisição é idêntica ao endpoint Get metrics data. Da mesma forma, o payload enviado para a metrics_webhook_url seguirá o mesmo formato da resposta do endpoint Get metrics data.
{
"metrics_webhook_url": "https://sua-aplicacao.com/webhook/metrics",
"customer_integration": "4addc0da-8583-4dbb-a0e9-c7e2e8470f50",
"start": "2024-01-01",
"end": "2024-09-01",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "ig:story_replies",
"component": "number_v1",
"metrics": ["replies"],
"dimensions": ["stories"]
},
{
"id": "3051ed66-a05c-462a-aece-e1d900e78b02",
"reference_key": "ig:followers_gender",
"component": "chart_v1",
"metrics": ["followers"],
"dimensions": ["gender"]
},
{
"id": "b3a949ac-f6ae-4bd1-bb90-1e8e0cbe8ed5",
"reference_key": "ig:clicks_breakdown",
"component": "datatable_v1",
"metrics": ["count", "ctr"],
"dimensions": ["clicks_breakdown"]
}
]
}Integrações Disponíveis
Explore as diversas plataformas de marketing e redes sociais que podem ser integradas com a API do Reportei Connect.
1. Conecte a integração: Use o endpoint de Customer Integrations para criar uma sessão e conectar a conta do cliente
2. Explore as métricas: Use o Connect Explorer para testar a coleta e ver métricas disponíveis, ou copie payloads diretamente do Reportei Application (veja a seção Metrics acima)
3. Consulte os dados: Use os endpoints /metrics/get-data ou /metrics/get-data-async com o payload copiado
facebook
facebook_ads
instagram
threads
google_analytics
google_analytics_4
google_adwords
search_console
google_my_business
youtube
linkedin
linkedin_ads
twitter
twitter_ads
tiktoktiktok_ads
pinterestpinterest_ads
rdstation
rd_crm
hubspot_marketinghubspot_crm
pipedrive
active_campaign
mailchimp
egoi
kommo
phonetrack
shopify
woo_commerce
nuvem_shop
hotmart
eduzzWebhooks
Cadastre webhooks para ser notificado automaticamente sobre eventos das integrações dos seus clientes, como expiração de token ou remoção de uma integração — sem precisar ficar consultando a API periodicamente.
Ao cadastrar um webhook, você escolhe quais eventos ele deve receber através do campo events:
customer_integration.status_updated- disparado quando o status de uma integração muda (ex: token expirou e a integração precisa ser reconectada)customer_integration.deleted- disparado quando uma integração de cliente é removidaoauth_started- disparado quando um cliente inicia o fluxo de autenticação OAuth de uma integraçãooauth_saved- disparado quando as credenciais OAuth de uma integração são salvas com sucessosession_completed- disparado quando uma sessão de integração é concluída
Retorna uma lista paginada dos webhooks cadastrados para o seu merchant.
{
"data": [
{
"id": 12,
"url": "https://sua-aplicacao.com/webhooks/reportei",
"events": ["customer_integration.status_updated", "customer_integration.deleted"],
"is_active": true,
"created_at": "2026-08-05T18:23:55.000000Z",
"updated_at": "2026-08-05T18:23:55.000000Z"
}
],
"meta": {
"current_page": 1,
"per_page": 15,
"total": 1
}
}Cadastra uma nova URL de webhook para o seu merchant. A URL deve usar http ou https e não pode apontar para endereços privados/internos (ex: localhost, 127.0.0.1, redes 10.x.x.x/192.168.x.x).
Parâmetros:
url- URL que receberá as notificações (obrigatório, deve ser única por merchant)events- array com pelo menos um dos eventos listados acima (obrigatório)is_active- habilita/desabilita o envio de notificações para este webhook (opcional, padrãotrue)
Nota: Tentar cadastrar uma URL já registrada para o seu merchant retorna 422 com uma mensagem de validação.
{
"url": "https://sua-aplicacao.com/webhooks/reportei",
"events": ["customer_integration.status_updated", "customer_integration.deleted"],
"is_active": true
}Atualiza parcialmente um webhook já cadastrado. Envie apenas os campos que deseja alterar.
{
"is_active": false
}Remove um webhook cadastrado do seu merchant.
{
"success": true
}Toda requisição enviada para a sua url cadastrada inclui os headers x-api-token e x-api-signature, permitindo validar que a notificação realmente veio do Reportei Connect antes de processá-la.
O header x-api-signature tem o formato t={timestamp},s={assinatura}, onde a assinatura é um HMAC-SHA256 de {timestamp}{client_id} usando o seu client_secret como chave. Recalcule esse hash do seu lado e compare com o valor recebido para confirmar a autenticidade.