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).
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.
Tipo | Descrição |
Public key | A 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 token | Access 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.
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
}
Campo | Descriçã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.
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
}
Campo | Descriçã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.
Campo | Descriçã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.
Campo | Descriçã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. |