Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Última atualização em 25/04/2024
Relatórios de faturamento
Obter período
Consultar primeiro este endpoint é opcional, pois a key necessária para consumir o restante dos endpoints é fornecida no primeiro dia do mês. Por exemplo: 2023-06-01. Permite que você obtenha informações sobre os períodos de faturamento para o grupo de faturamento indicado (Mercado Livre ou Mercado Pago). Por padrão, você recebe os últimos 6 períodos, com a possibilidade de consultar períodos mais antigos usando a paginação de offset e limit. (valor máximo: 12)
Parâmetro obrigatório
document_type: tipo de documento a obter. Pode ser Bill ou Credit_note.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/monthly/periodsExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/monthly/periods?group=MP&document_type=BILL&offset=1&limit=2Resposta:
{
"offset": 1,
"limit": 2,
"total": 27,
"results": [{
"amount": 30.46000027656555,
"unpaid_amount": 0.0,
"period": {
"date_from": "2020-02-19",
"date_to": "2020-03-18"
},
"key": "2020-03-01"
"expiration_date": "2020-03-24",
"debt_expiration_date": "2020-03-24",
"debt_expiration_date_move_reason": null,
"debt_expiration_date_move_reason_description": null,
"period_status": "CLOSED"
},
{
"amount": 477888.1484375,
"unpaid_amount": 0.0,
"period": {
"date_from": "2020-01-19",
"date_to": "2020-02-18"
},
"expiration_date": "2020-02-24",
"debt_expiration_date": "2020-03-23",
"debt_expiration_date_move_reason": "PAYMENT_ANNULMENT",
"debt_expiration_date_move_reason_description": "Anulación de pago",
"period_status": "CLOSED"
}
]
}Campos da resposta
- amount: valor total do período.
- unpaid_amount: valor total pendente de pagamento.
- period: range de datas do período.
- date_from: data de início do período.
- date_to: data de fim do período.
Obter documentos de um período
Permite obter informação de documentos (faturas e notas de crédito) para um período de faturamento em particular para o grupo de faturamento indicado (Mercado Livre ou Mercado Pago).
Filtros opcionais
- document_id: permite buscar pelo ID da fatura. Ex: document_id=987046992
- document_type: permite buscar por tipo de documento: Fatura ou Nota de Crédito. Valores possíveis: BILL | CREDIT_NOTE
- offset: permite buscar desde um número de resultado adiante. Ex: offset=100 (devolve a partir do resultado número 100).
- limit: limita a quantidade de resultados. Por padrão o mínimo é 150. Máximo valor permitido: 1000. Ex: limit=300 (devolve até 300 resultados).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/documentsExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/documents?group=MP&document_type=BILL&limit=1Resposta:
{
"offset": 0,
"limit": 1,
"total": 2,
"results": [{
"id": 987654321,
"user_id": 1234,
"document_type": "BILL",
"expiration_date": "2021-06-02",
"associated_document_id": null,
"amount": 3.86,
"unpaid_amount": 0.0,
"document_status": "BILLED",
"site_id": "MLM",
"period": {
"date_from": "2021-05-03",
"date_to": "2021-05-03"
},
"currency_id": "MXN",
"count_details": 1,
"files": [
{
"file_id": "1234_FE_MEPF00869625_pdf",
"reference_number": "MEPF00999999"
},
{
"file_id": "1234_FE_MEPF00869625_xml",
"reference_number": "MEPF00999999"
}
]
}]
}Resumo de faturamento
Permite obter o resumo de comissões e bonificações que teve o vendedor para um período de tempo em particular.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/summary/detailsExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2023-10-01/summary/detailsResposta:
{
"user": {
"nickname": "TEST"
},
"period": {
"date_from": "2023-06-19",
"date_to": "2023-07-18",
"expiration_date": "2023-07-24",
"key": "2023-07-01"
},
"bill_includes": {
"total_amount": 171070532.64,
"total_perceptions": 33077380.48,
"bonuses": [
{
"label": "Bonificación cargo por Mercado Envíos",
"amount": 385261.63,
"type": "BXD",
"groupId": 3
},
{
"label": "Bonificación del cargo por venta",
"amount": 6123337.46,
"type": "BXD",
"groupId": 4
},
{
"label": "Bonificación campañas de publicidad - Product Ads",
"amount": 12967.5,
"type": "BXD",
"groupId": 5
},
{
"label": "Bonificación cargo por Mercado Envíos",
"amount": 28132.36,
"type": "BXD",
"groupId": 6
}
],
"charges": [
{
"label": "Campañas de publicidad - Product Ads",
"amount": 48600,
"type": "PADS",
"groupId": 24
},
{
"label": "Percepción impuesto a los IIBB Rég. General de Salta",
"amount": 111.18,
"type": "CXD",
"groupId": 25
},
{
"label": "Percepción impuesto IIBB Com. Electrónico La Pampa",
"amount": 178050.01,
"type": "CXD",
"groupId": 26
},
{
"label": "Percep. gral. impuesto IIBB CABA Mercado Envíos",
"amount": 257364.18,
"type": "CXD",
"groupId": 27
},
{
"label": "Percepción impuesto IIBB CABA",
"amount": 2593731.92,
"type": "CXD",
"groupId": 25
},
{
"label": "Cargo por Mercado Envíos",
"amount": 11195255.36
"type": "CXD",
"groupId": 24
},
{
"label": "Cargo por venta",
"amount": 131285530.48,
"type": "CV",
"groupId": 28
},
]
},
"payment_collected": {
"operation_discount": 136492738.16,
"total_payment": 33353689.85,
"total_credit_note": 1989281,
"total_collected": 171070532.64,
"total_debt": 0.00
},
"errors": []
}Campos da resposta
- user
- nickname: nome do usuário.
- period
- date_from: data de início do período.
- date_to: data do fim do período.
- expiration_date: data de expiração.
- key: data do primeiro dia do mês.
- bill_includes
- total_amount: valor total.
- total_perceptions: valor total dos pagamentos.
- bonuses
- label: descrição da bonificação.
- amount: valor da bonificação.
- type: tipo de bonificação.
- groupId: grupo da bonificação.
- charges
- label: descrição da cobrança
- amount: valor da cobrança.
- type: tipo de cobrança.
- groupId: grupo da cobrança.
- payment_collected:
- operation_discount: operações descontadas das vendas.
- total_payment: pagamentos realizados.
- total_credit_note: total de notas de crédito.
- total_collected: total pago.
- total_debt: total da dívida.
As bonificações podem ser pelos seguintes conceitos:
- Cobranças de venda e envios: se uma venda não se concretiza devido a uma devolução ou por problemas no transporte (como perda ou dano do produto), reembolsaremos a comissão de venda e a cobrança do envio.
- Cobranças de publicidade: se por erro for contratado o serviço ou houve algum problema com o pagamento, reembolsaremos a diferença.
- Bonificações por Percepções Tributárias: quando se devolve uma cobrança por venda também se inclui a devolução correspondente da percepção tributária de IVA (já seja por um anúncio de novo ou usado) e da renda bruta. O mesmo se houver erros na aplicação de uma percepção.
- charges: diferentes cobranças que pode ter o vendedor: comissões por vendas, custo de publicações, percepções tributárias, pagamento de serviços. Por exemplo: Mercado Envios, Mercado Shops, etc.
No caso de contratar campanhas publicitárias, também aparecerão nas cobranças.
Errores
| Código | Tipo | Mensaje | Solución |
|---|---|---|---|
| 206 | Partial content | An error occurred while retrieving the information. Try again. | Sucede cuando faltan algunos datos y la respuesta es incompleta. Aplica a todos los recursos, excepto el download de documento legal y reporte de conciliación en formato XLSX y CSV. |
| 403 | ABUSE_PREVENTION_ERROR | Bloquea preventivamente una cantidad limitada de request por IP. | Evita realizar pegadas repetitivas que no requieran el uso de limit y offset para paginar. |
Seguinte: Conciliações.