Referencia de la API

Inicio rápido

1. El dueño del negocio abre API en el panel de Basely y crea una clave con los scopes que tu sistema necesita.
2. Guarda la clave en el entorno de tu servidor. Se muestra una sola vez.
3. Llama a /v1/me para probar la conexión y después a los endpoints que necesites.

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_..."

Autenticación

Envía la clave como Authorization: Bearer bsk_live_... en cada solicitud.

• El negocio sale de la clave. No hay id de negocio en la solicitud, y una clave nunca alcanza otro negocio.
• Las claves de prueba (bsk_test_) leen el negocio real y validan escrituras, pero nunca guardan.
• Solo el dueño del negocio crea, rota y revoca claves. La clave deja de funcionar cuando quien la creó ya no es el dueño.
• Rotar mantiene la clave anterior funcionando durante el plazo que elijas, para que tu servidor cambie sin caerse.

Scopes

Cada clave lleva solo los scopes que recibió. Un endpoint sin su scope responde 403 SCOPE_DENIED.

Endpoints

URL base abajo. Toda respuesta tiene el encabezado x-request-id.

Convenciones

• El dinero va en centavos enteros con la moneda. Las fechas en ISO 8601.
• Las listas devuelven object: list, data, has_more. Usa limit (hasta 100) y from/to para filtrar.
• Los saldos vienen de los libros, que el banco mantiene al día solo. Leer nunca le pregunta al banco directo.
• Actualizar ahora en el banco (Fresh) es una acción aparte, con su propia cuota mensual. Leer la API nunca gasta Fresh.
• Límite por clave por minuto: 120 lecturas, 30 escrituras, 20 reportes. Al pasarlo: 429 con retry-after.

Errores

El error tiene un código estable, un mensaje para personas y el id de la solicitud. Los errores de escritura agregan reason y field.

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

Webhooks

El dueño registra la dirección de tu sistema y elige los eventos. La entrega reintenta durante 24 horas.

Cada entrega va firmada con el secreto de la dirección en basely-signature y trae basely-event-id para descartar repeticiones. Verifícalo así:

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 ?? ""));
}