API v1

Documentação da API

Referência completa dos endpoints de MateriasComIA. Integração via REST com autenticação JWT.

Base URL https://materias.globals.tech/api/v1
Chaves secretas não aparecem nesta página. Configure JWT_SECRET_KEY, MASTER_TOKEN e demais variáveis apenas no .env do servidor.

Segurança e autenticação

Dois níveis de credenciais protegem a API e o painel web.

Bearer JWT

Usuário final

Criar, listar e ler matérias; consultar cota e perfil.

Authorization: Bearer <access_token>
Master

Administração

Gerenciar planos, usuários e relatórios de custo.

X-Master-Token: <master_token>
Variável (.env)Função
JWT_SECRET_KEYAssina tokens JWT — nunca expor publicamente
MASTER_TOKENAcesso aos endpoints /master/*
REGISTRATION_ENABLEDtrue ou false para cadastro público

Health check

GET https://materias.globals.tech/api/health Público

Verifica se a API está online. Não requer autenticação.

Resposta
{
  "status": "ok",
  "service": "materiascomia-api"
}

Autenticação

POST /api/v1/auth/register Condicional

Cria conta e retorna JWT. Ativo apenas com REGISTRATION_ENABLED=true.

Corpo da requisição
{
  "email": "usuario@empresa.com",
  "password": "SenhaSegura123",
  "name": "Nome do Usuário",
  "plan_slug": "basico"
}
POST /api/v1/auth/login Público

Autentica usuário existente e retorna access_token.

Corpo da requisição
{
  "email": "usuario@empresa.com",
  "password": "SenhaSegura123"
}
GET /api/v1/auth/me Bearer

Retorna dados do usuário autenticado e plano vinculado.

Planos

GET /api/v1/plans Público

Lista planos ativos com limites mensais de matérias.

Matérias

Geração assíncrona em fila. Todas as rotas exigem Bearer JWT.

POST /api/v1/articles Bearer

Enfileira nova matéria. Resposta 202 Accepted.

Corpo da requisição
{
  "subject": "Como funciona o Tesouro Direto em 2026",
  "style": "especialista",
  "instructions": "Foque no sistema Y e na empresa X. Tom mais pessimista nos riscos."
}

style: especialista · humanizado · tecnico

instructions (opcional): conteúdo avançado para personalizar foco, tom, produto ou empresa (máx. 4000 caracteres).

GET /api/v1/articles/generation-status Bearer

Resumo da fila: queued, processing, published, failed.

GET /api/v1/articles Bearer

Lista matérias do usuário. Query: page, per_page, status.

GET /api/v1/articles/{id} Bearer

Detalhe com html_content, capa, meta e status de geração.

DELETE /api/v1/articles/{id} Bearer

Remove matéria. Resposta 204 No Content.

queuedNa fila
processingGerando
publishedPronta
failedErro

Cota mensal

GET /api/v1/quota Bearer

Limite do plano, matérias usadas e restantes no mês corrente.

Administração (Master)

Requer header X-Master-Token em todas as requisições.

  • POST/api/v1/master/usersCriar usuário
  • POST/api/v1/master/plansCriar plano
  • GET/api/v1/master/plansListar planos
  • PATCH/api/v1/master/plans/{id}Atualizar plano

Custos de geração

Relatórios de consumo DeepSeek + imagens. Requer X-Master-Token.

  • GET/api/v1/master/costs/summaryTotais e médias
  • GET/api/v1/master/costsLista paginada
  • GET/api/v1/master/costs/articles/{id}Detalhe por matéria

Painel de gestão

Interface web em /painel/login para administrar matérias com login e senha próprios (separado da API).

  • Dashboard com cota e status da fila
  • Gerar e atualizar Bearer token da conta API
  • Criar, listar, visualizar e excluir matérias

Visualizador web

As rotas /materias e /materias/{id} exigem token JWT válido:

  • Query string: ?token=SEU_ACCESS_TOKEN
  • Header: Authorization: Bearer SEU_ACCESS_TOKEN

Fluxo rápido

  1. 1
    Login

    POST /auth/login → obter access_token

  2. 2
    Cota

    GET /quota → verificar limite disponível

  3. 3
    Enfileirar

    POST /articles → matéria entra na fila

  4. 4
    Acompanhar

    Polling em /generation-status ou /articles/{id}

  5. 5
    Publicar

    Usar html_content ou /materias/{id}?token=...

Exemplo cURL
# Login
curl -s -X POST https://materias.globals.tech/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"usuario@empresa.com","password":"SUA_SENHA"}'

# Enfileirar matéria
curl -s -X POST https://materias.globals.tech/api/v1/articles \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Assunto da matéria","style":"especialista","instructions":"Foque na empresa X e apresente o sistema Y"}'

# Status da fila
curl -s https://materias.globals.tech/api/v1/articles/generation-status \
  -H "Authorization: Bearer TOKEN"