Documentação da API Reportei V2

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

Escolha seu caminho

Sou novo na API Reportei

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

Já uso a API v1 e quero migrar

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

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

Recurso	Endpoints	Descrição
Empresas	GET	Na API v2, companies representa a conta/empresa do usuário na plataforma
Projetos	GET	Gerencie projetos (clientes) da sua conta
Integrações	GET	Na API v2, integrations permitem que você acesse as integrações conectadas aos projetos da sua company
Métricas	GET, POST	Colete dados e métricas das integrações conectadas
Templates	GET	Gerencie templates de relatórios reutilizáveis
Relatórios	GET, POST	Na API v2, reports permitem que você acesse e crie relatórios da sua company
Dashboards	GET, POST	Na API v2, dashboards permitem que você acesse e crie dashboards da sua company
Webhooks	GET, POST, PUT, DELETE	Configure webhooks para receber notificações em tempo real sobre eventos na plataforma
Eventos da Timeline	GET, POST, PUT, DELETE	Adicione 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

1Acesse app.reportei.com
2Faça login na sua conta
3Navegue até Configurações da Empresa
4Acesse a seção "API Reportei"
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 {seu_token_aqui}

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âmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página atual
per_page	integer	15	Itens por página (máx: 100)
sortBy	string	created_at	Campo para ordenação
descending	boolean	false	Ordem 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

# Relatórios de um projeto específico criados em janeiro de 2024
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

Campo	Tipo	Descrição
id	integer	Identificador único do recurso
created_at	string (datetime)	Data de criação (ex.: "2024-09-24 17:07:34")
updated_at	string (datetime)	Data da última atualização (ex.: "2024-09-24 17:07:34")

Limites de Requisição

Para garantir performance otimizada e equidade, a API impõe limites de requisição (rate limits). Cada endpoint tem um limite específico de requisições por minuto.

Limites por Tipo de Operação

Tipo de Operação	Limite	Endpoints Afetados
GET Leitura	120 req/min	Todos os endpoints GET (listagem e detalhes)
POST Criacao	60 req/min	POST /projects, /reports, /dashboards, /webhooks, /timeline-events
POST Criação de Métricas	30 req/min	POST /metrics/get-data
PUT Atualização	60 req/min	PUT/PATCH em todos os recursos
DELETE Deleção	60 req/min	DELETE em todos os recursos

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

Nome	Tipo	Obrigatorio	Descricao
page	integer	Nao	Número da página
per_page	integer	Nao	Itens por página (padrão: 100)
sortBy	string	Nao	Campo para ordenação
descending	boolean	Nao	Ordenaçã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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Nome	Tipo	Obrigatorio	Descricao
project_id	integer	Nao	Filtrar por projeto específico
name	string	Nao	Filtrar pelo nome da integração
slug	string	Nao	Filtrar pelo tipo de integração (facebook_ads, google_analytics_4, etc)
page	integer	Nao	Número da página
per_page	integer	Nao	Itens por página (máx: 100)
sortBy	string	Nao	Campo para ordenação
descending	boolean	Nao	Ordem 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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Nome	Tipo	Obrigatorio	Descricao
integration_slug	string	Sim	Slug da integração (ex: facebook_ads, google_analytics)
page	integer	Nao	Número da página
per_page	integer	Nao	Itens 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

Campo	Tipo	Obrigatorio	Descricao
start	string	Sim	Data de início do período (YYYY-MM-DD)
end	string	Sim	Data de fim do período (YYYY-MM-DD)
integration_id	integer	Sim	ID da integração
metrics	array	Sim	Array de métricas a serem consultadas
comparison_start	string	Nao	Data de início do período de comparação (YYYY-MM-DD)
comparison_end	string	Nao	Data 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

Nome	Tipo	Obrigatorio	Descricao
page	integer	Nao	Número da página
per_page	integer	Nao	Itens 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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Nome	Tipo	Obrigatorio	Descricao
project_id	integer	Nao	Filtrar por projeto específico (client_id)
created_at	string	Nao	Filtrar por data de criação (YYYY-MM-DD)
updated_at	string	Nao	Filtrar por data de atualização (YYYY-MM-DD)
page	integer	Nao	Número da página
per_page	integer	Nao	Itens por página (padrão: 100)
sortBy	string	Nao	Campo para ordenação
descending	boolean	Nao	Ordenaçã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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Campo	Tipo	Obrigatorio	Descricao
title	string	Sim	Título do relatório
subtitle	string	Sim	Legenda do relatório
start	string	Sim	Data de início da análise (YYYY-MM-DD)
end	string	Sim	Data de fim da análise (YYYY-MM-DD)
template_id	integer	Sim	ID do template
integration_ids	array	Sim	Array de IDs das integrações selecionadas
project_id	integer	Sim	ID do projeto
comparison_start	string	Nao	Data de início da comparação (YYYY-MM-DD)
comparison_end	string	Nao	Data 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

Nome	Tipo	Obrigatorio	Descricao
project_id	integer	Nao	Filtrar por projeto específico (client_id)
created_at	string	Nao	Filtrar por data de criação (YYYY-MM-DD)
updated_at	string	Nao	Filtrar por data de atualização (YYYY-MM-DD)
page	integer	Nao	Número da página
per_page	integer	Nao	Itens por página (padrão: 100)
sortBy	string	Nao	Campo para ordenação
descending	boolean	Nao	Ordenaçã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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Campo	Tipo	Obrigatorio	Descricao
title	string	Sim	Titulo do dashboard
subtitle	string	Sim	Legenda do dashboard
start	string	Sim	Data de inicio da analise (YYYY-MM-DD)
end	string	Sim	Data de fim da analise (YYYY-MM-DD)
template_id	integer	Sim	ID do template
integration_ids	array	Sim	Array de IDs das integracoes selecionadas
project_id	integer	Sim	ID do projeto
comparison_start	string	Nao	Data de inicio da comparacao (YYYY-MM-DD)
comparison_end	string	Nao	Data de fim da comparacao (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 usuario esta inscrito (webhook_subscriptions da company).

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
project_id	integer	Nao	Filtrar por projeto (client_id)
event_type	string	Nao	Filtrar por tipo de evento
source	string	Nao	Filtrar por source (custom, make, zapier, n8n, etc)
status	integer	Nao	Filtrar por status
page	integer	Nao	Numero da pagina
per_page	integer	Nao	Itens por pagina
sortBy	string	Nao	Campo para ordenacao
descending	boolean	Nao	Ordenacao 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 disponiveis 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 inscricao de webhook especifica a partir do id.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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 inscricao de webhook para algum evento. Retorna 201 Created com a representacao JSON do webhook. O parametro source e automaticamente preenchido no backend; quando nao for de nenhum conector (make, zapier, n8n, etc), sera salvo como "custom".

Corpo da Requisição

Campo	Tipo	Obrigatorio	Descricao
url	string	Sim	URL de callback para receber os eventos
event_type	string	Sim	Tipo de evento a monitorar
project_id	integer	Nao	ID do projeto para filtrar eventos de um projeto especifico

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 inscricao de webhook existente. Retorna 200 OK com a representacao JSON atualizada. Nota: se o usuario editar uma inscricao de algum conector (make, n8n, etc), aquele webhook pode deixar de funcionar na plataforma do conector.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID do webhook

Corpo da Requisição

Campo	Tipo	Obrigatorio	Descricao
url	string	Nao	URL de callback atualizada
event_type	string	Nao	Tipo de evento atualizado
project_id	integer	Nao	ID 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 inscricao de webhook. Retorna 200 OK se a delecao for bem-sucedida. Nota: se o usuario deletar uma inscricao de algum conector (make, n8n, etc), aquele webhook deixara de funcionar na plataforma do conector.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Nome	Tipo	Obrigatorio	Descricao
project_id	integer	Nao	Filtrar por projeto (client_id)
report_id	integer	Nao	Filtrar por relatório
date	string	Nao	Filtrar por data (YYYY-MM-DD)
page	integer	Nao	Número da página
per_page	integer	Nao	Itens por página
sortBy	string	Nao	Campo para ordenação
descending	boolean	Nao	Ordenaçã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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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

Campo	Tipo	Obrigatorio	Descricao
project_id	integer	Sim	ID do projeto
report_id	integer	Nao	ID do relatório (opcional)
title	string	Sim	Título do evento
content	string	Sim	Conteú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. Retorna 200 OK com a representação JSON atualizada do evento.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID do evento

Corpo da Requisição

Campo	Tipo	Obrigatorio	Descricao
project_id	integer	Sim	ID do projeto
report_id	integer	Nao	ID do relatório (opcional)
title	string	Sim	Título do evento
content	string	Sim	Conteú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

Nome	Tipo	Obrigatorio	Descricao
id	integer	Sim	ID 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 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.

Exemplo: Payload de uma rede completa

Payload copiado ao clicar em "Copiar payload" sobre uma rede inteira. Contem todas as metricas daquela integracao.

{
  "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 metrica individual

Payload copiado ao clicar em "Copiar payload" sobre um widget especifico.

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

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 e 456

Descobrir o integration_id e slug

Liste as integracoes do projeto para obter o ID e slug da integracao.

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

Resultado: o integration_id e 789 e o slug e facebook_ads

Listar metricas disponiveis

Descubra quais metricas estao disponiveis para a integracao.

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

Resultado: lista de metricas disponiveis com IDs e estrutura

Consultar dados das metricas

Envie a requisicao com as metricas desejadas e o periodo.

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 metricas com valores do periodo e comparacao

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

Dica de Performance

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

Casos de Uso

Exemplos praticos de uso da API Reportei v2, com fluxos completos passo a passo.

Obter valores de metricas de um relatorio

Copie o payload diretamente de um relatorio ou dashboard existente no Reportei e envie para POST /v2/metrics/get-data. Existem duas opcoes:

Opcao A: Rede completa

Copie o payload de uma rede inteira para obter todas as metricas daquela integracao.

Opcao B: Metrica individual

Copie o payload de um widget especifico para obter apenas aquela metrica.

Veja exemplos completos com payloads e respostas na secao Como Coletar Metricas acima.

Construir consulta de metricas via API

Construa uma consulta de metricas do zero via API, sem precisar copiar payload de um relatorio existente. Util para automacoes e integracoes.

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

Veja o fluxo completo com requisicoes e respostas de cada etapa na secao Como Coletar Metricas > Opcao B acima.

Criar evento na Linha do Tempo

Registre eventos importantes (campanhas, lancamentos, mudancas) que serao visualizados nos relatorios. 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 para v2

Este guia descreve como migrar integrações da API v1 para v2 do Reportei.

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.

Checklist de Migração

1Atualizar base URL /v1 → /v2
2Renomear recursos: clients → projects
3Atualizar rotas nested para query params (ex: /clients/{id}/reports → /reports?project_id={id})
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.

v1	v2	Nota
GET /v1/clients	GET /v2/projects	Lista projetos
GET /v1/clients/{id}	GET /v2/projects/{id}	Detalhes do projeto
GET /v1/clients/{id}/reports	GET /v2/reports?project_id={id}	Filtro via query param
GET /v1/clients/{id}/integrations	GET /v2/integrations?project_id={id}	Filtro via query param
GET /v1/me	GET /v2/companies/settings	Rota renomeada

Exemplo de Migração

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

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

Mapeamento de Parâmetros

Conceito	v1	v2
Projeto/Cliente	client_id	project_id
Empresa	company_id	company_id (sem mudanca)
Integracao	integration_id	integration_id (sem mudanca)

Paginação e Filtros

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

Parametro	Tipo	Padrao	Descricao
page	integer	1	Pagina atual (1-based)
per_page	integer	15	Itens por pagina (max: 100)
sortBy	string	created_at	Campo de ordenacao
descending	boolean	true	Ordenacao descendente
q	string	-	Busca textual

Exemplo de chamada v2

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

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

sortByOrdenacao (name, created_at, updated_at)

Integrations

project_idFiltrar por projeto

nameFiltrar por nome

slugFiltrar por slug

Reports

project_idFiltrar por projeto

created_atData de criacao (YYYY-MM-DD)

updated_atData de atualizacao (YYYY-MM-DD)

Dashboards

project_idFiltrar por projeto

created_atData de criacao (YYYY-MM-DD)

updated_atData de atualizacao (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 relatorio

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 versoes em paralelo durante a transicao. Isso permite validar cada mudanca 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, nos:

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

Convencoes usadas

Breaking ChangesMudancas que exigem acao do cliente

AddedNovos endpoints, campos opcionais, recursos

ChangedAlteracoes compativeis

DeprecatedAinda funciona, mas sera removido

RemovedRemovido (somente em major nova)

FixedCorrecoes de bugs

[2.0.0]

2026-01-14

Breaking Changes

Mudancas de Nomenclatura

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

Reestruturacao 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 metricas

Company settings

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

Added

Novos recursos em v2

Listagem de integracoes: GET /v2/integrations
API de Metricas: GET /v2/metrics e POST /v2/metrics/get-data
CRUD de Relatorios: POST /v2/reports
CRUD de Dashboards: GET, POST /v2/dashboards
CRUD completo de Webhooks
CRUD de Timeline Events

Paginacao padronizada

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

Filtros avancados

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 serao desenvolvidos exclusivamente na v2. Recomendamos migrar para v2 o quanto antes para aproveitar novos recursos e melhorias de performance.