Paginação

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âmetro	Padrão	Máximo	Descrição
`limit`	varia por endpoint (10 ou 20)	`100`	Quantos 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.

Comece por aqui

Conceitos

Parâmetros

Estrutura da resposta

Próxima página

Percorrer todas as páginas

Filtros

​Parâmetros

​Estrutura da resposta

​Próxima página

​Percorrer todas as páginas

​Filtros

Parâmetros

Estrutura da resposta

Próxima página

Percorrer todas as páginas

Filtros