API
Referencia publica de integracoes. Endpoints privados exigem autenticação, escopos apropriados e geracao de chave de API.
A API publica está disponível em https://seujornaleiro.bilheking.com.br. A plataforma usa uma infraestrutura de backend segura para processar requisicoes, proteger credenciais e isolar operações privadas do navegador.
Catalogos publicos retornam apenas dados de jornais, planos, categorias e espaços ativos. Dados pessoais, pagamentos sensíveis, sessoes, arquivos protegidos, webhooks e credenciais não são superficies publicas.
Fluxos da interface usam sessão autenticada do usuário. Integracoes servidor-servidor usam chave sj_live_ criada no painel do jornal em Chaves de API. Envie a chave em Authorization: Bearer sj_live_... ou X-API-Key: sj_live_....
As chaves podem ser revogadas e possuem escopos limitados: catalog:read, payments:read e reports:read. Credenciais administrativas, webhooks e segredos de gateway nunca devem trafegar no navegador.
| Metodo | Endpoint | Uso |
|---|---|---|
GET | /api/health | Status operacional da API. |
GET | /api/public/newspapers | Catalogo de jornais ativos, com filtros state, category e limit. |
GET | /api/public/ad-spaces | Espaços publicitários ativos com jornal, formato, preço e prazo. |
GET | /api/public/publisher-plans | Planos SaaS disponiveis para donos de jornal. |
GET | /api/public/ad-categories | Categorias publicas de anúncios. |
| Metodo | Endpoint | Uso |
|---|---|---|
POST | /api/payments/checkout | Cria checkout para assinatura, anúncio ou plano do jornal. |
POST | /api/pdf/upload-url | Gera autorização temporaria para upload de PDF. |
POST | /api/pdf/access | Gera acesso temporario a PDF protegido, quando permitido. |
POST | /api/emails/welcome | Dispara e-mail transacional para usuário autenticado. |
No checkout, o cliente informa a vertical e o identificador do produto. O servidor valida produto, permissões, preço, disponibilidade e status da operação; o cliente nunca define valores financeiros, repasses ou recebedores.
| Metodo | Endpoint | Uso |
|---|---|---|
GET | /api/integrations/me | Válida a chave e retorna identidade, organização e escopos. |
GET | /api/integrations/payments | Lista pagamentos permitidos pelo escopo payments:read. |
GET | /api/integrations/reports/revenue | Retorna métricas agregadas pelo escopo reports:read. |
GET | /api/integrations/api-keys | Lista chaves do usuário autenticado. |
POST | /api/integrations/api-keys | Gera uma chave sj_live_ e mostra o segredo uma unica vez. |
POST | /api/integrations/api-keys/revoke | Revoga uma chave gerada pelo usuário. |
curl https://seujornaleiro.bilheking.com.br/api/integrations/me \
-H "Authorization: Bearer sj_live_sua_chave"POST /api/payments/checkout
Authorization: Bearer <supabase_access_token>
Content-Type: application/json
{
"kind": "subscription",
"newspaper_id": "uuid-do-jornal"
}Verticais aceitas: assinatura de leitor, compra de espaco publicitário e plano do jornal. O servidor válida o produto, a permissão e a disponibilidade antes de iniciar a operação.
Webhooks de pagamento são endpoints privados usados para confirmação de eventos externos. Eles exigem assinatura válida da origem e processamento idempotente.
Arquivos protegidos exigem autorização válida e acesso temporario. Operações negadas podem gerar registro de auditoria.
A API aplica autenticação, autorização por escopo, válidação de entrada, segregacao entre cliente e servidor, e proteção contra exposicao de credenciais.