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"
}