Paginação e filtros

Os endpoints que listam objetos devolvem uma página de cada vez, do mais recente para o mais antigo. Cada resposta diz se há mais itens e traz o cursor para buscar a próxima página.

A resposta de uma listagemCopiar link da seção

{
  "object": "list",
  "data": [
    { "id": "ltr_8Kq2wX4mN7pR", "object": "letter", "status": "posted" }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Imx0cl84S3Eyd1g0bU43cFIifQ"
}

No exemplo, cada item foi encurtado. Na resposta real, cada item é o objeto inteiro.

Os parâmetrosCopiar link da seção

O cursor é um texto opaco: não tente montar nem alterar. Ao buscar a próxima página, mantenha os mesmos filtros e o mesmo limit da primeira. Itens criados depois que você começou a percorrer a lista aparecem só em uma nova listagem, a partir da primeira página.

FiltrosCopiar link da seção

Todos os filtros são opcionais e podem ser combinados.

• status e type aceitam um dos valores listados na referência de cada endpoint.
• reference encontra os itens com exatamente esse valor de reference. Veja Metadados e referência.
• created_after inclui os itens criados a partir desse momento. created_before inclui os criados antes dele. Use data e hora ISO 8601, como 2026-10-01T00:00:00Z.
• object_id mostra os eventos de um objeto, como todos os eventos de uma correspondência.

Por exemplo, todas as correspondências postadas em outubro de 2026:

curl "https://api.cartaflow.com.br/v1/letters?status=posted&created_after=2026-10-01T00:00:00Z&created_before=2026-11-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $CARTAFLOW_API_KEY"

Lembre de codificar os valores na URL: o + de um fuso horário, por exemplo, vira %2B. Datas em UTC com Z evitam esse cuidado.

Percorrer todas as páginasCopiar link da seção

async function* listAll(path, params = {}) {
  let cursor;
  do {
    const query = new URLSearchParams({ ...params, limit: '100', ...(cursor ? { cursor } : {}) });
    const response = await fetch(`https://api.cartaflow.com.br/v1${path}?${query}`, {
      headers: { Authorization: `Bearer ${process.env.CARTAFLOW_API_KEY}` },
    });
    const page = await response.json();
    yield* page.data;
    cursor = page.has_more ? page.next_cursor : undefined;
  } while (cursor);
}

for await (const letter of listAll('/letters', { status: 'posted', created_after: '2026-10-01T00:00:00Z' })) {
  console.log(letter.id, letter.reference);
}