Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação do

Última atualização em 21/10/2024

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.

Nota:
Todos os endpoints necessitam do parâmetro group, grupo de faturamento para obter informação: ML (Mercado Livre) o MP (Mercado Pago). Caso não especifiquem, obterá a informação de ambos.

Obter período

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

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/periods

Exemplo:

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 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/documents

    Exemplo:

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

    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.

    Importante:

    Não recomendamos utilizar este endpoint dentro de um processamento batch. Seu uso é recomendado de forma sequencial. A informação que oferece este endpoint não se modifica durante o dia, por esse motivo um consumo diario por usuário é suficiente.

    Chamada:

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

    Exemplo:

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

    Resposta:

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