API Pública do Scrivox

Imagine que o Scrivox é uma biblioteca onde você guarda e cria artigos. Normalmente você acessa essa biblioteca pelo site — clicando, navegando, lendo. A API pública é uma "entrada de serviço" dessa mesma biblioteca: uma forma de outros programas e sistemas acessarem seus artigos automaticamente, sem precisar de alguém clicando na tela.

A sigla API vem do inglês Application Programming Interface, mas o que importa é o que ela faz: permite que seu site, suas automações ou qualquer outro sistema "converse" com o Scrivox e busque seus artigos de forma automática.

A chave de API é como um crachá de acesso exclusivo para sistemas externos. Em vez de dar seu login e senha do Scrivox para outro programa, você cria uma chave específica para ele. Se precisar cancelar o acesso, é só apagar a chave — sem precisar trocar sua senha principal.

Como criar uma chave:

1. 1No Scrivox, clique em Configurações no menu lateral
2. 2Role até a seção Chaves de API
3. 3No campo Nome da chave, escreva de onde vem (ex: "Meu site WordPress", "Zapier")
4. 4Clique em + Criar
5. 5A chave aparece uma única vez — copie agora e guarde em local seguro (gerenciador de senhas). Depois disso, ela nunca mais será exibida completa.

Todo sistema que aceita API precisa saber "quem está fazendo essa pergunta". Isso é feito através de um cabeçalho (header) — um dado extra enviado junto com a requisição, invisível para o usuário final.

O Scrivox usa o padrão chamado Bearer Token — um dos mais comuns na internet. Funciona assim:

Authorization: Bearer scrivox_sk_sua_chave_aqui

Entendendo cada parte:

Se esse cabeçalho não for enviado — ou se a chave estiver errada — o Scrivox retorna o erro 401 Unauthorized. É como tentar entrar em um lugar sem o crachá.

"Fazer uma chamada" significa enviar uma pergunta para o Scrivox via internet e receber uma resposta com seus dados. Veja como fazer isso nas ferramentas mais comuns:

No Zapier (sem programação):

1. 1Crie um novo Zap e adicione o trigger que desejar (ex: agendado diariamente)
2. 2Adicione uma ação: Webhooks by Zapier → GET
3. 3URL: https://scrivox.com.br/api/v1/articles
4. 4Em Headers, adicione: Key: Authorization / Value: Bearer scrivox_sk_sua_chave
5. 5Clique em "Test" — seus artigos aparecerão como dados para usar nas próximas etapas do Zap

No terminal / linha de comando (para testar rapidamente):

curl https://scrivox.com.br/api/v1/articles \
  -H "Authorization: Bearer scrivox_sk_sua_chave_aqui"

Em JavaScript (para o seu site ou app):

const resposta = await fetch('https://scrivox.com.br/api/v1/articles', {
  headers: {
    'Authorization': 'Bearer scrivox_sk_sua_chave_aqui'
  }
})

const dados = await resposta.json()
console.log(dados.articles)  // lista de artigos
console.log(dados.total)     // total de artigos existentes

Um endpoint é um "ponto de acesso" da API — um endereço específico para cada tipo de dado. O Scrivox tem o endpoint de artigos:

GET https://scrivox.com.br/api/v1/articles

GET significa "quero buscar" — não criar, não apagar, só ler. Pense como fazer uma pergunta: "me dê meus artigos".

Filtrando os resultados:

Você pode refinar o que quer receber adicionando parâmetros no final da URL, após o ?. É como adicionar filtros em uma busca.

Valores possíveis para cada filtro:

Exemplos de URLs completas:

# Só artigos do LinkedIn
GET /api/v1/articles?channel=linkedin

# Os 5 artigos mais recentes publicados
GET /api/v1/articles?limit=5&status=published

# Todos os rascunhos
GET /api/v1/articles?status=draft

# Artigos de newsletter, 10 por vez
GET /api/v1/articles?channel=newsletter&limit=10

# Todos os artigos (qualquer canal ou status)
GET /api/v1/articles?status=all

A resposta vem no formato JSON — um formato de texto estruturado que computadores entendem. Parece intimidador, mas é simplesmente uma lista organizada de dados. Veja um exemplo real:

{
  "articles": [
    {
      "id":           "abc-123-def",
      "title":        "Como a IA está mudando o marketing",
      "channel":      "linkedin",
      "status":       "published",
      "language":     "pt",
      "content":      "Texto completo do artigo aqui...",
      "created_at":   "2026-05-29T10:00:00Z",
      "published_at": "2026-05-29T14:00:00Z"
    },
    {
      "id":           "xyz-456-ghi",
      "title":        "5 tendências de conteúdo para 2027",
      "channel":      "newsletter",
      "status":       "draft",
      "language":     "pt",
      "content":      "Rascunho do texto...",
      "created_at":   "2026-05-28T09:00:00Z",
      "published_at": null
    }
  ],
  "total":  42,
  "limit":  20,
  "offset": 0
}

O que cada campo significa:

Se você tem 100 artigos, a API não retorna todos de uma vez. Ela retorna em "páginas" para não sobrecarregar. O padrão é 20 artigos por chamada.

# Chamada 1 — artigos 1 a 20
GET /api/v1/articles?limit=20&offset=0

# Chamada 2 — artigos 21 a 40
GET /api/v1/articles?limit=20&offset=20

# Chamada 3 — artigos 41 a 60
GET /api/v1/articles?limit=20&offset=40

# Chamada 4 — artigos 61 a 80
GET /api/v1/articles?limit=20&offset=60

# Chamada 5 — artigos 81 a 100
GET /api/v1/articles?limit=20&offset=80

Use o campo total da resposta para saber quantas chamadas você precisa fazer:

Fórmula: número de chamadas = Math.ceil(total / limit)

Revogar significa cancelar o acesso de uma chave — ela deixa de funcionar imediatamente. Qualquer sistema que usar a chave revogada receberá o erro 401 Unauthorized e não conseguirá mais acessar seus dados.

Quando algo dá errado, a API retorna um código de status HTTP — um número que indica o tipo do problema. Os mais comuns:

O erro mais comum: 401

Quase sempre causado por um destes motivos:

• →Esqueceu de incluir o cabeçalho Authorization
• →Escreveu Bearer sem o espaço antes da chave
• →A chave foi revogada e precisa criar uma nova
• →Copiou a chave com espaço extra no começo ou no final

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Além de ler seus artigos, a API também aceita enviar itens de pesquisa — notícias, estudos, relatórios que você (ou um assistente de IA) já levantou sobre um tema. Esses itens caem no Radar de Autoridade, prontos pra você selecionar e transformar em post ou artigo.

POST https://scrivox.com.br/api/v1/research-items/batch

Igual ao endpoint de artigos, use o cabeçalho Authorization: Bearer scrivox_sk_.... Envie até 100 itens por chamada.

{
  "briefing_date": "2026-07-22",
  "items": [
    {
      "title": "Dados e drones ajudam a elevar o retorno por hectare",
      "source_name": "Farm Progress",
      "source_url": "https://exemplo.com/artigo-drones",
      "published_at": "2026-07-22",
      "category": "Agronegócio",
      "summary_factual": "Resumo objetivo, sem opinião.",
      "practical_impact": "O que muda na prática para produtores.",
      "tags": ["drones", "agricultura de precisão", "IA"],
      "relevance_score": 91
    }
  ]
}

Campos de cada item:

Itens com a mesma source_url (já normalizada — sem parâmetros de rastreamento) não são duplicados: a chamada simplesmente os ignora e reporta em skipped.

{
  "imported": 4,
  "skipped": 1,
  "skipped_items": [
    { "title": "...", "category": "Agronegócio", "source_url": "https://..." }
  ],
  "errors": [],
  "total": 5
}

Se você já tem uma tarefa agendada no ChatGPT que pesquisa temas do seu interesse (ex.: novidades de agronegócio, tecnologia em saúde), dá pra fazer ela enviar o resultado direto pro Scrivox, sem copiar e colar nada — usando o recurso de Actions de uma Custom GPT da OpenAI.

Passo a passo:

1. 1No ChatGPT, crie (ou edite) sua GPT customizada em Explorar GPTs → Criar
2. 2Na aba Configurar, role até Actions → Criar nova ação
3. 3Cole o schema abaixo no campo de esquema (Schema)
4. 4Em Authentication, escolha API Key → Bearer e cole sua chave criada em Configurações → Chaves de API
5. 5Nas instruções da GPT, peça pra ela chamar a action importResearchItems ao final da pesquisa agendada, com os itens encontrados

openapi: 3.1.0
info:
  title: Scrivox — Radar de Autoridade
  version: 1.0.0
servers:
  - url: https://www.scrivox.com.br
paths:
  /api/v1/research-items/batch:
    post:
      operationId: importResearchItems
      summary: Envia um lote de itens de pesquisa para o Radar de Autoridade do Scrivox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                briefing_date:
                  type: string
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required: [title, source_url]
                    properties:
                      title: { type: string }
                      source_name: { type: string }
                      source_url: { type: string, format: uri }
                      published_at: { type: string }
                      category: { type: string }
                      language: { type: string }
                      source_type: { type: string }
                      evidence_level: { type: string }
                      summary_factual: { type: string }
                      practical_impact: { type: string }
                      tags:
                        type: array
                        items: { type: string }
                      key_claims:
                        type: array
                        items: { type: string }
                      image_url: { type: string, format: uri }
                      relevance_score: { type: number, minimum: 0, maximum: 100 }
      responses:
        '201':
          description: Itens processados
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
security:
  - ApiKeyAuth: []