Reportei API
PostmanMCP ServerCLI
Navegação
Recursos da API
Materiais Complementares
Postman CollectionAPI v1 (legado)

Documentação da API Reportei V2

Bem-vindo à documentação completa da API Reportei V2.

Escolha seu caminho

Sou novo na API Reportei

  1. 1Gere seu token de autenticação
  2. 2Importe a Postman Collection
  3. 3Teste com GET /v2/companies/settings
  4. 4Entenda Paginação e Filtros
  5. 5Revise Erros e Limites de Requisição
  6. 6Explore os endpoints por recurso

Já uso a API v1 e quero migrar

  1. 1Leia o Guia de Migração v1 → v2
  2. 2Confira o Changelog completo
  3. 3Importe a Postman Collection v2
  4. 4Execute endpoints v1 e v2 em paralelo
  5. 5Migre gradualmente, endpoint a endpoint

Precisa consultar a documentação antiga? API v1 →

Base URL

https://app.reportei.com/api/v2

Quick Start

1. Configure seu Token

Gere seu token na seção Autenticação e depois configure a variável abaixo.

export TOKEN="seu-token-aqui"

2. Seu primeiro request

curl -H "Authorization: Bearer $TOKEN" \
     "https://app.reportei.com/api/v2/companies/settings"

3. Listar seus projetos

curl -H "Authorization: Bearer $TOKEN" \
     "https://app.reportei.com/api/v2/projects?page=1&per_page=50"

4. Criar um relatório

curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://app.reportei.com/api/v2/reports" \
     -d '{
       "title": "Relatorio Mensal",
       "subtitle": "Janeiro 2025",
       "start": "2025-01-01",
       "end": "2025-01-31",
       "template_id": 1,
       "integration_ids": [1, 2],
       "project_id": 1
     }'

Recursos Disponíveis

RecursoEndpointsDescrição
EmpresasGETNa API v2, companies representa a conta/empresa do usuário na plataforma
ProjetosGETGerencie projetos (clientes) da sua conta
IntegraçõesGETNa API v2, integrations permitem que você acesse as integrações conectadas aos projetos da sua company
MétricasGET, POSTColete dados e métricas das integrações conectadas
TemplatesGETGerencie templates de relatórios reutilizáveis
RelatóriosGET, POSTNa API v2, reports permitem que você acesse e crie relatórios da sua company
DashboardsGET, POSTNa API v2, dashboards permitem que você acesse e crie dashboards da sua company
WebhooksGET, POST, PUT, DELETEConfigure webhooks para receber notificações em tempo real sobre eventos na plataforma
Eventos da TimelineGET, POST, PUT, DELETEAdicione eventos personalizados à timeline dos relatórios para documentar ações e marcos importantes

Exemplo: Criar relatório automatizado

// 1. Buscar configuracoes da empresa
const settings = await fetch('/v2/companies/settings', {
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});

// 2. Listar projetos
const projects = await fetch('/v2/projects?per_page=100', {
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});
const projectId = projects.data[0].id;

// 3. Buscar integracoes do projeto
const integrations = await fetch(`/v2/integrations?project_id=${projectId}`, {
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});
const integrationIds = integrations.data.map(i => i.id);

// 4. Listar templates disponiveis
const templates = await fetch('/v2/templates', {
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});
const templateId = templates.data[0].id;

// 5. Criar relatorio
const report = await fetch('/v2/reports', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: "Relatorio de Vendas",
    subtitle: "Relatorio de Janeiro 2025",
    start: "2025-01-01",
    end: "2025-01-31",
    project_id: projectId,
    template_id: templateId,
    integration_ids: integrationIds
  })
});

console.log(`Relatorio criado: ${report.external_url}`);

Autenticação

Todas as requisições da API requerem autenticação através do header Authorization utilizando um Bearer token.

Como gerar seu Token de API

  1. 1Acesse app.reportei.com
  2. 2Faça login na sua conta
  3. 3Navegue até Configurações da Empresa
  4. 4Acesse a seção "API Reportei"
  5. 5Clique em Gerar novo token ou copie seu token existente

Importante

Mantenha seu token seguro e nunca o exponha em código do lado do cliente ou repositórios públicos.

Header de Autenticação

Authorization: Bearer {your_token_here}

Exemplo de Requisição

curl -X GET "https://app.reportei.com/api/v2/companies/settings" \
  -H "Authorization: Bearer seu-token-aqui" \
  -H "Content-Type: application/json"

Paginação e Filtros

A maioria dos endpoints de listagem são paginados e suportam filtros. Você pode controlar o tamanho da página, ordenação e aplicar filtros.

ParâmetroTipoPadrãoDescrição
pageinteger1Número da página atual
per_pageinteger15Itens por página (máx: 100)
sortBystringcreated_atCampo para ordenação
descendingbooleanfalseOrdem descendente

Filtros Específicos por Endpoint

Além dos parâmetros de paginação, cada endpoint pode ter filtros específicos:

Projects
q (busca por nome)
Integrations
project_idnameslug
Reports
project_idcreated_atupdated_at
Dashboards
project_idcreated_atupdated_at
Webhooks
project_idevent_typestatus
Timeline Events
project_idreport_iddate

Exemplo de Filtro Combinado

GET /v2/reports?project_id=123&created_at=2024-01-01&page=1&per_page=50

Exemplo de Resposta Paginada

{
  "data": [...],
  "links": {
    "first": "https://app.reportei.com/api/v2/projects?page=1",
    "last": "https://app.reportei.com/api/v2/projects?page=10",
    "prev": null,
    "next": "https://app.reportei.com/api/v2/projects?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 15,
    "to": 15,
    "total": 142
  }
}

Tratamento de Erros

Todos os erros retornarão um código de status HTTP junto com uma mensagem descritiva no corpo da resposta.

401

Unauthorized

Bearer token inválido ou ausente

403

Forbidden

Acesso ao recurso não permitido

404

Not Found

O recurso solicitado não foi encontrado

422

Unprocessable Entity

Dados enviados incorretos ou incompletos

429

Too Many Requests

Rate limit excedido

500

Internal Server Error

Algo deu errado do nosso lado

Exemplo de Resposta Bem-sucedida

{
  "project": {
    "id": 1,
    "name": "Projeto 1",
    "logo": "logo.png",
    "timezone": "America/Sao_Paulo",
    "locale": "pt_br",
    "date_format": "DD/MM/YYYY",
    "decimal_separator_format": "dot_comma"
  }
}

Exemplo de Erro (404)

{
  "message": "O recurso solicitado nao foi encontrado."
}

Exemplo de Erro de Validação (422)

{
  "message": "Os dados fornecidos sao invalidos.",
  "errors": {
    "project_id": [
      "O campo project_id e obrigatorio."
    ],
    "start_date": [
      "O campo start_date deve ser uma data valida.",
      "O campo start_date deve ser anterior a end_date."
    ]
  }
}

Formatos de Respostas

Todas as respostas da API são retornadas em formato JSON.

Para respostas de listagem (paginadas), consulte a seção Paginação e Filtros.

Resposta de Recurso Único

Em geral, respostas de recurso único retornam um objeto dentro de uma chave com o nome do recurso (ex.: project).

{
  "project": {
    "id": 1,
    "name": "Projeto 1",
    "logo": "logo.png",
    "timezone": "America/Sao_Paulo",
    "locale": "pt_br",
    "date_format": "DD/MM/YYYY",
    "decimal_separator_format": "dot_comma"
  }
}

Campos Comuns

CampoTipoDescrição
idintegerIdentificador único do recurso
created_atstring (datetime)Data de criação (ex.: "2024-09-24 17:07:34")
updated_atstring (datetime)Data da última atualização (ex.: "2024-09-24 17:07:34")

Limites de Requisição

Para garantir performance e equidade, a API impõe limites de requisição (rate limits). Os limites são aplicados por empresa (company/conta). Existem dois níveis de limite: um limite global por token que se aplica a todos os endpoints, e limites isolados por endpoint para operações específicas.

Limite Global

Todas as requisições à API compartilham um limite global vinculado ao seu token. Todos os endpoints (GET, POST, PUT, DELETE) consomem o mesmo bucket global.

Tipo de ContaLimite por MinutoLimite por Segundo
Trial50 req/min4 req/s
Paga100 req/min4 req/s

Limites Isolados por Endpoint

Alguns endpoints possuem limites próprios (buckets isolados), independentes do limite global. Atingir o limite de um endpoint isolado não afeta os demais.

EndpointLimiteEscopo
POST /v2/metrics/get-data100 req/minPor empresa
POST /v2/reports30 req/diaPor empresa
POST /v2/dashboards30 req/diaPor empresa

Headers de Resposta

Todas as respostas da API incluem headers de rate limit para que você possa monitorar seu consumo programaticamente.

HeaderQuandoDescrição
X-RateLimit-LimitTodas as respostasNúmero máximo de requisições permitidas na janela atual
X-RateLimit-RemainingTodas as respostasNúmero de requisições restantes na janela atual
Retry-AfterApenas em 429Segundos para aguardar antes de enviar uma nova requisição

Comportamento ao Receber 429

Ao receber um status 429 (Too Many Requests), não existe bloqueio temporário adicional nem penalidade. Basta aguardar o tempo indicado no header Retry-After e reenviar a requisição. Também não existem limites extras de burst ou concorrência além do rate limit.

HTTP 429
// Response Headers
Retry-After: 42
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 0

// Response Body
{
  "message": "Too many requests. Try again later."
}

Empresas

Na API v2, companies representa a conta/empresa do usuário na plataforma. Não é possível enumerar as companies no Reportei, então este é o único endpoint de company disponível na API.

GET/v2/companies/settings

Retorna os dados da company atual autenticada.

Exemplo de Resposta JSON
{
  "company": {
    "id": 1,
    "name": "Reportei",
    "logo": "1638307862-logo.jpeg",
    "type": "agency",
    "potential_clients": "11-15",
    "company_specialty": "paid traffic"
  }
}
Copiar como cURL
curl -X GET "https://app.reportei.com/api/v2/companies/settings" \
  -H "Authorization: Bearer seu-token-aqui"

Projetos

Gerencie projetos (clientes) da sua conta. Projetos são a unidade principal para organizar integrações, relatórios e dashboards.

GET/v2/projects

Lista todos os projetos da empresa com suporte a paginação e filtros.

Parâmetros
NomeTipoObrigatórioDescrição
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página (padrão: 100)
sortBystringNãoCampo para ordenação
descendingbooleanNãoOrdenação descendente
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "name": "Projeto 1",
      "logo": "logo.png",
      "timezone": "America/Sao_Paulo",
      "locale": "pt_br",
      "date_format": "DD/MM/YYYY",
      "decimal_separator_format": "dot_comma"
    },
    {
      "id": 2,
      "name": "Projeto 2",
      "logo": "logo.png",
      "timezone": "America/Sao_Paulo",
      "locale": "pt_br",
      "date_format": "DD/MM/YYYY",
      "decimal_separator_format": "dot_comma"
    }
  ],
  "meta": {
    "current_page": 2,
    "from": 101,
    "last_page": 650,
    "path": "https://app.reportei.com/api/v2/projects",
    "per_page": 100,
    "to": 200,
    "total": 9750,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/projects"
GET/v2/projects/{id}

Retorna detalhes de um projeto específico.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do projeto
Exemplo de Resposta JSON
{
  "project": {
    "id": 1,
    "name": "Projeto 1",
    "logo": "logo.png",
    "timezone": "America/Sao_Paulo",
    "locale": "pt_br",
    "date_format": "DD/MM/YYYY",
    "decimal_separator_format": "dot_comma"
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/projects/1"

Integrações

Na API v2, integrations permitem que você acesse as integrações conectadas aos projetos da sua company. É possível listar todas as integrações ou filtrar por projeto específico.

GET/v2/integrations

Lista todas as integrações de todos os projetos de uma company. Use project_id para filtrar por projeto específico.

Parâmetros
NomeTipoObrigatórioDescrição
project_idintegerNãoFiltrar por projeto específico
namestringNãoFiltrar pelo nome da integração
slugstringNãoFiltrar pelo tipo de integração (facebook_ads, google_analytics_4, etc)
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página (máx: 100)
sortBystringNãoCampo para ordenação
descendingbooleanNãoOrdem descendente
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "name": "Reportei International",
      "slug": "facebook_ads",
      "status": "active",
      "project_id": 1,
      "project_name": "Cliente Teste",
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    },
    {
      "id": 2,
      "name": "Reportei Brasil",
      "slug": "google_analytics_4",
      "status": "active",
      "project_id": 1,
      "project_name": "Cliente Teste",
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    }
  ],
  "meta": {
    "current_page": 2,
    "from": 101,
    "last_page": 650,
    "path": "https://app.reportei.com/api/v2/integrations",
    "per_page": 100,
    "to": 200,
    "total": 9750,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/integrations?per_page=100&page=2&project_id=1"
GET/v2/integrations/{id}

Retorna os detalhes de uma integração específica a partir do id.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID da integração
Exemplo de Resposta JSON
{
  "integration": {
    "id": 1,
    "name": "Reportei International",
    "slug": "facebook_ads",
    "status": "active",
    "project_id": 1,
    "project_name": "Cliente Teste",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/integrations/1"

Métricas

Colete dados e métricas das integrações conectadas. Este é o endpoint principal para obter dados de performance.

GET/v2/metrics

Lista todas as métricas disponíveis para uma integração específica. O parâmetro integration_slug é obrigatório para filtrar o resultado a apenas uma integração.

Parâmetros
NomeTipoObrigatórioDescrição
integration_slugstringSimSlug da integração (ex: facebook_ads, google_analytics)
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página (padrão: 100)
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": "1d59ec11-9288-4949-8e3a-d3f2c8415f211",
      "reference_key": "fb_ads:spend",
      "component": "number_v1",
      "metrics": ["spend"],
      "type": ["spend"]
    },
    {
      "id": "2a48bc22-1234-5678-9abc-def012345678",
      "reference_key": "fb_ads:impressions",
      "component": "number_v1",
      "metrics": ["impressions"],
      "type": ["impressions"]
    }
  ],
  "meta": {
    "current_page": 2,
    "from": 101,
    "last_page": 5,
    "path": "http://api.reportei.com/v2/metrics",
    "per_page": 100,
    "to": 200,
    "total": 450,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/metrics?per_page=100&page=2&integration_slug=facebook_ads"
POST/v2/metrics/get-data

Retorna os dados de todas as métricas requisitadas de uma integração de um projeto para um período específico.

Corpo da Requisição
CampoTipoObrigatórioDescrição
startstringSimData de início do período (YYYY-MM-DD)
endstringSimData de fim do período (YYYY-MM-DD)
integration_idintegerSimID da integração
metricsarraySimArray de métricas a serem consultadas
comparison_startstringNãoData de início do período de comparação (YYYY-MM-DD)
comparison_endstringNãoData de fim do período de comparação (YYYY-MM-DD)
Exemplo de Requisição JSON
{
  "start": "2025-02-01",
  "end": "2025-02-28",
  "comparison_start": "2025-01-01",
  "comparison_end": "2025-01-31",
  "integration_id": 1,
  "metrics": [
    {
      "id": "1d59ec11-9288-4949-8e3a-d3f2c8415f211",
      "reference_key": "fb_ads:spend",
      "component": "number_v1",
      "metrics": ["spend"],
      "type": ["spend"]
    },
    {
      "id": "2a48bc22-1234-5678-9abc-def012345678",
      "reference_key": "fb_ads:impressions",
      "component": "number_v1",
      "metrics": ["impressions"],
      "type": ["impressions"]
    }
  ]
}
Exemplo de Resposta JSON
{
  "data": {
    "1d59ec11-9288-4949-8e3a-d3f2c8415f211": {
      "values": 6995,
      "comparison": {
        "values": 6948,
        "difference": 0.67645365572827,
        "absoluteDifference": 47
      }
    },
    "2a48bc22-1234-5678-9abc-def012345678": {
      "values": 125000,
      "comparison": {
        "values": 118500,
        "difference": 5.48523206751055,
        "absoluteDifference": 6500
      }
    }
  }
}
Copiar como cURL
curl -s -X POST -H "Authorization: Bearer seu-token-aqui" -H "Content-Type: application/json" \
  -d '{"start":"2025-02-01","end":"2025-02-28","comparison_start":"2025-01-01","comparison_end":"2025-01-31","integration_id":1,"metrics":[{"id":"1d59ec11-9288-4949-8e3a-d3f2c8415f211","reference_key":"fb_ads:spend","component":"number_v1","metrics":["spend"],"type":["spend","ads-cost_per_conversion"]}]}' \
  https://app.reportei.com/api/v2/metrics/get-data

Templates

Gerencie templates de relatórios reutilizáveis.

GET/v2/templates

Lista todos os templates disponíveis na empresa.

Parâmetros
NomeTipoObrigatórioDescrição
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "title": "Template: Relatório Completo",
      "description": "Template padrão com todas as métricas",
      "used_count": 1513970,
      "created_at": "2024-01-20T16:23:24.000000Z",
      "updated_at": "2024-04-19T21:16:29.000000Z"
    },
    {
      "id": 2,
      "title": "Template: Redes Sociais",
      "description": "Focado em métricas de redes sociais",
      "used_count": 45230,
      "created_at": "2024-02-15T10:00:00.000000Z",
      "updated_at": "2024-05-20T14:30:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 15
  }
}
Copiar como cURL
curl -X GET "https://app.reportei.com/api/v2/templates" \
  -H "Authorization: Bearer seu-token-aqui"
GET/v2/templates/{id}

Retorna detalhes de um template específico.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do template
Exemplo de Resposta JSON
{
  "template": {
    "id": 1,
    "title": "Template: Relatório Completo",
    "description": "Template padrão com todas as métricas",
    "sections": [
      {
        "id": 1,
        "title": "Visão Geral",
        "widgets": ["sessions", "users", "pageviews"]
      },
      {
        "id": 2,
        "title": "Redes Sociais",
        "widgets": ["followers", "engagement", "reach"]
      }
    ],
    "used_count": 1513970
  }
}
Copiar como cURL
curl -X GET "https://app.reportei.com/api/v2/templates/1" \
  -H "Authorization: Bearer seu-token-aqui"

Relatórios

Na API v2, reports permitem que você acesse e crie relatórios da sua company. É possível listar, filtrar por projeto e criar novos reports.

GET/v2/reports

Lista todos os relatórios com suporte a filtros por projeto e datas.

Parâmetros
NomeTipoObrigatórioDescrição
project_idintegerNãoFiltrar por projeto específico (client_id)
created_atstringNãoFiltrar por data de criação (YYYY-MM-DD)
updated_atstringNãoFiltrar por data de atualização (YYYY-MM-DD)
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página (padrão: 100)
sortBystringNãoCampo para ordenação
descendingbooleanNãoOrdenação descendente
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "title": "Test title",
      "subtitle": "Subtitle test",
      "start_date": "2025-01-01",
      "end_date": "2025-01-31",
      "comparison_start_date": "2024-01-01",
      "comparison_end_date": "2024-01-31",
      "template_id": 1,
      "client_id": 1,
      "views": 0,
      "created_at": "2025-01-01T00:00:00",
      "internal_url": "https://internal.example",
      "external_url": "https://external.example"
    }
  ],
  "meta": {
    "current_page": 2,
    "from": 101,
    "last_page": 650,
    "path": "https://app.reportei.com/api/v2/reports",
    "per_page": 100,
    "to": 200,
    "total": 9750,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/reports?per_page=100&page=2&project_id=1"
GET/v2/reports/{id}

Retorna os detalhes de um relatório específico a partir do id.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do relatório
Exemplo de Resposta JSON
{
  "report": {
    "id": 1,
    "title": "Test title",
    "subtitle": "Subtitle test",
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "comparison_start_date": "2024-01-01",
    "comparison_end_date": "2024-01-31",
    "template_id": 1,
    "client_id": 1,
    "views": 0,
    "created_at": "2025-01-01T00:00:00",
    "internal_url": "https://internal.example",
    "external_url": "https://external.example"
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/reports/1"
POST/v2/reports

Cria um novo relatório. Consulte projects para IDs de projetos, integrations para IDs de integrações e templates para IDs de templates.

Corpo da Requisição
CampoTipoObrigatórioDescrição
titlestringSimTítulo do relatório
subtitlestringSimLegenda do relatório
startstringSimData de início da análise (YYYY-MM-DD)
endstringSimData de fim da análise (YYYY-MM-DD)
template_idintegerSimID do template
integration_idsarraySimArray de IDs das integrações selecionadas
project_idintegerSimID do projeto
comparison_startstringNãoData de início da comparação (YYYY-MM-DD)
comparison_endstringNãoData de fim da comparação (YYYY-MM-DD)
Exemplo de Requisição JSON
{
  "title": "Relatório de Vendas",
  "subtitle": "Relatório de Vendas de 2025",
  "start": "2025-01-01",
  "end": "2025-01-31",
  "comparison_start": "2024-01-01",
  "comparison_end": "2024-01-31",
  "project_id": 1,
  "template_id": 16,
  "integration_ids": [1, 2, 3]
}
Exemplo de Resposta JSON
{
  "report": {
    "id": 2,
    "title": "Relatório de Vendas",
    "subtitle": "Relatório de Vendas de 2025",
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "comparison_start_date": "2024-01-01",
    "comparison_end_date": "2024-01-31",
    "template_id": 16,
    "views": 0,
    "created_at": "2025-01-01T00:00:00",
    "internal_url": "https://internal.example",
    "external_url": "https://external.example"
  }
}
Copiar como cURL
curl -s -X POST -H "Authorization: Bearer seu-token-aqui" -H "Content-Type: application/json" \
  -d '{"title":"Relatório de Vendas","subtitle":"Relatório de Vendas de 2025","start":"2025-01-01","end":"2025-01-31","comparison_start":"2024-01-01","comparison_end":"2024-01-31","template_id":16,"integration_ids":[1,2,3],"project_id":1}' \
  https://app.reportei.com/api/v2/reports

Dashboards

Na API v2, dashboards permitem que você acesse e crie dashboards da sua company. É possível listar, filtrar por projeto e criar novos dashboards.

GET/v2/dashboards

Lista todos os dashboards com suporte a filtros por projeto e datas.

Parâmetros
NomeTipoObrigatórioDescrição
project_idintegerNãoFiltrar por projeto específico (client_id)
created_atstringNãoFiltrar por data de criação (YYYY-MM-DD)
updated_atstringNãoFiltrar por data de atualização (YYYY-MM-DD)
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página (padrão: 100)
sortBystringNãoCampo para ordenação
descendingbooleanNãoOrdenação descendente
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "title": "Test title",
      "subtitle": "Subtitle test",
      "start_date": "2025-01-01",
      "end_date": "2025-01-31",
      "comparison_start_date": "2024-01-01",
      "comparison_end_date": "2024-01-31",
      "template_id": 1,
      "client_id": 1,
      "views": 0,
      "created_at": "2025-01-01T00:00:00",
      "internal_url": "https://internal.example",
      "external_url": "https://external.example"
    }
  ],
  "meta": {
    "current_page": 2,
    "from": 101,
    "last_page": 650,
    "path": "https://app.reportei.com/api/v2/reports",
    "per_page": 100,
    "to": 200,
    "total": 9750,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/dashboards?per_page=100&page=2&project_id=1"
GET/v2/dashboards/{id}

Retorna os detalhes de um dashboard específico a partir do id.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do dashboard
Exemplo de Resposta JSON
{
  "dashboard": {
    "id": 1,
    "title": "Test title",
    "subtitle": "Subtitle test",
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "comparison_start_date": "2024-01-01",
    "comparison_end_date": "2024-01-31",
    "template_id": 1,
    "client_id": 1,
    "views": 0,
    "created_at": "2025-01-01T00:00:00",
    "internal_url": "https://internal.example",
    "external_url": "https://external.example"
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/dashboards/1"
POST/v2/dashboards

Cria um novo dashboard. Consulte projects para IDs de projetos, integrations para IDs de integrações e templates para IDs de templates.

Corpo da Requisição
CampoTipoObrigatórioDescrição
titlestringSimTítulo do dashboard
subtitlestringSimLegenda do dashboard
startstringSimData de início da análise (YYYY-MM-DD)
endstringSimData de fim da análise (YYYY-MM-DD)
template_idintegerSimID do template
integration_idsarraySimArray de IDs das integrações selecionadas
project_idintegerSimID do projeto
comparison_startstringNãoData de início da comparação (YYYY-MM-DD)
comparison_endstringNãoData de fim da comparação (YYYY-MM-DD)
Exemplo de Requisição JSON
{
  "title": "Dashboard de Vendas",
  "subtitle": "Dashboard de Vendas de 2025",
  "start": "2025-01-01",
  "end": "2025-01-31",
  "comparison_start": "2024-01-01",
  "comparison_end": "2024-01-31",
  "project_id": 1,
  "template_id": 16,
  "integration_ids": [1, 2, 3]
}
Exemplo de Resposta JSON
{
  "dashboard": {
    "id": 2,
    "title": "Dashboard de Vendas",
    "subtitle": "Dashboard de Vendas de 2025",
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "comparison_start_date": "2024-01-01",
    "comparison_end_date": "2024-01-31",
    "template_id": 16,
    "views": 0,
    "created_at": "2025-01-01T00:00:00",
    "internal_url": "https://internal.example",
    "external_url": "https://external.example"
  }
}
Copiar como cURL
curl -s -X POST -H "Authorization: Bearer seu-token-aqui" -H "Content-Type: application/json" \
  -d '{"title":"Dashboard de Vendas","subtitle":"Dashboard de Vendas de 2025","start":"2025-01-01","end":"2025-01-31","comparison_start":"2024-01-01","comparison_end":"2024-01-31","template_id":16,"integration_ids":[1,2,3],"project_id":1}' \
  https://app.reportei.com/api/v2/dashboards

Webhooks

Configure webhooks para receber notificações em tempo real sobre eventos na plataforma.

GET/v2/webhooks

Retorna uma lista paginada de todos os webhooks em que o usuário está inscrito.

Parâmetros
NomeTipoObrigatórioDescrição
project_idintegerNãoFiltrar por projeto (client_id)
event_typestringNãoFiltrar por tipo de evento
sourcestringNãoFiltrar por source (custom, make, zapier, n8n, etc)
statusintegerNãoFiltrar por status
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página
sortBystringNãoCampo para ordenação
descendingbooleanNãoOrdenação descendente
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "url": "http://localhost:5678/webhook-test",
      "event_type": "report_created",
      "source": "custom",
      "company_id": 1,
      "project_id": 1,
      "status": 1,
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    },
    {
      "id": 2,
      "url": "http://localhost:5678/webhook-test-2",
      "event_type": "report_created",
      "source": "make",
      "company_id": 1,
      "project_id": null,
      "status": 1,
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http://api.reportei.com/v2/webhooks",
    "per_page": 15,
    "to": 2,
    "total": 2,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  https://app.reportei.com/api/v2/webhooks
GET/v2/webhooks/events

Retorna uma lista de todos os eventos de webhook disponíveis na API, independente de subscriptions.

Exemplo de Resposta JSON
{
  "events": ["report_viewed", "report_created", "dashboard_created", "automation_executed", "control_goal_met", "control_goal_not_met", "timeline_milestone_added"]
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  https://app.reportei.com/api/v2/webhooks/events
GET/v2/webhooks/{id}

Retorna os detalhes de uma inscrição de webhook específica a partir do id.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do webhook
Exemplo de Resposta JSON
{
  "webhook": {
    "id": 1,
    "url": "http://localhost:5678/webhook-test",
    "event_type": "report_created",
    "source": "custom",
    "company_id": 1,
    "project_id": 1,
    "status": 1,
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  https://app.reportei.com/api/v2/webhooks/1
POST/v2/webhooks

Cria uma nova inscrição de webhook para algum evento.

Corpo da Requisição
CampoTipoObrigatórioDescrição
urlstringSimURL de callback para receber os eventos
event_typestringSimTipo de evento a monitorar
project_idintegerNãoID do projeto para filtrar eventos de um projeto específico
Exemplo de Requisição JSON
{
  "url": "http://localhost:5678/webhook-test",
  "event_type": "report_created",
  "project_id": 1
}
Exemplo de Resposta JSON
{
  "webhook": {
    "id": 1,
    "url": "http://localhost:5678/webhook-test",
    "event_type": "report_created",
    "source": "custom",
    "company_id": 1,
    "project_id": 1,
    "status": 1,
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -X POST -H "Authorization: Bearer seu-token-aqui" -H "Content-Type: application/json" \
  -d '{"url":"http://localhost:5678/webhook-test","event_type":"report_created","project_id":1}' \
  https://app.reportei.com/api/v2/webhooks
PUT/v2/webhooks/{id}

Atualiza uma inscrição de webhook existente.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do webhook
Corpo da Requisição
CampoTipoObrigatórioDescrição
urlstringNãoURL de callback atualizada
event_typestringNãoTipo de evento atualizado
project_idintegerNãoID do projeto (opcional)
Exemplo de Requisição JSON
{
  "url": "http://localhost:5678/webhook-test-updated",
  "event_type": "report_created",
  "project_id": 1
}
Exemplo de Resposta JSON
{
  "webhook": {
    "id": 1,
    "url": "http://localhost:5678/webhook-test-updated",
    "event_type": "report_created",
    "source": "custom",
    "company_id": 1,
    "project_id": 1,
    "status": 1,
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -X PUT -H "Authorization: Bearer seu-token-aqui" -H "Content-Type: application/json" \
  -d '{"url":"http://localhost:5678/webhook-test-updated","event_type":"report_created","project_id":1}' \
  https://app.reportei.com/api/v2/webhooks/1
DELETE/v2/webhooks/{id}

Deleta uma inscrição de webhook.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do webhook
Exemplo de Resposta JSON
{
  "success": true,
  "message": "Webhook successfully removed"
}
Copiar como cURL
curl -s -X DELETE -H "Authorization: Bearer seu-token-aqui" \
  https://app.reportei.com/api/v2/webhooks/1

Eventos da Timeline

Adicione eventos personalizados à timeline dos relatórios para documentar ações e marcos importantes.

GET/v2/timeline-events

Lista todos os eventos das timelines de cada projeto em sua company.

Parâmetros
NomeTipoObrigatórioDescrição
project_idintegerNãoFiltrar por projeto (client_id)
report_idintegerNãoFiltrar por relatório
datestringNãoFiltrar por data (YYYY-MM-DD)
pageintegerNãoNúmero da página
per_pageintegerNãoItens por página
sortBystringNãoCampo para ordenação
descendingbooleanNãoOrdenação descendente
Exemplo de Resposta JSON
{
  "data": [
    {
      "id": 1,
      "title": "Evento 1",
      "content": "<p>Exemplo de conteúdo HTML</p>",
      "project_id": 1,
      "report_id": 1,
      "date": "2025-01-01",
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    },
    {
      "id": 2,
      "title": "Evento 2",
      "content": "<p>Exemplo de conteúdo HTML</p>",
      "project_id": 1,
      "report_id": null,
      "date": "2025-01-01",
      "created_at": "2025-01-01T00:00:00",
      "updated_at": "2025-01-01T00:00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://app.reportei.com/api/v2/timeline-events",
    "per_page": 15,
    "to": 2,
    "total": 2,
    "sortBy": null,
    "descending": false
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/timeline-events"
GET/v2/timeline-events/{id}

Retorna os detalhes de um evento da timeline específico a partir do id.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do evento
Exemplo de Resposta JSON
{
  "timeline_event": {
    "id": 1,
    "title": "Evento 1",
    "content": "<p>Exemplo de conteúdo HTML</p>",
    "project_id": 1,
    "report_id": 1,
    "date": "2025-01-01",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/timeline-events/1"
POST/v2/timeline-events

Cria um novo evento na timeline.

Corpo da Requisição
CampoTipoObrigatórioDescrição
project_idintegerSimID do projeto
report_idintegerNãoID do relatório (opcional)
titlestringSimTítulo do evento
contentstringSimConteúdo do evento (aceita HTML)
Exemplo de Requisição JSON
{
  "title": "Evento 1",
  "content": "<p>Exemplo de conteúdo HTML</p>",
  "report_id": 1,
  "project_id": 1
}
Exemplo de Resposta JSON
{
  "timeline_event": {
    "id": 1,
    "title": "Evento 1",
    "content": "<p>Exemplo de conteúdo HTML</p>",
    "project_id": 1,
    "report_id": 1,
    "date": "2025-01-01",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -X POST -H "Authorization: Bearer seu-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{"title":"Evento 1","content":"<p>Exemplo de conteúdo HTML</p>","report_id":1,"project_id":1}' \
  "https://app.reportei.com/api/v2/timeline-events"
PUT/v2/timeline-events/{id}

Atualiza um evento da timeline existente.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do evento
Corpo da Requisição
CampoTipoObrigatórioDescrição
project_idintegerSimID do projeto
report_idintegerNãoID do relatório (opcional)
titlestringSimTítulo do evento
contentstringSimConteúdo do evento (aceita HTML)
Exemplo de Requisição JSON
{
  "title": "Evento 1 atualizado",
  "content": "<p>Exemplo de conteúdo HTML atualizado</p>",
  "report_id": 1,
  "project_id": 1
}
Exemplo de Resposta JSON
{
  "timeline_event": {
    "id": 1,
    "title": "Evento 1 atualizado",
    "content": "<p>Exemplo de conteúdo HTML atualizado</p>",
    "project_id": 1,
    "report_id": 1,
    "date": "2025-01-01",
    "created_at": "2025-01-01T00:00:00",
    "updated_at": "2025-01-01T00:00:00"
  }
}
Copiar como cURL
curl -s -X PUT -H "Authorization: Bearer seu-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{"title":"Evento 1 atualizado","content":"<p>Exemplo de conteúdo HTML atualizado</p>","report_id":1,"project_id":1}' \
  "https://app.reportei.com/api/v2/timeline-events/1"
DELETE/v2/timeline-events/{id}

Remove um evento da timeline.

Parâmetros
NomeTipoObrigatórioDescrição
idintegerSimID do evento
Exemplo de Resposta JSON
{
  "success": true,
  "message": "Evento da timeline removido com sucesso"
}
Copiar como cURL
curl -s -X DELETE -H "Authorization: Bearer seu-token-aqui" \
  "https://app.reportei.com/api/v2/timeline-events/1"

Como Coletar Métricas

Existem duas formas principais de obter métricas: copiando o payload diretamente de um relatório existente ou construindo a consulta via API.

Opção A: Copiar payload de um relatório

A forma mais rápida de obter métricas é copiando o payload de um relatório ou dashboard existente no Reportei.

Importante: ao copiar o payload, mantenha a opção "Formato para o connect" desmarcada.

Copiar payload de uma rede completa

Passe o mouse em cima da rede desejada e clique no botão "Copiar payload" para obter todas as métricas.

Copiar payload da rede

Copiar payload de uma métrica específica

Passe o mouse em cima do widget desejado e clique em "Gerar consulta de widget" para obter apenas aquela métrica.

Copiar payload do widget

Exemplo: Payload de uma rede completa

Payload copiado ao clicar em "Copiar payload" sobre uma rede inteira. Contém todas as métricas daquela integração.

{
  "start": "2025-01-01",
  "end": "2025-01-31",
  "comparison_start": "2024-01-01",
  "comparison_end": "2024-01-31",
  "integration_id": 123,
  "metrics": [
    {
      "id": "1d59ec11-9288-4949-8e3a-d3f2c8415f211",
      "reference_key": "fb_ads:spend",
      "component": "number_v1",
      "metrics": ["spend"],
      "type": ["spend"]
    },
    {
      "id": "2a48bc22-1234-5678-9abc-def012345678",
      "reference_key": "fb_ads:reach",
      "component": "number_v1",
      "metrics": ["reach"],
      "type": ["reach"]
    },
    {
      "id": "3b59cd33-2345-6789-0def-123456789abc",
      "reference_key": "fb_ads:impressions",
      "component": "number_v1",
      "metrics": ["impressions"],
      "type": ["impressions"]
    }
  ]
}

Exemplo: Payload de uma métrica individual

Payload copiado ao clicar em "Copiar payload" sobre um widget específico.

{
  "start": "2025-01-01",
  "end": "2025-01-31",
  "comparison_start": "2024-01-01",
  "comparison_end": "2024-01-31",
  "integration_id": 123,
  "metrics": [
    {
      "id": "1d59ec11-9288-4949-8e3a-d3f2c8415f211",
      "reference_key": "fb_ads:page_follows",
      "component": "number_v1",
      "metrics": ["page_follows"]
    }
  ]
}

Opção B: Construir consulta via API

Para automações e integrações, você pode construir a consulta de métricas do zero via API.

1

Descobrir o project_id

Liste os projetos para encontrar o ID do projeto desejado.

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/projects?q=Cliente ABC"

Resultado: o project_id é 456

2

Descobrir o integration_id e slug

Liste as integrações do projeto para obter o ID e slug da integração.

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/integrations?project_id=456&slug=facebook_ads"

Resultado: o integration_id é 789 e o slug é facebook_ads

3

Listar métricas disponíveis

Descubra quais métricas estão disponíveis para a integração.

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/metrics?integration_slug=facebook_ads&per_page=100"

Resultado: lista de métricas disponíveis com IDs e estrutura

4

Consultar dados das métricas

Envie a requisição com as métricas desejadas e o período.

curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2025-01-01",
    "end": "2025-01-31",
    "comparison_start": "2024-12-01",
    "comparison_end": "2024-12-31",
    "integration_id": 789,
    "metrics": [
      {
        "id": "a1b2c3d4-1234-5678-9abc-def012345678",
        "reference_key": "fb_ads:spend",
        "component": "number_v1",
        "metrics": ["spend"],
        "type": "spend"
      },
      {
        "id": "b2c3d4e5-2345-6789-0abc-ef0123456789",
        "reference_key": "fb_ads:reach",
        "component": "number_v1",
        "metrics": ["reach"],
        "type": "reach"
      }
    ]
  }' \
  "https://app.reportei.com/api/v2/metrics/get-data"

Resultado: dados das métricas com valores do período e comparação

EtapaEndpointO que obtemos
1GET /v2/projects?q={nome}project_id
2GET /v2/integrations?project_id={id}integration_id, slug
3GET /v2/metrics?integration_slug={slug}Lista de métricas
4POST /v2/metrics/get-dataValores das métricas

Dica de Performance

O endpoint de métricas tem rate limit de 100 requisições por minuto. Para coletar muitas métricas, agrupe widgets na mesma requisição.

Casos de Uso

Exemplos práticos de uso da API Reportei v2, com fluxos completos passo a passo.

Obter valores de métricas de um relatório

Copie o payload diretamente de um relatório ou dashboard existente no Reportei e envie para POST /v2/metrics/get-data. Existem duas opções:

Opção A: Rede completa

Copie o payload de uma rede inteira para obter todas as métricas daquela integração.

Opção B: Métrica individual

Copie o payload de um widget específico para obter apenas aquela métrica.

Veja exemplos completos com payloads e respostas na seção Como Coletar Métricas acima.

Construir consulta de métricas via API

Construa uma consulta de métricas do zero via API, sem precisar copiar payload de um relatório existente. Útil para automações e integrações.

EtapaEndpointO que obtemos
1GET /v2/projects?q={nome}project_id
2GET /v2/integrations?project_id={id}&slug={tipo}integration_id, slug
3GET /v2/metrics?integration_slug={slug}Lista de metricas
4POST /v2/metrics/get-dataValores das metricas

Veja o fluxo completo com requisições e respostas de cada etapa na seção Como Coletar Métricas > Opção B acima.

Criar evento na Linha do Tempo

Registre eventos importantes (campanhas, lançamentos, mudanças) que serão visualizados nos relatórios. O campo content aceita HTML.

Etapa 1: Descobrir o project_id

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/projects?q=Cliente ABC"

Etapa 2 (opcional): Descobrir o report_id para vincular

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/reports?project_id=456&per_page=5"
Exemplo A: Criar evento SEM vincular a relatório
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lancamento Campanha Black Friday",
    "content": "<p>Nova campanha de <strong>Black Friday 2024</strong> lancada!</p><ul><li>Budget: R$ 50.000</li><li>Duracao: 15 dias</li><li>Redes: Facebook Ads + Google Ads</li></ul>",
    "project_id": 456,
    "date": "2024-11-15"
  }' \
  "https://app.reportei.com/api/v2/timeline-events"
Exemplo B: Criar evento vinculado a um relatório
curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lancamento Campanha Black Friday",
    "content": "<p>Nova campanha de <strong>Black Friday 2024</strong> lancada!</p><ul><li>Budget: R$ 50.000</li><li>Duracao: 15 dias</li><li>Redes: Facebook Ads + Google Ads</li></ul>",
    "project_id": 456,
    "report_id": 1234,
    "date": "2024-11-15"
  }' \
  "https://app.reportei.com/api/v2/timeline-events"
Operações adicionais com eventos 
# Atualizar evento
curl -s -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Campanha Black Friday - ATUALIZADO","content":"<p>Campanha encerrada com sucesso!</p>","project_id":456,"date":"2024-11-15"}' \
  "https://app.reportei.com/api/v2/timeline-events/789"

# Deletar evento
curl -s -X DELETE -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/timeline-events/789"

# Listar eventos de um projeto
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.reportei.com/api/v2/timeline-events?project_id=456"

Dicas: Use HTML no conteudo para formatacao rica. Use a data real do evento (lancamento, mudanca), nao a data de criacao do registro. Vincule a relatorios quando o evento for relevante ao periodo.

Migração v1 → v2

Guia completo para migrar seus sistemas da API v1 para a v2.

Base URL v1

https://app.reportei.com/api/v1

Base URL v2 (atual)

https://app.reportei.com/api/v2

A API v1 está em Maintenance Mode

A v1 continuará funcionando, mas apenas receberá correções de segurança e bugs críticos. Novos recursos e melhorias serão desenvolvidos exclusivamente na v2.

Documentação API v1 (legado)

Checklist de Migração

  • 1Atualizar base URL /v1 → /v2
  • 2Renomear recursos: clients → projects
  • 3Atualizar rotas nested para query params
  • 4Ajustar paginação/ordenação em endpoints de listagem
  • 5Revisar mudanças de contrato (tipos, campos obrigatórios, novos endpoints)
  • 6Migrar widgets para API de métricas
  • 7Migrar webhooks para novo CRUD
  • 8Remover dependências de endpoints deprecated em v1

Mudanças de Nomenclatura

A v2 adota nomenclatura mais alinhada com a interface do Reportei. O principal destaque é a mudança de clients para projects.

v1v2Nota
GET /v1/clientsGET /v2/projectsLista projetos
GET /v1/clients/{id}GET /v2/projects/{id}Detalhes do projeto
GET /v1/clients/{id}/reportsGET /v2/reports?project_id={id}Filtro via query param
GET /v1/clients/{id}/integrationsGET /v2/integrations?project_id={id}Filtro via query param
GET /v1/meGET /v2/companies/settingsRota renomeada

Exemplo de Migração

const clients = await fetch('/v1/clients', { headers: { 'Authorization': `Bearer ${token}` } });
const reports = await fetch(`/v1/clients/${clientId}/reports`, { headers: { 'Authorization': `Bearer ${token}` } });

Mapeamento de Parâmetros

Conceitov1v2
Projeto/Clienteclient_idproject_id
Empresacompany_idcompany_id (sem mudança)
Integraçãointegration_idintegration_id (sem mudança)

Paginação e Filtros

A v2 possui paginação consistente em todos os endpoints de listagem.

ParâmetroTipoPadrãoDescrição
pageinteger1Página atual (1-based)
per_pageinteger15Itens por página (max: 100)
sortBystringcreated_atCampo de ordenação
descendingbooleantrueOrdenação descendente
qstring-Busca textual

Exemplo de chamada v2

GET /v2/projects?page=1&per_page=50&sortBy=name&descending=false&q=search

Exemplo de resposta com meta

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://app.reportei.com/api/v2/reports",
    "per_page": 100,
    "to": 7,
    "total": 7,
    "sortBy": null,
    "descending": false
  }
}

Filtros específicos por endpoint

Projects
qBusca por nome
sortByOrdenação (name, created_at, updated_at)
Integrations
project_idFiltrar por projeto
nameFiltrar por nome
slugFiltrar por slug
Reports
project_idFiltrar por projeto
created_atData de criação (YYYY-MM-DD)
updated_atData de atualização (YYYY-MM-DD)
Dashboards
project_idFiltrar por projeto
created_atData de criação (YYYY-MM-DD)
updated_atData de atualização (YYYY-MM-DD)
Webhooks
project_idFiltrar por projeto
event_typeTipo de evento
sourceOrigem (custom, make, zapier, n8n)
statusStatus (active, inactive)
Timeline Events
project_idFiltrar por projeto
report_idFiltrar por relatório
dateData (YYYY-MM-DD)

Migração Endpoint por Endpoint

Tratamento de Erros Padronizado

A v2 possui respostas de erro consistentes e mais informativas.

{
  "error": "Client not found"
}

Recomendação

Migre endpoint por endpoint e rode as duas versões em paralelo durante a transição. Isso permite validar cada mudança antes de desativar completamente a v1.

Changelog

Este changelog documenta todas as mudanças na API do Reportei.

Política de depreciação

Quando algo for marcado como Deprecated, nós: Deprecated

  1. 1. Anunciamos neste changelog com antecedência;
  2. 2. Disponibilizamos um caminho de migração (guia / exemplos);
  3. 3. Recomendamos que você migre para a nova versão o quanto antes.

Convenções usadas

Breaking ChangesMudanças que exigem ação do cliente
AddedNovos endpoints, campos opcionais, recursos
ChangedAlterações compatíveis
DeprecatedAinda funciona, mas será removido
RemovedRemovido (somente em major nova)
FixedCorreções de bugs

[2.0.0]

2026-01-14

Breaking Changes

Mudanças de Nomenclatura

Clientes para Projetos: O recurso /clients foi renomeado para /projects

Reestruturação de rotas nested

Removidas rotas nested em favor de filtros via query parameters

Webhooks

Rota de eventos movida de /v1/webhook/events para /v2/webhooks/events

Integrations - Widgets

Removidas rotas de widgets em favor da nova API de métricas

Company settings

Rota renomeada de /v1/me para /v2/companies/settings

Added

Novos recursos em v2

  • Listagem de integrações: GET /v2/integrations
  • API de Métricas: GET /v2/metrics / POST /v2/metrics/get-data
  • CRUD de Relatórios: POST /v2/reports
  • CRUD de Dashboards: GET, POST /v2/dashboards
  • CRUD completo de Webhooks
  • CRUD de Timeline Events

Paginação padronizada

Todos os endpoints de listagem suportam: page, per_page, sortBy, descending, q

Filtros avançados

Filtros por data (created_at, updated_at), relacionamento (project_id), e status

Deprecated

GET /v1/clients — Migre para GET /v2/projects

GET /v1/clients/{id}/reports — Migre para GET /v2/reports?project_id={id}

GET /v1/integrations/{id}/widgets — Migre para GET /v2/metrics?integration_slug={slug}

GET /v1/me — Migre para GET /v2/companies/settings

[1.x]

Maintenance Mode

Novos recursos serão desenvolvidos exclusivamente na v2. Recomendamos migrar para v2 o quanto antes para aproveitar novos recursos e melhorias de performance.

ReporteiAPI Documentation v2
SiteApp

© 2024 Reportei.