Guía de Integración API

Primeros Pasos

Para usar la API de Suma necesitas una cuenta y una clave API.

Inicia sesión en tu cuenta de Suma en sumabot.online.
Ve a Configuración > Claves API y crea una nueva clave. Cópiala de inmediato — solo se muestra una vez.
Incluye la clave en cada petición como token Bearer en el encabezado Authorization.

URL base: https://sumabot.online/api/v1

Autenticación

Todas las peticiones API requieren un token Bearer. Las claves API comienzan con sb_ y están vinculadas a tu cuenta. Incluye el token en el encabezado Authorization.

Authorization: Bearer sb_your_api_key_here

Las claves se almacenan hasheadas en nuestra base de datos — no podemos recuperar una clave perdida. Crea una nueva si es necesario.

Probar Conexión

Pega tu clave API abajo y haz clic en Probar para verificar que funciona. Esto llama a GET /api/v1/ping.

Límite de Peticiones

La API permite 60 peticiones por minuto por defecto. La información del límite se incluye en los encabezados de respuesta.

Header	Descripción
`X-RateLimit-Limit`	Máximo de peticiones por ventana
`X-RateLimit-Remaining`	Peticiones restantes en la ventana actual
`X-RateLimit-Reset`	Marca de tiempo Unix cuando se reinicia la ventana

Manejo de Errores

Los errores devuelven una estructura JSON consistente con un código legible por máquina y un mensaje legible por humanos.

{"error": {"code": "not_found", "message": "Resource not found"}}

Estado	Significado
`400`	Bad Request
`401`	Unauthorized (invalid/missing API key)
`403`	Forbidden / Feature disabled
`404`	Not Found
`422`	Validation Error
`429`	Rate Limited

Paginación

Los endpoints de listado soportan paginación basada en offset con los parámetros page y per_page. Por defecto: 25 elementos por página, máximo 100.

GET /api/v1/transactions?page=2&per_page=25

Las respuestas paginadas incluyen un objeto meta con los conteos totales.

{"data": [...], "meta": {"page": 2, "per_page": 25, "total": 150, "total_pages": 6}}

Ejemplos de Código

Estos ejemplos muestran el uso básico con transacciones. La API soporta más de 90 operaciones incluyendo categorías, presupuestos, alertas, recurrentes, grupos, importación/exportación y más. Consulta la referencia completa más abajo.

bash

# List transactions (with filters)
curl -s "https://sumabot.online/api/v1/transactions?type=expense&per_page=10" \
  -H "Authorization: Bearer sb_YOUR_KEY" | jq

# Create a transaction
curl -s -X POST https://sumabot.online/api/v1/transactions \
  -H "Authorization: Bearer sb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50.00",
    "type": "expense",
    "description": "Lunch",
    "date": "2026-03-16",
    "currency": "USD",
    "category_id": "CATEGORY_UUID"
  }' | jq

# Delete a transaction
curl -s -X DELETE https://sumabot.online/api/v1/transactions/TRANSACTION_ID \
  -H "Authorization: Bearer sb_YOUR_KEY" | jq

bash

# List transactions (with filters)
http GET "https://sumabot.online/api/v1/transactions?type=expense&per_page=10" \
  Authorization:"Bearer sb_YOUR_KEY"

# Create a transaction
http POST https://sumabot.online/api/v1/transactions \
  Authorization:"Bearer sb_YOUR_KEY" \
  amount="50.00" type="expense" description="Lunch" \
  date="2026-03-16" currency="USD" category_id="CATEGORY_UUID"

# Delete a transaction
http DELETE https://sumabot.online/api/v1/transactions/TRANSACTION_ID \
  Authorization:"Bearer sb_YOUR_KEY"

python

import requests

BASE = "https://sumabot.online/api/v1"
HEADERS = {"Authorization": "Bearer sb_YOUR_KEY"}

# List transactions (with filters)
resp = requests.get(f"{BASE}/transactions", headers=HEADERS, params={
    "type": "expense",
    "per_page": 10,
})
for tx in resp.json()["data"]:
    print(f"{tx['date']} {tx['description']}: {tx['amount']} {tx['currency']}")

# Create a transaction
resp = requests.post(f"{BASE}/transactions", headers=HEADERS, json={
    "amount": "50.00",
    "type": "expense",
    "description": "Lunch",
    "date": "2026-03-16",
    "currency": "USD",
    "category_id": "CATEGORY_UUID",
})
tx = resp.json()["data"]
print(f"Created: {tx['id']}")

# Delete a transaction
requests.delete(f"{BASE}/transactions/{tx['id']}", headers=HEADERS)

javascript

const BASE = "https://sumabot.online/api/v1";
const HEADERS = {
  "Authorization": "Bearer sb_YOUR_KEY",
  "Content-Type": "application/json",
};

// List transactions (with filters)
const resp = await fetch(`${BASE}/transactions?type=expense&per_page=10`, {
  headers: HEADERS,
});
const { data, meta } = await resp.json();
console.log(`Page ${meta.page} of ${meta.total_pages}`);

// Create a transaction
const created = await fetch(`${BASE}/transactions`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    amount: "50.00",
    type: "expense",
    description: "Lunch",
    date: "2026-03-16",
    currency: "USD",
    category_id: "CATEGORY_UUID",
  }),
});
const { data: tx } = await created.json();
console.log(`Created: ${tx.id}`);

// Delete a transaction
await fetch(`${BASE}/transactions/${tx.id}`, {
  method: "DELETE",
  headers: HEADERS,
});

Respuesta

json

{
  "data": {
    "id": "a1b2c3d4-...",
    "amount": "50.00",
    "type": "expense",
    "description": "Lunch",
    "date": "2026-03-16",
    "currency": "USD",
    "category_id": "e5f6a7b8-...",
    "category": { "id": "e5f6a7b8-...", "name": "Food", "type": "expense" },
    "group_id": null,
    "metadata": { "source": "api" },
    "inserted_at": "2026-03-16T12:00:00Z",
    "updated_at": "2026-03-16T12:00:00Z"
  }
}

Referencia API Completa

Esta página cubre lo básico. La API completa tiene más de 90 operaciones en 44 grupos de recursos. Explora la documentación interactiva para todos los endpoints, parámetros y esquemas de respuesta.

Swagger UI ReDoc OpenAPI JSON

El Swagger UI te permite probar endpoints directamente en el navegador con tu API key.