Flux API — Consulte posts, agendamentos e aprovações do Flux

Flux API v1

Somente leitura

Bem-vindo à API do Flux

O Flux é a plataforma de planejamento, aprovação e agendamento de conteúdo para redes sociais do ecossistema Reportei. A API v1 é pública e somente leitura: ela responde o que está agendado, o que está esperando aprovação, o que já foi publicado e em quais contas.

O modelo é simples. Um projeto é o cliente final da agência, com contas sociais conectadas e fuso horário próprio. Um post é uma peça para uma conta; a mesma peça publicada em várias redes compartilha um grupo de conteúdo. Antes de ir ao ar, o conteúdo pode passar por ciclos de aprovação com revisores.

Projetos

Os clientes que o seu token alcança, com fuso, idioma e as contas conectadas de cada um.

Posts e agendamentos

Filtre por projeto, período, status, rede e tipo de peça. Legenda, mídias e grupo de conteúdo incluídos.

Aprovações

Quem aprovou, quem pediu ajuste e o que escreveu — mais os pacotes enviados ao cliente.

Contas conectadas

Detecte uma autorização expirada antes de a publicação falhar.

Base URL

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

Autenticação

Toda requisição exige um token de acesso no header Authorization, no formato Bearer. O token é vinculado a uma conta e só devolve dados dessa conta — não existe parâmetro capaz de alcançar dados de outra.

Bearer token

Envie o token em toda requisição, junto do header Accept.

Authorization: Bearer flux_19ZcURVroVw2mRBj41EPxstH8IPgH2XpC6ZtSlBeSJ1XNK6K
Accept: application/json

Como gerar o token

Já autenticado no Flux, acesse Configurações → Tokens de API, em /company/edit/api

1Na seção Tokens de API, clique em Criar token e dê um nome que identifique o uso (por exemplo, "Integração do BI").
2Marque os escopos que a integração precisa. Um endpoint chamado sem o escopo correspondente responde 403.
3Escolha o alcance de projetos: todos os atuais e próximos, todos os atuais, ou uma seleção específica.
4Confirme. O token aparece uma única vez, começando com flux_.
5Copie e guarde num gerenciador de segredos. Para revogar, use o botão de revogar na mesma tela — o efeito é imediato.

O token aparece uma única vez

O banco guarda apenas o hash: depois de fechar a tela, o valor não é recuperável. Se você perder o token, ou se ele for exposto, revogue-o e emita outro. Nunca coloque o token em código versionado ou em aplicação client-side.

Escopos

Cada token carrega uma lista de escopos, marcada no momento da criação. Um endpoint chamado sem o escopo correspondente responde 403 com o escopo exigido em details.required_scope.

Escopo	Concede
projects:read	GET /projects, GET /projects/{id}
posts:read	GET /posts, GET /posts/{id}, GET /posts/group/{asset_group_id}
reviews:read	GET /posts/{id}/reviews, GET /review-groups, GET /review-groups/{id}
integrations:read	GET /integrations

Escopos de escrita (posts:create, posts:update, media:write, reviews:create) estão reservados e ainda não habilitam nenhum endpoint.

Alcance de projetos

Além dos escopos, um token tem um alcance de projetos definido na emissão. Você não consegue emitir um token com mais alcance do que o seu próprio dentro do Flux.

Todos os atuais e próximos

Alcança todos os projetos da conta, inclusive os criados depois da emissão do token.

Todos os atuais

Retrato de hoje: vira uma lista explícita, e projetos novos não entram.

Seleção específica

Só os projetos escolhidos. Um projeto criado depois não entra automaticamente; é preciso emitir um token novo.

Fora do alcance responde 404, não 403

Projeto fora do alcance do token responde 404, igual a projeto inexistente — a API não distingue os dois casos, para não revelar a existência de dados que você não pode ler. Isso vale para GET /projects/{id}, GET /posts/{id}, o filtro ?project_id= e qualquer combinação de filtros na listagem.

Se você não sabe qual é o alcance do seu token, GET /api/v1/projects responde exatamente com o que ele enxerga.

Convenções

Paginação, fuso horário, expiração das mídias e limite de requisições valem para todos os endpoints.

Paginação

As listagens usam o formato padrão {data, links, meta}. O parâmetro per_page aceita de 1 a 50, com padrão 15 — acima de 50 a API responde 422. O parâmetro page começa em 1.

{
  "data": [],
  "links": {
    "first": "https://flux.reportei.com/api/v1/projects?per_page=2&page=1",
    "last": "https://flux.reportei.com/api/v1/projects?per_page=2&page=3",
    "prev": null,
    "next": "https://flux.reportei.com/api/v1/projects?per_page=2&page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://flux.reportei.com/api/v1/projects",
    "per_page": 2,
    "to": 2,
    "total": 5
  }
}

Siga links.next como ele vem, sem remontar a URL: ele já carrega os filtros e o per_page da chamada original.

Datas e fuso horário

Toda data e hora sai em ISO-8601 com o offset do fuso do projeto. Cada projeto tem o seu, e o mesmo instante aparece com offsets diferentes em projetos diferentes.

"schedule_at": "2026-09-15T07:00:00-03:00"   // projeto em America/Sao_Paulo
"schedule_at": "2026-09-15T07:00:00+01:00"   // projeto em Europe/Lisbon

Os filtros start_date e end_date recebem apenas a data (AAAA-MM-DD) e são interpretados no fuso do projeto, com os limites inclusivos (de 00:00:00 a 23:59:59).

URLs de mídia expiram em 48 horas

As URLs em media[].url são assinadas e temporárias: expiram 48 horas após a resposta, como indicado em media[].url_expires_at. O mesmo vale para o thumbnail dos posts de um grupo.

Não persista essas URLs. Se precisar do arquivo, baixe-o e armazene o binário do seu lado — guardar a URL resulta em link quebrado dois dias depois. Para obter uma URL nova, consulte o post outra vez.

Limite de requisições

120requisições por minuto, por token

Ao exceder, a API responde 429 com o header Retry-After indicando quantos segundos aguardar. Respeite o intervalo em vez de tentar de novo imediatamente.

Status de post

O campo status usa um vocabulário público estável, que agrupa os estados internos do Flux. Os estados internos podem mudar entre versões; estes sete valores, não.

draft

Rascunho, ainda em edição

in_review

Em aprovação com o cliente ou revisor

scheduled

Aprovado e agendado, aguardando a hora de publicar

publishing

Em publicação neste momento

published

Publicado com sucesso

failed

A publicação falhou

archived

Arquivado

Situação da aprovação

O campo review_status só é preenchido enquanto o post está em in_review; nos demais status vem null. Em in_review ele é sempre um dos três valores abaixo — nunca null.

pending

Enviado para revisão, sem resposta ainda

approved

Aprovado pelo revisor

request_changes

Revisor pediu ajustes

Redes e tipos de peça

O campo network identifica a integração específica e network_group agrupa as variações da mesma rede — instagram e instagram_business, por exemplo, compartilham o grupo instagram.

network

instagraminstagram_businessfacebookthreadsxyoutubelinkedinlinkedin_personaltiktokpinterestgoogle_my_business

network_group

instagramfacebookthreadsxyoutubelinkedintiktokpinterestgoogle_my_business

type

feedstoryreelsshortsphoto

Projetos

Um projeto é o cliente final da agência. É por aqui que se começa: o id devolvido aqui é o project_id dos demais endpoints, e o timezone do projeto é o fuso de todas as datas dos posts dele.

GET/api/v1/projectsprojects:read

Listar projetos

Projetos da conta do token, com as contas conectadas de cada um. Por padrão a listagem traz apenas os ativos.

Nome	Tipo	Descrição
archived	boolean	1 retorna somente os projetos arquivados
all	boolean	1 retorna ativos e arquivados juntos
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/projects?per_page=2"

GET/api/v1/projects/{id}projects:read

Consultar um projeto

Um projeto pelo id, com as contas conectadas. Um projeto que não existe, que foi excluído ou que pertence a outra conta responde 404.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/projects/5"

O campo status de cada integração indica a saúde da conexão: active quando a conta está conectada e válida, e outro valor quando exige reconexão pelo painel do Flux.

Posts

Posts são as peças de conteúdo, uma por conta de destino. A mesma peça publicada em várias redes compartilha um grupo de conteúdo, cujo id vem em asset_group_id.

GET/api/v1/postsposts:read

Listar posts

Posts com filtros combináveis de projeto, janela de datas, status, rede, tipo de peça e situação de aprovação.

Nome	Tipo	Descrição
project_id	integer	Restringe a um projeto. Um id fora do alcance do token responde 404
start_date	date	Posts com schedule_at a partir desta data, inclusive (AAAA-MM-DD)
end_date	date	Posts com schedule_at até esta data, inclusive. Precisa ser maior ou igual a start_date
status	string \| array	Um ou mais status públicos. Aceita status=scheduled e status[]=scheduled&status[]=published
network	string \| array	Filtra pela rede. Aceita valor único ou lista
network_group	string	Filtra pelo grupo de rede
type	string \| array	feed, story, reels, shorts ou photo
review_status	string	pending, approved ou request_changes. Como só posts em revisão têm esse campo, o filtro restringe implicitamente a status=in_review
order	string	schedule_at (padrão) ou created_at
direction	string	asc (padrão) ou desc
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts?status=published&per_page=1"

Filtro inválido responde 422

Parâmetros desconhecidos são ignorados, mas um valor inválido em um parâmetro conhecido responde 422 — a API não devolve lista vazia para filtro errado.

Campos do post

Campo	Descrição
id	Identificador do post no Flux
asset_group_id	Grupo de conteúdo do post: a mesma peça publicada em várias redes compartilha esse id
project	Projeto dono do post, com o fuso usado nas datas
network	Rede de destino (network) e o grupo que reúne suas variações (network_group)
account	Conta conectada onde o post será publicado; id é o identificador na rede
type	feed, story, reels, shorts ou photo
status	Status público do post
review_status	Situação da aprovação, apenas quando status é in_review
caption	Legenda final em texto plano, já com os placeholders resolvidos. Quando o post não tem legenda própria, cai para a legenda do grupo de conteúdo
first_comment	Primeiro comentário programado (Instagram), quando houver
schedule_at	Data e hora do agendamento. null em post sem agendamento definido
published_url	URL do post na rede, preenchida após a publicação
media	Arquivos anexados, na ordem de publicação

Campos da mídia

Campo	Descrição
id	Identificador do arquivo
type	image, video ou pdf
url	URL temporária assinada — expira em 48h, não persista
url_expires_at	Momento exato da expiração da URL
width	Largura em pixels, quando conhecida
height	Altura em pixels, quando conhecida
aspect_ratio	Proporção, por exemplo 4:5

Campos podem vir null quando o arquivo foi enviado antes de o Flux passar a extrair aquele metadado.

GET/api/v1/posts/{id}posts:read

Consultar um post

O mesmo objeto da listagem, sob a chave data, mais o bloco review com o agregado da aprovação. Um post que não existe, que foi excluído ou que pertence a outra conta responde 404.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts/30"

O bloco review

GET /posts/{id} devolve o mesmo objeto da listagem mais o bloco review, com o agregado da aprovação. Ele só é preenchido enquanto o post está em in_review; nos demais status vem null. O bloco não existe na listagem: agregá-lo por linha custaria uma consulta por post.

Campo	Descrição
status	Situação agregada da aprovação. Sempre igual ao review_status do mesmo post
cycle_started_at	Início do ciclo de aprovação corrente. null em post que nunca foi reenviado para revisão
reviewers_total	Revisores atribuídos ao post neste momento
decided	Decisões válidas no ciclo corrente, uma por revisor
approved	Quantas dessas decisões foram aprovações
request_changes	Quantas dessas decisões pediram ajuste
pending	Revisores atribuídos que ainda não decidiram no ciclo corrente

decided + pending pode não fechar com reviewers_total

decided conta decisões, pending conta revisores. Um revisor que decidiu e depois foi retirado do post continua em decided mas não entra em reviewers_total. A leitura confiável de "falta alguém aprovar" é pending > 0.

GET/api/v1/posts/group/{asset_group_id}posts:read

Consultar um grupo de conteúdo

O resumo do lote — o que ele é como um todo — e os posts, resumidos. Um grupo que não existe, cujos posts foram excluídos ou que pertence a outra conta responde 404.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts/group/71"

Campos do grupo de conteúdo

Um grupo de conteúdo é a peça escrita uma vez e publicada em várias redes: cada rede vira um post, e todos carregam o mesmo asset_group_id.

Campo	Descrição
id	Identificador do grupo — é o asset_group_id que os posts carregam
project	Projeto dono do grupo, com o fuso usado nas datas
review_group_id	Grupo de aprovação a que o lote pertence. null quando nunca foi enviado para revisão
posts_count	Posts do grupo, um por rede
networks	Redes alcançadas pelo lote, sem repetir
accounts	Contas conectadas onde o lote será publicado, sem repetir
status_summary	Quantos posts em cada status, só os status presentes, na ordem do ciclo de vida
schedule_dates	Datas de agendamento do lote, sem repetir e em ordem. Post sem agendamento não entra

O grupo vem inteiro, sem paginação: são poucos posts, um por rede. Cada post vem resumido, com um thumbnail da primeira mídia — legenda, mídias e o bloco review continuam em GET /posts/{id}.

Contas conectadas

Lista as contas de rede social conectadas aos projetos da conta. É o endpoint que permite detectar uma conta expirada antes de a publicação falhar.

GET/api/v1/integrationsintegrations:read

Listar contas conectadas

As contas de rede social conectadas aos projetos que o token alcança, com a situação de cada conexão.

Nome	Tipo	Descrição
project_id	integer	Restringe a um projeto
network	string \| array	Filtra por rede. Aceita network=facebook ou network[]=facebook&network[]=instagram
status	string	active, expired ou deleted
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/integrations?status=expired"

Status da conta conectada

active

Conectada e válida

expired

A autorização caiu; a conta precisa ser reconectada no Flux

deleted

A conta foi desconectada do projeto

Conta desconectada continua aparecendo

Uma conta desconectada aparece com status deleted em vez de desaparecer: posts publicados por ela seguem apontando para esse registro, e a listagem precisa explicar esses posts.

Reconexão da mesma conta no mesmo projeto faz o registro antigo voltar a valer: o registro expirado passa a responder active e não aparece mais em ?status=expired. O filtro sempre concorda com o status que vem no corpo.

Aprovações

Grupos de aprovação são os pacotes de posts enviados de uma vez ao cliente. Cada post dentro deles acumula decisões de revisores, e esse histórico é auditoria: nada é removido dele.

GET/api/v1/posts/{id}/reviewsreviews:read

Listar as decisões de aprovação de um post

Histórico das decisões de aprovação do post, em ordem cronológica. É auditoria: nada é removido dessa lista. Um post fora do alcance do token responde 404.

Nome	Tipo	Descrição
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts/84/reviews"

Campos da decisão

Campo	Descrição
reviewer	Quem decidiu. Apenas nome e e-mail — nenhum outro dado do revisor é exposto
status	approved ou request_changes. Nunca pending: pendente é ausência de decisão
reasons	Motivos marcados no pedido de ajuste, quando houver
comments	Comentário livre do revisor
is_invalidated	true quando a decisão foi anulada por uma edição posterior do post
decided_at	Momento da decisão
created_at	Momento em que a decisão foi registrada

GET/api/v1/review-groupsreviews:read

Listar grupos de aprovação

Os pacotes de posts enviados de uma vez ao cliente. Os mais recentes vêm primeiro.

Nome	Tipo	Descrição
project_id	integer	Restringe a um projeto
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/review-groups?project_id=1"

Campos do grupo de aprovação

Campo	Descrição
posts_count	Todos os posts do grupo, em qualquer status
review_summary	Quantos posts ainda em revisão estão em cada situação
reviewers_count	Revisores atribuídos ao grupo

review_summary pode somar menos que posts_count

review_summary cobre só os posts que ainda estão em in_review. Um post que já foi agendado ou publicado saiu da fila de aprovação e não entra na soma. A diferença é intencional: chamar de "pendente" um post já publicado seria pior que deixar a conta aberta.

GET/api/v1/review-groups/{id}reviews:read

Consultar um grupo de aprovação

O mesmo grupo da listagem e, junto, todos os posts do pacote. É o endpoint para abrir um grupo: saber o que foi enviado ao cliente e em que pé está cada post.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/review-groups/419"

O grupo vem inteiro, sem paginação — um pacote é fechado quando é enviado ao cliente. A ordem é a do grupo, a mesma que o cliente vê na tela de aprovação, e é ela que dá sentido à numeração usada no feedback ("o terceiro post"). Post excluído não aparece e não conta em posts_count.

Como funciona a aprovação no Flux

Quatro regras explicam praticamente todas as dúvidas sobre os campos de aprovação.

1. Pendente é ausência de decisão, não um valor gravado

Uma decisão só existe como approved ou request_changes. "Pendente" quer dizer que o revisor ainda não respondeu — não há linha nenhuma em GET /posts/{id}/reviews para ele. Exemplo: post com 3 revisores atribuídos e nenhuma resposta devolve "data": [] no histórico.

"review": { "status": "pending", "reviewers_total": 3, "decided": 0, "pending": 3 }

2. "Pedido de mudança" tem precedência

Basta um revisor pedir ajustes para o post inteiro ficar em request_changes, mesmo que os outros já tenham aprovado. É a mesma regra que o Flux usa na tela.

3 revisores: um aprovou, um pediu ajustes, um não respondeu

"review": {
  "status": "request_changes",
  "reviewers_total": 3, "decided": 2, "approved": 1, "request_changes": 1, "pending": 1
}

Os 3 aprovaram

"review": {
  "status": "approved",
  "reviewers_total": 3, "decided": 3, "approved": 3, "request_changes": 0, "pending": 0
}

3. Um post pode voltar para aprovação quantas vezes for preciso

Depois de um pedido de ajustes, o post é corrigido e reenviado — isso abre um ciclo novo. cycle_started_at marca o começo do ciclo corrente, e decisões anteriores a ele pertencem ao passado: continuam visíveis em GET /posts/{id}/reviews, mas não entram no agregado. Exemplo: aprovação em 01/09, reenvio em 05/09 e pedido de ajustes em 06/09, com 3 revisores.

"review": {
  "status": "request_changes",
  "cycle_started_at": "2026-09-05T09:00:00-03:00",
  "reviewers_total": 3, "decided": 1, "approved": 0, "request_changes": 1, "pending": 2
}

A aprovação de 01/09 aparece no histórico, mas decided é 1 — só a decisão do ciclo atual conta. Um post que nunca foi reenviado tem cycle_started_at null e considera todas as decisões válidas.

4. Decisão anulada aparece marcada, não desaparece

Editar um post já aprovado anula as aprovações: elas passam a valer como se não tivessem acontecido, e o post volta a esperar resposta. No histórico, essas decisões vêm com is_invalidated true; no agregado, não são contadas.

"data": [
  {
    "id": 55020,
    "status": "approved",
    "is_invalidated": true,
    "decided_at": "2026-09-08T10:12:00-03:00"
  }
]

Erros

Todo erro sai no mesmo envelope, com um código estável para tratamento programático e um identificador de requisição para o suporte.

{
  "error": {
    "type": "invalid_request",
    "message": "Os parâmetros enviados são inválidos.",
    "details": { "per_page": ["The per page field must not be greater than 50."] },
    "request_id": "01M1EGMBW481B34NQKA1Z2MYKN"
  }
}

Campo	Descrição
type	Código estável, adequado para tratamento programático
message	Descrição legível. Pode mudar entre versões — não use em condicional
details	Presente apenas em alguns erros, com os campos rejeitados
request_id	Também devolvido no header X-Request-Id. Informe-o ao suporte ao relatar um problema; é por ele que rastreamos a requisição

Códigos HTTP

401 unauthorized

Token ausente, inválido, expirado ou revogado

403 insufficient_scope

Token válido, sem o escopo do endpoint. details.required_scope traz o escopo exigido

404 not_found

Recurso inexistente, excluído ou de outra conta

405 method_not_allowed

Método HTTP não suportado pelo endpoint

422 invalid_request

Parâmetro inválido. details lista os campos

429 rate_limit_exceeded

Passou do limite de requisições. Aguarde o que indica Retry-After

500 internal_error

Falha no Flux. Informe o request_id ao suporte

Por que 401 e 404 são propositalmente opacos

O 401 é idêntico para token ausente, inexistente, expirado e revogado — a API não confirma se um token existe. Pelo mesmo motivo, um recurso de outra conta responde 404 e nunca 403: a API não revela a existência de dados de terceiros.

Exemplos reais

401 — token inválido

{
  "error": {
    "type": "unauthorized",
    "message": "Token de acesso ausente ou inválido.",
    "request_id": "01M1EGMBJ7JED66J067A9CBZF2"
  }
}

403 — token sem o escopo posts:read

{
  "error": {
    "type": "insufficient_scope",
    "message": "Este token não possui o escopo necessário para esta operação.",
    "details": { "required_scope": "posts:read" },
    "request_id": "01M1EGN1165BP5NP8Z5B2X7M79"
  }
}

404 — post de outra conta

{
  "error": {
    "type": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "01M1EGMBPV0Q361CWZKH74W5X9"
  }
}

422 — rede inexistente no filtro network

{
  "error": {
    "type": "invalid_request",
    "message": "Os parâmetros enviados são inválidos.",
    "details": { "network.0": ["The selected network.0 is invalid."] },
    "request_id": "01M1EGMC1DFAZ2TXZ1B5707WTA"
  }
}

Receita: o que está agendado e o que ainda não foi aprovado

O caso de uso mais comum da API, ponta a ponta. Não é preciso varrer todos os posts para acompanhar um mês: filtre por período e status, e siga links.next até o fim de cada listagem.

Descubra os projetos que o token alcança

A resposta é exatamente o que o seu token enxerga. Guarde os ids para usar como project_id.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/projects"

Liste os posts da semana que ainda esperam aprovação

Trocando review_status por request_changes você recebe os que voltaram com ajustes, e por approved os que já passaram e estão prontos para agendar.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts?project_id=1&status=in_review&review_status=pending&start_date=2026-09-07&end_date=2026-09-13"

Liste o que já está agendado no período

Mesma janela de datas, agora com status=scheduled — é a agenda confirmada do cliente.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts?project_id=1&status=scheduled&start_date=2026-09-07&end_date=2026-09-13"

Para um post travado, veja quem falta e o que foi pedido

O bloco review do primeiro diz quantos revisores faltam; o segundo diz o que cada um respondeu.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts/84"

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts/84/reviews"

Antes de confiar no agendamento, confira as contas conectadas

Qualquer resultado aqui é uma publicação que vai falhar se a conta não for reconectada.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/integrations?status=expired"

Boas práticas

Guarde o token em segredo

Ele dá acesso de leitura a todos os dados da conta. Nunca o coloque em código versionado ou em aplicação client-side.

Baixe as mídias, não guarde as URLs

Elas expiram em 48 horas. Armazene o binário do seu lado.

Trate type, não message

As mensagens são texto para humanos e podem mudar entre versões.

Respeite o Retry-After

Ao receber 429, aguarde o intervalo indicado em vez de tentar de novo imediatamente.

Pagine sempre

Uma conta com muitos posts tem centenas de páginas. Siga links.next como ele vem, sem remontar a URL.

Filtre por data e status

Em vez de varrer tudo e filtrar do seu lado — é mais rápido e consome menos do seu limite.

Registre o request_id dos erros

É o que permite ao suporte investigar o que aconteceu naquela requisição.

Flux API v1

Somente leitura

Bem-vindo à API do Flux

Projetos

Os clientes que o seu token alcança, com fuso, idioma e as contas conectadas de cada um.

Posts e agendamentos

Filtre por projeto, período, status, rede e tipo de peça. Legenda, mídias e grupo de conteúdo incluídos.

Aprovações

Quem aprovou, quem pediu ajuste e o que escreveu — mais os pacotes enviados ao cliente.

Contas conectadas

Detecte uma autorização expirada antes de a publicação falhar.

Base URL

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

Autenticação

Bearer token

Envie o token em toda requisição, junto do header Accept.

Authorization: Bearer flux_19ZcURVroVw2mRBj41EPxstH8IPgH2XpC6ZtSlBeSJ1XNK6K
Accept: application/json

Como gerar o token

Já autenticado no Flux, acesse Configurações → Tokens de API, em /company/edit/api

1Na seção Tokens de API, clique em Criar token e dê um nome que identifique o uso (por exemplo, "Integração do BI").
2Marque os escopos que a integração precisa. Um endpoint chamado sem o escopo correspondente responde 403.
3Escolha o alcance de projetos: todos os atuais e próximos, todos os atuais, ou uma seleção específica.
4Confirme. O token aparece uma única vez, começando com flux_.
5Copie e guarde num gerenciador de segredos. Para revogar, use o botão de revogar na mesma tela — o efeito é imediato.

O token aparece uma única vez

Escopos

Cada token carrega uma lista de escopos, marcada no momento da criação. Um endpoint chamado sem o escopo correspondente responde 403 com o escopo exigido em details.required_scope.

Escopo	Concede
projects:read	GET /projects, GET /projects/{id}
posts:read	GET /posts, GET /posts/{id}, GET /posts/group/{asset_group_id}
reviews:read	GET /posts/{id}/reviews, GET /review-groups, GET /review-groups/{id}
integrations:read	GET /integrations

Escopos de escrita (posts:create, posts:update, media:write, reviews:create) estão reservados e ainda não habilitam nenhum endpoint.

Alcance de projetos

Além dos escopos, um token tem um alcance de projetos definido na emissão. Você não consegue emitir um token com mais alcance do que o seu próprio dentro do Flux.

Todos os atuais e próximos

Alcança todos os projetos da conta, inclusive os criados depois da emissão do token.

Todos os atuais

Retrato de hoje: vira uma lista explícita, e projetos novos não entram.

Seleção específica

Só os projetos escolhidos. Um projeto criado depois não entra automaticamente; é preciso emitir um token novo.

Fora do alcance responde 404, não 403

Se você não sabe qual é o alcance do seu token, GET /api/v1/projects responde exatamente com o que ele enxerga.

Convenções

Paginação, fuso horário, expiração das mídias e limite de requisições valem para todos os endpoints.

Paginação

As listagens usam o formato padrão {data, links, meta}. O parâmetro per_page aceita de 1 a 50, com padrão 15 — acima de 50 a API responde 422. O parâmetro page começa em 1.

{
  "data": [],
  "links": {
    "first": "https://flux.reportei.com/api/v1/projects?per_page=2&page=1",
    "last": "https://flux.reportei.com/api/v1/projects?per_page=2&page=3",
    "prev": null,
    "next": "https://flux.reportei.com/api/v1/projects?per_page=2&page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://flux.reportei.com/api/v1/projects",
    "per_page": 2,
    "to": 2,
    "total": 5
  }
}

Siga links.next como ele vem, sem remontar a URL: ele já carrega os filtros e o per_page da chamada original.

Datas e fuso horário

Toda data e hora sai em ISO-8601 com o offset do fuso do projeto. Cada projeto tem o seu, e o mesmo instante aparece com offsets diferentes em projetos diferentes.

"schedule_at": "2026-09-15T07:00:00-03:00"   // projeto em America/Sao_Paulo
"schedule_at": "2026-09-15T07:00:00+01:00"   // projeto em Europe/Lisbon

Os filtros start_date e end_date recebem apenas a data (AAAA-MM-DD) e são interpretados no fuso do projeto, com os limites inclusivos (de 00:00:00 a 23:59:59).

URLs de mídia expiram em 48 horas

As URLs em media[].url são assinadas e temporárias: expiram 48 horas após a resposta, como indicado em media[].url_expires_at. O mesmo vale para o thumbnail dos posts de um grupo.

Limite de requisições

120requisições por minuto, por token

Ao exceder, a API responde 429 com o header Retry-After indicando quantos segundos aguardar. Respeite o intervalo em vez de tentar de novo imediatamente.

Status de post

O campo status usa um vocabulário público estável, que agrupa os estados internos do Flux. Os estados internos podem mudar entre versões; estes sete valores, não.

draft

Rascunho, ainda em edição

in_review

Em aprovação com o cliente ou revisor

scheduled

Aprovado e agendado, aguardando a hora de publicar

publishing

Em publicação neste momento

published

Publicado com sucesso

failed

A publicação falhou

archived

Arquivado

Situação da aprovação

O campo review_status só é preenchido enquanto o post está em in_review; nos demais status vem null. Em in_review ele é sempre um dos três valores abaixo — nunca null.

pending

Enviado para revisão, sem resposta ainda

approved

Aprovado pelo revisor

request_changes

Revisor pediu ajustes

Redes e tipos de peça

O campo network identifica a integração específica e network_group agrupa as variações da mesma rede — instagram e instagram_business, por exemplo, compartilham o grupo instagram.

network

instagraminstagram_businessfacebookthreadsxyoutubelinkedinlinkedin_personaltiktokpinterestgoogle_my_business

network_group

instagramfacebookthreadsxyoutubelinkedintiktokpinterestgoogle_my_business

type

feedstoryreelsshortsphoto

Projetos

Um projeto é o cliente final da agência. É por aqui que se começa: o id devolvido aqui é o project_id dos demais endpoints, e o timezone do projeto é o fuso de todas as datas dos posts dele.

GET/api/v1/projectsprojects:read

Listar projetos

Projetos da conta do token, com as contas conectadas de cada um. Por padrão a listagem traz apenas os ativos.

Nome	Tipo	Descrição
archived	boolean	1 retorna somente os projetos arquivados
all	boolean	1 retorna ativos e arquivados juntos
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/projects?per_page=2"

GET/api/v1/projects/{id}projects:read

Consultar um projeto

Um projeto pelo id, com as contas conectadas. Um projeto que não existe, que foi excluído ou que pertence a outra conta responde 404.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/projects/5"

O campo status de cada integração indica a saúde da conexão: active quando a conta está conectada e válida, e outro valor quando exige reconexão pelo painel do Flux.

Posts

Posts são as peças de conteúdo, uma por conta de destino. A mesma peça publicada em várias redes compartilha um grupo de conteúdo, cujo id vem em asset_group_id.

GET/api/v1/postsposts:read

Listar posts

Posts com filtros combináveis de projeto, janela de datas, status, rede, tipo de peça e situação de aprovação.

Nome	Tipo	Descrição
project_id	integer	Restringe a um projeto. Um id fora do alcance do token responde 404
start_date	date	Posts com schedule_at a partir desta data, inclusive (AAAA-MM-DD)
end_date	date	Posts com schedule_at até esta data, inclusive. Precisa ser maior ou igual a start_date
status	string \| array	Um ou mais status públicos. Aceita status=scheduled e status[]=scheduled&status[]=published
network	string \| array	Filtra pela rede. Aceita valor único ou lista
network_group	string	Filtra pelo grupo de rede
type	string \| array	feed, story, reels, shorts ou photo
review_status	string	pending, approved ou request_changes. Como só posts em revisão têm esse campo, o filtro restringe implicitamente a status=in_review
order	string	schedule_at (padrão) ou created_at
direction	string	asc (padrão) ou desc
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts?status=published&per_page=1"

Filtro inválido responde 422

Parâmetros desconhecidos são ignorados, mas um valor inválido em um parâmetro conhecido responde 422 — a API não devolve lista vazia para filtro errado.

Campos do post

Campo	Descrição
id	Identificador do post no Flux
asset_group_id	Grupo de conteúdo do post: a mesma peça publicada em várias redes compartilha esse id
project	Projeto dono do post, com o fuso usado nas datas
network	Rede de destino (network) e o grupo que reúne suas variações (network_group)
account	Conta conectada onde o post será publicado; id é o identificador na rede
type	feed, story, reels, shorts ou photo
status	Status público do post
review_status	Situação da aprovação, apenas quando status é in_review
caption	Legenda final em texto plano, já com os placeholders resolvidos. Quando o post não tem legenda própria, cai para a legenda do grupo de conteúdo
first_comment	Primeiro comentário programado (Instagram), quando houver
schedule_at	Data e hora do agendamento. null em post sem agendamento definido
published_url	URL do post na rede, preenchida após a publicação
media	Arquivos anexados, na ordem de publicação

Campos da mídia

Campo	Descrição
id	Identificador do arquivo
type	image, video ou pdf
url	URL temporária assinada — expira em 48h, não persista
url_expires_at	Momento exato da expiração da URL
width	Largura em pixels, quando conhecida
height	Altura em pixels, quando conhecida
aspect_ratio	Proporção, por exemplo 4:5

Campos podem vir null quando o arquivo foi enviado antes de o Flux passar a extrair aquele metadado.

GET/api/v1/posts/{id}posts:read

Consultar um post

O mesmo objeto da listagem, sob a chave data, mais o bloco review com o agregado da aprovação. Um post que não existe, que foi excluído ou que pertence a outra conta responde 404.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts/30"

O bloco review

Campo	Descrição
status	Situação agregada da aprovação. Sempre igual ao review_status do mesmo post
cycle_started_at	Início do ciclo de aprovação corrente. null em post que nunca foi reenviado para revisão
reviewers_total	Revisores atribuídos ao post neste momento
decided	Decisões válidas no ciclo corrente, uma por revisor
approved	Quantas dessas decisões foram aprovações
request_changes	Quantas dessas decisões pediram ajuste
pending	Revisores atribuídos que ainda não decidiram no ciclo corrente

decided + pending pode não fechar com reviewers_total

GET/api/v1/posts/group/{asset_group_id}posts:read

Consultar um grupo de conteúdo

O resumo do lote — o que ele é como um todo — e os posts, resumidos. Um grupo que não existe, cujos posts foram excluídos ou que pertence a outra conta responde 404.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts/group/71"

Campos do grupo de conteúdo

Um grupo de conteúdo é a peça escrita uma vez e publicada em várias redes: cada rede vira um post, e todos carregam o mesmo asset_group_id.

Campo	Descrição
id	Identificador do grupo — é o asset_group_id que os posts carregam
project	Projeto dono do grupo, com o fuso usado nas datas
review_group_id	Grupo de aprovação a que o lote pertence. null quando nunca foi enviado para revisão
posts_count	Posts do grupo, um por rede
networks	Redes alcançadas pelo lote, sem repetir
accounts	Contas conectadas onde o lote será publicado, sem repetir
status_summary	Quantos posts em cada status, só os status presentes, na ordem do ciclo de vida
schedule_dates	Datas de agendamento do lote, sem repetir e em ordem. Post sem agendamento não entra

O grupo vem inteiro, sem paginação: são poucos posts, um por rede. Cada post vem resumido, com um thumbnail da primeira mídia — legenda, mídias e o bloco review continuam em GET /posts/{id}.

Contas conectadas

Lista as contas de rede social conectadas aos projetos da conta. É o endpoint que permite detectar uma conta expirada antes de a publicação falhar.

GET/api/v1/integrationsintegrations:read

Listar contas conectadas

As contas de rede social conectadas aos projetos que o token alcança, com a situação de cada conexão.

Nome	Tipo	Descrição
project_id	integer	Restringe a um projeto
network	string \| array	Filtra por rede. Aceita network=facebook ou network[]=facebook&network[]=instagram
status	string	active, expired ou deleted
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/integrations?status=expired"

Status da conta conectada

active

Conectada e válida

expired

A autorização caiu; a conta precisa ser reconectada no Flux

deleted

A conta foi desconectada do projeto

Conta desconectada continua aparecendo

Uma conta desconectada aparece com status deleted em vez de desaparecer: posts publicados por ela seguem apontando para esse registro, e a listagem precisa explicar esses posts.

Aprovações

Grupos de aprovação são os pacotes de posts enviados de uma vez ao cliente. Cada post dentro deles acumula decisões de revisores, e esse histórico é auditoria: nada é removido dele.

GET/api/v1/posts/{id}/reviewsreviews:read

Listar as decisões de aprovação de um post

Histórico das decisões de aprovação do post, em ordem cronológica. É auditoria: nada é removido dessa lista. Um post fora do alcance do token responde 404.

Nome	Tipo	Descrição
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/posts/84/reviews"

Campos da decisão

Campo	Descrição
reviewer	Quem decidiu. Apenas nome e e-mail — nenhum outro dado do revisor é exposto
status	approved ou request_changes. Nunca pending: pendente é ausência de decisão
reasons	Motivos marcados no pedido de ajuste, quando houver
comments	Comentário livre do revisor
is_invalidated	true quando a decisão foi anulada por uma edição posterior do post
decided_at	Momento da decisão
created_at	Momento em que a decisão foi registrada

GET/api/v1/review-groupsreviews:read

Listar grupos de aprovação

Os pacotes de posts enviados de uma vez ao cliente. Os mais recentes vêm primeiro.

Nome	Tipo	Descrição
project_id	integer	Restringe a um projeto
per_page	integer	1 a 50, padrão 15
page	integer	Página, a partir de 1

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/review-groups?project_id=1"

Campos do grupo de aprovação

Campo	Descrição
posts_count	Todos os posts do grupo, em qualquer status
review_summary	Quantos posts ainda em revisão estão em cada situação
reviewers_count	Revisores atribuídos ao grupo

review_summary pode somar menos que posts_count

GET/api/v1/review-groups/{id}reviews:read

Consultar um grupo de aprovação

O mesmo grupo da listagem e, junto, todos os posts do pacote. É o endpoint para abrir um grupo: saber o que foi enviado ao cliente e em que pé está cada post.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     -H "Accept: application/json" \
     "https://flux.reportei.com/api/v1/review-groups/419"

Como funciona a aprovação no Flux

Quatro regras explicam praticamente todas as dúvidas sobre os campos de aprovação.

1. Pendente é ausência de decisão, não um valor gravado

"review": { "status": "pending", "reviewers_total": 3, "decided": 0, "pending": 3 }

2. "Pedido de mudança" tem precedência

Basta um revisor pedir ajustes para o post inteiro ficar em request_changes, mesmo que os outros já tenham aprovado. É a mesma regra que o Flux usa na tela.

3 revisores: um aprovou, um pediu ajustes, um não respondeu

"review": {
  "status": "request_changes",
  "reviewers_total": 3, "decided": 2, "approved": 1, "request_changes": 1, "pending": 1
}

Os 3 aprovaram

"review": {
  "status": "approved",
  "reviewers_total": 3, "decided": 3, "approved": 3, "request_changes": 0, "pending": 0
}

3. Um post pode voltar para aprovação quantas vezes for preciso

"review": {
  "status": "request_changes",
  "cycle_started_at": "2026-09-05T09:00:00-03:00",
  "reviewers_total": 3, "decided": 1, "approved": 0, "request_changes": 1, "pending": 2
}

4. Decisão anulada aparece marcada, não desaparece

"data": [
  {
    "id": 55020,
    "status": "approved",
    "is_invalidated": true,
    "decided_at": "2026-09-08T10:12:00-03:00"
  }
]

Erros

Todo erro sai no mesmo envelope, com um código estável para tratamento programático e um identificador de requisição para o suporte.

{
  "error": {
    "type": "invalid_request",
    "message": "Os parâmetros enviados são inválidos.",
    "details": { "per_page": ["The per page field must not be greater than 50."] },
    "request_id": "01M1EGMBW481B34NQKA1Z2MYKN"
  }
}

Campo	Descrição
type	Código estável, adequado para tratamento programático
message	Descrição legível. Pode mudar entre versões — não use em condicional
details	Presente apenas em alguns erros, com os campos rejeitados
request_id	Também devolvido no header X-Request-Id. Informe-o ao suporte ao relatar um problema; é por ele que rastreamos a requisição

Códigos HTTP

401 unauthorized

Token ausente, inválido, expirado ou revogado

403 insufficient_scope

Token válido, sem o escopo do endpoint. details.required_scope traz o escopo exigido

404 not_found

Recurso inexistente, excluído ou de outra conta

405 method_not_allowed

Método HTTP não suportado pelo endpoint

422 invalid_request

Parâmetro inválido. details lista os campos

429 rate_limit_exceeded

Passou do limite de requisições. Aguarde o que indica Retry-After

500 internal_error

Falha no Flux. Informe o request_id ao suporte

Por que 401 e 404 são propositalmente opacos

Exemplos reais

401 — token inválido

{
  "error": {
    "type": "unauthorized",
    "message": "Token de acesso ausente ou inválido.",
    "request_id": "01M1EGMBJ7JED66J067A9CBZF2"
  }
}

403 — token sem o escopo posts:read

{
  "error": {
    "type": "insufficient_scope",
    "message": "Este token não possui o escopo necessário para esta operação.",
    "details": { "required_scope": "posts:read" },
    "request_id": "01M1EGN1165BP5NP8Z5B2X7M79"
  }
}

404 — post de outra conta

{
  "error": {
    "type": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "01M1EGMBPV0Q361CWZKH74W5X9"
  }
}

422 — rede inexistente no filtro network

{
  "error": {
    "type": "invalid_request",
    "message": "Os parâmetros enviados são inválidos.",
    "details": { "network.0": ["The selected network.0 is invalid."] },
    "request_id": "01M1EGMC1DFAZ2TXZ1B5707WTA"
  }
}

Receita: o que está agendado e o que ainda não foi aprovado

O caso de uso mais comum da API, ponta a ponta. Não é preciso varrer todos os posts para acompanhar um mês: filtre por período e status, e siga links.next até o fim de cada listagem.

Descubra os projetos que o token alcança

A resposta é exatamente o que o seu token enxerga. Guarde os ids para usar como project_id.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/projects"

Liste os posts da semana que ainda esperam aprovação

Trocando review_status por request_changes você recebe os que voltaram com ajustes, e por approved os que já passaram e estão prontos para agendar.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts?project_id=1&status=in_review&review_status=pending&start_date=2026-09-07&end_date=2026-09-13"

Liste o que já está agendado no período

Mesma janela de datas, agora com status=scheduled — é a agenda confirmada do cliente.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts?project_id=1&status=scheduled&start_date=2026-09-07&end_date=2026-09-13"

Para um post travado, veja quem falta e o que foi pedido

O bloco review do primeiro diz quantos revisores faltam; o segundo diz o que cada um respondeu.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts/84"

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/posts/84/reviews"

Antes de confiar no agendamento, confira as contas conectadas

Qualquer resultado aqui é uma publicação que vai falhar se a conta não for reconectada.

curl -H "Authorization: Bearer $FLUX_TOKEN" \
     "https://flux.reportei.com/api/v1/integrations?status=expired"

Boas práticas

Guarde o token em segredo

Ele dá acesso de leitura a todos os dados da conta. Nunca o coloque em código versionado ou em aplicação client-side.

Baixe as mídias, não guarde as URLs

Elas expiram em 48 horas. Armazene o binário do seu lado.

Trate type, não message

As mensagens são texto para humanos e podem mudar entre versões.

Respeite o Retry-After

Ao receber 429, aguarde o intervalo indicado em vez de tentar de novo imediatamente.

Pagine sempre

Uma conta com muitos posts tem centenas de páginas. Siga links.next como ele vem, sem remontar a URL.

Filtre por data e status

Em vez de varrer tudo e filtrar do seu lado — é mais rápido e consome menos do seu limite.

Registre o request_id dos erros

É o que permite ao suporte investigar o que aconteceu naquela requisição.