Guia de Integração da API

Primeiros Passos

Para usar a API do Suma você precisa de uma conta e uma chave de API.

Faça login na sua conta Suma em sumabot.online.
Vá em Configurações > Chaves de API e crie uma nova chave. Copie-a imediatamente — ela é mostrada apenas uma vez.
Inclua a chave em cada requisição como um token Bearer no cabeçalho Authorization.

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

Autenticação

Todas as requisições de API requerem um token Bearer. Chaves de API começam com sb_ e são vinculadas à sua conta. Inclua o token no cabeçalho Authorization.

Authorization: Bearer sb_your_api_key_here

Chaves são hasheadas no nosso banco de dados — não podemos recuperar uma chave perdida. Crie uma nova se necessário.

Testar Conexão

Cole sua chave de API abaixo e clique em Testar para verificar se funciona. Isso chama GET /api/v1/ping.

Limite de Taxa

A API permite 60 requisições por minuto por padrão. Informações de limite de taxa são incluídas nos cabeçalhos de resposta.

Header	Descrição
`X-RateLimit-Limit`	Máximo de requisições por janela
`X-RateLimit-Remaining`	Requisições restantes na janela atual
`X-RateLimit-Reset`	Timestamp Unix quando a janela reseta

Tratamento de Erros

Erros retornam uma estrutura JSON consistente com um código legível por máquina e uma mensagem legível por humanos.

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

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

Paginação

Endpoints de lista suportam paginação baseada em offset com parâmetros page e per_page. Padrão: 25 itens por página, máximo 100.

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

Respostas paginadas incluem um objeto meta com contagens totais.

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

Exemplos de Código

Estes exemplos mostram uso básico com transações. A API suporta 90+ operações em categorias, orçamentos, alertas, recorrentes, grupos, importação/exportação e mais. Veja a referência completa da API abaixo para todos os endpoints.

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,
});

Resposta

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"
  }
}

Referência Completa da API

Esta página cobre o básico. A API completa tem 90+ operações em 44 grupos de recursos. Explore a documentação interativa para todos os endpoints, parâmetros e esquemas de resposta.

Swagger UI ReDoc OpenAPI JSON

O Swagger UI permite testar endpoints diretamente no navegador com sua chave de API.