Reportei Connect
API Documentation v1.0

Reportei Connect API

Integre dados de métricas de redes sociais e marketing diretamente em sua aplicação com nossa API RESTful completa, segura e fácil de usar.

Testar API GratuitamentePostman Collection

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.

{
  "redirect_url": "https://sua-aplicacao.com/dashboard"
}

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. Recomendamos fortemente que você acesse o Reportei Application, crie uma conta de teste, integre suas redes, gere um dashboard e então use os endpoints abaixo para obter os dados.

Como Copiar Payloads do Reportei
Siga estes passos para obter o JSON de qualquer métrica diretamente da interface do Reportei
1

Acesse a integração desejada

Logue na sua conta de teste do Reportei, realize as integrações, gere um dashboard com as redes desejadas e navegue até a integração (Facebook, Google Ads, etc.) e visualize as métricas disponíveis.

Acesse a integração desejada
2

Clique no ícone de código

Passe o mouse sobre o widget desejado e clique no ícone de código (</>) para gerar a consulta.

Clique no ícone de código
3

Copie o JSON

No modal que aparecer, você verá o payload JSON completo. Clique no botão "Copiar" para usar na API.

Copie o JSON

Dica: O payload copiado já contém todas as métricas, dimensões e filtros configurados no widget. Você pode usar esse JSON diretamente nos endpoints /metrics/get-data ou /metrics/get-data-async.

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.

Métricas e Dimensões Disponíveis

Se você não quiser copiar o payload de um dashboard existente do Reportei, há uma lista completa de métricas e dimensões disponíveis por integração no GitHub:

Ver Payloads no GitHub

Cada pasta em /payloads contém dois arquivos JSON:

  • • metrics.json - Métricas predefinidas com componentes específicos
  • • setup.json - Métricas e dimensões disponíveis para construir seus próprios payloads
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. Copie o payload: Acesse o Reportei Application e copie o JSON da métrica desejada (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

Documentação completa: Para ver todas as métricas e dimensões disponíveis para cada integração, consulte o repositório no GitHub.

Documentação Completa no GitHub
Acesse o repositório para ver todos os payloads JSON disponíveis

Para cada integração, você encontrará dois arquivos no repositório:

  • • metrics.json - Métricas predefinidas prontas para uso
  • • setup.json - Todas as métricas e dimensões disponíveis para construir payloads customizados