Reportei Connect API — Integre mais de 50 plataformas com uma única API

Connect API v1

Bem-vindo à API do Reportei Connect

O Reportei Connect é um conector de dados: ele coloca dentro do seu software as mais de 50 integrações que o Reportei já mantém com redes sociais, plataformas de anúncios e ferramentas de marketing. Em vez de implementar e manter um conector para cada plataforma, você acessa todas por uma única API, com autenticação, coleta e renovação de tokens resolvidas pelo Connect.

O modelo é direto: o seu merchant cria customers, cada customer conecta integrações através de uma sessão, e as métricas são consultadas a partir de cada integração conectada.

Para gerar o seu token de merchant, é preciso ter uma conta no Reportei Connect com o trial iniciado.

Iniciar trial no Reportei Connect

Base URL

https://connect.reportei.com/api

Autenticação

A API usa dois tokens: o Bearer Token do merchant, presente em todas as chamadas, e o customer token, exigido nos endpoints que acessam dados de um cliente específico.

Bearer Token (Merchant)

Para autenticar requisições relacionadas à sua conta de merchant, inclua seu token de acesso no cabeçalho Authorization.

Authorization: Bearer YOUR_ACCESS_TOKEN

Customer Token

Para 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_TOKEN

Importante

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.

Paginação, Respostas e Erros

Convenções que valem para todos os endpoints da API: como paginar listas, qual é a estrutura das respostas e como interpretar os códigos de status.

Paginação

Endpoints que retornam listas de recursos suportam paginação através dos parâmetros page e per_page.

Nome	Descrição
page	Número da página (padrão: 1)
per_page	Itens por página (padrão: 15, máximo: 100)

Requisição

curl -X GET "https://connect.reportei.com/api/customers?page=2&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Resposta

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Formato de Respostas

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
    }
  }
}

Tratamento de Erros

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"]
    }
  }
}

Merchants

Gerencie as configurações do seu merchant e visualize as integrações disponíveis.

GET/merchants/settings

Settings

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.

Período de Trial

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.

GET/customers

Listar Clientes

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
  }
}

GET/customers/{uuid}

Obter Cliente

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"
  }
}

POST/customers

Criar Cliente

Cria um novo cliente associado ao seu merchant. O api_token gerado neste momento é crucial e não poderá ser recuperado depois.

{
  "name": "Nome do Novo Cliente"
}

PUT/customers/{uuid}

Atualizar Cliente

Atualiza o nome de um cliente existente.

{
  "name": "Novo Nome do Cliente"
}

DELETE/customers/{uuid}

Deletar Cliente

Remove um cliente e todas as suas integrações associadas.

{
  "success": true,
  "message": "Record successfully removed"
}

POST/customers/{uuid}/update-payment-status

Atualizar Status de Pagamento

Marca um cliente como pagante ou não pagante, afetando o acesso a recursos após o período de trial.

{
  "is_paying": true
}

GET/customers/settings

Configurações do Cliente

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 o x-customer-token para acessar estes endpoints.

Status da Integração

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.

activeexpiredrevoked

POST/customer-integrations/session

Criar Sessão de Integraçã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.

Campo	Descrição
redirect_url	URL de redirecionamento após a integração
locale	Idioma da interface de integração (ex: pt_BR, en, es, fr)
limits	Array de objetos para controlar o comportamento da sessão (veja os limites disponíveis abaixo)
limit_reached_url	URL para redirecionar quando o limite de integrações for atingido
expires_in_minutes	Tempo de expiração da sessão em minutos (mínimo: 1)
close_on_finish	Se true, fecha a janela ao finalizar a integração
enable_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_countintegerbloqueia

Limita o número total de integrações que o customer pode conectar nesta sessão.

{ "name": "integration_count", "value": 5 }

same_type_integrationintegerbloqueia

Limita quantas integrações do mesmo tipo (ex: Instagram Business) o customer pode conectar.

{ "name": "same_type_integration", "value": 2 }

same_integration_across_customersintegerbloqueia

Limita quantos customers não pagantes 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_integrationsarray 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.

{
  "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
}

GET/customer-integrations/{uuid}

Obter Integração

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"
    }
  }
}

DELETE/customer-integrations/{uuid}?session_id={uuid}

Deletar Integração

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. Use 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.

Connect Explorer

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.

Acessar Connect Explorer

Estrutura de Métricas

Cada métrica no array metrics possui a seguinte estrutura:

Campo	Descrição
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"].
dimensionsOpcional	Detalhamento adicional da métrica, ex: ["stories", "date", "device"].
component	Tipo da métrica, que altera a estrutura da resposta final.
entity_idOpcional	Junto com entity_type, informa o ID e o tipo da entidade para filtrar resultados (ad, campaign ou adset).

Componentes disponíveis

component	Descrição
number_v1	Retorna um único valor numérico.
datatable_v1	Retorna dados tabulares.
chart_v1	Retorna dados formatados para gráficos.

Importante

Dependendo da rede da integração do cliente, algumas combinações de métricas e dimensões podem não ser compatíveis.

POST/metrics/get-data

Obter Dados de Métricas

Retorna um objeto com os valores das métricas solicitadas de uma integração de cliente.

Parâmetros obrigatórios

Nome	Descrição
customer_integration	UUID da integração do cliente
start	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

Nome	Descrição
comparison_start	Data de início da comparação (ISO 8601)
comparison_end	Data de fim da comparação (ISO 8601)

{
  "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"]
    }
  ]
}

POST/metrics/get-data-async

Obter Dados de Métricas (Assíncrono)

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

Nome	Descrição
metrics_webhook_url	URL que receberá o payload de métricas
customer_integration	UUID da integração do cliente
start	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

Nome	Descrição
comparison_start	Data de início da comparação (ISO 8601)
comparison_end	Data de fim da comparação (ISO 8601)

A estrutura do corpo da requisição é idêntica ao endpoint /metrics/get-data, e o payload enviado para a metrics_webhook_url segue o mesmo formato da resposta daquele endpoint. A chamada retorna 200 OK assim que o processo de coleta é iniciado.

{
  "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"]
    }
  ]
}

Webhooks

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.

Eventos disponíveis

Ao cadastrar um webhook, você escolhe quais eventos ele deve receber através do campo events:

Evento	Descrição
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 é removida.
oauth_started	Disparado quando um cliente inicia o fluxo de autenticação OAuth de uma integração.
oauth_saved	Disparado quando as credenciais OAuth de uma integração são salvas com sucesso.
session_completed	Disparado quando uma sessão de integração é concluída.

GET/webhook-subscriptions

Listar Webhooks

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
  }
}

POST/webhook-subscriptions

Cadastrar Webhook

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 ou internos (ex: localhost, 127.0.0.1, redes 10.x.x.x e 192.168.x.x).

Parâmetros

Nome	Descrição
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 ou desabilita o envio de notificações para este webhook (opcional, padrão true).

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
}

PUT/webhook-subscriptions/{id}

Atualizar Webhook

Atualiza parcialmente um webhook já cadastrado. Envie apenas os campos que deseja alterar.

{
  "is_active": false
}

DELETE/webhook-subscriptions/{id}

Remover Webhook

Remove um webhook cadastrado do seu merchant.

{
  "success": true
}

Verificando a autenticidade das notificações

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.

Integrações Disponíveis

Explore as diversas plataformas de marketing e redes sociais que podem ser integradas com a API do Reportei Connect.

Como usar as integrações

Conecte a integração: use o endpoint de Customer Integrations para criar uma sessão e conectar a conta do cliente.

Explore as métricas: use o Connect Explorer para testar a coleta e ver as métricas disponíveis, ou copie payloads diretamente da aplicação do Reportei (veja a seção Metrics acima).

Consulte os dados: use os endpoints /metrics/get-data ou /metrics/get-data-async com o payload copiado.

Lista de integrações

Nome e slug de cada integração disponível para uso na API.

Facebookfacebook

Meta Adsfacebook_ads

Instagraminstagram

Threadsthreads

Google Analyticsgoogle_analytics

Google Analytics 4google_analytics_4

Google Adsgoogle_adwords

Google Search Consolesearch_console

Google My Businessgoogle_my_business

YouTubeyoutube

LinkedInlinkedin

LinkedIn Adslinkedin_ads

Twittertwitter

Twitter Adstwitter_ads

TikToktiktok

TikTok Adstiktok_ads

Pinterestpinterest

Pinterest Adspinterest_ads

RD Station Marketingrdstation

RD Station CRMrd_crm

HubSpot Marketinghubspot_marketing

HubSpot CRMhubspot_crm

Pipedrivepipedrive

Active Campaignactive_campaign

Mailchimpmailchimp

Egoiegoi

Kommokommo

Phonetrackphonetrack

Shopifyshopify

WooCommercewoo_commerce

NuvemShopnuvem_shop

Hotmarthotmart

Eduzzeduzz

Implemente o Connect usando IA

Copie o prompt abaixo e cole no seu agente — Claude Code, Cursor ou Codex. Ele cria a conta, lê a especificação da API e implementa a integração no seu projeto. Você só precisa preencher o cadastro quando ele pedir.

Prompt para o seu agente

Preciso integrar o Reportei Connect neste projeto. Leia as instruções em https://app.connect.reportei.com/provision-trial.md e siga o passo a passo descrito lá.

Connect API v1

Bem-vindo à API do Reportei Connect

O modelo é direto: o seu merchant cria customers, cada customer conecta integrações através de uma sessão, e as métricas são consultadas a partir de cada integração conectada.

Para gerar o seu token de merchant, é preciso ter uma conta no Reportei Connect com o trial iniciado.

Iniciar trial no Reportei Connect

Base URL

https://connect.reportei.com/api

Autenticação

A API usa dois tokens: o Bearer Token do merchant, presente em todas as chamadas, e o customer token, exigido nos endpoints que acessam dados de um cliente específico.

Bearer Token (Merchant)

Para autenticar requisições relacionadas à sua conta de merchant, inclua seu token de acesso no cabeçalho Authorization.

Authorization: Bearer YOUR_ACCESS_TOKEN

Customer Token

Para 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_TOKEN

Importante

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.

Paginação, Respostas e Erros

Convenções que valem para todos os endpoints da API: como paginar listas, qual é a estrutura das respostas e como interpretar os códigos de status.

Paginação

Endpoints que retornam listas de recursos suportam paginação através dos parâmetros page e per_page.

Nome	Descrição
page	Número da página (padrão: 1)
per_page	Itens por página (padrão: 15, máximo: 100)

Requisição

curl -X GET "https://connect.reportei.com/api/customers?page=2&per_page=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Resposta

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Formato de Respostas

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
    }
  }
}

Tratamento de Erros

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"]
    }
  }
}

Merchants

Gerencie as configurações do seu merchant e visualize as integrações disponíveis.

GET/merchants/settings

Settings

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.

Período de Trial

Para remover a restrição, atualize o status de pagamento do cliente utilizando o endpoint /customers/{uuid}/update-payment-status.

GET/customers

Listar Clientes

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
  }
}

GET/customers/{uuid}

Obter Cliente

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"
  }
}

POST/customers

Criar Cliente

Cria um novo cliente associado ao seu merchant. O api_token gerado neste momento é crucial e não poderá ser recuperado depois.

{
  "name": "Nome do Novo Cliente"
}

PUT/customers/{uuid}

Atualizar Cliente

Atualiza o nome de um cliente existente.

{
  "name": "Novo Nome do Cliente"
}

DELETE/customers/{uuid}

Deletar Cliente

Remove um cliente e todas as suas integrações associadas.

{
  "success": true,
  "message": "Record successfully removed"
}

POST/customers/{uuid}/update-payment-status

Atualizar Status de Pagamento

Marca um cliente como pagante ou não pagante, afetando o acesso a recursos após o período de trial.

{
  "is_paying": true
}

GET/customers/settings

Configurações do Cliente

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 o x-customer-token para acessar estes endpoints.

Status da Integração

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.

activeexpiredrevoked

POST/customer-integrations/session

Criar Sessão de Integraçã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.

Campo	Descrição
redirect_url	URL de redirecionamento após a integração
locale	Idioma da interface de integração (ex: pt_BR, en, es, fr)
limits	Array de objetos para controlar o comportamento da sessão (veja os limites disponíveis abaixo)
limit_reached_url	URL para redirecionar quando o limite de integrações for atingido
expires_in_minutes	Tempo de expiração da sessão em minutos (mínimo: 1)
close_on_finish	Se true, fecha a janela ao finalizar a integração
enable_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_countintegerbloqueia

Limita o número total de integrações que o customer pode conectar nesta sessão.

{ "name": "integration_count", "value": 5 }

same_type_integrationintegerbloqueia

Limita quantas integrações do mesmo tipo (ex: Instagram Business) o customer pode conectar.

{ "name": "same_type_integration", "value": 2 }

same_integration_across_customersintegerbloqueia

Limita quantos customers não pagantes 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_integrationsarray 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.

{
  "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
}

GET/customer-integrations/{uuid}

Obter Integração

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"
    }
  }
}

DELETE/customer-integrations/{uuid}?session_id={uuid}

Deletar Integração

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

Connect Explorer

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.

Acessar Connect Explorer

Estrutura de Métricas

Cada métrica no array metrics possui a seguinte estrutura:

Campo	Descrição
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"].
dimensionsOpcional	Detalhamento adicional da métrica, ex: ["stories", "date", "device"].
component	Tipo da métrica, que altera a estrutura da resposta final.
entity_idOpcional	Junto com entity_type, informa o ID e o tipo da entidade para filtrar resultados (ad, campaign ou adset).

Componentes disponíveis

component	Descrição
number_v1	Retorna um único valor numérico.
datatable_v1	Retorna dados tabulares.
chart_v1	Retorna dados formatados para gráficos.

Importante

Dependendo da rede da integração do cliente, algumas combinações de métricas e dimensões podem não ser compatíveis.

POST/metrics/get-data

Obter Dados de Métricas

Retorna um objeto com os valores das métricas solicitadas de uma integração de cliente.

Parâmetros obrigatórios

Nome	Descrição
customer_integration	UUID da integração do cliente
start	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

Nome	Descrição
comparison_start	Data de início da comparação (ISO 8601)
comparison_end	Data de fim da comparação (ISO 8601)

{
  "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"]
    }
  ]
}

POST/metrics/get-data-async

Obter Dados de Métricas (Assíncrono)

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

Nome	Descrição
metrics_webhook_url	URL que receberá o payload de métricas
customer_integration	UUID da integração do cliente
start	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

Nome	Descrição
comparison_start	Data de início da comparação (ISO 8601)
comparison_end	Data de fim da comparação (ISO 8601)

{
  "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"]
    }
  ]
}

Webhooks

Eventos disponíveis

Ao cadastrar um webhook, você escolhe quais eventos ele deve receber através do campo events:

Evento	Descrição
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 é removida.
oauth_started	Disparado quando um cliente inicia o fluxo de autenticação OAuth de uma integração.
oauth_saved	Disparado quando as credenciais OAuth de uma integração são salvas com sucesso.
session_completed	Disparado quando uma sessão de integração é concluída.

GET/webhook-subscriptions

Listar Webhooks

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
  }
}

POST/webhook-subscriptions

Cadastrar Webhook

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 ou internos (ex: localhost, 127.0.0.1, redes 10.x.x.x e 192.168.x.x).

Parâmetros

Nome	Descrição
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 ou desabilita o envio de notificações para este webhook (opcional, padrão true).

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
}

PUT/webhook-subscriptions/{id}

Atualizar Webhook

Atualiza parcialmente um webhook já cadastrado. Envie apenas os campos que deseja alterar.

{
  "is_active": false
}

DELETE/webhook-subscriptions/{id}

Remover Webhook

Remove um webhook cadastrado do seu merchant.

{
  "success": true
}

Verificando a autenticidade das notificações

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.

Integrações Disponíveis

Explore as diversas plataformas de marketing e redes sociais que podem ser integradas com a API do Reportei Connect.

Como usar as integrações

Conecte a integração: use o endpoint de Customer Integrations para criar uma sessão e conectar a conta do cliente.

Explore as métricas: use o Connect Explorer para testar a coleta e ver as métricas disponíveis, ou copie payloads diretamente da aplicação do Reportei (veja a seção Metrics acima).

Consulte os dados: use os endpoints /metrics/get-data ou /metrics/get-data-async com o payload copiado.

Lista de integrações

Nome e slug de cada integração disponível para uso na API.

Facebookfacebook

Meta Adsfacebook_ads

Instagraminstagram

Threadsthreads

Google Analyticsgoogle_analytics

Google Analytics 4google_analytics_4

Google Adsgoogle_adwords

Google Search Consolesearch_console

Google My Businessgoogle_my_business

YouTubeyoutube

LinkedInlinkedin

LinkedIn Adslinkedin_ads

Twittertwitter

Twitter Adstwitter_ads

TikToktiktok

TikTok Adstiktok_ads

Pinterestpinterest

Pinterest Adspinterest_ads

RD Station Marketingrdstation

RD Station CRMrd_crm

HubSpot Marketinghubspot_marketing

HubSpot CRMhubspot_crm

Pipedrivepipedrive

Active Campaignactive_campaign

Mailchimpmailchimp

Egoiegoi

Kommokommo

Phonetrackphonetrack

Shopifyshopify

WooCommercewoo_commerce

NuvemShopnuvem_shop

Hotmarthotmart

Eduzzeduzz

Implemente o Connect usando IA

Prompt para o seu agente

Preciso integrar o Reportei Connect neste projeto. Leia as instruções em https://app.connect.reportei.com/provision-trial.md e siga o passo a passo descrito lá.