Reportei Connect - Integração de Dados de Marketing

Introdução

Bem-vindo à API do Reportei Connect

Uma API RESTful completa para integração de dados de métricas de redes sociais

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/api

Paginação

Como trabalhar com resultados paginados

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

Formato de Respostas

Estrutura padrão das respostas da API

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

Códigos de status HTTP e mensagens de erro

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

Bearer Token (Merchant)

Autenticação principal para a maioria dos endpoints

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

Acesso a dados específicos do cliente

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.

Merchants

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

Settings

GET /merchants/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.

Listar Clientes

GET /customers

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

Obter Cliente

GET /customers/{uuid}

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

Criar Cliente

POST /customers

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

Atualizar Cliente

PUT /customers/{uuid}

Atualiza o nome de um cliente existente.

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

Deletar Cliente

DELETE /customers/{uuid}

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

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

Atualizar Status de Pagamento

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

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

{
  "is_paying": true
}

Configurações do Cliente

GET /customers/settings

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.

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

Criar Sessão de Integração

POST /customer-integrations/session

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çã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 detalhes 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_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.

Obter Integração

GET /customer-integrations/{uuid}

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

Deletar Integração

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

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.

Connect Explorer

Teste consultas de métricas e explore os dados disponíveis diretamente no navegador

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.

Catálogo de métricas no Connect Explorer

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

Entenda como construir payloads de métricas personalizados

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.

Obter Dados de Métricas

POST /metrics/get-data

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

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

Obter Dados de Métricas (Assíncrono)

POST /metrics/get-data-async

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é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 (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.

Como Usar as Integrações

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

Lista de Integrações

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