Pular para o conteúdo principal

Consultar Extrato

Use esta rota para consultar o extrato da sua conta ou de um parceiro específico. A resposta é uma lista unificada de créditos e débitos, ordenada da movimentação mais recente para a mais antiga.

GETv3/financial/statement

Request Query Params​

AtributoTipoDescrição
sub_seller_idstringID do parceiro cujo extrato será consultado. Quando omitido, a consulta retorna o extrato da conta do seller.
date_startdateInício do intervalo no formato YYYY-MM-DD. Padrão: 7 dias antes de date_end (hoje, horário de Brasília).
date_enddateFim do intervalo no formato YYYY-MM-DD. Padrão: hoje (horário de Brasília). Deve ser maior ou igual a date_start.
pageint32Página da consulta. Padrão: 1. Mínimo: 1.
page_sizeint32Quantidade de itens por página. Padrão: 20. Mínimo: 1. Máximo: 100.
Intervalo máximo

O intervalo entre date_start e date_end não pode ultrapassar 180 dias.

Dica

net_value, gross_amount e splits_amount são em centavos e assinados: positivos no crédito, negativos no débito. O sentido está em operation_type (credit ou debit).

Como o extrato é montado​

Cada linha é um lançamento imutável. Uma transação estornada ou em chargeback gera dois lançamentos: o crédito original e o débito posterior, cada um com a sua data.

Eventotypeoperation_typeQuando entra
Transação pagatransactioncreditNa data em que a transação foi paga.
Venda não antecipadatransactioncreditUma linha na data da venda, com o nó receivables[] listando as parcelas (inclusive futuras). No dia do saque entra só o wd_; a data efetiva é preenchida no array da venda.
Estorno ou chargebacktransactiondebitNa data do estorno/chargeback. O crédito original permanece. status é refunded ou chargedback.
Saque (manual ou automático)withdrawaldebitPara saques manuais no momento da solicitação, para contas que possuem repasse automático no momento da transferência.

Identificadores​

O entry_id é determinístico. Você pode usá-lo para deduplicar páginas:

typeFormato do entry_id
transaction (crédito)txn_{transaction_id}_credit
transaction (débito)txn_{transaction_id}_debit
withdrawalwd_{withdrawal_id}

Response Object​

AtributoTipoDescrição
totalint32Total de lançamentos que atendem ao filtro passado na consulta.
pageint32Página atual referente ao offset de páginas.
offsetint32Total de páginas para page_size dividido pelo total de lançamentos da consulta.
statementarrayLançamentos do intervalo, ordenados por data de criação decrescente.
statement[][entry_id]stringID determinístico do lançamento.
statement[][type]stringTipo. Valores: transaction, withdrawal.
statement[][status]stringStatus da origem. Exemplos: paid, refunded, chargedback, processing, transferred.
statement[][source_id]stringID da origem: transação Marlim original ou saque.
statement[][date_created]dateTimeData do lançamento no formato ISODateTime.
statement[][date_created_timestamp]int64Epoch em milissegundos de date_created, usado na ordenação.
statement[][date_updated]dateTimeData da última atualização do lançamento no formato ISODateTime.
statement[][operation_type]stringSentido do lançamento. Valores: credit, debit.
statement[][transaction_id]stringID da transação. null em saques.
statement[][withdrawal_id]stringID do saque. null em transações. No repasse automático é o UUID da TED.
statement[][installments]stringNúmero de parcelas da transação. null em saques.
statement[][payment_method]stringMeio de pagamento da transação. null em saques.
statement[][gross_amount]int32Valor bruto da venda em centavos, assinado. No débito é negativo. Em parcela não antecipada é o bruto da transação, não o da parcela.
statement[][rate]numberTaxa da venda em percentual. Para operações de débito: 0.
statement[][rate_value]int32Valor da taxa da venda em centavos. Para operações de débito: 0.
statement[][splits_amount]int32Soma dos split.amount da transação, em centavos, assinada. No saque: 0.
statement[][net_value]int32Valor líquido em centavos, assinado. Seller: gross_amount - rate_value - splits_amount (no crédito). Parceiro: o amount do split. Saque: igual a gross_amount.
statement[][acquirer]stringAdquirente da transação. null em saques.
statement[][receivables]arrayPresente em créditos e débitos de venda não antecipada. Omitido em transações antecipadas e em saques. payable_details não é devolvido neste endpoint.
statement[][receivables][][installment]int32Número da parcela.
statement[][receivables][][gross_amount]int32Valor bruto da parcela, em centavos.
statement[][receivables][][net_amount]int32Valor líquido da parcela, em centavos.
statement[][receivables][][rate]numberTaxa da parcela em percentual, duas casas decimais.
statement[][receivables][][rate_value]int32Valor da taxa da parcela, em centavos.
statement[][receivables][][expected_settlement_date]dateTimeData prevista de repasse (execution_date da Barte).
statement[][receivables][][effective_settlement_date]dateTimeData do saque/TED que liquidou a parcela. null até o repasse.
Exemplo de Response
{
  "total": 2,
  "page": 1,
  "offset": 1,
  "statement": [
    {
      "entry_id": "wd_withdrawal_1234567890",
      "type": "withdrawal",
      "status": "processing",
      "source_id": "withdrawal_1234567890",
      "date_created": "2026-08-20T14:30:00.000Z",
      "date_created_timestamp": 1755700200000,
      "date_updated": "2026-08-20T14:30:00.000Z",
      "operation_type": "debit",
      "transaction_id": null,
      "withdrawal_id": "withdrawal_1234567890",
      "installments": null,
      "payment_method": null,
      "gross_amount": -10000,
      "rate": 0,
      "rate_value": 0,
      "splits_amount": 0,
      "net_value": -10000,
      "acquirer": null
    },
    {
      "entry_id": "txn_HcDscltTIVK3VMAAOj7J_credit",
      "type": "transaction",
      "status": "paid",
      "source_id": "HcDscltTIVK3VMAAOj7J",
      "date_created": "2026-08-18T14:30:00.000Z",
      "date_created_timestamp": 1755527400000,
      "date_updated": "2026-08-18T14:30:00.000Z",
      "operation_type": "credit",
      "transaction_id": "HcDscltTIVK3VMAAOj7J",
      "withdrawal_id": null,
      "installments": "1",
      "payment_method": "credit_card",
      "gross_amount": 90000,
      "rate": 2.49,
      "rate_value": 2241,
      "splits_amount": 86310,
      "net_value": 86310,
      "acquirer": "sample_acquirer"
    }
  ]
}
Exemplo de lançamento não antecipado
{
  "entry_id": "txn_HcDscltTIVK3VMAAOj7J_credit",
  "type": "transaction",
  "status": "paid",
  "source_id": "HcDscltTIVK3VMAAOj7J",
  "date_created": "2026-08-18T14:30:00.000Z",
  "date_created_timestamp": 1755527400000,
  "date_updated": "2026-08-18T14:30:00.000Z",
  "operation_type": "credit",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "withdrawal_id": null,
  "installments": "2",
  "payment_method": "credit_card",
  "gross_amount": 10000,
  "rate": 3.00,
  "rate_value": 300,
  "splits_amount": 0,
  "net_value": 9700,
  "acquirer": "sample_acquirer",
  "receivables": [
    {
      "installment": 1,
      "gross_amount": 5000,
      "net_amount": 4850,
      "rate": 3.00,
      "rate_value": 150,
      "expected_settlement_date": "2026-09-18T03:05:00.000Z",
      "effective_settlement_date": "2026-09-18T14:30:00.000Z"
    },
    {
      "installment": 2,
      "gross_amount": 5000,
      "net_amount": 4850,
      "rate": 3.00,
      "rate_value": 150,
      "expected_settlement_date": "2026-10-18T03:05:00.000Z",
      "effective_settlement_date": null
    }
  ]
}

Error Object​

AtributoTipoDescrição
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.
Exemplo de erro
{
  "errors": [
    {
      "type": "date_end",
      "message": "The parameter [ date_end ] must be at most 180 days after date_start."
    }
  ]
}

Exemplos​

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim.

Request
curl -X GET -G "https://api.marlim.co/v3/financial/statement" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d date_start="2026-08-14" \ 
-d date_end="2026-08-20"
Response200
{
  "total": 1,
  "page": 1,
  "offset": 1,
  "statement": [
    {
      "entry_id": "txn_HcDscltTIVK3VMAAOj7J_credit",
      "type": "transaction",
      "status": "paid",
      "source_id": "HcDscltTIVK3VMAAOj7J",
      "date_created": "2026-08-18T14:30:00.000Z",
      "date_created_timestamp": 1755527400000,
      "date_updated": "2026-08-18T14:30:00.000Z",
      "operation_type": "credit",
      "transaction_id": "HcDscltTIVK3VMAAOj7J",
      "withdrawal_id": null,
      "installments": "1",
      "payment_method": "credit_card",
      "gross_amount": 90000,
      "rate": 2.49,
      "rate_value": 2241,
      "splits_amount": 86310,
      "net_value": 86310,
      "acquirer": "sample_acquirer"
    }
  ]
}