Pular para o conteúdo principal

​
O que é o Ledger?

O Ledger é a camada contábil da Owem — a única fonte de verdade para saldos, conciliações e auditorias. Cada movimentação financeira gera uma entrada (entry) no Ledger:
  • credit: dinheiro entrando na conta (PIX IN)
  • debit: dinheiro saindo da conta (PIX OUT)
Nenhum saldo é alterado diretamente. Toda mudança ocorre pela criação de uma nova entrada no Ledger.

​
Por que usar o Ledger?

BenefícioDescrição
ImutabilidadeEntradas não são alteradas após criação
RastreabilidadeToda operação tem causa clara e auditável
ConciliaçãoSaldos são sempre consistentes
TransparênciaCada crédito/débito tem origem documentada

​
Consultas Disponíveis

​
1. Listar Movimentações

curl -X GET "https://api.owem.com.br/v4/i/ledger?type=credit&status=succeeded&page=1&limit=50" \
  -u "API_KEY:API_SECRET"
Filtros disponíveis:
ParâmetroDescrição
typecredit ou debit
reasonEx: pix_in:qrcode_paid, pix_out:processing
statusprocessing, succeeded, failed
startDateTimestamp inicial (ms)
endDateTimestamp final (ms)
pagePágina (default: 1)
limitItens por página (max: 100)

​
2. Buscar por externalId (Seu Identificador)

Ideal para conciliação quando você usa seu próprio ID: 
curl -X GET "https://api.owem.com.br/v4/i/ledger/external-id/{seu_id}" \
  -u "API_KEY:API_SECRET"

​
3. Buscar por endToEndId (Identificador PIX)

Para rastrear pelo código E2E do PIX: 
curl -X GET "https://api.owem.com.br/v4/i/ledger/end-to-end/{e2eId}" \
  -u "API_KEY:API_SECRET"

​
4. Buscar por entryId/txId (ID do QR Code)

Para confirmar pagamentos de QR Code: 
curl -X GET "https://api.owem.com.br/v4/i/ledger/entry-id/{txId}" \
  -u "API_KEY:API_SECRET"
O txId retornado na criação do QR é o mesmo que o entryId no Ledger.

​
Fluxo de Conciliação

​
Conciliação Diária

​
Exemplo: Conciliação de PIX IN

// Buscar todos os PIX IN do dia anterior
const yesterday = Date.now() - 86400000
const today = Date.now()

const response = await fetch(
  `https://api.owem.com.br/v4/i/ledger?` +
    `type=credit&` +
    `reason=pix_in:qrcode_paid&` +
    `status=succeeded&` +
    `startDate=${yesterday}&` +
    `endDate=${today}&` +
    `limit=100`,
  {
    headers: {
      Authorization: `Basic ${btoa("API_KEY:API_SECRET")}`,
    },
  }
)

const { data, pagination } = await response.json()

for (const entry of data) {
  await reconcileEntry({
    id: entry.id,
    amount: entry.netAmount,
    endToEndId: entry.endToEndId,
    entryId: entry.entryId,
    createdAt: entry.createdAt,
  })
}

// Se houver mais páginas, continuar
if (pagination.page < pagination.totalPages) {
  // Buscar próxima página
}

​
Estrutura de uma Entrada

{
  "id": "E123456789...",
  "type": "credit",
  "reason": "pix_in:qrcode_paid",
  "status": "succeeded",
  "grossAmount": 100.0,
  "feeAmount": 0.15,
  "netAmount": 99.85,
  "endToEndId": "E123456789...",
  "entryId": "abc123def...",
  "externalId": "PEDIDO-001",
  "accountId": "123456789012",
  "userId": "usr_abc123",
  "createdAt": 1766523042000,
  "createdDate": "2025-12-24",
  "payer": {
    "name": "JOAO DA SILVA",
    "cpfCnpj": "12345678900"
  },
  "receiver": {
    "name": "MINHA EMPRESA"
  }
}

​
Campos Importantes

CampoDescrição
idIdentificador único da entrada
typecredit (entrada) ou debit (saída)
reasonMotivo contábil (ex: pix_in:qrcode_paid)
statusprocessing, succeeded, failed
grossAmountValor bruto
feeAmountTarifa cobrada
netAmountValor líquido (gross - fee ou gross + fee)
endToEndIdIdentificador E2E do PIX
entryIdID do QR Code (PIX IN)
externalIdSeu identificador (se enviado)

​
Reasons (Motivos)

ReasonTipoDescrição
pix_in:qrcode_paidcreditPagamento de QR Code
pix_in:creditedcreditCrédito via chave PIX
pix_out:processingdebitPIX OUT enviado
pix_in:refunded_processingdebitEstorno de PIX IN
pix_out:refunded_processingcreditDevolução de PIX OUT

​
Boas Práticas

Sempre envie seu identificador nas operações. Facilita muito a reconciliação.
Execute rotinas de conciliação pelo menos uma vez ao dia.
Entradas em processing ainda não estão finalizadas. Verifique novamente depois.
Em caso de suporte, o requestId ajuda a rastrear problemas rapidamente.

​
Próximos Passos

API Reference

Documentação completa do Ledger

MEDs

Lidando com disputas