Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt

Use this file to discover all available pages before exploring further.

Endpoints de listagem (GET /customers, GET /invoices, etc.) retornam uma página por vez usando paginação por cursor (keyset). Você não pula para uma página específica — você avança página por página, do início ao fim.

​
Parâmetros

ParâmetroPadrãoMáximoDescrição
limitvaria por endpoint (10 ou 20)100Quantos itens por página
page——Cursor opaco da próxima página (recebido na resposta anterior)
O default exato de cada endpoint está documentado na referência. Independente do default, o máximo é sempre 100 itens por página.
page aqui não é um número de página. É um cursor opaco que o Simplo devolve para você usar na próxima chamada. Não tente construir o cursor manualmente.

​
Estrutura da resposta

{
  "object": "list",
  "url": "/api/v1/customers",
  "has_more": true,
  "data": [
    { "id": "cus_...", "name": "Maria Silva", "...": "..." },
    { "id": "cus_...", "name": "João Santos", "...": "..." }
  ]
}
  • object — sempre "list" em respostas de listagem.
  • url — caminho do endpoint que gerou esta lista.
  • has_more — true se ainda há mais itens depois desta página, false se chegou ao fim.
  • data — os recursos da página atual.

​
Próxima página

O cursor para a próxima página vem nos headers da resposta. Procure pelos headers padrão de paginação (Link, Current-Page, Page-Items, Total-Count) — o cursor para a próxima página é o valor de page na URL rel="next" do header Link. Exemplo de header: 
Link: <https://besimplo.com/api/v1/customers?page=eyJpZCI6...&limit=10>; rel="next"
Você usa esse cursor diretamente na próxima requisição: 
curl "https://besimplo.com/api/v1/customers?page=eyJpZCI6...&limit=10" \
  -H "Authorization: ApiKey $SIMPLO_API_KEY"

​
Percorrer todas as páginas

# Ruby
def each_customer(api_key:)
  url = "https://besimplo.com/api/v1/customers?limit=100"
  loop do
    response = HTTP.headers("Authorization" => "ApiKey #{api_key}").get(url)
    body = JSON.parse(response.body.to_s)
    body["data"].each { |customer| yield customer }
    break unless body["has_more"]
    next_link = response.headers["Link"]
    url = next_link[/<([^>]+)>;\s*rel="next"/, 1]
  end
end

// Node.js
async function* allCustomers(apiKey) {
  let url = "https://besimplo.com/api/v1/customers?limit=100";
  while (url) {
    const res = await fetch(url, { headers: { Authorization: `ApiKey ${apiKey}` } });
    const body = await res.json();
    for (const customer of body.data) yield customer;
    if (!body.has_more) break;
    const link = res.headers.get("link") ?? "";
    const match = link.match(/<([^>]+)>;\s*rel="next"/);
    url = match ? match[1] : null;
  }
}
Use limit=100 (o máximo) para reduzir o número de chamadas e evitar rate limit.

​
Filtros

Vários endpoints aceitam filtros adicionais. Por exemplo, listar faturas pagas de um cliente: 
curl "https://besimplo.com/api/v1/invoices?customer=cus_xxx&status=paid&limit=100" \
  -H "Authorization: ApiKey $SIMPLO_API_KEY"
Os filtros disponíveis estão documentados em cada endpoint na referência da API.