Relatórios de faturamento

Obter período

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.

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.