Gerar relatório via API
A API de relatórios de outras operações permite definir o conteúdo e o canal de entrega do arquivo, gerar relatórios manualmente ou programar sua criação automática e baixá-los quando estiverem disponíveis.
Para enviar solicitações, use seu Access Token de produçãoChave privada da aplicação criada no Mercado Pago e utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Produção > Credenciais de produção..
O fluxo consiste nas seguintes etapas:
- Configurar as colunas do arquivo e os notificadores de entrega.
- Gerar o relatório manualmente, consultar seu status e baixá-lo quando estiver disponível.
- Programar a criação automática se precisar receber o relatório periodicamente.
- Consultar o conteúdo das notificações Webhook e validar sua assinatura.
Lembre-se de que o tipo de relatório que você deseja configurar, gerar ou programar é definido pelo parâmetro de rota reportId. Os valores disponíveis são os seguintes:
reportId | Tipo de relatório | Descrição |
activities_collection | Relatório de cobranças | Inclui as cobranças recebidas por checkout, QR, Point, marketplace e outros canais. |
activities_after_collection | Relatório pós-cobrança | Inclui devoluções, contestações, reclamações e ajustes posteriores à cobrança. |
activities_withdraw | Relatório de saques | Inclui saques e transferências de fundos da conta. |
1. Configurar seus relatórios
A configuração determina quais colunas o arquivo terá, como os dados serão exibidos e por quais canais o relatório será informado ou entregue. Você deve criar uma configuração para cada tipo de relatório, identificado por reportId, antes de gerar ou programar arquivos.
Para criá-la, envie uma solicitação para /v1/reporting/operations/{reportId}/configPOST com os objetos structure e notifiers.
- Em
structure, atribua um nome à configuração por meio denamee defina as colunas do arquivo emcolumns. Cada elemento decolumnsdeve conter akeyde um campo aceito pelo tipo de relatório. Consulte os valores disponíveis em Campos do relatório. - Em
structure.file_format, você pode definir os separadores, o formato de data, o nome e o prefixo do arquivo. - Em
structure.display_timezone, você pode definir o fuso horário usado para exibir as datas do arquivo. Esse valor não altera o intervalo enviado posteriormente emfilters.creation_date.range. - Em
notifiers, inclua pelo menos um canal para informar que o relatório está disponível ou entregar o arquivo gerado.
Cada elemento de notifiers contém um type, que identifica o canal de entrega, e um objeto data, que reúne os dados de conexão exigidos por esse canal.
Valor de notifiers[].type | Canal de entrega | Campos que devem ser enviados em notifiers[].data |
webhook | Envia uma notificação para uma URL própria. | url, key |
ftp | Entrega o arquivo em um servidor FTP ou SFTP mediante senha. | server, port, username, password, remote_dir |
ftp_pkey | Entrega o arquivo em um servidor SFTP mediante uma chave privada SSH. | server, port, username, private_key, remote_dir |
internal_sftp | Entrega o arquivo pelo canal SFTP interno do Mercado Pago. | Envie data como um objeto vazio; seus atributos são gerenciados internamente. |
Em caso de sucesso, a resposta contém structure.id, que identifica a configuração, e notifiers[].id, que identifica cada notificador criado. Salve esses valores: você precisará deles para atualizar a configuração ou programar a criação automática.
Para consultar a configuração ativa de um tipo de relatório, envie uma solicitação para /v1/reporting/operations/{reportId}/configGET. A resposta retorna a estrutura, os notificadores associados e seus respectivos identificadores.
Para modificar uma configuração existente, use o valor de structure.id como structureId em /v1/reporting/operations/{reportId}/config/{structureId}PUT.
Com essa solicitação, você pode atualizar o nome e as colunas do relatório, a configuração do arquivo de saída, o fuso horário usado para exibir as datas e os notificadores de entrega.
2. Gerar relatório manualmente
Gere um relatório para um período específico e baixe-o quando estiver disponível.
Para gerar o relatório, envie uma solicitação para /v1/reporting/operations/{reportId}/statementsPOST. Com essa solicitação, você pode definir o período do relatório, aplicar os filtros aceitos pelo tipo selecionado e escolher o formato do arquivo. O período não pode exceder um ano.
curl -X POST \
'https://api.mercadopago.com/v1/reporting/operations/activities_collection/statements' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"filters":{"creation_date":{"range":{"gte":"2026-03-01T00:00:00-03:00","lte":"2026-03-31T23:59:59-03:00"}}}}'Em caso de sucesso, a resposta retorna record_id. Use esse valor como uid para consultar o status do relatório e baixar o arquivo.
Para consultar o status de um relatório, use o record_id obtido ao criá-lo como uid em /v1/reporting/operations/{reportId}/statements/{uid}GET.
| Status | Descrição |
pending | O relatório está em processo de geração. |
available | O arquivo está disponível para download. |
failed | Não foi possível concluir a geração. |
empty | Nenhuma operação foi encontrada para o intervalo e os filtros enviados. |
Você também pode listar os relatórios gerados por meio de /v1/reporting/operations/{reportId}/statementsGET e filtrar os resultados por status, data de criação e origem.
Quando o relatório tiver o status available, baixe-o por meio de /v1/reporting/operations/{reportId}/statements/{uid}/downloadGET. Use o mesmo uid da consulta e escolha entre os formatos CSV e XLSX. Os arquivos maiores podem ser entregues compactados em .zip.
3. Programar relatório automaticamente
Crie uma programação para gerar o relatório automaticamente de forma diária, semanal ou mensal.
Para ativar a criação automática, envie uma solicitação para /v1/reporting/operations/{reportId}/schedulePOST. Com essa solicitação, você pode definir a frequência e a hora de geração, indicar a configuração do relatório e selecionar seus notificadores de entrega.
Em caso de sucesso, a resposta retorna id, que identifica a programação criada. Salve esse valor para desativá-la posteriormente como scheduleId.
Use o identificador da programação como scheduleId em /v1/reporting/operations/{reportId}/schedule/{scheduleId}DELETE. Ao desativá-la, novos relatórios deixam de ser gerados, mas os arquivos criados anteriormente permanecem disponíveis.
4. Notificações
Quando o relatório está disponível, o Mercado Pago envia uma solicitação POST para a URL definida em notifiers[].data.url para o notificador do tipo webhook. O corpo identifica o relatório e os arquivos disponíveis.
{
"report_id": "activities_collection",
"statement_id": "6d17e034-6eb3-48fc-a6fa-461e886fa406",
"status": "available",
"files": [
{
"type": "text/csv",
"name": "activities_collection.csv",
"size": 20480,
"has_zip_version": false
}
]
}Verifique a assinatura da notificação com o secret enviado em notifiers[].data.key e descarte o evento caso ela não coincida.