Relatórios

Exporte transações, lançamentos e saldo consolidado de uma carteira e baixe o arquivo quando ficar pronto.

A exportação é assíncrona: você solicita o relatório, consulta até ele ficar pronto e baixa o arquivo por um link temporário.

Para listar e consultar relatórios, a credencial precisa de monkeypay:reports:read. Essa permissão é separada das permissões de carteiras e transações. Um 403 com type terminado em /auth-permission-denied indica falta da permissão exigida pela operação; confirme o acesso com o administrador da organização.

1POST /resource/reports

2 │ 202, completed: false

3 │ consulte a cada poucos segundos

4 ▼

5GET /resource/reports/{id}

6 │ completed: true e downloadUrl

7 │ link válido por 1 hora

8 ▼

9baixe o arquivo

1. Solicite

1POST /resource/reports

2Authorization: Bearer <seu-token>

3Content-Type: application/json

2 "walletId": "<sua-carteira>",

3 "type": "transactions",

4 "format": "csv",

5 "startDate": "2026-09-01T00:00:00.000Z",

6 "endDate": "2026-09-30T23:59:59.999Z",

7 "idempotencyKey": "extrato-2026-09"

`type`	Conteúdo	Formatos
`transactions`	Transações da carteira	`xlsx`, `csv`, `parquet`
`ledger-entries`	Lançamentos de crédito e débito	`xlsx`, `csv`, `parquet`
`consolidated-balance`	Saldo consolidado do período, até 90 dias	somente `pdf`

endDate não pode ser anterior a startDate.
idempotencyKey é opcional. Repetir a mesma chave devolve o relatório já criado, sem gerar outro: use-a para reenviar com segurança depois de um timeout.

A resposta é 202, com o relatório em data e completed: false. Guarde data.id.

2. Aguarde a geração

1GET /resource/reports/{id}

2 "error": false,

3 "message": "Report is still being generated",

4 "data": {

5 "id": "<id-do-relatorio>",

6 "fileName": null,

7 "format": "csv",

8 "completed": false,

9 "downloadUrl": null

10 }

11}

Consulte a cada poucos segundos até completed ser true. O arquivo não é enviado por webhook.

3. Baixe o arquivo

Com completed: true, downloadUrl traz um link assinado, válido por 1 hora. Baixe o arquivo direto desse link, sem o cabeçalho Authorization. Se o link expirar, consulte GET /resource/reports/{id} de novo para obter outro.

GET /resource/reports?walletId=<sua-carteira> lista os relatórios da carteira, paginados, com o mesmo downloadUrl nos que estão prontos.

Use apenas os campos documentados na referência. A resposta da solicitação pode trazer campos internos de armazenamento, que não fazem parte do contrato e podem mudar.

Permissões

Solicitar exige monkeypay:reports:write; consultar e listar exigem monkeypay:reports:read. Carteira de outra organização responde 404.