# Referência da API

> Rotas da API para equipes técnicas que integram sem o plugin do WordPress.

O plugin do WordPress já usa a API por você. Esta página é para equipes técnicas que integram outro CMS ou um front-end próprio.

- Endereço: `https://api-publishers.sevntech.com`
- Rotas `/v1`: chamadas do servidor do portal, com a chave de API no cabeçalho `Authorization: Bearer {chave de API}`. Nunca chame essas rotas do navegador.
- Rotas `/public/v1`: chamadas do navegador do leitor, com a chave pública do site (`site`).
- Respostas em JSON. Erros trazem `{"error": "mensagem"}` e, quando há, um `code`:
  - `429` com `code: "quota_exceeded"`: limite do plano atingido;
  - `403` com `code: "module_not_contracted"`: o módulo não está no plano do portal;
  - `403` com `code: "trial_over"`: o teste grátis do módulo terminou.
- Nas gerações automáticas (como o resumo), a falta de cota não vira erro: o item volta com `status: "failed"` e o motivo.

## Portal e uso

| Método | Rota | O que faz |
|---|---|---|
| GET | `/v1/me` | O portal dono da chave e o plano |
| GET | `/v1/usage` | Uso do mês por módulo, com o limite e o estado (`ok`, `warning`, `blocked`, `daily_blocked`) |
| GET/PUT | `/v1/settings` | Configurações do portal (modos, idiomas, regras) |

## Matérias

| Método | Rota | O que faz |
|---|---|---|
| POST | `/v1/articles` | Cria ou atualiza uma matéria: `external_id`, `title`, `body_html`; opcionais `url`, `subtitle`, `author`, `section`, `tags`, `published_at`, `image_url`, `image_credit` e `narrate` ("Narrar esta matéria": `true`, `false` ou `null`) |
| POST | `/v1/articles/batch` | Envia várias matérias de uma vez (importação do acervo) |
| GET | `/v1/articles/{external_id}` | Lê uma matéria |
| DELETE | `/v1/articles/{external_id}` | Apaga a matéria e o que foi gerado para ela |
| GET | `/v1/articles/{external_id}/summary` | Resumo da matéria |
| POST | `/v1/articles/{external_id}/summary/generate` | Gera ou refaz o resumo |
| PUT | `/v1/articles/{external_id}/summary` | Edita os tópicos (`bullets`) ou muda o status (`approved`, `draft`) |
| GET/PUT | `/v1/articles/{external_id}/social` | Pacote Social da matéria: lê, edita ou aprova |
| POST | `/v1/articles/{external_id}/social/generate` | Gera ou refaz o Pacote Social |
| GET | `/v1/articles/{external_id}/social/carousel` | Imagens do carrossel |
| GET | `/v1/articles/{external_id}/translations` | Traduções da matéria |
| POST | `/v1/articles/{external_id}/translations/{idioma}/generate` | Gera a tradução (`en` ou `es`) |
| PUT | `/v1/articles/{external_id}/translations/{idioma}` | Edita, aprova ou despublica a tradução |

## Copiloto

| Método | Rota | O que faz |
|---|---|---|
| POST | `/v1/copilot/suggest` | Títulos, linha fina, SEO, tags e links internos do rascunho enviado (`title`, `body_html`) |
| POST | `/v1/copilot/review` | Revisão de ortografia, gramática e manual de redação |
| GET/PUT | `/v1/copilot/style-guide` | Manual de redação do portal |

## Transcrição

| Método | Rota | O que faz |
|---|---|---|
| GET/POST | `/v1/transcriptions` | Lista as transcrições ou envia um arquivo novo |
| GET/PUT | `/v1/transcriptions/{id}` | Lê a transcrição ou edita o título e quem fala em cada trecho |
| POST | `/v1/transcriptions/{id}/draft` | Gera o rascunho de matéria |
| GET | `/v1/transcriptions/{id}/srt` | Legenda em SRT |

## Newsletter

| Método | Rota | O que faz |
|---|---|---|
| GET/POST | `/v1/newsletters` | Lista ou gera uma edição (`segment`, `days`, `count`) |
| GET/PUT/DELETE | `/v1/newsletters/{id}` | Edição com HTML e texto; edita, aprova ou apaga |
| GET/POST | `/v1/newsletters/schedules` | Envios automáticos (com o link e o RSS de cada um) |
| PUT/DELETE | `/v1/newsletters/schedules/{id}` | Muda, pausa ou exclui um envio automático |
| GET/POST/DELETE | `/v1/newsletters/mailchimp` | Conecta, confere ou desconecta o Mailchimp do portal |
| POST | `/v1/newsletters/{id}/mailchimp` | Manda uma edição para o Mailchimp (enviar, agendar ou rascunho) |

## Radar e Áudio

| Método | Rota | O que faz |
|---|---|---|
| GET | `/v1/radar/topics` | Assuntos do Radar, com nota e cobertura |
| POST | `/v1/radar/topics/{id}/draft` | Pauta e rascunho de um assunto |
| GET | `/v1/radar/bulletin` | Boletim em texto |
| GET | `/v1/audio` | Matérias com áudio, uso do mês e vozes |
| POST | `/v1/audio/{external_id}/generate` | Gera o áudio de uma matéria |

## Rotas públicas (navegador do leitor)

| Método | Rota | O que faz |
|---|---|---|
| GET | `/embed/v1/sevn-ai.js` | Script dos widgets ([sites headless](https://docs-press.sevntech.com/comecar/sites-headless/)) |
| GET | `/public/v1/config?site=` | Módulos do leitor ligados no portal |
| GET | `/public/v1/summary?site=&article=` | Resumo aprovado |
| POST | `/public/v1/ask` | Pergunte ao Portal |
| GET | `/public/v1/related?site=&article=` | Leia também |
| GET | `/public/v1/audio?site=&article=` | Áudio aprovado |
| GET | `/public/v1/podcast/{chave pública}.xml` | Feed do podcast |
| GET | `/public/v1/newsletter/{código}/rss.xml` | Feed RSS de um envio automático da newsletter |
| GET | `/public/v1/newsletter/{código}/latest.html` | Última edição de um envio automático |