Inicio
Documentação
Recursos
Parcerias
Comunidade

Recursos

Confira as atualizaçÔes das nossas soluçÔes e do funcionamento do sistema ou peça suporte técnico.

Parcerias

Conheça nosso programa para agĂȘncias ou desenvolvedores que oferecem serviços de integração e vendedores que desejam contratĂĄ-los.

Comunidade

Fique por dentro das Ășltimas novidades, peça ajuda a outros integradores e compartilhe seu conhecimento.

Gerar relatório - Relatório de vendas da solução split de pagamentos - Mercado Pago Developers

Busca inteligente powered by OpenAI 

Gerar relatĂłrio

Para gerar o relatĂłrio, primeiro vocĂȘ deve criar as configuraçÔes necessĂĄrias, onde poderĂĄ definir os emails para os quais o relatĂłrio serĂĄ enviado ou a frequĂȘncia com que deseja que ele seja gerado, entre outras opçÔes. Em seguida, vocĂȘ deve criar o relatĂłrio, que pode ser de forma automĂĄtica (event) ou manual (statement).

Importante
Para gerar os relatĂłrios, serĂĄ necessĂĄrio ter o Access Token de suas credenciais de produção. Este Ă© uma chave privada da aplicação que sempre deve ser usada no backend para gerar pagamentos. Se vocĂȘ ainda nĂŁo possui essas informaçÔes, siga as etapas descritas abaixo.

Gerar Access Token

As credenciais sĂŁo senhas exclusivas usadas para identificar uma integração em sua conta. Elas desempenham um papel fundamental na captura segura de pagamentos em lojas online e outras aplicaçÔes. VocĂȘ pode encontrĂĄ-las em Detalhes da aplicação > Credenciais dentro do Painel do desenvolvedor ou em sua conta do Mercado Pago, acessando Seu negĂłcio > ConfiguraçÔes > GestĂŁo e administração > Credenciais.

Existem dois tipos diferentes de credenciais:

  • Credenciais de teste: Use as credenciais de teste para testar suas integraçÔes. Elas podem ser combinadas com cartĂ”es de crĂ©dito de teste para simular transaçÔes e verificar o funcionamento correto das integraçÔes. Recomenda-se usar essas credenciais antes de passar para as credenciais de produção.
  • Credenciais de produção: Use as credenciais de produção para receber pagamentos.

Ambos os tipos de credenciais consistem em dois pares de chaves que vocĂȘ deve usar de acordo com o produto escolhido. Consulte a documentação especĂ­fica de cada produto para obter detalhes sobre as chaves a serem usadas.

TipoDescrição
Public keyA chave pĂșblica da aplicação Ă© geralmente usada no frontend. Permite, por exemplo, acessar informaçÔes sobre mĂ©todos de pagamento e criptografar os dados do cartĂŁo.
Access tokenAccess token Ă© a chave privada da aplicação que sempre deve ser usada no backend para gerar pagamentos. É essencial manter esta informação segura em seus servidores.

Para gerar o relatĂłrio de vendas, vocĂȘ deve usar o seu Access Token de produção.

Gerar Access Token

Criar configuração

Antes de gerar o relatĂłrio, vocĂȘ deve criar as configuraçÔes correspondentes, o que permitirĂĄ personalizar os emails para os quais o relatĂłrio serĂĄ enviado, a frequĂȘncia de geração e sua estrutura.

A criação das configuraçÔes consiste em 2 etapas: primeiro, definir a estrutura do relatório e, em seguida, configurar as vias de notificação.

Estruturar relatĂłrio

Criar a estrutura do relatĂłrio permite definir as caracterĂ­sticas que ele terĂĄ no momento da geração. AtravĂ©s dos structures, vocĂȘ pode especificar o fuso horĂĄrio em que deseja que o relatĂłrio seja gerado, adicionar um prefixo para identificar o arquivo gerado e incorporar a quantidade de colunas desejadas, juntamente com separadores de colunas e decimais.

Para definir esta estrutura, faça a seguinte chamada à API, levando em consideração as especificaçÔes da tabela abaixo:

curl

curl --location --request POST 'https://api.mercadopago.com/v1/reports/marketplace_sellers_sales/structures' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "display_timezone": "GMT-03",
    "name": "Structure de mi marketplace",
    "file_format": {
        "prefix": "marketplace",
        "column_separator": ";",
        "decimal_separator": "."
    },
    "columns": [
        {
            "key": "COLLECTOR",
            "alias": ""
        },
        {
            "key": "COLLECTOR_NICKNAME",
            "alias": ""
        },
        {
            "key": "PAYMENT",
            "alias": ""
        },
        {
            "key": "STATUS_DESCRIPTION",
            "alias": ""
        },
        {
            "key": "STATUS_DETAIL",
            "alias": ""
        },
        {
            "key": "PURCHASE_ORDER",
            "alias": ""
        },
        {
            "key": "PAYMENT_METHOD_TYPE",
            "alias": ""
        },
        {
            "key": "TRANSACTION_AMOUNT",
            "alias": ""
        },
        {
            "key": "DATE_CREATED",
            "alias": ""
        },
        {
            "key": "DATE_APPROVED",
            "alias": ""
        },
        {
            "key": "MARKETPLACE_FEE_AMOUNT",
            "alias": ""
        },
        {
            "key": "MERCADOPAGO_FEE_AMOUNT",
            "alias": ""
        },
        {
            "key": "TOTAL_PAID_AMOUNT",
            "alias": ""
        },
        {
            "key": "NET_RECEIVED_AMOUNT",
            "alias": ""
        }
    ]
}'

Resposta

json

{
    "id": {{structure_id}},
    "version": 0,
    "date_created": null,
    "date_last_updated": null,
    "name": null,
    "file_format": null,
    "columns": null,
    "file_config": null,
    "report_translation": null,
    "include_withdraw": null,
    "refund_detailed": null,
    "show_fee_prevision": null,
    "coupon_detailed": null,
    "show_chargeback_cancel": null
}
CampoDescrição
display_timezone (opcional)Este campo determina a data e a hora que sĂŁo exibidas nos relatĂłrios. Se vocĂȘ nĂŁo configurar este campo com um fuso horĂĄrio, o sistema usarĂĄ o valor padrĂŁo GMT-04. Se vocĂȘ escolher um fuso horĂĄrio que utiliza horĂĄrio de verĂŁo, serĂĄ necessĂĄrio fazer o ajuste manual quando houver mudança de horĂĄrio.
columns (obrigatório)Campo com os detalhes das colunas a serem incluídas em seu relatório. Encontre todos os possíveis valores na seção Glossårio.
name (obrigatĂłrio)Campo para atribuir um nome Ă  estrutura.
file_format.prefix (obrigatório)Prefixo que compÔe o nome do relatório uma vez gerado.
file_column_separator (obrigatĂłrio)Caractere que vocĂȘ pode usar no arquivo .csv quando nĂŁo deseja que o separador seja um ponto e vĂ­rgula.

Vias de notificação

Depois de estabelecer a estrutura do relatório, determine como deseja receber as notificaçÔes, seja por email ou SFTP. Configure um notifier conforme mostrado abaixo, e atente-se às características de cada campo descritas na tabela a seguir.

Email

curl

curl --location --request POST 'https://api.mercadopago.com/v1/reports/notifiers' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "email",
    "data": {
        "recipients": ["test@mercadolibre.com"]
    },
    "description": "test notifier email"
}'

Resposta

json

{
    "id": {{notifier_id}},
    "type": "email",
    "data": {
        "recipients": [
            "test@mercadolibre.com"
        ]
    },
    "description": null,
    "version": 0,
    "status": "ACTIVE",
    "is_pii_data": true
}

SFTP

curl

curl --location --request POST 'https://api.mercadopago.com/v1/reports/notifiers?type=ftp' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "ftp",
    "data": {
        "ip": "test.files.com",
        "port": 22,
        "password": "test",
        "protocol": "SFTP",
        "username": "test@mercadolibre.com",
        "remote_dir": "/"
    },
    "description": "test notifier sftp"
}'

Resposta

json

{
    "id": {{notifier_id}},
    "type": "ftp",
    "data": {
        "protocol": "SFTP",
        "ip": "test.files.com",
        "username": "test@mercadolibre.com",
        "password": "test",
        "remote_dir": "/",
        "port": 22
    },
    "description": null,
    "version": 0,
    "status": "ACTIVE",
    "is_pii_data": false
}
CampoDescrição
type (obrigatório)Define o tipo de notificação a ser configurado. Valores possíveis: email; ftp.
data (obrigatório)Contém as informaçÔes do destinatårio do notifier. Dependendo do valor indicado em type, pode conter os seguintes objetos:

- email: ContĂ©m o campo recipients, onde vocĂȘ pode indicar os emails para os quais o relatĂłrio serĂĄ enviado. Pode ser mais de um, se desejar.

- ftp: Contém os seguintes campos:
- ip: URL do servidor FTP
- port: Porta do servidor FTP
- password: Senha de acesso ao servidor FTP
- protocolo: SFTP
- username: Nome de usuĂĄrio para acessar o servidor FTP
- remote_dir: DiretĂłrio remoto de destino no servidor FTP.

Criar relatĂłrio

ApĂłs criar as configuraçÔes iniciais, vocĂȘ tem duas opçÔes para criar o relatĂłrio:

  • Agendar um evento: Isso automatiza a criação de relatĂłrios, permitindo que vocĂȘ defina a frequĂȘncia.
  • Gerar um evento manualmente: VocĂȘ poderĂĄ criar um relatĂłrio sob demanda para um perĂ­odo especĂ­fico de sua escolha

Agendar um relatĂłrio (Events)

Ao agendar um evento, é possível gerar relatórios de forma automåtica e definir sua periodicidade. Para executar essa ação, crie um event, seguindo o exemplo abaixo. Certifique-se de ter em mãos as configuraçÔes previamente estabelecidas e as informaçÔes da tabela a seguir para garantir um agendamento bem-sucedido do relatório.

curl

curl --location --request POST 'https://api.mercadopago.com/v1/reports/marketplace_sellers_sales/events' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "frequency",
    "data": {
        "period": "daily",
        "value": 0,
        "hour": 0
    },
    "description": "event test",
    "structure_id": {{structure_id}},
    "notifiers": [      
       {{notifier_id}}
    ],
    "status": "ACTIVE",
    "version": 0
}'

Reposta

json

{
    "id": {{event_id}},
    "type": "frequency",
    "data": {
        "period": "daily",
        "value": 0,
        "hour": 20,
        "skip_non_working_days": false
    },
    "description": "event test",
    "structure_id": {{structure_id}},
    "notifiers": [],
    "status": "ACTIVE",
    "version": 0,
    "user_id": {{user_id}}
}

VocĂȘ pode ver a descrição dos campos presentes nos curls na tabela abaixo.

CampoDescrição
type (obrigatĂłrio)Este campo define o tipo de evento. O Ășnico valor possĂ­vel Ă© frequĂȘncia.
data (obrigatĂłrio)Este campo contĂ©m a frequĂȘncia com que o relatĂłrio serĂĄ gerado. Pode ser diariamente (period=daily), semanalmente (period=weekly) ou mensalmente (period=monthly).
Dentro de value, vocĂȘ pode definir qual dia da semana deseja que o relatĂłrio seja gerado (se period=weekly), atribuindo um nĂșmero de 1 a 7, ou qual dia do mĂȘs (se period=monthly), atribuindo um nĂșmero de 1 a 31.
AlĂ©m disso, no campo hour, vocĂȘ pode programar a hora do dia em que o relatĂłrio serĂĄ gerado.
description (obrigatĂłrio)Campo para atribuir um nome ao evento. MĂĄximo de 50 caracteres.
structure_id (obrigatĂłrio)Campo para atribuir a estrutura com a qual o relatĂłrio serĂĄ gerado. VocĂȘ deve preenchĂȘ-lo com o valor obtido para este mesmo campo na resposta Ă  criação da estrutura.
notifier_id (obrigatĂłrio)Campo para atribuir a forma pela qual deseja receber as notificaçÔes. VocĂȘ deve preenchĂȘ-lo com a identificação obtida na resposta Ă  criação das notificaçÔes.

Gerar relatĂłrio manualmente (Statements)

A criação manual possibilita gerar um relatório sob demanda, especificando o intervalo de tempo desejado.

Para isso, crie uma statement, conforme mostrado abaixo. AlĂ©m disso, tenha em mĂŁos as configuraçÔes que vocĂȘ criou anteriormente e as informaçÔes da tabela a seguir para garantir a criação bem-sucedida do relatĂłrio.

curl

curl --location --request POST 'https://api.mercadopago.com/v1/reports/marketplace_sellers_sales/statements' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{TOKEN}}' \
--data-raw '{
    "user_description": "",
    "created_by": "automatic",
    "origin": {
        "type": "date_range",
        "data": {
            "date_start": "2023-04-01T03:00:00Z",
    		"date_end": "2023-04-02T02:27:44Z"
        }
    },
    "structure_id": {{structure_id}},
    "notifiers_id": [{{notifier_id}}]
}'

Resposta

json

{
    "status_code": 201,
    "request_id": {{statement_id}},
    "message": ""
}

VocĂȘ pode ver a descrição dos campos presentes nos curls na tabela abaixo.

CampoDescrição
user_description (obrigatório)Descrição desejada. Extensão måxima: 50 caracteres.
created_by (obrigatório)Criador da solicitação. No momento, só pode receber o valor automatic.
Origin (obrigatório)Este campo contém a informação do período que deseja incluir no relatório.
- type: o Ășnico valor possĂ­vel Ă© date_range, jĂĄ que vocĂȘ deverĂĄ indicar o perĂ­odo a ser consultado.
- date_start: indica o inĂ­cio do perĂ­odo que deseja consultar no formato: yyyy-MM-dd HH:mm:ss.SSS.
- date_end: indica o fim do perĂ­odo que deseja consultar no formato: yyyy-MM-dd HH:mm:ss.SSS.
structure_id (obrigatĂłrio)Campo para atribuir a estrutura com a qual o relatĂłrio serĂĄ gerado. VocĂȘ deverĂĄ preenchĂȘ-lo com o valor obtido para este mesmo campo na resposta Ă  criação da estrutura.
notifiers_id (obrigatĂłrio)Campo para atribuir a forma como deseja receber as notificaçÔes. VocĂȘ deverĂĄ preenchĂȘ-lo com a identificação obtida na resposta Ă  criação de notificaçÔes.