Consultar

Webhook avisa. Consulta confirma. Toda reconciliação termina num GET.

Pelo id

Copiar#!/usr/bin/env bash
# Consulta uma cobrança pelo id. O GET é sempre a fonte de verdade do status.
#   LM_TRANSACTION_ID=txn_01j... ./get-transaction.sh
set -euo pipefail

curl --fail-with-body -sS "$LM_API_URL/v1/transactions/$LM_TRANSACTION_ID" \
  -H "Authorization: Bearer $LM_API_KEY"

Esta é a fonte de verdade do status. Se o seu sistema e o nosso discordam, o GET decide.

Id que não existe, id de outra conta e id do outro ambiente respondem os três 404. A resposta não distingue os casos de propósito, para não confirmar a existência de um objeto que não é seu.

A listagem

Copiar#!/usr/bin/env bash
# Primeira página de cobranças pagas, com os totais do recorte.
# A resposta traz `next_cursor`: repita a chamada com `cursor=<next_cursor>` até vir nulo.
set -euo pipefail

curl --fail-with-body -sS -G "$LM_API_URL/v1/transactions" \
  -H "Authorization: Bearer $LM_API_KEY" \
  --data-urlencode "status=paid" \
  --data-urlencode "created_from=2026-09-01T00:00:00Z" \
  --data-urlencode "with_totals=1" \
  --data-urlencode "limit=50"

Paginação por cursor, explicada em Paginação. Os filtros disponíveis estão na referência da operação; em resumo, você recorta por status, por janela de criação, por janela de pagamento e por busca.

with_totals=1 acrescenta os totais do recorte: quantas cobranças e quanto em bruto, taxa e líquido, sobre o filtro inteiro e não sobre a página. Peça na primeira página só; o número é o mesmo em todas.

Expiradas ficam de fora

A listagem não traz cobrança expired, e os totais também não a contam. Pedir status=expired responde 400 validation_failed.

Para ver uma cobrança expirada, consulte pelo id. O motivo e as consequências estão em Expiração.

Busca por q

q aceita um critério por vez, e ele é detectado pelo formato do que você mandar:

• Começa com txn_: busca pelo id da cobrança.
• Contém arroba: busca pelo e-mail exato do cliente. Exato mesmo, não é busca parcial.
• Só dígitos: busca pelo documento do cliente.

Qualquer outro formato é 400 validation_failed com param igual a q. Não existe busca por nome, nem por trecho de e-mail, nem por conteúdo de metadata.

A timeline

Quando o suporte pergunta "o que aconteceu com essa cobrança", a resposta está aqui:

Copiar// Consulta uma cobrança e imprime a timeline dela.
//   LM_TRANSACTION_ID=txn_01j... node get-transaction.mjs
const apiUrl = process.env.LM_API_URL;
const apiKey = process.env.LM_API_KEY;
const id = process.env.LM_TRANSACTION_ID;

const auth = { Authorization: `Bearer ${apiKey}` };

const res = await fetch(`${apiUrl}/v1/transactions/${id}`, { headers: auth });
const cobranca = await res.json();

if (!res.ok) {
  // Id de outro ambiente ou de outra conta responde 404, nunca 403.
  console.error(res.status, cobranca.error.code, cobranca.error.request_id);
  process.exit(1);
}

console.log(cobranca.status, cobranca.amount, cobranca.paid_at ?? 'ainda não paga');

const timeline = await fetch(`${apiUrl}/v1/transactions/${id}/timeline`, { headers: auth });
const { data } = await timeline.json();

for (const evento of data) {
  console.log(evento.at, evento.type);
}

A timeline junta, em ordem cronológica, três coisas: as mudanças de status da própria cobrança, os lançamentos financeiros que ela gerou, e cada tentativa de entrega de webhook, com a tentativa e o código HTTP que o seu servidor respondeu.

É por aí que se descobre que o webhook foi entregue e o seu endpoint devolveu 500, o que é bem mais comum do que webhook não enviado.

Quando consultar, e quando não

Consulte no fechamento do dia, ao reconciliar, e sempre que o cliente reclamar. Consulte também depois de um 503 na criação, para saber o que sobrou.

Não consulte em laço para descobrir se a cobrança foi paga. Isso queima o limite de leitura e chega depois do webhook. Use transaction.paid.

Próximo passo

Webhooks, para parar de perguntar e começar a ser avisado.

Referência: Consulta uma cobrança, Lista cobranças do seller e Timeline de uma cobrança.