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 número do período
→Campos do recurso
→Resumo de faturamento
→Campos do recurso
→Detalhe de conciliação
→Campos do recurso


Obter número do período

Importante: o período de faturamento pode variar dependendo do usuário.
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/443033562/billing/period?access_token=$ACCESS_TOKEN

Resposta:

{
    "period": [
        {
            "paid": "N",
            "date_from": "2020-01-24T00:00:00.000-04:00",
            "date_to": "2020-01-28T00:00:00.000-04:00",
            "expiration_date": "2020-02-28T00:00:00.000-04:00",
            "period": "20200228",
            "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/443033562/invoices/32976ad7-0bd0-asd123e-967c?type=pdf"
        },
        {
            "paid": "Y",
            "date_from": "2019-12-24T00:00:00.000-04:00",
            "date_to": "2020-01-23T00:00:00.000-04:00",
            "expiration_date": "2020-01-28T00:00:00.000-04:00",
            "period": "20200128",
            "url_invoice": "https://myaccount.mercadolibre.com.uy/billing/v2/api/billing/user/443033562/invoices/32976ad7-0bd0-asd123-hasd45?type=pdf"
        },
        {
            "paid": "Y",
            "date_from": "2019-12-02T00:00:00.000-04:00",
            "date_to": "2020-01-01T00:00:00.000-04:00",
            "expiration_date": "2020-01-07T00:00:00.000-04:00",
            "period": "20200107",
            "url_invoice": ""
        },
        {
            "paid": "Y",
            "date_from": "2019-11-24T00:00:00.000-04:00",
            "date_to": "2019-12-23T00:00:00.000-04:00",
            "expiration_date": "2019-12-30T00:00:00.000-04:00",
            "period": "20191230",
            "url_invoice": ""
        },
        {
            "paid": "Y",
            "date_from": "2018-07-02T00:00:00.000-04:00",
            "date_to": "2019-12-01T00:00:00.000-04:00",
            "expiration_date": "2019-12-09T00:00:00.000-04:00",
            "period": "20191209",
            "url_invoice": ""
        },
        {
            "paid": "Y",
            "date_from": "2019-11-02T00:00:00.000-04:00",
            "date_to": "2019-11-23T00:00:00.000-04:00",
            "expiration_date": "2019-11-28T00:00:00.000-04:00",
            "period": "20191128",
            "url_invoice": ""
        },
        {
            "paid": "Y",
            "date_from": "2019-10-02T00:00:00.000-04:00",
            "date_to": "2019-11-01T00:00:00.000-04:00",
            "expiration_date": "2019-11-07T00:00:00.000-04:00",
            "period": "20191107",
            "url_invoice": ""
        }
    ]
}


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 do período a utilizar nos próximos recursos.
url_invoice: URL da fatura legal gerada.

Importante:
Este último campo está disponível para o Uruguai e o Peru. Em breve, durante este ano de 2020, o habilitaremos para os outros países.
Nota:
O campo Paid pode não aparecer para todas as contas. Este recurso apresenta no máximo os últimos 12 meses.


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


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.
Chamada:

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

Exemplo:

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

Resposta:

{
  "paging": {
    "total": 6409,
    "offset": 0,
    "limit": 150
  },
  "results": [
    {
      "concept": "Cargo por Mercado Envíos",
      "id": 27920673513,
      "type": "shipment",
      "subtype": "CXD",
      "date": {
        "billable": "2019-04-05T01:35:41.000-04:00",
        "created": "2019-04-05T01:35:41.000-04:00"
      },
      "prepaid": true,
      "amount": 187.49,
      "currency_id": "ARS",
      "site_id": "MLA",
      "document": {
        "id": 806818557,
        "date_of_expiration": "2019-05-10T00:00:00.000-04:00",
        "society": "MCA"
      },
      "order": {
        "id": 1980848182,
        "item_id": null
      }
    },
    {
      "concept": "Cargo por venta",
      "id": 4652334681,
      "type": "mp_operation",
      "subtype": "CV",
      "date": {
        "billable": "2019-04-05T01:35:45.000-04:00",
        "created": "2019-04-05T01:35:45.000-04:00"
      },
      "prepaid": true,
      "amount": 259.9,
      "currency_id": "ARS",
      "site_id": "MLA",
      "document": {
        "id": 806818565,
        "date_of_expiration": "2019-05-10T00:00:00.000-04:00",
        "society": "ML"
      },
      "order": {
        "id": 1980848182,
        "item_id": 762856563
      }
    }
   }
  ]
}


Campos do recurso

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

type:

  • shipment: Quando a taxa é por Mercado Envios.
  • mp_operation: Quando a taxa é por uma venda.
  • tax: Quando a taxa é por uma venda.

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.

currency_id: identificador da moeda de acordo com o site_id.

order:

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

date_of_expiration: data de vencimento do documento. society: referido à entidade emissora dos documentos.

society: hace referencia a la entidad que emite los documentos.

date:

  • billable: data de faturamento.
  • created: data de criação do documento.