Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Última atualização em 08/06/2026
Provisões
Obtenha o detalhamento para conferir as notas fiscais e as cobranças de vendas de um período específico, o grupo de faturamento (Mercado Livre ou Mercado Pago) e o tipo de documento (Nota Fiscal ou Nota de Crédito) conforme a unidade de negócio que você escolher: Mercado Livre, Mercado Pago, Mercado Envios Flex, Fulfillment e Insurtech. Você pode filtrar com os parâmetros: group (ML, MP) e document_type (BILL, CREDIT_NOTE).
Parâmetros de paginação
Propomos o uso de 2 parâmetros para gerenciar a paginação:
- limit: limita a quantidade de resultados a obter. O valor mínimo é 1 e o máximo permitido é 1000. Por padrão, seu valor é 150.
- from_id: permite buscar a partir de um Id de detalhe específico. Este valor é retornado no campo last_id da resposta JSON. Por padrão, seu valor é 0.
Para ordenar e obter os resultados de forma correta, devem ser adicionados à request os seguintes parâmetros:
- sort_by: propriedade pela qual se deseja ordenar (ID ou DATE)
- order_by: orientação da ordenação (ASC ou DESC)
A API de relatórios de faturamento permite ajustar a quantidade de resultados por página através do parâmetro limit. Por padrão, esse valor é 150, com um máximo permitido de 1000. Isso significa que você pode incrementar o número de registros por solicitação até 1000, conforme suas necessidades.
A frequência de consumo depende do volume de dados e das necessidades específicas da sua aplicação. Se você lida com grandes volumes de informação, é recomendável realizar solicitações periódicas, ajustando o limit e utilizando o from_id para paginar os resultados de forma eficiente. Por exemplo, se você deseja obter os primeiros 1000 registros, pode estabelecer limit=1000 e from_id=0. Para a próxima página, mantenha limit=1000, from_id=<last_id da request anterior> e assim sucessivamente. Essa abordagem permite dividir a informação em páginas gerenciáveis e processá-las de maneira eficiente.
Filtros opcionais
- date_sort: permite ordenar a busca.
- asc: ordena os resultados de forma ascendente (valor padrão)
- desc: ordena os resultados de forma descendente
- Exemplo: date_sort=asc
- sort_by: permite selecionar por qual campo ordenar.
- Valores possíveis: ID (valor padrão) e DATE
- detail_type: permite buscar por tipos de detalhes.
- charge: retorna somente cobranças.
- bonus: retorna somente bonificações.
- Exemplo: detail_type=charge
- detail_sub_types: permite filtrar por subtipos de detalhes. É possível definir vários separados por vírgula.
- Valores possíveis:
- Exemplo: detail_sub_types=CV, BV
- detail_excluded_sub_types: permite excluir da busca os subtipos de detalhes indicados. É possível definir vários separados por vírgula.
- Exemplo: not_subtypes=CXD, BXD
- marketplace_type: permite buscar pelo marketplace da cobrança e/ou bonificação.
- Valores possíveis:
- Exemplo: marketplace_type=SHIPPING
- order_ids: permite buscar por um ou vários ids da order. Disponível para Mercado Livre.
- Exemplo: order_ids=2294412230
- item_ids: permite buscar por um ou mais ids do anúncio.
- Exemplo: item_ids=724159812
- document_ids: permite buscar por um ou mais ids da nota fiscal.
- Exemplo: document_ids=987046992
- detail_ids: permite buscar por um ou mais ids do detalhe.
- Exemplo: detail_ids=724159812
- offset: permite buscar a partir de um número de resultado em diante. O valor mínimo permitido é 0 e o valor máximo permitido é 10000. Por padrão, o valor é 0 – Recomendamos utilizar mais filtros e limitar os resultados.
- limit: limita a quantidade de resultados. Por padrão, o mínimo é 1 e o máximo permitido: 1000.
- from_id: permite buscar a partir de um Id de detalhe específico. Este valor é retornado no campo last_id da resposta JSON. Por padrão, seu valor é 0.
Exemplo de paginação: Detalhes de Mercado Pago
Primeira página:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2024-11-01/group/MP/details?document_type=BILL&limit=1000&from_id=0
Segunda página:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2024-11-01/group/MP/details?document_type=BILL&limit=1000&from_id=12345678
Considerações
Como se integrar para garantir que, mesmo realizando várias consultas, a informação não fique duplicada?
Para evitar duplicatas ao realizar múltiplas consultas, é fundamental utilizar corretamente os parâmetros limit e from_id em cada solicitação. O parâmetro limit define a quantidade de registros a obter e from_id permite indicar um id de detalhe específico. Ao incrementar o limit em cada solicitação e enviar o from_id, você garante que cada página de resultados seja única e não se repitam registros.
- Para obter a primeira página: limit=1000 e from_id=0.
- Para a segunda página: limit=1000 e from_id=<last_id da request anterior>.
- E assim sucessivamente até consultar todos os detalhes.
Esse método garante uma paginação eficaz sem duplicatas.
Você também encontrará o parâmetro offset. O offset permite buscar a partir de um número de resultado em diante. O valor mínimo permitido é 0 e o valor máximo permitido é 9999. Este parâmetro só é recomendado em casos onde a quantidade de detalhes é menor que 10000.
Mercado Livre
Você verá as cobranças faturadas, informações da venda, descontos, envios e o anúncio.
Para MLB, a resposta da API incluirá uma nova entidade com informações detalhadas sobre a composição da tarifa de venda (sale_fee). Essa melhoria permitirá visualizar de forma mais clara os componentes da tarifa associados à venda, separando os descontos aplicados e os rebates recebidos por cada order.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/group/ML/details
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/group/ML/details?document_type=BILL&limit=1
Resposta:
{
"charge_info": {
"legal_document_number": null,
"legal_document_status": "PROCESSING",
"legal_document_status_description": "Em processamento",
"creation_date_time": "2024-11-14T10:36:38",
"detail_id": 126303124,
"transaction_detail": "Taxa de parcelamento (acréscimo no valor pago pelo comprador)",
"debited_from_operation": "NO",
"debited_from_operation_description": "Não",
"status": null,
"status_description": null,
"charge_bonified_id": null,
"detail_amount": 2.75,
"detail_type": "CHARGE",
"detail_sub_type": "CFONPN"
},
"discount_info": {
"charge_amount_without_discount": 2.75,
"discount_amount": 0,
"discount_reason": null,
"rebate": null
},
"sales_info": [
{
"order_id": 2000009839350282,
"operation_id": 93353250128,
"sale_date_time": "2024-11-14T09:36:25",
"sales_channel": "Mercado Livre",
"payer_nickname": "TESTUSER1317068011",
"state_name": null,
"transaction_amount": 100,
"financing_transfer_total": 102.75,
"financing_fee": 2.75,
"sale_fee": {
"gross": 13.84,
"net": 8.39,
"rebate": 5.45,
"discount": 0.0,
"discount_reason": "reason"
}
}
],
"shipping_info": null,
"items_info": null,
"document_info": {
"document_id": 3454540850
},
"marketplace_info": {
"marketplace": "MP"
},
"currency_info": {
"currency_id": "BRL"
}
}
Campos de resposta Mercado Livre:
- charge_info: informações da cobrança.
- legal_document_number: número do documento.
- legal_document_status: estado de geração do documento.
- Valores possíveis: PROCESSING, PROCESSED.
- legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
- creation_date_time: data de criação da cobrança.
- detail_id: identificador da cobrança.
- transaction_detail: detalhe da cobrança.
- debited_from_operation: indica se foi descontado da operação.
- Valores possíveis: YES, NO, INAPPLICABLE.
- debited_from_operation_description: descrição internacionalizada do campo debited_from_operation.
- status: estado da cobrança.
- Valores possíveis:
- BONUS_ON_CREDIT_NOTE,
- BONUS_PART_ON_CREDIT_NOTE,
- BONUS_ON_BILL,
- BONUS_PART_ON_BILL,
- BONUS_ON, BONUS_PART_ON.
- Valores possíveis:
- status_description: descrição internacionalizada de status.
- charge_bonified_id: identificador da cobrança que bonifica.
- detail_amount: valor da cobrança.
- detail_type: tipo de detalhe.
- Valores possíveis:
- detail_sub_type: subtipos de detalhes.
- Valores possíveis:
- discount_info: informações sobre descontos.
- applied_percentage: porcentagem aplicada para calcular o valor da cobrança. [Exclusivo para Argentina]
- charge_amount_without_discount: valor da cobrança sem desconto.
- discount_amount: valor do desconto.
- discount_reason: motivo do desconto.
- rebate: valor do desconto por participação em campanha comercial.
- sales_info: informações das vendas.
- order_id: identificador da venda.
- operation_id: identificador do pagamento.
- sale_date_time: data e hora da venda.
- sales_channel: canal de venda.
- payer_nickname: cliente.
- state_name: estado.
- transaction_amount: valor total da venda.
- financing_fee: diferenciação no preço conforme o número de parcelas escolhidas pelo comprador [Exclusivo para Brasil].
- financing_transfer_total: valor total pago pelo cliente pelo produto [Exclusivo para Brasil].
- sale_fee: informações sobre a tarifa da venda (Exclusivo para Brasil).
- gross: valor da cobrança sem desconto.
- net: valor da cobrança.
- rebate: valor do desconto por participação em campanha comercial.
- discount: valor do desconto.
- discount_reason: motivo do desconto.
- shipping_info: informações do envio.
- shipping_id: identificador do envio.
- pack_id: identificador do pacote.
- receiver_shipping_cost: frete a cargo do cliente.
- items_info: informações sobre os anúncios.
- item_id: identificador do anúncio.
- item_kit_id: identificador do kit. [Disponível apenas para Argentina, Brasil e México]
- item_title: título do anúncio.
- Kits Virtuais: No caso de um produto pertencer a um kit, o nome do item é concatenado com Produto em Kit: <nome do kit>. [Disponível apenas para Argentina, Brasil e México]
- item_type: tipo de anúncio.
- item_category: categoria do anúncio.
- inventory_id: código do Mercado Livre.
- item_amount: quantidade de itens vendidos.
- item_price: preço unitário do item.
- order_id: order à qual o item pertence.
- fees_added_in_publication: indica se o anúncio oferece parcelamento. [Disponível apenas para Argentina]
- document_info: informações do documento.
- document_id: número Id do documento.
- marketplace_info: informações do marketplace.
- marketplace: nome do marketplace.
- currency_info: informações da moeda de acordo com o site_id.
- currency_id: identificador da moeda de acordo com o site_id.
- store_info: informações da filial.
- store_id: identificador da filial. [Disponível apenas para MLM, MLC, MCO e MLA]
- store_name: nome da filial. [Disponível apenas para MLM, MLC, MCO e MLA]
Relatórios de Faturamento por Orders e Packs
Este endpoint permite obter os relatórios de faturamento pelo filtro de orders e packs.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/group/ML/order/details?order_ids=$ORDER_ID
Parâmetros de consulta:
- order_ids: Permite buscar por um ou vários ids de order. Limite máximo: 60 order_ids por consulta.
- pack_id: Permite buscar por um id de pack.
- sort_by:
- Valores possíveis: ID e DATE;
- Valor padrão: ID
- order_by: Permite ordenar a busca.
- Valores possíveis: ASC, DESC;
- Valor padrão: ASC
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/group/ML/order/details?order_ids=1234567890000
Resposta:
{
"offset": 0,
"limit": 150,
"total": 1,
"results": [
{
"order_id": 1234567890000,
"payment_info": [
{
"payment_id": 99999999999,
"date_approved": "2024-04-23T03:11:47",
"date_created": "2024-04-23T03:11:43",
"money_release_date": "2024-05-02T19:40:45",
"money_release_days": 28,
"money_release_status": "released",
"payer_id": 12345678,
"payment_method_id": "visa",
"payment_type_id": "credit_card",
"status": "approved",
"status_details": null,
"tax_details": [
{
"from": "collector",
"to": "mp",
"original_amount": 2018.99,
"refunded_amount": 0,
"mov_detail": "tax_withholding",
"mov_financial_entity": "retencion_ganancias",
"tax_id": 9999999997,
"tax_status": "applied"
},
{
"from": "collector",
"to": "mp",
"original_amount": 6056.97,
"refunded_amount": 0,
"mov_detail": "tax_withholding",
"mov_financial_entity": "retencion_iva",
"tax_id": 9999999998,
"tax_status": "applied"
},
{
"from": "collector",
"to": "mp",
"original_amount": 1211.39,
"refunded_amount": 0,
"mov_detail": "tax_withholding_collector",
"mov_financial_entity": "debitos_creditos",
"tax_id": 9999999999,
"tax_status": "applied"
},
{
"from": "collector",
"to": "mp",
"original_amount": 201.9,
"refunded_amount": 0,
"mov_detail": "tax_withholding_sirtac",
"mov_financial_entity": "cordoba",
"tax_id": 9999999990,
"tax_status": "applied"
}
]
}
],
"sale_fee": {
"gross": 120,
"net": 100,
"rebate": 20,
"discount": 0,
"discount_reason": null
},
"details": [
{
"charge_info": {
"legal_document_number": "0011A03800000",
"legal_document_status": "PROCESSED",
"legal_document_status_description": "Procesado",
"creation_date_time": "2024-04-22T23:12:02",
"detail_id": 5555566666,
"transaction_detail": "Cargo por venta",
"debited_from_operation": "YES",
"debited_from_operation_description": "Si",
"status": null,
"status_description": null,
"charge_bonified_id": null,
"detail_amount": 28265.86,
"detail_type": "CHARGE",
"detail_sub_type": "CV"
},
"discount_info": {
"charge_amount_without_discount": 28265.86,
"discount_amount": 0,
"discount_reason": "Descuento general",
"applied_percentage": 14,
"rebate": null
},
"sales_info": [
{
"order_id": 1234567890000,
"operation_id": 99999999999,
"sale_date_time": "2024-04-22T23:11:42",
"sales_channel": "Mercado Libre",
"payer_nickname": "NICKNAME",
"state_name": "Córdoba",
"transaction_amount": 201899,
"financing_transfer_total": 102.75,
"financing_fee": 2.75
}
],
"shipping_info": {
"shipping_id": "5555566666",
"pack_id": null,
"receiver_shipping_cost": null
},
"items_info": [
{
"item_id": "MLA920316309",
"item_title": "Calefactor A Gas Eskabe Miniconvex 5000 S21p Marfil Clase A",
"item_type": "gold_special",
"item_category": "Electrodomésticos y Aires Ac. > Climatización > Estufas y Calefactores > A Gas",
"inventory_id": null,
"item_amount": 1,
"item_price": 201899,
"order_id": 1234567890000,
"fees_added_in_publication": "No"
}
],
"document_info": { "document_id": 5555566666 },
"marketplace_info": { "marketplace": "CORE" },
"currency_info": { "currency_id": "ARS" }
},
{
"charge_info": {
"legal_document_number": "0011A03800000",
"legal_document_status": "PROCESSED",
"legal_document_status_description": "Procesado",
"creation_date_time": "2024-04-22T23:12:02",
"detail_id": 5555566666,
"transaction_detail": "Cargo por Mercado Envíos",
"debited_from_operation": "YES",
"debited_from_operation_description": "Si",
"status": null,
"status_description": null,
"charge_bonified_id": null,
"detail_amount": 9380.99,
"detail_type": "CHARGE",
"detail_sub_type": "CXD"
},
"discount_info": {
"charge_amount_without_discount": 18761.99,
"discount_amount": 9381,
"discount_reason": "Descuento general",
"rebate": null
},
"sales_info": [
{
"order_id": 1234567890000,
"operation_id": 99999999999,
"sale_date_time": "2024-04-22T23:11:42",
"sales_channel": "Mercado Libre",
"payer_nickname": "NICKNAME",
"state_name": "Córdoba",
"transaction_amount": 201899
}
],
"shipping_info": {
"shipping_id": "5555566666",
"pack_id": null,
"receiver_shipping_cost": 0
},
"items_info": [
{
"item_id": "MLA920316309",
"item_title": "Calefactor A Gas Eskabe Miniconvex 5000 S21p Marfil Clase A",
"item_type": "gold_special",
"item_category": "Electrodomésticos y Aires Ac. > Climatización > Estufas y Calefactores > A Gas",
"inventory_id": null,
"item_amount": 1,
"item_price": 201899,
"order_id": 1234567890000,
"fees_added_in_publication": "No"
}
],
"document_info": { "document_id": 5555566666 },
"marketplace_info": { "marketplace": "SHIPPING" },
"currency_info": { "currency_id": "ARS" }
}
]
}
]
}
Parâmetros de resposta
- order_id: Identificador da venda.
- payment_info: Informações do pagamento.
- payment_id: Identificador do pagamento.
- date_approved: Data de aprovação.
- date_created: Data de criação.
- money_release_date: Data de liberação do pagamento.
- money_release_days: Dias para a liberação do pagamento.
- money_release_status: Estado da liberação do pagamento.
- payer_id: Identificador do cliente.
- payment_method_id: Método de pagamento.
- payment_type_id: Tipo de meio de pagamento.
- status: Estado do pagamento.
- status_details: Detalhes do estado do pagamento.
- tax_details: Detalhes de impostos.
- details: Detalhes de cobranças.
- charge_info: Informações da cobrança.
- discount_info: Informações sobre descontos.
- sales_info: Informações sobre a venda.
- shipping_info: Informações do envio.
- items_info: Informações do anúncio.
- document_info: Informações do documento.
- marketplace_info: Informações do marketplace.
- currency_info: Informações da moeda conforme o site_id.
- sale_fee: Informações sobre a tarifa da venda (Exclusivo para Brasil).
- gross: Valor da cobrança sem desconto.
- net: Valor da cobrança.
- rebate: Valor do desconto por participação em campanha comercial.
- discount: Valor do desconto.
- discount_reason: Motivo do desconto.
Links úteis
1. Valores a receber
-
GET /orders: dados do pedido.
- unit_price: valor unitário do item com o desconto "de/por" já aplicado.
- quantity: quantidade de itens do pedido.
- sale_fee: tarifa por unidade.
- marketplace_fee: tarifa totalizada no pedido.
-
GET /packs: identificar as orders dentro de um pack.
- orders_ids: identificadores dos pedidos que compõem o pack.
-
GET /shipments: identificar o custo de envio.
- seller.cost: custo de envio subsidiado pelo vendedor.
Exemplo de cálculo simplificado:
(unit_price * quantity) - marketplace_fee - seller.cost = valor líquido do pedido.
2. Custos e descontos aplicados
-
GET /orders/{order_id}/discounts: informações de descontos e campanhas aplicadas ao pedido.
- discounts, coupon: tipos de descontos aplicados.
- supplier: provedor da campanha.
- meli_campaign: campanha de descontos associada ao cupom.
- offer_id: identificador da oferta (útil para rastrear a promoção).
- funding_mode: tipo de promoção (ex.: sale_fee).
- amounts.total: valor total do desconto (parte MELI + parte vendedor).
-
GET /items/{item_id}/sale_price: identificar o preço de venda aplicado a um item.
- amount: preço vigente do produto (já com desconto).
- regular_amount: preço original antes da promoção.
- metadata.promotion_id: identificador da promoção associada.
- metadata.promotion_type: tipo da promoção (ex.: custom, deal).
-
GET /seller-promotions/offers/{offer_id}: identificar alterações e estado das ofertas promocionais.
- promotion_id: ID da promoção associada.
- type: tipo da promoção (ex.: DEAL).
- status.id: estado atual da promoção (ex.: ACTIVE, FINISHED).
3. Conciliação financeira
A conciliação é feita a partir da combinação dos seguintes recursos:
- GET /orders
- GET /orders/{id}/discounts
- GET /shipments
- GET /packs
O cálculo consolidado considera:
- Valor do item (unit_price * quantity).
- Taxas (sale_fee, marketplace_fee).
- Custos de envio (seller.cost).
- Descontos aplicados (discounts, coupon).
Resultado: Visão consolidada dos valores líquidos a receber por pedido ou pack.
Mercado Pago
Você verá o detalhe das cobranças faturadas com informações complementares sobre a operação de Mercado Pago, como os movimentos, meios de pagamento, payer, filial, ponto de venda, entre outros.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/group/MP/details
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2024-05-01/group/MP/details?document_type=BILL&limit=1
Resposta:
{
"offset": 0,
"limit": 1,
"total": 1,
"results": [
{
"charge_info": {
"legal_document_number": "0029A01508173",
"legal_document_status": "PROCESSED",
"legal_document_status_description": "Procesado",
"detail_id": 24168819712,
"movement_id": "199835301597",
"transaction_detail": "Cargo de Mercado Pago",
"debited_from_operation": "INAPPLICABLE",
"debited_from_operation_description": "No aplica",
"status": "BONUS_ON_BILL",
"status_description": "Anulado en factura",
"charge_bonified_id": null,
"creation_date_time": "2023-07-19T07:29:02",
"detail_amount": 3122.76,
"detail_type": "CHARGE",
"detail_sub_type": "CCMP"
},
"operation_info": {
"operation_type": "BUY",
"operation_type_description": "Pago",
"reference_id": 60833750481,
"sales_channel": "Checkout",
"store_id": null,
"store_name": null,
"external_reference": "385080",
"payer_nickname": "SALADO1958",
"financing_fee": 9.2,
"financing_transfer_total": 109.2,
"transaction_amount": 73999
},
"perception_info": {
"aliquot": null,
"taxable_amount": null
},
"document_info": {
"document_id": 2589999426
},
"marketplace_info": { "marketplace": "MP" },
"currency_info": { "currency_id": "ARS" }
}
]
}Campos de resposta:
- charge_info: informações da cobrança.
- legal_document_number: número do documento.
- detail_id: identificador da cobrança.
- legal_document_status: estado de geração do documento.
- Valores possíveis: PROCESSING, PROCESSED, NOT_APPLICABLE.
- legal_document_status_description: descrição internacionalizada.
- movement_id: número do movimento.
- transaction_detail: detalhe.
- debited_from_operation:
- Valores possíveis: YES, NO, INAPPLICABLE.
- debited_from_operation_description: descrição internacionalizada.
- status: estado da cobrança.
- Valores possíveis: BONUS_ON_CREDIT_NOTE, BONUS_PART_ON_CREDIT_NOTE, BONUS_ON_BILL, BONUS_PART_ON_BILL, BONUS_ON, BONUS_PART_ON.
- status_description: descrição internacionalizada de status.
- charge_bonified_id: identificador da cobrança que bonifica.
- creation_date_time: data da cobrança.
- detail_amount: valor da cobrança.
- detail_type: tipo de detalhe.
- detail_sub_type: subtipos de detalhes.
- operation_info: informações da operação sobre a qual se aplica.
- operation_type: tipo de operação.
- Valores possíveis: BUY, TAX.
- operation_type_description: descrição internacionalizada.
- reference_id: número da operação relacionada.
- sales_channel: tipo de pagamento.
- store_id: número da filial.
- store_name: nome da filial.
- external_reference: número de referência externa.
- payer_nickname: cliente.
- financing_fee / financing_transfer_total: Exclusivo para Brasil.
- transaction_amount: valor da operação.
- operation_type: tipo de operação.
- perception_info: informações de percepção.
- aliquot: alíquota.
- taxable_amount: valor tributável.
- document_info: informações do documento (document_id).
- marketplace_info: informações do marketplace.
- currency_info: informações da moeda (currency_id).
Mercado Envios Flex
Você verá o detalhamento para conferir as bonificações e anulações de Flex para um período específico, o grupo de faturamento Mercado Livre e o tipo de documento (nota de débito ou nota de crédito). Além disso, informações sobre o envio e informações da venda.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/group/ML/flex/details
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2023-03-01/group/ML/flex/details?document_type=BILL&limit=1
Resposta:
{
"offset": 0,
"limit": 1,
"total": 100,
"results": [{
"charge_info": {
"legal_document_number": "00AA11AA00",
"legal_document_status": "PROCESSED",
"legal_document_status_description": "Procesado",
"creation_date_time": "2023-02-21T12:35:58",
"detail_id": 2020202020,
"detail_associated_id": 4040404040,
"detail_amount": 163,
"transaction_detail": "Anulación de bonificación por Mercado Envíos Flex",
"detail_type": "CHARGE",
"detail_sub_type": "CFLX",
"concept_type": "FLEX"
},
"shipping_info": {
"shipping_id": 4444455555,
"receiver_nickname": "NICKNAME",
"pack_id": "12345678",
"receiver_shipping_cost": 814.99,
"order": {
"order_id": 9000000008888888,
"date_created": "2023-02-15T11:54:51",
"total_amount": 29499,
"payment_id": 998899889988,
"buyer_nickname": "NICKNAME"
}
},
"document_info": { "document_id": 776677667711 }
}],
"errors": []
}Campos de resposta:
- charge_info: informações da cobrança.
- legal_document_number: número do documento.
- legal_document_status: estado de geração do documento.
- Valores possíveis: PROCESSING, PROCESSED.
- legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
- creation_date_time: data de criação da cobrança.
- detail_id: identificador da cobrança.
- detail_associated_id: identificador da cobrança associada (em caso de anulação de bonificação).
- detail_amount: valor da cobrança.
- transaction_detail: detalhe da cobrança.
- detail_type: tipo de detalhe.
- detail_sub_type: subtipos de detalhes.
- concept_type: tipo de conceito.
- shipping_info: informações sobre envio.
- shipping_id: identificador do envio.
- receiver_nickname: cliente.
- pack_id: número do pacote.
- receiver_shipping_cost: custo do envio.
- order: informações da venda.
- order_id: identificador da venda.
- date_created: data da order.
- total_amount: total da order.
- payment_id: identificador do pagamento.
- buyer_nickname: cliente.
- document_info: informações do documento.
- document_id: id do documento.
Fulfillment
Você verá as cobranças e bonificações por coleta e/ou armazenamento para um período específico, o grupo de faturamento Mercado Livre e o tipo de documento (nota fiscal ou nota de crédito). Também informações do produto armazenado ou coletado. Os tipos de cobranças para o relatório de Fulfillment podem ser por: retirada de estoque, armazenamento prolongado, serviço de coleta, descumprimento, armazenamento.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/group/ML/full/details
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2023-03-01/group/ML/full/details?document_type=BILL&limit=1
Resposta:
{
"offset": 0,
"limit": 100,
"total": 634,
"results": [{
"charge_info": {
"legal_document_number": "000AAA00000000",
"legal_document_status": "PROCESSED",
"legal_document_status_description": "Procesado",
"creation_date_time": "2021-07-23T16:37:58",
"detail_id": 11111111111,
"detail_amount": 2.54,
"transaction_detail": "Cargo por servicio de colecta Full",
"charge_bonified_id": null,
"detail_type": "CHARGE",
"detail_sub_type": "CFCB",
"concept_type": "FULFILLMENT",
"payment_id": 222222222
},
"fulfillment_info": {
"type": "WITHDRAWAL",
"amount": 2.54,
"sku": "3125404000009",
"ean": "3125404000009",
"item_id": "MLM788740252",
"item_title": "VESTIDO CORTO AZUL MARINO BORDADO EN PECHO DEVENDI",
"variation": "AZUL MARINO | EG",
"quantity": 1,
"volume_type": null,
"inventory_id": "LLLGGKK12",
"inbound_id": 555555,
"volume_unit": "large",
"amount_per_volume_unit": 500,
"volume": 0.00507,
"volume_total": 0.00507
},
"document_info": { "document_id": 333333333 }
}],
"errors": []
}Campos de resposta Mercado Envios Fulfillment:
- charge_info: informações da cobrança.
- legal_document_number: número do documento.
- legal_document_status: estado de geração do documento.
- Valores possíveis: PROCESSING, PROCESSED.
- legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
- creation_date_time: data de criação da cobrança.
- detail_id: identificador da cobrança.
- detail_associated_id: identificador da cobrança associada (em caso de anulação de bonificação).
- detail_amount: valor da cobrança.
- transaction_detail: detalhe da cobrança.
- detail_type: tipo de detalhe.
- detail_sub_type: subtipos de detalhes.
- concept_type: tipo de conceito.
- fulfillment_info: informações de fulfillment.
- type: tipo de fulfillment.
- Valores possíveis: WITHDRAWAL, AGING, INBOUND_COLLECT, INBOUND_PENALTY, WAREHOUSING, OVERAGE, SPACE_PURCHASE, SPACE_CANCELLATION.
- amount_per_unit: valor por unidade.
- amount: valor total.
- sku: stock keeping unit.
- item_id: número do anúncio.
- item_title: título do anúncio.
- variation: variante do produto.
- quantity: unidades armazenadas ou coletadas.
- volume_type: tamanho da unidade.
- inventory_id: código do inventário do ML.
- withdrawal_id: número da retirada – TYPE WITHDRAWAL: Cobrança por retirada de estoque.
- shipment_type: forma de retirada – TYPE WITHDRAWAL: Cobrança por retirada de estoque.
- volume_unit: unidade de medida (m3) – TYPE WITHDRAWAL: Cobrança por retirada de estoque.
- amount_per_volume_unit: valor por m3 – TYPE WITHDRAWAL: Cobrança por retirada de estoque.
- volume: volume unitário (cm3) – TYPE WITHDRAWAL: Cobrança por retirada de estoque.
- volume_total: volume total – TYPE WITHDRAWAL: Cobrança por retirada de estoque.
- months_range: antiguidade em meses – TYPE AGING: Cobrança por armazenamento prolongado.
- stock_details: detalhes do estoque – TYPE AGING: Cobrança por armazenamento prolongado.
- quantity: quantidade em estoque – TYPE AGING: Cobrança por armazenamento prolongado.
- inventory_status: estado do inventário – TYPE AGING: Cobrança por armazenamento prolongado.
- inbound_id: número do envio – TYPE INBOUND_COLLECT: Cobrança por serviço de coleta / TYPE INBOUND_PENALTY: Cobrança por descumprimento.
- volume_unit: unidade de medida (m³) – TYPE INBOUND_COLLECT: Cobrança por serviço de coleta.
- amount_per_volume_unit: valor por m³ – TYPE INBOUND_COLLECT: Cobrança por serviço de coleta.
- volume: volume unitário (cm³) – TYPE INBOUND_COLLECT: Cobrança por serviço de coleta.
- volume_total: volume total – TYPE INBOUND_COLLECT: Cobrança por serviço de coleta.
- penalty_type: tipo de descumprimento – TYPE INBOUND_PENALTY: Cobrança por descumprimento.
- warehouse_id: identificador do warehouse – TYPE WAREHOUSING: Cobrança por armazenamento.
- size: tamanho da unidade – TYPE WAREHOUSING: Cobrança por armazenamento.
- item_quantity: unidades armazenadas – TYPE WAREHOUSING: Cobrança por armazenamento.
- space: indica o tipo de espaço que se compra ou cancela – TYPE SPACE_PURCHASE / SPACE_CANCELLATION.
- Valores possíveis (2 espaços): Pequenos e médios, Grandes e extra grandes.
- Valores possíveis (1 espaço): Armazenamento.
- type: tipo de fulfillment.
- document_info: informações do documento.
- document_id: ID do documento.
Insurtech
Você verá o detalhamento para conferir as cobranças e bonificações das garantias aplicadas sobre os produtos para um período específico, o grupo de faturamento Mercado Livre e o tipo de documento (Nota Fiscal ou Nota de Crédito).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/$KEY/group/ML/insurtech/details
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/billing/integration/periods/key/2022-10-01/group/ML/insurtech/details?document_type=BILL&limit=1
Resposta:
{
"offset": 0,
"limit": 150,
"total": 1,
"results": [
{
"charge_info": {
"legal_document_number": "001112131415",
"legal_document_status": "PROCESSED",
"legal_document_status_description": "Procesado",
"creation_date_time": "2022-10-04T22:24:18",
"detail_id": 123456,
"detail_amount": 520.01,
"transaction_detail": "Cargo por seguro de garantía extendida",
"status": null,
"status_description": null,
"charge_bonified_id": null,
"detail_type": "CHARGE",
"detail_sub_type": "CEW",
"concept_type": "WARRANTY"
},
"warranty_info": {
"warranty_id": "11111111-43c2-44ea-8436-00000000",
"certificate_id": "MLA999999",
"warranty_product": "GAREX",
"buyer_nickname": "TEST",
"order": {
"order_id": 102030405060,
"order_items": [
{
"listing_type_id": "gold_special",
"item": {
"item_id": "MLA88888888",
"category_id": "MLA1234",
"category_name": "Auriculares"
}
}
]
},
"quote_model": null,
"quote_brand": null,
"quote_description": ""
},
"prepaid_info": {
"operation_id": 55558888,
"movement_id": 123456789,
"doc_id": 11111111111,
"payment": {
"payment_id": 5555555555,
"date_created": "2022-10-04T22:23:40",
"transaction_amount": 736.98,
"money_release_date": "2023-03-03T22:23:41"
}
},
"document_info": { "document_id": 3333333333 }
}
]
}Campos de resposta Insurtech:
- charge_info: informações da cobrança.
- legal_document_number: número do documento.
- legal_document_status: estado de geração do documento.
- Valores possíveis: PROCESSING, PROCESSED.
- legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
- creation_date_time: data de criação da cobrança.
- detail_id: identificador da cobrança.
- detail_amount: valor da cobrança.
- transaction_detail: detalhe da cobrança.
- status: estado da cobrança.
- Valores possíveis: BONUS_ON_CREDIT_NOTE, BONUS_PART_ON_CREDIT_NOTE, BONUS_ON_BILL, BONUS_PART_ON_BILL, BONUS_ON, BONUS_PART_ON.
- status_description: descrição internacionalizada de status.
- charge_bonified_id: identificador da cobrança que bonifica.
- detail_type: tipo de detalhe.
- detail_sub_type: subtipos de detalhes.
- concept_type: tipo de conceito.
- warranty_info: informações da garantia.
- warranty_id: identificador da garantia.
- certificate_id: identificador do certificado.
- warranty_product: tipo de garantia.
- Valores possíveis: CARDS, GAREX, RODA.
- buyer_nickname: número do comprador.
- buyer_state_name: estado do comprador.
- order: informações da order.
- order_id: identificador da order.
- order_items: lista de itens da order.
- listing_type_id: tipo de anúncio.
- item: informações do item (item_id, title, category_id, category_name).
- quote_model: modelo do produto. Aplica-se a RODA.
- quote_brand: marca do produto. Aplica-se a RODA.
- quote_description: descrição adicional. Aplica-se a RODA.
- prepaid_info: informações do pré-pago.
- operation_id: identificador da operação.
- movement_id: identificador do movimento.
- doc_id: identificador do documento.
- payment: informações do pagamento.
- payment_id: identificador do pagamento.
- date_created: data do pagamento.
- transaction_amount: valor do pagamento.
- money_release_date: data de liberação do dinheiro.
- document_info: informações do documento.
- document_id: ID do documento.
Próximo: Pagamentos.