Referência da API

Começo rápido

1. O dono do negócio abre API no painel da Basely e cria uma chave com os scopes que o seu sistema precisa.
2. Guarde a chave no ambiente do seu servidor. Ela aparece uma vez só.
3. Chame /v1/me para testar a conexão e depois os endpoints que precisar.

curl https://api.baselyapp.com/v1/me \
  -H "Authorization: Bearer bsk_live_..."

curl "https://api.baselyapp.com/v1/financial/summary?period=2026-09" \
  -H "Authorization: Bearer bsk_live_..."

Autenticação

Mande a chave como Authorization: Bearer bsk_live_... em toda requisição.

• O negócio sai da chave. Não existe id de negócio no pedido, e uma chave nunca alcança outro negócio.
• Chaves de teste (bsk_test_) leem o negócio de verdade e validam escritas, mas nunca gravam.
• Só o dono do negócio cria, gira e revoga chaves. A chave para de funcionar quando quem a criou deixa de ser dono.
• Girar mantém a chave antiga funcionando pelo prazo que você escolher, para o servidor trocar sem cair.

Scopes

Cada chave leva só os scopes que recebeu. Endpoint sem o scope responde 403 SCOPE_DENIED.

Endpoints

Base abaixo. Toda resposta tem o cabeçalho x-request-id.

Convenções

• Dinheiro em centavos inteiros com a moeda. Datas em ISO 8601.
• Listas devolvem object: list, data, has_more. Use limit (até 100) e from/to para filtrar.
• Os saldos vêm dos livros, que o banco mantém em dia sozinho. Ler nunca pergunta ao banco direto.
• Atualizar agora no banco (Fresh) é uma ação separada, com cota mensal própria. Ler a API nunca gasta Fresh.
• Limite por chave por minuto: 120 leituras, 30 escritas, 20 relatórios. Passou: 429 com retry-after.

Erros

O erro tem um código estável, uma mensagem para gente e o id da requisição. Erro de escrita traz reason e field.

{ "error": { "code": "SCOPE_DENIED", "message": "...", "scope": "invoices:write", "request_id": "req_..." } }

Webhooks

O dono cadastra o endereço do seu sistema e escolhe os eventos. A entrega tenta de novo por 24 horas.

Cada entrega vem assinada com o segredo do endereço em basely-signature e traz basely-event-id para você descartar repetição. Confira assim:

import { createHmac, timingSafeEqual } from "node:crypto";

// header: basely-signature: t=<unix seconds>,v1=<hex>
export function isFromBasely(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}