Relatórios de faturamento

Com esta funcionalidade você pode conhecer os relatórios de faturamento feito pelo Mercado Libre para os vendedores. Para isso, recomendamos que você consulte /billing/period para obter informações sobre os últimos 12 períodos, então com /bills você obterá todas as notas fiscais (faturas) de um período, e por último, com /summary e /details você acessa ao resumo de faturamento um período e seus detalhes, respectivamente.

Conteúdos

→Relatórios de Mercado Pago →Obter o período →Obter faturas de um período →Resumo de faturamento →Detalhe de conciliação       ↳Filtros opcionais


Relatórios de Mercado Pago

Agora você pode utilizar o parâmetro society=MP em todos os recursos para obter informações de faturamento do Mercado Pago para conciliar faturas. Por padrão, se você não enviar, retornaremos as informações de faturamento do Mercado Livre.


Exemplo:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/billing/period/20190510/details&society=MP

Resposta:

{
   "paging":{
      "offset":5,
      "limit":150,
      "total":238618
   },
   "results":[
      {
         "concept":"Pago Comisión MercadoPago",
         "id":878787878787,
         "type":"MP",
         "subtype":"CCMP",
         "detail_type":"CHARGE",
         "date_created":"2021-02-01T04:01:01",
         "prepaid":true,
         "amount":1.47,
         "currency_id":"ARS",
         "site_id":"ARS",
         "document":{
            "id":123456789,
            "date_of_expiration":"2021-03-02",
            "society":"MERCADO-PAGO"
         },
         "mp_info":{
            "id":15454547,
            "ref":"53245543",
            "amount":152,
            "detail":"payment",
            "nickname":"nickname"
         }
      }
   ]
}
Nota:
Se você enviar um society inválido ou usar society=MP com qualquer um dos filtros type, order_id, item_id, date_from e/ou date_to, nossa API retornará os seguintes erros:

Erro de society inválido:

{
   "statusCode": 1024,
   "message": "Society parameter is invalid. Possible value: MP"
}

Erro ao utilizar um filtro não permitido com society=MP:

{
   "statusCode": 1019,
   "message": "Filter type is not allowed to get Mercado-Pago society details"
}

Obter o período

Importante:
O período de faturamento pode variar dependendo do usuário. Além disso, não pode consultar com usuários TEST.

Conheça o período e o vencimento com qual realizará as consultas.
Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/users/$USER_ID/billing/period

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/123456789/billing/period

Resposta:

{
    "period": [
        {
            "paid": "Y",
            "date_from": "2020-02-05T00:00:00.000-04:00",
            "date_to": "2020-03-04T00:00:00.000-04:00",
            "expiration_date": "2020-03-10T00:00:00.000-04:00",
            "period": "20200310",
            "total_amount": 3440,
            "bills": [
                {
                    "id": 1003544720,
                    "status": "A",
                    "expired_date": "2020-03-10T00:00:00.000-04:00",
                    "amount": 3440,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2020-02-05T00:00:00.000-04:00",
                        "date_to": "2020-03-04T00:00:00.000-04:00"
                    },
                    "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/123456789/invoices/349ac13f-b578?type=pdf"
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2020-01-05T00:00:00.000-04:00",
            "date_to": "2020-02-04T00:00:00.000-04:00",
            "expiration_date": "2020-02-10T00:00:00.000-04:00",
            "period": "20200210",
            "total_amount": 3440,
            "bills": [
                {
                    "id": 980292894,
                    "status": "A",
                    "expired_date": "2020-02-10T00:00:00.000-04:00",
                    "amount": 3440,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2020-01-05T00:00:00.000-04:00",
                        "date_to": "2020-02-04T00:00:00.000-04:00"
                    }
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2019-12-05T00:00:00.000-04:00",
            "date_to": "2020-01-04T00:00:00.000-04:00",
            "expiration_date": "2020-01-10T00:00:00.000-04:00",
            "period": "20200110",
            "total_amount": 3180,
            "bills": [
                {
                    "id": 958238325,
                    "status": "A",
                    "expired_date": "2020-01-10T00:00:00.000-04:00",
                    "amount": 3180,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2019-12-05T00:00:00.000-04:00",
                        "date_to": "2020-01-04T00:00:00.000-04:00"
                    },
                    "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/123456789/invoices/36006403-dc10?type=pdf"
                }
            ]
        },
        {
            "paid": "Y",
            "date_from": "2019-11-05T00:00:00.000-04:00",
            "date_to": "2019-12-04T00:00:00.000-04:00",
            "expiration_date": "2019-12-10T00:00:00.000-04:00",
            "period": "20191210",
            "total_amount": 3180,
            "bills": [
                {
                    "id": 935204108,
                    "status": "A",
                    "expired_date": "2019-12-10T00:00:00.000-04:00",
                    "amount": 3180,
                    "pending_amount": 0,
                    "pay_status": "Y",
                    "period": {
                        "date_from": "2019-11-05T00:00:00.000-04:00",
                        "date_to": "2019-12-04T00:00:00.000-04:00"
                    }
                }
            ]
        },
    ]
}


Campos da resposta

paid: campo que indica se houve o pagamento da fatura.
date_from: data de início do período de faturamento.
date_to: data de fim do período de faturamento.
expiration_date: data de vencimento da fatura.
period: número de período para usar nossos próximos recursos.
total_amount: valor total de todos os documentos para esse período.
bills: retorna uma lista com todos os documentos existentes no período pesquisado.

  • id: identificador de documento.
  • status: status do documento, ativo ou inativo.
  • expired_date: data de validade do documento.
  • amount: quantidade do cabeçalho do documento.
  • pending_amount: valor restante a pagar.
  • pay_status: se o documento for pago ou não (Y o N).
  • period: período em que suas cobranças entram.
  •       date_from: data de criação da primeira cobrança do período.
          date_to: data de criação da última cobrança do período.

  • url_invoice: URL da fatura legal gerada.
Notas:
- O campo paid pode não aparecer para todas as contas. Este recurso apresenta no máximo os últimos 12 periodos.
- O campo url_invoice pode não aparecer se, no momento da consulta, não houver fatura legal para esse documento.

Obter faturas de um período

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/bills?$FI LTROS_OPCIONALES

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/period/20210101/bills?offset=150

Resposta:

{
   "paging":{
      "offset":150,
      "limit":150,
      "total":238618
   },
   "results":[
      {
         "id":1003544720,
         "expired_date":"2020-03-10T00:00:00.000-04:00",
         "amount":3440,
         "pending_amount":0,
         "pay_status":"Y",
         "period":{
            "date_from":"2020-02-05T00:00:00.000-04:00",
            "date_to":"2020-03-04T00:00:00.000-04:00"
         }
      }
   ]
}

Filtros disponíveis

document_id: Permite pesquisar pelo id da fatura. Ej: document_id=987046992 offset: Permite que você pesquise a partir de um número de resultado Ej: offset=100 (retorna a partir do resultado número 100) limit: Limitar o número de resultados. Por padrão, o mínimo é 150. Valor máximo permitido: 1000. Ej: limit=300 (retorna até 300 resultados).

Resumo de faturamento

Se quiser conhecer um resumo dos encargos e compensações que você teve como vendedor em um período de tempo, deverá fazer um GET ao recurso /summary.

Chamada:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/summary

Exemplo:

curl -X GET  -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/billing/period/20190510/summary

Resposta:

{
  "user": {
    "nickname": "TESTING123"
  },
  "period": {
    "date_from": "2019-04-05T00:00:00.000-04:00",
    "date_to": "2019-05-04T00:00:00.000-04:00",
    "date_of_expiration": "2019-05-10T00:00:00.000-04:00"
  },
  "summary": {
    "amount": 4141767.47,
    "credit_note": 43111.7,
    "tax": 492483.66,
    "bonuses": [
      {
        "label": "Bonificación del cargo por venta",
        "amount": 71007.49
      },
    ],
    "charges": [
      {
        "label": "Cargo por venta",
        "amount": 2784300.73
      },
      {
        "label": "Cargo por Mercado Envíos",
        "amount": 605717.77
      },
       {
        "label": "Percepción IIBB Com. Electrónico",
        "amount": 15529.9
      }
     ]
  }
}

Resposta:

{
  "user": {
    "nickname": "TESTING123"
  },
  "period": {
    "date_from": "2019-04-05T00:00:00.000-04:00",
    "date_to": "2019-05-04T00:00:00.000-04:00",
    "date_of_expiration": "2019-05-10T00:00:00.000-04:00"
  },
  "summary": {
    "amount": 4141767.47,
    "credit_note": 43111.7,
    "tax": 492483.66,
    "bonuses": [
      {
        "label": "Bonificación del cargo por venta",
        "amount": 71007.49
      },
    ],
    "charges": [
      {
        "label": "Cargo por venta",
        "amount": 2784300.73
      },
      {
        "label": "Cargo por Mercado Envíos",
        "amount": 605717.77
      },
    ]
  }
}

Campos da resposta

summary: vemos os Encargos e Bonificações do vendedor.

amount: total a ser pago dentro do período de faturamento consultado. É a soma de Encargos e Taxas menos as Bonificações.

credit_note: são as bonificações de encargos gerados em outros períodos. As notas de crédito são utilizadas para pagar notas fiscais devidas.

tax: são as taxas geradas pelos diferentes regimes tributários.

bonuses: é a devolução de comissões por suas vendas e serviços não concretizados. Você vai ver estes discriminados segundo o tipo de bonificação.

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

As bonificações podem ser para os seguintes conceitos:

Encargos de venda e envios: caso uma venda não seja concretizada devido a uma devolução ou por problemas com os correios (como perda ou danificação do produto), a comissão pela venda e as despesas com o envio serão retornadas.
Despesas com publicidade: se você contratar o serviço por engano ou tiver algum problema com a cobrança, nós devolveremos a diferença.
Bonificações por Taxas Tributárias: quando uma taxa por venda é retornada, também é incluída a devolução relacionada à taxa. O mesmo acontece quando há erros na aplicação de uma taxa.

charges: representam as diferentes taxas que o vendedor possa ter, como comissões por vendas, custo de anúncios, taxas, cobranças de serviços, por exemplo, Mercado Envios, Mercado Shops, etc. Se campanhas publicitárias forem contratadas, elas também aparecem aqui.


Detalhe de conciliação

O detalhe de conciliação é um relatório no qual você pode conciliar suas notas fiscais de Mercado Livre e Mercado Envios com as taxas das vendas realizadas.

Nota:
Caso a resposta tenha mais de 10.000 registros, você deve usar os filtros a seguir para restringir os resultados.

Filtros opcionais

  • date_sort
    asc: oclassifica os resultados em ordem crescente (valor padrão)
    desc: classifica os resultados em ordem decrescente
    Ex: date_sort=asc
  • date_from y date_to: devem ser usados ​​juntos e permitem pesquisar dentro de um período. Você também pode usar horas. Lembre-se de que o período deve estar sempre dentro das datas de início e término do período
    Formatos possíveis: yyyy-MM-dd o yyyy-MM-ddThh:mm:ss.sss.
    Ex: Data única: date_from=2019-05-09&date_to=2019-05-15
    Data e hora: date_from=2019-05-09T00:00:00.000&date_to=2019-05-15T00:00:00.000.
  • det_id: permite procurar um ID de detalhe específico.Ex: det_id=8398490328
  • det_type
    charge: retorna apenas cobranças
    bonus: retorna apenas bônus
    Ej: det_type=charge
  • subtypes: permite filtrar por subtipos de detalhes. Múltiplos podem ser definidos separados por vírgulas.
    Ej: subtypes=CV,BV
  • not_subtypes: permite excluir da pesquisa os subtipos de detalhes indicados. Múltiplos podem ser definidos separados por vírgulas.
    Ej: not_subtypes=CXD,BXD
  • type: permite pesquisar pelo market de detalhe.
    Ej: type=SHIPPING
  • order_id: permite pesquisar pelo ID da order.br/>Ex: order_id=2294412230
  • item_id: permite pesquisar pelo ID da publicação.
    Ex: item_id=724159812
  • document_id: permite pesquisar pelo ID da fatura.
    Ex: document_id=987046992
  • offset:permite pesquisar a partir de um número de resultado.
    Ex: offset=100 (retorna do resultado # 100)
  • limit: limite o número de resultados. Por padrão, o mínimo é 150 e o valor máximo permitido: 1000.
    Ex: limit=300 (retorna até 300 resultados)

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/details?$FILTROS_OPCIONALES

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/443033562/billing/period/20190510/details

Resposta:

{
    "paging": {
        "total": 2679,
        "offset": 0,
        "limit": 150
    },
    "results": [
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782869395,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 68.4,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290642081
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226734621
        },
        {
            "concept": "Cargo por venta",
            "id": 5782859370,
            "type": "CORE",
            "subtype": "CV",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 272.87,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290642081,
                "item_id": 725366950
            },
            "detail_type": "CHARGE",
            "mp_op_id": 5801583834
        },
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782887632,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 50.8,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290649986
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226824168
        },
        {
            "concept": "Cargo por venta",
            "id": 5782887634,
            "type": "CORE",
            "subtype": "CV",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 285.87,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290649986,
                "item_id": 620189246
            },
            "detail_type": "CHARGE",
            "mp_op_id": 5801916351
        },
        {
            "concept": "Cargo por Mercado Envíos",
            "id": 5782897217,
            "type": "SHIPPING",
            "subtype": "CFF",
            "date": {
                "billable": "2020-01-21T00:00:00.000-04:00",
                "created": "2020-01-21T00:00:00.000-04:00"
            },
            "prepaid": true,
            "amount": 68.4,
            "currency_id": "MXN",
            "site_id": "MLM",
            "document": {
                "id": 987046992,
                "date_of_expiration": "2020-02-25T00:00:00.000-04:00",
                "society": "ML"
            },
            "order": {
                "id": 2290651588
            },
            "detail_type": "CHARGE",
            "mp_op_id": 28226713276
        },
]


Campos da resposta

concept: são todas as vendas e operações que você fez no seu período de faturamento.

type:

  • core: são principalmente comissões de vendas, mas também incluem a compra de produtos e a comissão de garantia. No Equador e na Costa Rica, também será publicado no marketplace.
  • mp: cobranças e percepções geradas pelo Mercado Pago.
  • shipping: cobranças relacionados a logística.
  • taxes: impostos nacionais e provinciais do Mercado Livre (Argentina).
  • eshop: cobranças de eShop.
  • mshops: cobranças de Mercado Shops.
  • mclics: cobranças relacionadas à publicidade.
  • becommerce: se deve ao uso da plataforma beCommerce no Brasil.
  • credits: cobranças por produtos de Mercado Crédito (Argentina, Brasil e México).
  • classified: Essas são as cobranças pelos pacotes de publicação e pela publicação em categorias classificados de um usuário normal. Há também taxas de showroom.
  • mango: cobranças pelo uso da plataforma Mango (Argentina).

subtype: é o sub tipo que te permite identificar melhor cada operação. Existem 730 subtypes para distinguir cargos, inscrições, pacotes, impressões, bonificações, anulações, serviços, etc.

date: é a data da transação.

prepaid:

  • true: A taxa é automaticamente debitada através de Mercado Pago.
  • false: A taxa não é debitada automaticamente.

amount: preço detalhe.

currency_id: identificador da moeda de acordo com o site_id.

site_id: site onde os detalhes foram gerados.

document:

  • id: número de identificação do documento.
  • date_of_expiration: data de vencimiento daquele documento.
  • society: faz referência à entidade que emite os documentos.

order:

  • id: Número de identificação da ordem relacionada ao conceito.
  • item_id: Número de identificação do produto comprometido na ordem.

detail_type: indicar se é uma cobrança (charge) ou bônus (bonus).

mp_op_id:é o número da operação de Mercado Pago.

ou registre-se para receber as últimas notícias sobre nossa API