Relatórios de faturamento

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 10/11/2023

Relatórios de faturamento

Com esta funcionalidade você pode disponibilizar os detalhes de faturamento realizados no Mercado Livre e Mercado Pago para os vendedores.
Consultando /billing/monthly/periods você irá obter informação dos últimos 12 períodos. Depois, com /documents conseguirá todas as faturas (documentos) de um período, e finalmente, com /summary e /details poderá acessar o resumo de faturamento de um período e respectivamente, os detalhes.

Faturamento do Mercado Livre e Mercado Pago

Cada um dos endpoints permite obter informação de faturamento tanto do Mercado Livre, como do Mercado Pago. Através do parâmetro de query obrigatório group podemos especificar de que grupo de faturamento queremos obter a informação.

Nota:

- Não é obrigatório consultar primeiro o endpoint de períodos, já que a key necessária para consumir o resto dos endpoints é o primeiro dia do mês. Por exemplo: 2023-06-01.

- O parâmetro document_type é obrigatório em /monthly/periods e opcional em /documents.

- O parâmetro limit suporta até 12 como máximo em /monthly/periods.

Obter período

Importante:

O período de faturamento pode variar segundo o usuário.

Permite obter informação dos períodos de facturamento para o grupo de facturamento indicado (Mercado Livre ou Mercado Pago). Por padrão devolvemos os últimos 6 períodos, com a possibilidade de consultar períodos mais antigos utilizando a paginação de offset e limit.

Nota:

Através do parâmetro document_type pode ser filtrado o tipo de documento que se deseja obter BILL | CREDIT_NOTE.

Chamada para os sites MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods

Chamada para os sites MLA, MLB MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periods

Exemplo para os sites MLA, MLB MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/monthly/periods?group=MP&document_type=BILL&offset=1&limit=2

Resposta:

{
    "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.

key: é a data do primeiro dia do mês. Para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR é o valor utilizado para consumir os endpoints de documents, details e summary.

expiration_date: data de fim do período. Se informa sempre que o estado do período se encontra fechado. Para o resto dos sites (MLM) é o valor utilizado para consumir os endpoints de documents, details e summary.

debt_expiration_date: data de vencimento da dívida. No caso que não se mova a data de vencimento este campo será igual ao expiration_date.

debt_expiration_date_move_reason: motivo da mudança de data de vencimento da dívida. No caso que não se mova a data de vencimento este campo será null.

Valores possíveis: AUTOMATIC_DOCUMENT_CLOSURE_PROCES | RECEIPT_ANNULMENT_PROCESS_UNRECORDED | RECEIPT_ANNULMENT_PROCESS | PERIOD_EXTENDED_BY_ADMIN | PAYMENT_ANNULMENT.

debt_expiration_date_move_reason_description: descrição internacionalizada de debt_expiration_date_move_reason. No caso que não se mova a data de vencimento este campo será null.

period_status: indica se o período se encontra aberto ou fechado. Valores possíveis:OPEN | CLOSED.

Obter documentos de um período

Permite obter informação de documentos (faturas e notas de crédito) para um período de faturamento em particular para o grupo de faturamento indicado (Mercado Livre ou Mercado Pago).

Chamada para os sites MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/documents

Chamada para os sites MLA, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/documents

Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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=1

Resposta:

{
  "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"
               }
           ]
  }]
}

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).

Resumo de faturamento

Permite obter o resumo de comissões e bonificações que teve o vendedor para um período de tempo em particular.

Nota:

Através do parâmetro document_type pode ser filtrado o tipo de documento que se deseja obter BILL | CREDIT_NOTE.

Chamada para os sites MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/summary

Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/summary

Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06 -012/summary?group=MP&document_type=BILL

Resposta:

{
  "user": {
    "nickname": "TEST"
  },
  "period": {
    "date_from": "2021-05-01",
    "date_to": "2021-06-01",
    "expiration_date": "2021-06-02"
  },
  "summary": {
    "amount": 545562.37,
    "credit_note": 0,
    "tax": 0.00,
    "bonuses": [{
      "label": "Bonificación de MercadoPago",
      "amount": 7354.60
    },
    {
      "label": "Bonificación Impuesto a los Ingresos Brutos Cap. Fed.",
      "amount": 116.43
    },
    {
      "label": "Bonificación Impuesto al Valor Agregado Régimen General",
      "amount": 116.43
    }
    ],
    "charges": [{
        "label": "Cargo de MercadoPago",
        "amount": 524228.80
      },
      {
        "label": "Percepción General IIBB de CABA",
        "amount": 13003.72
      }, {
        "label": "Percepción IVA Régimen General",
        "amount": 13003.72

      },
      {
        "label": "Cargo por transferencia de dinero",
        "amount": 2913.59
      }
    ]
  }
}

Campos da resposta

summary: cobranças e bonificações que o vendedor teve.
amount: total a pagar dentro do período de faturamento consultado. É formado pela soma de Cobranças e Impostos subtraindo as Bonificações.
credit_note: bonificações de cobranças geradas em outros períodos. As notas de crédito são utilizadas para pagar faturas de dívidas.
tax: percepções geradas por distintos regimes tributários (Argentina).
bonuses: reembolso de comissões por suas vendas e serviços que não se concretizaram. Você vai vê-los discriminados segundo o tipo de bonificação.

label: nome da bonificação.
amount: valor desta bonificação.

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.

Detalhe de conciliação

Permite obter o detalhe para conciliar as faturas e as cobranças de vendas para um período em particular, ou grupo de facturamento (Mercado Libre ou Mercado Pago) e o tipo de documento (Fatura ou Nota de Crédito). Esta informação é a mesma que se disponibiliza através da seção de relatórios de faturamento.

Notas:

- Caso a resposta tenha mais de 10.000 registros, você deve usar os filtros a seguir para restringir os resultados., evitando respostas demoradas.
- Através do parámetro document_type poderá ser filtrado o tipo de documento que se deseja obter BILL | CREDIT_NOTE.

Mercado Livre

Para o caso de Mercado Livre, se expõe o detalhe das cobranças efetuadas, informação de venda, de descontos, de envios e da publicação.

Chamada para os sites MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/ML/details

Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/details

Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-012/group/ML/details?document_type=BILL&limit=1

Resposta:

{
  "offset": 0,
  "limit": 150,
  "total": 1,
  "results": [
      {
          "charge_info": {
              "legal_document_number": "0001A00123456",
              "legal_document_status": "PROCESSED",
              "legal_document_status_description": "Procesado",
              "creation_date_time": "2021-05-13T08:08:24",
              "detail_id": 123456789,
              "detail_amount": 342.49,
              "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_type": "CHARGE",
              "detail_sub_type": "CXD",
              "concept_type": "SHIPPING"
          },
          "discount_info": {
              "charge_amount_without_discount": 684.99,
              "discount_amount": 342.5,
              "discount_reason": "Descuento general"
          },
          "sales_info": [
              {
                  "order_id": 12345,
                  "operation_id": null,
                  "sale_date_time": "2021-05-13T08:05:10",
                  "sales_channel": "Mercado Libre",
                  "payer_nickname": "ABCD",
                  "state_name": "Neuquén",
                  "transaction_amount": 2499
              },
           ],
          "shipping_info": {
              "shipping_id": "123456789",
              "pack_id": "200000123456789",
              "receiver_shipping_cost": 0
          },
          "items_info": [
              {
                  "item_id": "MLA987654321",
                  "item_title": "Fabrica Magdalenas Cup Cake Maker Atma Cm8910e",
                  "item_type": "gold_special",
                  "item_type_description": "Clásica",
"item_category": "Electrodomésticos y Aires Ac. > Pequeños Electrodomésticos > Para Cocina > Máquinas para Postres > Máquinas de Cupcakes",
                  "inventory_id": null,
                  "item_amount": 1,
                  "item_price": 2499,
                  "order_id": 1234
              }
          ],
          "document_info": {
              "document_id": 1615633359
          },
          "marketplace_info": {
              "marketplace": "SHIPPING"
          },
          "currency_info": {
              "currency_id": "ARS"
          }
      }
  ],
  errors:[]
}

Campos de resposta Mercado Livre

charge_info: informação da cobrança.

legal_document_number: número do documento.
legal_document_status: estado de criaçã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 está 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.
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.
detail_sub_type: subtipos de detalhes.

discount_info: informação sobre descontos.

charge_amount_without_discount: valor da cobrança sem desconto.
discount_amount: valor do desconto.
discount_reason: motivo do desconto.
sales_info: informação de vendas.

sale_info: informação sobre a venda.

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.

shipping_info: informação do envio.

shipping_id: identificador do envio.
pack_id: identificador do pacote.
receiver_shipping_cost: envio a cobrança do cliente.

items_info: informação sobre publicações.

item_id: identificador da publicação.
item_title: título da publicação.
item_type: tipo de publicação.
item_category: categoria da publicação.
inventory_id: código de Mercado Livre.
item_amount: quantidade de itens vendidos.
item_price: preço unitário de item.
order_id: ordem à qual o item pertence.

documentInfo: informação do documento.

document_id: número Id de documentos.

marketplaceInfo: informação do marketplace.

marketplace: nome do marketplace.

currency_info: informação da moeda de acordo ao site_id.

currency_id: identificador da moeda de acordo ao site_id.

Mercado Pago

Para Mercado Pago se expõe o detalhe de cobranças facturadas com informação complementar sobre a operação do Mercado Pago, como os movimentos, meios de pagamento, payer, filial, ponto de venda entre outros.

Chamada para os sites MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/MP/details

Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/MP/details

Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/group/MP/details?document_type=BILL&limit=1

Resposta:


  {
     "offset": 0,
     "limit": 1,
     "total": 9,
     "results": [
         {
             "charge_info": {
                 "legal_document_number": null,
                 "legal_document_status": "PROCESSING",
                 "legal_document_status_description": "En proceso",
                 "concept_id": "12345678",
                 "transaction_detail": "Cargo de MercadoPago",
                 "creation_date_time": "2021-06-01T17:45:39",
                 "detail_amount": 13.8,
         "detail_type": "CHARGE",
         "detail_sub_type": "CCMP"
                 
             },
             "operation_info": {
                 "operation_type": "BUY",
                 "operation_type_description": "Pago",
                 "reference_id": 12345678,
                 "sales_channel": "Point",
                 "store_id": 2222222,
                 "store_name": "Store",
                 "external_reference": "Venta presencial",
                 "payer_nickname": "TEST",
                 "transaction_amount": 340
             },
             "perception_info": {
                 "aliquot": null,
                 "taxable_amount": null
             },
            "document_info": {
         "document_id": 8888899999,
        },
       "market_type_info": {
         "marketplace": "MP"
             },
   
             "currency_info": {
                 "currency_id": "MXN"
             }
         }
     ]
  }

Campos de resposta Mercado Pago

charge_info: informação da cobrança.

legal_document_number: número do documento.
detail_id: identificador da cobrança.
movement_id: número de movimento.
transaction_detail: detalhe.
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ção de operação sobre a que se aplica.

operation_type: tipo de operação. Valores possíveis BUY | TAX.
operation_type_description: descrição internacionalizada do campo operation.
reference_id: número de operação relacionada.
sales_channel: tipo de pagamento.
store_id: número de filial/loja.
store_name: nome da filial/loja.
external_reference: número de referência externa.
payer_nickname: cliente.
transation_amount: valor da operação.

perception_info: informação da percepção.

aliquot: valor da alíquota.
taxable_amount: base tributável.

documentInfo: informação do documento.

document_id: número Id de documentos.

marketplaceInfo: informação do marketplace.

nome do marketplace.

currency_info: informação da moeda de acordo ao site_id.

currency_id: identificador da moeda de acordo ao site_id.

Mercado Envios Flex

Para Mercado Envios com logística Flex, é apresentando o detalhe para conciliar as bonificações e anulações de Flex para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (Nota de débito ou Nota de crédito). Além disso, oferece a informação sobre o envio e sobre a venda.

Nota:

O endpoint de Flex está disponível apenas nos sites MLA, MLC e MCO.

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-012/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 Mercado Envios Flex

charge_info: informações de cobrança.

legal_document_number: número do documento.
legal_document_status: estado de geração do documento. Possíveis valores: 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 cancelamento 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ção sobre envio.

shipping_id: identificador do envio.
receiver_nickname: cliente.
pack_id: número do pacote.
receiver_shipping_cost: custo do envio.

order: informação da venda.

order_id: identificador da venda.
date_created: data da order.
totalAmount: valor total da order.
paymentId: identificador de pagamento.
buyerNickname: cliente.

document_info: informação do documento.

document_id: ID do documento.

Fulfillment

Para Mercado Envios com logística Full, será apresentado o detalhe para conciliar as taxas e as bonificações por coleta e/ou armazenamento para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (Nota fiscal ou Nota de crédito). Além disso, oferece a informação do produto armazenado ou recoletado. A seguir verá os tipos de taxas existen para o relatório de Fulfillment:

Taxa por retirada de estoque.
Taxa por armazenamento prolongado.
Taxa por serviço de coleta.
Taxa por não cumprimento.
Taxa por armazenamento.

Nota:

O endpoint de FULL está disponível apenas nos sites MLA, MLB, MLM, MCO e MLC.

Chamada para o site MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/ML/full/details

Chamada para os sites MLA, MLB, MCO e MLC

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/full/details

Exemplo para os sites MLA, MLB, MCO e MLC:

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": "INBOUND_COLLECT",
        "amount_per_unit": 2.54,
        "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": "m3",
        "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ção da cobrança.

legal_document_number: número do documento.
legal_document_status: estado de geração do documento. Possíveis valores: PROCESSING, PROCESSED
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.
charge_bonified_id: identificador da cobrança que bonifica.
detail_type: tipo de detalhe.
detail_sub_type: subtipos de detalhe.
concept_type: tipo de conceito.
payment_id: identificador do pagamento.

fulfillment_info: Informação de fulfillment.

type: tipo de fulfillment. Possíveis valores: WITHDRAWAL | AGING | INBOUND_COLLECT | INBOUND_PENALTY | WAREHOUSING
amount_per_unit: valor por unidade.
amount: total.
sku: stock-keeping-unit.
item_id: número da publicação.
item_title: titulo da publicação.
variation: variável do produto.
quantity: unidades armazenadas ou recoletadas.
volume_type: tamanho da unidade.
inventory_id: código do inventário do Mercado Livre.
withdrawal_id: número de retirada –TYPE WITHDRAWAL custo por retirada de estoque –
shipment_type: forma de retirada. –TYPE WITHDRAWAL custo por retirada de estoque –
volume_unit: unidade de medida (m3). –TYPE WITHDRAWAL custo por retirada de estoque –
amount_per_volume_unit: valor por m3. –TYPE WITHDRAWAL custo por retirada de estoque –
volume: volume unitário (cm3) –TYPE WITHDRAWAL custo por retirada de estoque–
volume_total: volume total. –TYPE WITHDRAWAL custo por retirada de estoque –
months_range: antiguidade em meses. –TYPE AGING custo por armazenamento prolongado –
stock_details: detalhes de estoque. –TYPE AGING custo por armazenamento prolongado –
quantity: quantidade em estoque. –TYPE AGING custo por armazenamento prolongado–
inventory_status: estado do inventário. –TYPE AGING custo por armazenamento prolongado –
inbound_id: número de envio. –TYPE INBOUND_COLLECT custo por serviço de coleta –
volume_unit: unidade de medida (m3) –TYPE INBOUND_COLLECT custo por serviço de coleta –
amount_per_volume_unit: valor por m3. –TYPE INBOUND_COLLECT custo por serviço de coleta –
volume: volume unitário (cm3) –TYPE INBOUND_COLLECT custo por serviço de coleta –
volume_total: volume total. –TYPE INBOUND_COLLECT custo por serviço de coleta–
inbound_id: número de envio. –TYPE INBOUND_PENALTY custo por não cumprimento -
penalty_type: tipo de não cumprimento. –TYPE INBOUND_PENALTY custo por não cumprimento –
warehouse_id: identificador de warehouse.–TYPE WAREHOUSING custo por não cumprimento –
size: tamanho da unidade.–TYPE WAREHOUSING custo por armazenamento–
item_quantity: unidades armazenadas.–TYPE WAREHOUSING custo por armazenamento–

idocument_info: informação do documento.

document_id: ID do documento.

Insurtech

Permite obter o detalhe para conciliar os encargos e bonificações das garantias aplicadas sobre os produtos para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (fatura ou Nota de Crédito). Esta informação é a mesma que se disponibiliza através da seção de relatório de faturamento para os usuários de Insurtech. As opções de filtro podem ser usadas da mesma forma que temos disponível para os detalhes do Mercado Livre e Mercado Pago.

Nota:

O endpoint de Insurtech está disponível apenas para os sites MLA, MLB e MLC

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",
                 "buyer_state_name": "Salta",
                 "order": {
                     "order_id": 102030405060,
                     "order_items": [
                         {
                             "unit_price": 10791,
                             "listing_type_id": "gold_special",
                             "item": {
                                 "item_id": "MLA88888888",
                                 "title": "Auriculares Inalámbricos Jbl Tune 510bt Negro",
                                 "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ção da cobrança.

legal_document_number: número do documento.
legal_document_status: estado de geração do documento. Valores possiveís: 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 bonificada.
detail_type: tipo de detalhe.
detail_sub_type: subtipos de detalhes.
concept_type: ipo de conceito.

wanrranty_info: informação da garantia.

wanrranty_id: identificador da garantia.
certificate_id: identificador do certificado.
waranty_product: tipo de garantia. Valores possíveís: CARDS, GAREX, RODA.
buyer_nickname: numero do comprador.
buyer_state_name: província do comprador.
order: informação da venda.
order_items: lista de items da venda.
unit_price: preço por unidade.
listing_type_id: tipo de publicação.
item: informação do item.
item_id: identificador do produto.
tittle: titulo do produto.
category_id: identificador da categoria.
category_name: nome da categoria.
quote_model: modelo do produto. Aplica a RODA.
quote_brand: marca do produto. Aplica a RODA.
quote_description: descrição adicional. Aplica a RODA.

prepaid_info: informação do pagamento.

operation_id: identificador da operação.
movement_id: identificador do pagamento.
doc_id: identificador do documento.

payment: informação do pagamento.

payment_id: identificador do pagamento.
date_created: data de papamento.
transaction_amount: valor do pago.
money_release_date: data de liberação do dinheiro.

document_info: informação do documento

document_id: ID do documento.

Filtros opcionais

order_by: permite ordenar a busca.
asc: ordena os resultados de forma ascendente (valor por default).
desc: ordena os resultados de forma descendente.
Ex: order_by=asc

sort_by: permite selecionar por que campo ordenar. Valores possíveis: DATE.

detail_typepermite buscar por tipos de detalhes.
charge: traz somente cobranças.
bonus: traz somente bonificações.
Ex: detail_type=charge.

detail_sub_types: permite buscar por tipos de detalhes. Se pueden definir varios separados por comas. Se pueden definir varios separados por coma.
Ex: detail_sub_types=CV, BV

detail_excluded_sub_types: permite excluir da busca os subtipos de detalhes indicados. Podem ser definidos vários separados por vírgula.
Ex: not_subtypes=CXD, BXD

marketplace_type: permite buscar pelo market do detalhe.
Ex: marketplace_type=SHIPPING

order_ids: permite buscar por um ou vários ID de order. Disponível para Mercado Libre.
Ex: order_ids=2294412230

item_ids: permite buscar por um ou mais IDs de publicação.
Ex: item_ids=724159812

document_ids: permite buscar por um ou mais IDs de fatura.
Ex: document_ids=987046992

detail_ids: permite buscar por um ou mais IDs de detalhe.
Ex: detail_ids=724159812

offset: permite buscar desde 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. Ex: offset=100 (devolve a partir do resultado nro 100).

limit: limita a quantidade de resultados. Por padrão o mínimo é 1 e o máximo valor permitido: 1000.
Ex: limit=300 (devolve até 300 resultados).

Relatórios de pagamentos

Permite obter o detalhe das notas fiscais do vendedor abonadas em um determinado período.

Chamada para MLM:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$expiration_date/group/ML/payment/details

Parâmetros de URL:

expiration_date: período em que deseja obter detalhe. (Formato: YYYY-mm-dd)

Chamada para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/group/ML/payment/details

Parâmetros de URL:

key: data do primeiro dia do mês. (Formato: YYYY-mm-dd)

Parâmetros de consulta opcionais:

sort_by:

Valores possíveis: DATE,ID.
Valor padrão: DATE.

order_by: Permite ordenar as buscas.

Valores possíveis: ASC, DESC.
Valor padrão: ASC.

offset: permite buscar desde um número de resultado adiante. O valor mínimo permitido é 0 e o valor máximo permitido é 10000. Por padrão o valor é 0.
limit: limita a quantidade de resultado, O valor mínimo permitido é 1 e o valor máximo permitido é 1000. Por padrão o valor é 150.

Campos de resposta

payment_id: número de pagamento.
credit_note_number: número de nota de crédito (se corresponde).
payment_date: data do pagamento.
payment_type_description: Descrição do tipo de pagamento.
payment_type: tipo de pagamento.
payment_method_description: descrição do método de pagamento.
payment_method: método de pagamento.
payment_status_description: descrição do estado do pagamento.
payment_status: estado do pagamento.
payment_amount: importe total do pagamento.
amount_in_this_period: importe aplicado neste período.
amount_in_other_period: importe aplicado em outro período.
remaining_amount: saldo a favor para próximas notas fiscais.

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-08-01/group/ML/payment/details?limit=1

Resposta:

"payment_info": {
       "payment_id": 57062878565,
       "credit_note_number": null,      
       "payment_date": "2023-04-19T12:53:24",
       "payment_type": "payment",
       "payment_type_description": "Pagos manuales",
       "payment_method": "amex",
       "payment_method_description": "American Express online",
       "payment_status": "approved",
       "payment_status_description": "Aplicado",
       "payment_amount": 999888,
       "amount_in_this_period": 103985.84,
       "amount_in_other_period": 895902.16,
       "remaining_amount": 0,
     }

Download de documento Legal

Permite baixar as faturas legais do Mercado Livre e Mercado Pago em formato PDF para todos os sites.

Notas:

- O file_id se obtêm consumindo o endpoint de Documents.Em alguns casos, o endpoint de Documents pode devolver dois file_id. Nestes casos sempre se deverá utilizar o file_id correspondente ao PDF.

- Se o endpoint de Document devolve um único file_id. Então esse é o dado para o download do documento legal.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/legal_document/{file_id}

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/legal_document/1234_FE_MEPF00869625_pdf

Resposta: download do arquivo em formato PDF.

Download do relatório de conciliação

Para fazer o download dos relatórios de conciliação do Mercado Livre, Mercado Envios Flex, Insurtech e Mercado Pago nos formatos XLSX e CSV você deve seguir um processo de gerar o relatório. Esse mesmo processo servirá para o relatório de Fulfillment e para o relatório de pagamentos, que admitem apenas o formato de download XLSX.
O processo de gerar o relatório consiste en três passos: primeiro irá gerar o relatório de conciliação, em seguida, deverá consultar o estado de geração do relatório até que esteja gerado e por fim, poderá proceder com o download.

1. Criação do relatório

Através deste endpoint irá realizar a criação do relatório.

Chamada para os sites MLM:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
  https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/reports

Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...} https://api.mercadolibre.com/billing/integration/periods/key/$key/reports

Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
  -d '{
     "group": "ML",
     "document_type": "BILL",
     "report_format": "CSV"
  }' 
  https://api.mercadolibre.com/billing/integration/periods/key/2021-08 -01/reports

O valor do parâmetro group varia segundo o relatório que queira gerar:

ML para relatório de ML
MP para relatório de MP
FLEX para relatório de Flex
FULL para relatório de Fulfillment
INSURTECH para relatório de Insurtech
PAYMENT para relatório de pagamentos

Resposta:

{
  "fileId": "ML-report-BILL-2021-08-04-11119999-CSV-v2"
  }

2. Estado de criação de relatório

Permitirá obter o estado de criação de um relatório.Os estados podem ser:

PROCESSING: o relatório está sendo gerado.
READY: o relatório terminou de ser criado.
ERROR: a criação do relatório falhou, deverá ser consultado novamente.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/{file_i d}/status

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2/status?document_type=BILL

Resposta:

{
"status": "PROCESSING"
}

3. Download do relatório

Com este endpoint poderá realizar o download do relatório. Este download poderá ser feito uma vez que o estado da criação seja Ready.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/{file_id}

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2?document_type=BILL

Resumo de percepções

Importante:

Aplica apenas para Argentina.

Permite obter o resumo de percepções que teve o vendedor para um período em particular, ou grupo de faturamento (Mercado Livre ou Mercado Pago).

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/$key/perceptions/summary

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-08-01/perceptions/summary?group=MP

Resposta:

{
  "summary": [
         {
          "document_id": 123456789,
          "society": "ML",
          "legal_document_number": "0011A012345678",
          "user_fiscal_condition": "Responsable inscripto sin incumplimientos",
          "amount": 229314.11,
          "regimen_tax_type": "MLA_RE_IVA_N",
          "regimen_tax_type_description": "Percepción de IVA nuevos del régimen 
  especial",
          "taxable_amount": 22931410.96,
          "aliquot": 1.00,
             "coefficient": 1.0000,
             "perception_charge_number": 1123456789,
             "tax_type": "CRGI",
             "tax_type_description": 
  "Percepción Impuesto al Valor Agregado nuevos",
             "bill_date": "2021-11-29",
             "status": "APPLIED",
             "status_description": "Aplicado"
        "tax_ids": [123345678,233455678]  
         }
  ],
  "errors": []
  }

Campos de resposta

summary: informação do resumo.

document_id: identificador do documento.
society: sociedade. Valores possíveis ML | MP.
legal_document_number: número do documento.
user_fiscal_condition: condição fiscal do usuário.
amount: total a pagar dentro do período consultado.
regimen_tax_type: regime do tipo de imposto.
regimen_tax_type_description: descrição internacionalizada do regime do tipo de imposto.
taxable_amount: base tributária.
aliquot: valor da alíquota.
coefficient: coeficiente que impacta no cálculo do imposto.
perception_charge_number: número de cobrança de percepção.
tax_type: tipo de imposto.
tax_type_description: descrição internacionalizada do tipo de imposto.
bill_date: data de faturamento.
status: estado do resumo.
status_description: descrição internacionalizada do estado.
tax_ids: tipos de impostos.

Detalhe de percepções

Permite obter o detalhe de uma determinada percepção.Para percepções de Mercado Livre a partir do código de percepção e número de documento. Para percepções de Mercado Pago a partir do código de percepção, número de documento e identificador fiscal.

Notas:

- Mercado Pago: com o campo tax_type, document_id e tax_id se acessa o detalhe da percepção e do documento indicado nos filtros. Mercado Livre: com o campo tax_type e document_id se acessa o detalhe da percepção e do documento indicado nos filtros.
- Ambos campos são obtidos do endpoint Resumo de percepções.
- Os campos de resultados variam de acordo ao tax_type consultado: Régimen General, Régimen Especial, Régimen Tucumán.

Mercado Livre

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details

Exemplo (Regime geral):

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details?document_id=333555777&tax_type=CIVA&offset=1&limit=2

Resposta (Regime geral):

{
   "offset": 0,
   "limit": 150,
   "total": 4241,
   "results": [
       {
           "detail_id": 12345678,
           "date_created": "2021-10-30",
           "taxable_amount": 2660.0,
           "aliquot": 3.0,
           "tax_amount": 79.8,
           "transaction_detail": "CV",
           "transaction_detail_description": "Cargo por venta",
           "charge_bonified_id": null,
           "amount": 2660.0,
           "gross_amount": 3218.6,
           "detail_type": "CHARGE",
           "detail_type_description": "Cargo"
       }],
   "errors": []
}

Mercado Pago

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details

Exemplo (Regime geral):

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details?document_id=333555777&tax_type=CIVAMP&tax_id=12345&offset=1&limit=2

Resposta (Regime geral):

{
   "offset": 0,
   "limit": 150,
   "total": 5,
   "results": [
       {
           "detail_id": 1114444,
           "date_created": "2021-10-30",
           "taxable_amount": 154.93,
           "aliquot": 3.0,
           "tax_amount": 4.6479,
           "movement_id": "1234567",
           "reference_id": 1234567,
           "transaction_detail": "CCMP",
           "transaction_detail_description": "Cargo de MercadoPago",
           "amount": 154.93,
           "gross_amount": 187.46,
           "detail_type": "CHARGE",
           "detail_type_description": "Cargo"
       }],
   "errors": []
}

Campos de resposta

Para Mercado Livre e para uma percepção de Regime geral retornam os seguintes dados:

detail_id: identificador do detalhe.
date_created: data de criação.
taxable_amount: base tributária.
aliquot: valor da alíquota.
tax_amount: importe do imposto.
transaction_detai: detalhe da transacção.
transaction_detail_description: descrição internacionalizada de detalhe da transacção.
charge_bonified_id: identificador da cobrança que bonifica no caso que o cargo seja um bônus.
amount: valor da percepção.
gross_amount: valor bruto da percepção.
gross_amount: detail_type: tipo de detalhe a que aplica a percepção.
gross_amount: detail_type_description: descrição do tipo de detalhe ao que aplica a percepção.

Para Mercado livre e para uma percepção do Regime Especial se informam também os seguintes dados:

publish_number: número da publicação.
publish_title: título da publicação.
sale_date: data de venda.
sale_number: número de venda.
buyer_name: número do comprador.
buyer_state_name: estado do comprador.

Para Mercado Livre e para uma percepção do Regime Tucumán se informa também o seguinte dado:

coefficient: coeficiente com que se calcula o importe do imposto.

Para Mercado Pago se informam também os seguintes dados:

movement_id: número de movimento.
reference_id: operação relacionada.

Código de resposta HTTP

206 – Partial content: em alguns casos, os endpoints devolverão o código 206 – Partial content. Isso acontece quando a solicitação para alguns dos dados falha, servirá para informá-lo de que você receberá uma resposta incompleta (por exemplo, desconto de um detalhe).Os erros serão exibidos no campo de erros da resposta do endpoint.

Estrutura do campo erros:

"errors": [
       {
           "index": 3,
           "error_type": "PARTIAL_CONTENT",
           "messages": "An error occurred while retrieving the information. Try        
   again"    
       },
]

Descrição dos campos:

index: posição do objeto que não pode ser recuperado.
date_created: tipo de erro.
taxable_amount: descrição de erro.

Nota:

Aplica a todos endpoints, exceto o download de documento legal e do relatório de detalhe de conciliação de relatório em formato XLSX e CSV.

Erros

Os erros esperados que podem ocorrer na aplicação serão retornados tendo a seguinte estrutura:

{
   "timestamp": string($date-time),
   "status": integer($int32),
   "type": string,
   "message": string,

  "path": string,
   "errors": {

<*>: string }
}

timestamp: informa a data e hora que foi gerado o erro.
status: informa o código de erro retornado.
type: código de erro de aplicação. Valores possíveis:

ABUSE_PREVENTION_ERROR
AUTHENTICATION_ERROR
AUTHORIZATION_ERROR
BAD_REQUEST_ERROR
VALIDATION_ERROR
TYPE_MISMATCH_ERROR
INTERNAL_ERROR
MISSING_PARAMETER_ERROR
METHOD_NOT_ALLOWED_ERROR
NOT_FOUND_ERROR

message: mostra uma mensagem de erro.
path: informa o endpoint que foi consumido.
errors: informa os erros ocorridos.

Exemplo:

{
   "timestamp": "2021-07-07T21:21:09.72319Z",
   "status": 422,
   "type": "TYPE_MISMATCH_ERROR",
   "message": "Type mismatch error.",
   "path": "/periods",
   "errors": {
       "group": "Invalid format for value "
   }
}