Relatórios de faturamento

Os seguintes recursos de API permitirão que você conheça os resumos de faturamento das suas vendas no Mercado Livre.

Conteúdos

→Obter o período
→Resumo de faturamento
→Detalhe de conciliação
       ↳Filtros opcionais disponíveis


Obter o período

Importante:
o período de faturamento pode variar dependendo do usuário.
Não é possível consultar os usuários do TEST.

Para conhecer o período e o vencimento com qual realizará as consultas, você deve fazer um GET no seguinte recurso:
Chamada:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/billing/period?access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET https://api.mercadolibre.com/users/123456789/billing/period?access_token=$ACCESS_TOKEN

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 do recurso

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.


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  https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/summary?access_token=$ACCESS_TOKEN

Exemplo:

curl -X GET  https://api.mercadolibre.com/users/443033562/billing/period/20190510/summary?access_token=$ACCESS_TOKEN

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 del recurso

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 de Mercado Envios com as taxas das vendas realizadas. Para isso, você deverá fazer um GET para o recurso Details.
Você também pode usar filtros que permitirão restringir e tornar sua pesquisa mais específica.

Nota:
Caso a resposta tenha mais de 10.000 registros, você deve usar os filtros a seguir para restringir os resultados, pois o recurso retorna até o valor mencionado. Em caso de exceder esse limite, a resposta será um erro 500.

Filtros opcionais disponíveis

  • 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.
    Ex: limit=300 (retorna até 300 resultados)

Chamada:

curl -X GET https://api.mercadolibre.com/users/$USER_ID/billing/period/$PERIODO/details?access_token=$ACCESS_TOKEN&$FILTROS_OPCIONALES

Exemplo:

curl -X GET https://api.mercadolibre.com/users/443033562/billing/period/20190510/details?access_token=$ACCESS_TOKEN

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 do recurso

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. -->Apenas para a 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. -->só para o Brasil
  • credits: cobranças por produtos de Mercado Crédito. -->Apenas para Argentina, Brasil y 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. -->Apenas para a 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