Uma API previsível começa por um contrato honesto.

01 — Início rápido

Faça a primeira chamada

A URL de produção é https://seujornaleiro.com.br. Corpos e respostas usam JSON UTF-8. Valores monetários são centavos inteiros, datas seguem ISO 8601 UTC e identificadores usam UUID.

curl --request GET \
  --url "https://seujornaleiro.com.br/api/public/newspapers?state=SP&limit=20" \
  --header "Accept: application/json"

02 — Autenticação

Chaves que sabem até onde podem ir

Integrações servidor-servidor usam uma chave sj_live_ vinculada a uma organização e emitida por um usuário autorizado. O segredo é exibido somente na criação. Nunca coloque a chave em navegador, aplicativo distribuído, URL, log ou repositório.

curl "https://seujornaleiro.com.br/api/integrations/me" \
  -H "Authorization: Bearer sj_live_SUA_CHAVE"

X-API-Key também é aceito. Prefira Bearer. Toda chave deve estar vinculada a uma organização.

03 — Catálogo público

Leitura sem credencial

Somente registros ativos e campos explicitamente públicos são retornados. limit aceita de 1 a 100 e assume 50.

04 — Integrações organizacionais

Dados privados com escopo

curl "https://seujornaleiro.com.br/api/integrations/payments?limit=25" \
  -H "Authorization: Bearer sj_live_SUA_CHAVE" \
  -H "Accept: application/json"

Cada chave acessa somente os dados da organização à qual está vinculada. Não existe parâmetro público para selecionar outra organização.

05 — Limites do contrato

O que pode ser usado por integrações

O arquivo OpenAPI lista toda a superfície pública suportada. Rotas usadas exclusivamente pela interface oficial, callbacks recebidos de fornecedores e endpoints internos podem mudar sem aviso e não devem ser chamados por integrações externas.

06 — Respostas

Sucesso e erro sem adivinhação

{
  "ok": true,
  "data": [],
  "meta": { "request_id": "uuid", "limit": 50 }
}

{
  "ok": false,
  "error": { "code": "invalid_api_key", "message": "Chave inválida." },
  "request_id": "uuid"
}

O campo error.code é o identificador estável para tratamento programático. A mensagem é destinada a pessoas e pode ser aprimorada sem mudança de versão.

07 — Segurança e limites

Projete integrações defensivas

• Ao receber 429, aguarde o número de segundos indicado em Retry-After e use backoff com jitter.
• Limites podem ser reduzidos emergencialmente para proteger o serviço; a resposta continuará usando 429 e Retry-After.
• Defina timeout no cliente e repita automaticamente somente requisições idempotentes.
• Não registre credenciais, tokens, URLs assinadas ou dados pessoais desnecessários.
• Rotacione e revogue chaves suspeitas e conceda apenas os escopos necessários.

08 — Webhooks

Ainda não disponíveis na API pública

O contrato atual não oferece webhooks de saída para integrações externas. Não dependa de callbacks ou endpoints de recebimento usados internamente pelo produto. Para discutir um caso de uso, fale com o atendimento técnico.

09 — Versão e suporte

Compatibilidade antes de novidade

Contrato vigente: 2026-08-22. Clientes devem ignorar propriedades desconhecidas e não depender da ordem dos campos. Remoções, renomeações ou mudanças semânticas incompatíveis exigirão nova versão e janela de migração de pelo menos 180 dias, salvo risco crítico, abuso ativo ou obrigação legal.