Documentação do Mercado Livre

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

Documentação

Última atualização em 16/02/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.

Faturamento do Mercado Livre e Mercado Pago

Cada um dos endpoints permite obter informação de faturamento tanto do Mercado Livre, como do Mercado Pago. Através do parâmetro de query obrigatório group podemos especificar de que grupo de faturamento queremos obter a informação.

Nota:
- Não é obrigatório consultar primeiro o endpoint de períodos, já que a key necessária para consumir o resto dos endpoints é o primeiro dia do mês. Por exemplo: 2023-06-01.

- O parâmetro document_type é obrigatório em /monthly/periods e opcional em /documents.

- O parâmetro limit suporta até 12 como máximo em /monthly/periods.

Obter período

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

Permite obter informação dos períodos de facturamento para o grupo de facturamento indicado (Mercado Livre ou Mercado Pago). Por padrão devolvemos os últimos 6 períodos, com a possibilidade de consultar períodos mais antigos utilizando a paginação de offset e limit.

Nota:
Através do parâmetro document_type pode ser filtrado o tipo de documento que se deseja obter BILL | CREDIT_NOTE.

Chamada para os sites MLM:

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

Chamada para os sites MLA, MLB MCO, MLC, MLU, MPE, MLV e MCR:

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

Exemplo para os sites MLA, MLB MCO, MLC, MLU, MPE, MLV e MCR:

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).

    Chamada para os sites MLM:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/documents

    Chamada para os sites MLA, MLC, MLU, MPE, MLV e MCR:

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

    Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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

    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).


    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.

    Nota:
    Através do parâmetro document_type pode ser filtrado o tipo de documento que se deseja obter BILL | CREDIT_NOTE.

    Chamada para os sites MLM:

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

    Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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

    Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06 -012/summary?group=MP&document_type=BILL

    Resposta:

    {
      "user": {
        "nickname": "TEST"
      },
      "period": {
        "date_from": "2021-05-01",
        "date_to": "2021-06-01",
        "expiration_date": "2021-06-02"
      },
      "summary": {
        "amount": 545562.37,
        "credit_note": 0,
        "tax": 0.00,
        "bonuses": [{
          "label": "Bonificación de MercadoPago",
          "amount": 7354.60
        },
        {
          "label": "Bonificación Impuesto a los Ingresos Brutos Cap. Fed.",
          "amount": 116.43
        },
        {
          "label": "Bonificación Impuesto al Valor Agregado Régimen General",
          "amount": 116.43
        }
        ],
        "charges": [{
            "label": "Cargo de MercadoPago",
            "amount": 524228.80
          },
          {
            "label": "Percepción General IIBB de CABA",
            "amount": 13003.72
          }, {
            "label": "Percepción IVA Régimen General",
            "amount": 13003.72
    
          },
          {
            "label": "Cargo por transferencia de dinero",
            "amount": 2913.59
          }
        ]
      }
    }

    Campos da resposta

    • summary: cobranças e bonificações que o vendedor teve.
    • amount: total a pagar dentro do período de faturamento consultado. É formado pela soma de Cobranças e Impostos subtraindo as Bonificações.
    • credit_note: bonificações de cobranças geradas em outros períodos. As notas de crédito são utilizadas para pagar faturas de dívidas.
    • tax: percepções geradas por distintos regimes tributários (Argentina).
    • bonuses: eembolso de comissões por suas vendas e serviços que não se concretizaram. Você vai vê-los discriminados segundo o tipo de bonificação.
      • label: nome da bonificação.
      • amount: valor desta bonificação.

    Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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

    Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'https://api.mercadolibre.com/billing/integration/periods/key/2023-10-01/summary/details
    Nota:
    Através do parâmetro opcional group você pode filtrar a informação correspondente a Mercado Livre ou Mercado Pago. Caso não especifique, obterá o resultado de ambos.

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



    Detalhe de conciliação

    Permite obter o detalhe para conciliar as faturas e as cobranças de vendas para um período em particular, ou grupo de facturamento (Mercado Libre ou Mercado Pago) e o tipo de documento (Fatura ou Nota de Crédito). Esta informação é a mesma que se disponibiliza através da seção de relatórios de faturamento.

    Notas:
    - Caso a resposta tenha mais de 10.000 registros, você deve usar os filtros a seguir para restringir os resultados., evitando respostas demoradas.
    - Através do parámetro document_type poderá ser filtrado o tipo de documento que se deseja obter BILL | CREDIT_NOTE.

    Mercado Livre

    Para o caso de Mercado Livre, se expõe o detalhe das cobranças efetuadas, informação de venda, de descontos, de envios e da publicação.

    Chamada para os sites MLM:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/ML/details

    Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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

    Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-012/group/ML/details?document_type=BILL&limit=1

    Resposta:

    {
      "offset": 0,
      "limit": 150,
      "total": 1,
      "results": [
          {
              "charge_info": {
                  "legal_document_number": "0001A00123456",
                  "legal_document_status": "PROCESSED",
                  "legal_document_status_description": "Procesado",
                  "creation_date_time": "2021-05-13T08:08:24",
                  "detail_id": 123456789,
                  "detail_amount": 342.49,
                  "transaction_detail": "Cargo por Mercado Envíos",
                  "debited_from_operation": "YES",
                  "debited_from_operation_description": "Si",
                  "status": null,
                  "status_description": null,
                  "charge_bonified_id": null,
                  "detail_type": "CHARGE",
                  "detail_sub_type": "CXD",
                  "concept_type": "SHIPPING"
              },
              "discount_info": {
                  "charge_amount_without_discount": 684.99,
                  "discount_amount": 342.5,
                  "discount_reason": "Descuento general"
              },
              "sales_info": [
                  {
                      "order_id": 12345,
                      "operation_id": null,
                      "sale_date_time": "2021-05-13T08:05:10",
                      "sales_channel": "Mercado Libre",
                      "payer_nickname": "ABCD",
                      "state_name": "Neuquén",
                      "transaction_amount": 2499
                  },
               ],
              "shipping_info": {
                  "shipping_id": "123456789",
                  "pack_id": "200000123456789",
                  "receiver_shipping_cost": 0
              },
              "items_info": [
                  {
                      "item_id": "MLA987654321",
                      "item_title": "Fabrica Magdalenas Cup Cake Maker Atma Cm8910e",
                      "item_type": "gold_special",
                      "item_type_description": "Clásica",
    "item_category": "Electrodomésticos y Aires Ac. > Pequeños Electrodomésticos > Para Cocina > Máquinas para Postres > Máquinas de Cupcakes",
                      "inventory_id": null,
                      "item_amount": 1,
                      "item_price": 2499,
                      "order_id": 1234
                  }
              ],
              "document_info": {
                  "document_id": 1615633359
              },
              "marketplace_info": {
                  "marketplace": "SHIPPING"
              },
              "currency_info": {
                  "currency_id": "ARS"
              }
          }
      ],
      errors:[]
    }

    Campos de resposta Mercado Livre

    • charge_info: informação da cobrança.
      • legal_document_number: número do documento.
      • legal_document_status: estado de criação do documento. Valores possíveis: PROCESSING | PROCESSED.
      • legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
      • creation_date_time: data de criação da cobrança.
      • detail_id: identificador da cobrança.
      • transaction_detail: detalhe da cobrança.
      • debited_from_operation: indica se está descontado da operação. Valores possíveis: YES | NO | INAPPLICABLE.
      • debited_from_operation_description: descrição internacionalizada do campo debited_from_operation.
      • status: estado da cobrança. Valores possíveis: BONUS_ON_CREDIT_NOTE | BONUS_PART_ON_CREDIT_NOTE | BONUS_ON_BILL | BONUS_PART_ON_BILL | BONUS_ON | BONUS_PART_ON.
      • status_description: descrição internacionalizada de status.
      • charge_bonified_id: identificador da cobrança que bonifica.
      • detail_amount: valor da cobrança.
      • detail_type: tipo de detalhe.
      • detail_sub_type: subtipos de detalhes.

    • discount_info: informação sobre descontos.
      • charge_amount_without_discount: valor da cobrança sem desconto.
      • discount_amount: valor do desconto.
      • discount_reason: motivo do desconto.
      • sales_info: informação de vendas.

    • sale_info: informação sobre a venda.
      • order_id: identificador da venda.
      • operation_id: identificador do pagamento.
      • sale_date_time: data e hora da venda.
      • sales_channel: canal de venda.
      • payer_nickname: cliente.
      • state_name: estado.
      • transaction_amount: valor total da venda.

    • shipping_info: informação do envio.
      • shipping_id: identificador do envio.
      • pack_id: identificador do pacote.
      • receiver_shipping_cost: envio a cobrança do cliente.

    • items_info: informação sobre publicações.
      • item_id: identificador da publicação.
      • item_title: título da publicação.
      • item_type: tipo de publicação.
      • item_category: categoria da publicação.
      • inventory_id: código de Mercado Livre.
      • item_amount: quantidade de itens vendidos.
      • item_price: preço unitário de item.
      • order_id: ordem à qual o item pertence.

    • documentInfo: informação do documento.
      • document_id: número Id de documentos.

    • marketplaceInfo: informação do marketplace.
      • marketplace: nome do marketplace.

    • currency_info: informação da moeda de acordo ao site_id.
      • currency_id: identificador da moeda de acordo ao site_id.


    Mercado Pago

    Para Mercado Pago se expõe o detalhe de cobranças facturadas com informação complementar sobre a operação do Mercado Pago, como os movimentos, meios de pagamento, payer, filial, ponto de venda entre outros.

    Chamada para os sites MLM:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/MP/details

    Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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

    Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-06-01/group/MP/details?document_type=BILL&limit=1

    Resposta:

    
      {
         "offset": 0,
         "limit": 1,
         "total": 9,
         "results": [
             {
                 "charge_info": {
                     "legal_document_number": null,
                     "legal_document_status": "PROCESSING",
                     "legal_document_status_description": "En proceso",
                     "concept_id": "12345678",
                     "transaction_detail": "Cargo de MercadoPago",
                     "creation_date_time": "2021-06-01T17:45:39",
                     "detail_amount": 13.8,
             "detail_type": "CHARGE",
             "detail_sub_type": "CCMP"
                     
                 },
                 "operation_info": {
                     "operation_type": "BUY",
                     "operation_type_description": "Pago",
                     "reference_id": 12345678,
                     "sales_channel": "Point",
                     "store_id": 2222222,
                     "store_name": "Store",
                     "external_reference": "Venta presencial",
                     "payer_nickname": "TEST",
                     "transaction_amount": 340
                 },
                 "perception_info": {
                     "aliquot": null,
                     "taxable_amount": null
                 },
                "document_info": {
             "document_id": 8888899999,
            },
           "market_type_info": {
             "marketplace": "MP"
                 },
       
                 "currency_info": {
                     "currency_id": "MXN"
                 }
             }
         ]
      }

    Campos de resposta Mercado Pago

    • charge_info: informação da cobrança.
      • legal_document_number: número do documento.
      • detail_id: identificador da cobrança.
      • movement_id: número de movimento.
      • transaction_detail: detalhe.
      • creation_date_time: data da cobrança.
      • detail_amount: valor da cobrança.
      • detail_type: tipo de detalhe.
      • detail_sub_type: subtipos de detalhes.

    • operation_info: informação de operação sobre a que se aplica.
      • operation_type: tipo de operação. Valores possíveis BUY | TAX.
      • operation_type_description: descrição internacionalizada do campo operation.
      • reference_id: número de operação relacionada.
      • sales_channel: tipo de pagamento.
      • store_id: número de filial/loja.
      • store_name: nome da filial/loja.
      • external_reference: número de referência externa.
      • payer_nickname: cliente.
      • transation_amount: valor da operação.

    • perception_info: informação da percepção.
      • aliquot: valor da alíquota.
      • taxable_amount: base tributável.

    • documentInfo: informação do documento.
      • document_id: número Id de documentos.

    • marketplaceInfo: informação do marketplace.
      • nome do marketplace.

    • currency_info: informação da moeda de acordo ao site_id.
      • currency_id: identificador da moeda de acordo ao site_id.

    Mercado Envios Flex

    Para Mercado Envios com logística Flex, é apresentando o detalhe para conciliar as bonificações e anulações de Flex para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (Nota de débito ou Nota de crédito). Além disso, oferece a informação sobre o envio e sobre a venda.


    Nota:
    O endpoint de Flex está disponível apenas nos sites MLA, MLC e MCO.

    Chamada:

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

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-03-012/group/ML/flex/details?document_type=BILL&limit=1

    Resposta:

    {
        "offset": 0,
        "limit": 1,
        "total": 100,
        "results": [{
          "charge_info": {
            "legal_document_number": "00AA11AA00",
            "legal_document_status": "PROCESSED",
            "legal_document_status_description": "Procesado",
            "creation_date_time": "2023-02-21T12:35:58",
            "detail_id": 2020202020,
            "detail_associated_id": 4040404040,
            "detail_amount": 163,
            "transaction_detail": "Anulación de bonificación por Mercado Envíos Flex",
            "detail_type": "CHARGE",
            "detail_sub_type": "CFLX",
            "concept_type": "FLEX"
          },
          "shipping_info": {
            "shipping_id": 4444455555,
            "receiver_nickname": "NICKNAME",
            "pack_id": "12345678",
            "receiver_shipping_cost": 814.99,
            "order": {
              "order_id": 9000000008888888,
              "date_created": "2023-02-15T11:54:51",
              "total_amount": 29499,
              "payment_id": 998899889988,
              "buyer_nickname": "NICKNAME"
            }
          },
          "document_info": {
            "document_id": 776677667711
          }
        }],
        "errors": []
      }

    Campos de resposta Mercado Envios Flex

    • charge_info: informações de cobrança.
      • legal_document_number: número do documento.
      • legal_document_status: estado de geração do documento. Possíveis valores: PROCESSING | PROCESSED
      • legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
      • creation_date_time: data de criação da cobrança.
      • detail_id: identificador da cobrança.
      • detail_associated_id: Identificador da cobrança associada (em caso de cancelamento de bonificação).
      • detail_amount: valor da cobrança.
      • transaction_detail: detalhe da cobrança.
      • detail_type: tipo de detalhe.
      • detail_sub_type: subtipos de detalhes.
      • concept_type: tipo de conceito.

    • shipping_info: informação sobre envio.
      • shipping_id: identificador do envio.
      • receiver_nickname: cliente.
      • pack_id: número do pacote.
      • receiver_shipping_cost: custo do envio.

    • order: informação da venda.
      • order_id: identificador da venda.
      • date_created: data da order.
      • totalAmount: valor total da order.
      • paymentId: identificador de pagamento.
      • buyerNickname: cliente.

    • document_info: informação do documento.
      • document_id: ID do documento.

    Fulfillment

    Para Mercado Envios com logística Full, será apresentado o detalhe para conciliar as taxas e as bonificações por coleta e/ou armazenamento para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (Nota fiscal ou Nota de crédito). Além disso, oferece a informação do produto armazenado ou recoletado. A seguir verá os tipos de taxas existen para o relatório de Fulfillment:


    • Taxa por retirada de estoque.
    • Taxa por armazenamento prolongado.
    • Taxa por serviço de coleta.
    • Taxa por não cumprimento.
    • Taxa por armazenamento.

    Nota:
    O endpoint de FULL está disponível apenas nos sites MLA, MLB, MLM, MCO e MLC.

    Chamada para o site MLM:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/group/ML/full/details

    Chamada para os sites MLA, MLB, MCO e MLC

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

    Exemplo para os sites MLA, MLB, MCO e MLC:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-03-01/group/ML/full/details?document_type=BILL&limit=1

    Resposta:

    {
        "offset": 0,
        "limit": 100,
        "total": 634,
        "results": [{
          "charge_info": {
            "legal_document_number": "000AAA00000000",
            "legal_document_status": "PROCESSED",
            "legal_document_status_description": "Procesado",
            "creation_date_time": "2021-07-23T16:37:58",
            "detail_id": 11111111111,
            "detail_amount": 2.54,
            "transaction_detail": "Cargo por servicio de colecta Full",
            "charge_bonified_id": null,
            "detail_type": "CHARGE",
            "detail_sub_type": "CFCB",
            "concept_type": "FULFILLMENT",
            "payment_id": 222222222
          },
          "fulfillment_info": {
            "type": "INBOUND_COLLECT",
            "amount_per_unit": 2.54,
            "amount": 2.54,
            "sku": "3125404000009",
            "ean": "3125404000009",
            "item_id": "MLM788740252",
            "item_title": "VESTIDO CORTO AZUL MARINO BORDADO EN PECHO DEVENDI",
            "variation": "AZUL MARINO | EG",
            "quantity": 1,
            "volume_type": null,
            "inventory_id": "LLLGGKK12",
            "inbound_id": 555555,
            "volume_unit": "m3",
            "amount_per_volume_unit": 500,
            "volume": 0.00507,
            "volume_total": 0.00507
          },
          "document_info": {
            "document_id": 333333333
          }
        }],
        "errors": []
      }

    Campos de resposta Mercado Envios Fulfillment

    • charge_info: informação da cobrança.
      • legal_document_number: número do documento.
      • legal_document_status: estado de geração do documento. Possíveis valores: PROCESSING, PROCESSED
      • creation_date_time: data de criação da cobrança.
      • detail_id: identificador da cobrança.
      • detail_amount: valor da cobrança.
      • transaction_detail: detalhe da cobrança.
      • charge_bonified_id: identificador da cobrança que bonifica.
      • detail_type: tipo de detalhe.
      • detail_sub_type: subtipos de detalhe.
      • concept_type: tipo de conceito.
      • payment_id: identificador do pagamento.

    • fulfillment_info: Informação de fulfillment.
      • type: tipo de fulfillment. Possíveis valores: WITHDRAWAL | AGING | INBOUND_COLLECT | INBOUND_PENALTY | WAREHOUSING
      • amount_per_unit: valor por unidade.
      • amount: total.
      • sku: stock-keeping-unit.
      • item_id: número da publicação.
      • item_title: titulo da publicação.
      • variation: variável do produto.
      • quantity: unidades armazenadas ou recoletadas.
      • volume_type: tamanho da unidade.
      • inventory_id: código do inventário do Mercado Livre.
      • withdrawal_id: número de retirada –TYPE WITHDRAWAL custo por retirada de estoque –
      • shipment_type: forma de retirada. –TYPE WITHDRAWAL custo por retirada de estoque –
      • volume_unit: unidade de medida (m3). –TYPE WITHDRAWAL custo por retirada de estoque –
      • amount_per_volume_unit: valor por m3. –TYPE WITHDRAWAL custo por retirada de estoque –
      • volume: volume unitário (cm3) –TYPE WITHDRAWAL custo por retirada de estoque–
      • volume_total: volume total. –TYPE WITHDRAWAL custo por retirada de estoque –
      • months_range: antiguidade em meses. –TYPE AGING custo por armazenamento prolongado –
      • stock_details: detalhes de estoque. –TYPE AGING custo por armazenamento prolongado –
      • quantity: quantidade em estoque. –TYPE AGING custo por armazenamento prolongado–
      • inventory_status: estado do inventário. –TYPE AGING custo por armazenamento prolongado –
      • inbound_id: número de envio. –TYPE INBOUND_COLLECT custo por serviço de coleta –
      • volume_unit: unidade de medida (m3) –TYPE INBOUND_COLLECT custo por serviço de coleta –
      • amount_per_volume_unit: valor por m3. –TYPE INBOUND_COLLECT custo por serviço de coleta –
      • volume: volume unitário (cm3) –TYPE INBOUND_COLLECT custo por serviço de coleta –
      • volume_total: volume total. –TYPE INBOUND_COLLECT custo por serviço de coleta–
      • inbound_id: número de envio. –TYPE INBOUND_PENALTY custo por não cumprimento -
      • penalty_type: tipo de não cumprimento. –TYPE INBOUND_PENALTY custo por não cumprimento –
      • warehouse_id: identificador de warehouse.–TYPE WAREHOUSING custo por não cumprimento –
      • size: tamanho da unidade.–TYPE WAREHOUSING custo por armazenamento–
      • item_quantity: unidades armazenadas.–TYPE WAREHOUSING custo por armazenamento–

    • idocument_info: informação do documento.
      • document_id: ID do documento.

    Insurtech

    Permite obter o detalhe para conciliar os encargos e bonificações das garantias aplicadas sobre os produtos para um período em particular, o grupo de faturamento Mercado Livre e o tipo de documento (fatura ou Nota de Crédito). Esta informação é a mesma que se disponibiliza através da seção de relatório de faturamento para os usuários de Insurtech. As opções de filtro podem ser usadas da mesma forma que temos disponível para os detalhes do Mercado Livre e Mercado Pago.

    Nota:
    O endpoint de Insurtech está disponível apenas para os sites MLA, MLB e MLC

    Chamada:

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

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2022-10-01/group/ML/insurtech/details?document_type=BILL&limit=1

    Resposta:

    
      {
         "offset": 0,
         "limit": 150,
         "total": 1,
         "results": [
             {
                 "charge_info": {
                     "legal_document_number": "001112131415",
                     "legal_document_status": "PROCESSED",
                     "legal_document_status_description": "Procesado",
                     "creation_date_time": "2022-10-04T22:24:18",
                     "detail_id": 123456,
                     "detail_amount": 520.01,
                     "transaction_detail": "Cargo por seguro de garantía extendida",
                     "status": null,
                     "status_description": null,
                     "charge_bonified_id": null,
                     "detail_type": "CHARGE",
                     "detail_sub_type": "CEW",
                     "concept_type": "WARRANTY"
                 },
                 "warranty_info": {
                     "warranty_id": "11111111-43c2-44ea-8436-00000000",
                     "certificate_id": "MLA999999",
                     "warranty_product": "GAREX",
                     "buyer_nickname": "TEST",
                     "buyer_state_name": "Salta",
                     "order": {
                         "order_id": 102030405060,
                         "order_items": [
                             {
                                 "unit_price": 10791,
                                 "listing_type_id": "gold_special",
                                 "item": {
                                     "item_id": "MLA88888888",
                                     "title": "Auriculares Inalámbricos Jbl Tune 510bt Negro",
                                     "category_id": "MLA1234",
                                     "category_name": "Auriculares"
                                 }
                             }
                         ]
                     },
                     "quote_model": null,
                     "quote_brand": null,
                     "quote_description": ""
                 },
                 "prepaid_info": {
                     "operation_id": 55558888,
                     "movement_id": 123456789,
                     "doc_id": 11111111111,
                     "payment": {
                         "payment_id": 5555555555,
                         "date_created": "2022-10-04T22:23:40",
                         "transaction_amount": 736.98,
                         "money_release_date": "2023-03-03T22:23:41"
                     }
                 },
                 "document_info": {
                     "document_id": 3333333333
                 }
             }
      ]


    Campos de resposta Insurtech

    • charge_info: informação da cobrança.
    • <
      • legal_document_number: número do documento.
      • legal_document_status: estado de geração do documento. Valores possiveís: PROCESSING | PROCESSED.
      • legal_document_status_description: descrição internacionalizada do estado do documento legal_document_status.
      • creation_date_time: data de criação da cobrança.
      • detail_id: identificador da cobrança.
      • detail_amount: valor da cobrança.
      • transaction_detail: detalhe da cobrança.
      • status: estado da cobrança. Valores possíveis: BONUS_ON_CREDIT_NOTE | BONUS_PART_ON_CREDIT_NOTE | BONUS_ON_BILL | BONUS_PART_ON_BILL | BONUS_ON | BONUS_PART_ON.
      • status_description: descrição internacionalizada de status.
      • charge_bonified_id: identificador da cobrança bonificada.
      • detail_type: tipo de detalhe.
      • detail_sub_type: subtipos de detalhes.
      • concept_type: ipo de conceito.

    • wanrranty_info: informação da garantia.
      • wanrranty_id: identificador da garantia.
      • certificate_id: identificador do certificado.
      • waranty_product: tipo de garantia. Valores possíveís: CARDS, GAREX, RODA.
      • buyer_nickname: numero do comprador.
      • buyer_state_name: província do comprador.
      • order: informação da venda.
      • order_items: lista de items da venda.
      • unit_price: preço por unidade.
      • listing_type_id: tipo de publicação.
      • item: informação do item.
      • item_id: identificador do produto.
      • tittle: titulo do produto.
      • category_id: identificador da categoria.
      • category_name: nome da categoria.
      • quote_model: modelo do produto. Aplica a RODA.
      • quote_brand: marca do produto. Aplica a RODA.
      • quote_description: descrição adicional. Aplica a RODA.

    • prepaid_info: informação do pagamento.
      • operation_id: identificador da operação.
      • movement_id: identificador do pagamento.
      • doc_id: identificador do documento.

    • payment: informação do pagamento.
      • payment_id: identificador do pagamento.
      • date_created: data de papamento.
      • transaction_amount: valor do pago.
      • money_release_date: data de liberação do dinheiro.

    • document_info: informação do documento
      • document_id: ID do documento.


    Filtros opcionais

    • order_by: permite ordenar a busca.
      asc: ordena os resultados de forma ascendente (valor por default).
      desc: ordena os resultados de forma descendente.
      Ex: order_by=asc
    • sort_by: permite selecionar por que campo ordenar. Valores possíveis: DATE.
    • detail_typepermite buscar por tipos de detalhes.
      charge: traz somente cobranças.
      bonus: traz somente bonificações.
      Ex: detail_type=charge.
    • detail_sub_types: permite buscar por tipos de detalhes. Se pueden definir varios separados por comas. Se pueden definir varios separados por coma.
      Ex: detail_sub_types=CV, BV
    • detail_excluded_sub_types: permite excluir da busca os subtipos de detalhes indicados. Podem ser definidos vários separados por vírgula.
      Ex: not_subtypes=CXD, BXD
    • marketplace_type: permite buscar pelo market do detalhe.
      Ex: marketplace_type=SHIPPING
    • order_ids: permite buscar por um ou vários ID de order. Disponível para Mercado Libre.
      Ex: order_ids=2294412230
    • item_ids: permite buscar por um ou mais IDs de publicação.
      Ex: item_ids=724159812
    • document_ids: permite buscar por um ou mais IDs de fatura.
      Ex: document_ids=987046992
    • detail_ids: permite buscar por um ou mais IDs de detalhe.
      Ex: detail_ids=724159812
    • offset: permite buscar desde um número de resultado em diante. O valor mínimo permitido é 0 e o valor máximo permitido é 10000. Por padrão o valor é 0. Ex: offset=100 (devolve a partir do resultado nro 100).
    • limit: limita a quantidade de resultados. Por padrão o mínimo é 1 e o máximo valor permitido: 1000.
      Ex: limit=300 (devolve até 300 resultados).

    Relatórios de pagamentos

    Permite obter o detalhe das notas fiscais do vendedor abonadas em um determinado período.


    Chamada para MLM:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/$expiration_date/group/ML/payment/details

    Parâmetros de URL:

    • expiration_date: período em que deseja obter detalhe. (Formato: YYYY-mm-dd)

    Chamada para los sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

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

    Parâmetros de URL:

    • key: data do primeiro dia do mês. (Formato: YYYY-mm-dd)

    Parâmetros de consulta opcionais:

    • sort_by:
    • Valores possíveis: DATE,ID.
    • Valor padrão: DATE.
    • order_by: Permite ordenar as buscas.
    • Valores possíveis: ASC, DESC.
    • Valor padrão: ASC.
    • offset: permite buscar desde um número de resultado adiante. O valor mínimo permitido é 0 e o valor máximo permitido é 10000. Por padrão o valor é 0.
    • limit: limita a quantidade de resultado, O valor mínimo permitido é 1 e o valor máximo permitido é 1000. Por padrão o valor é 150.

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2023-08-01/group/ML/payment/details?limit=1

    Resposta:

    "payment_info": {
                   "payment_id": 111111111,
                   "credit_note_number": null,
                   "payment_date": "2023-12-06T19:43:32",
                   "payment_type": "collections_forced",
                   "payment_type_description": "Pagos con débito automático",
                   "payment_method": "account_money",
                   "payment_method_description": "Mercado Pago",
                   "payment_status": "approved",
                   "payment_status_description": "Aplicado",
                   "payment_amount": 30000.5,
                   "amount_in_this_period": 500.32,
                   "amount_in_other_period": 300.18,
                   "remaining_amount": 0,
                   "return_amount": 200
               }

    Campos de resposta

    • payment_id: número de pagamento.
    • credit_note_number: número de nota de crédito (se corresponde).
    • payment_date: data do pagamento.
    • payment_type_description: Descrição do tipo de pagamento.
    • payment_type: tipo de pagamento.
    • payment_method_description: descrição do método de pagamento.
    • payment_method: método de pagamento.
    • payment_status_description: descrição do estado do pagamento.
    • payment_status: estado do pagamento.
    • payment_amount: importe total do pagamento.
    • amount_in_this_period: importe aplicado neste período.
    • amount_in_other_period: importe aplicado em outro período.
    • remaining_amount: saldo a favor para próximas notas fiscais.
    • return_amount: saldo a favor que o vendedor possui. Só será exibido quando o valor for maior que zero.

    Detalhes do pagamento

    Acesse os detalhes das cobranças e recebimentos correspondentes a um pagamento específico.


    Parâmetros opcionais:
    sort_by: permite que você selecione por qual campo classificar. Valores possíveis: DATE
    order_by: permite que você classifique a pesquisa.
    asc: classifica os resultados em ordem crescente (valor padrão)
    desc: classifica os resultados em ordem decrescente. Ex: date_sort=asc
    offset: permite pesquisar a partir de um número de resultado Ex: offset=100 (retorna a partir do número de resultado 100).
    limit: limita o número de resultados. Por padrão o mínimo é 150. Valor máximo permitido: 1000. Ex: limite=300 (retorna até 300 resultados).


    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
    https://api.mercadolibre.com/billing/integration/payment/$PAYMENT_ID/charges

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
    https://api.mercadolibre.com/billing/integration/payment/9999999999/charges

    Resposta:

    "payment_details": [
                  {
    	"payment_info": {
                   "payment_id": "9999999999",
                   "payment_date": "aaaa-mm-ddThh:mm:ss",
                   "association_amount": 4500,
                   "payment_amount": 999999,99
               },
           "charge_info": {
                   "detail_id": 999999999,
                   "detail_description": "xxxxxxxxxxx",               
                   "detail_date": "aaaa-mm-ddThh:mm:ss"
               }
                    }
    ]

    Campos de resposta

    payment_id: identificador de pagamento.
    payment_date: data de pagamento.
    association_amount: parte do pagamento aplicada a cobranças ou impostos.
    payment_amount: valor do pagamento aplicado a taxas ou impostos.
    detail_id: Id da cobrança.
    detail_description: descrição das cobranças.
    detail_date: data da cobrança.


    Permite baixar as faturas legais do Mercado Livre e Mercado Pago em formato PDF para todos os sites.

    Notas:
    - O file_id se obtêm consumindo o endpoint de Documents.Em alguns casos, o endpoint de Documents pode devolver dois file_id. Nestes casos sempre se deverá utilizar o file_id correspondente ao PDF.

    - Se o endpoint de Document devolve um único file_id. Então esse é o dado para o download do documento legal.

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/legal_document/{file_id}

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/legal_document/1234_FE_MEPF00869625_pdf

    Resposta: download do arquivo em formato PDF.



    Download do relatório de conciliação

    Para fazer o download dos relatórios de conciliação do Mercado Livre, Mercado Envios Flex, Insurtech e Mercado Pago nos formatos XLSX e CSV você deve seguir um processo de gerar o relatório. Esse mesmo processo servirá para o relatório de Fulfillment e para o relatório de pagamentos, que admitem apenas o formato de download XLSX.
    O processo de gerar o relatório consiste en três passos: primeiro irá gerar o relatório de conciliação, em seguida, deverá consultar o estado de geração do relatório até que esteja gerado e por fim, poderá proceder com o download.



    1. Criação do relatório

    Através deste endpoint irá realizar a criação do relatório.

    Chamada para os sites MLM:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...}
      https://api.mercadolibre.com/billing/integration/periods/$EXPIRATION_DATE/reports

    Chamada para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR:

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d {...} https://api.mercadolibre.com/billing/integration/periods/key/$key/reports

    Exemplo para os sites MLA, MLB, MCO, MLC, MLU, MPE, MLV e MCR

    curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
      -d '{
         "group": "ML",
         "document_type": "BILL",
         "report_format": "CSV"
      }' 
      https://api.mercadolibre.com/billing/integration/periods/key/2021-08 -01/reports

    O valor do parâmetro group varia segundo o relatório que queira gerar:

    • ML para relatório de ML
    • MP para relatório de MP
    • FLEX para relatório de Flex
    • FULL para relatório de Fulfillment
    • INSURTECH para relatório de Insurtech
    • PAYMENT para relatório de pagamentos

    Resposta:

    {
      "fileId": "ML-report-BILL-2021-08-04-11119999-CSV-v2"
      }

    2. Estado de criação de relatório

    Permitirá obter o estado de criação de um relatório.Os estados podem ser:

    • PROCESSING: o relatório está sendo gerado.
    • READY: o relatório terminou de ser criado.
    • ERROR: a criação do relatório falhou, deverá ser consultado novamente.

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/{file_i d}/status

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2/status?document_type=BILL
    

    Resposta:

    {
    "status": "PROCESSING"
    }
    

    3. Download do relatório

    Com este endpoint poderá realizar o download do relatório. Este download poderá ser feito uma vez que o estado da criação seja Ready.


    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/{file_id}

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/reports/ML-repo rt-BILL-2021-08-04-11119999-CSV-v2?document_type=BILL
    

    Resumo de percepções

    Importante:
    Aplica apenas para Argentina.

    Permite obter o resumo de percepções que teve o vendedor para um período em particular, ou grupo de faturamento (Mercado Livre ou Mercado Pago).


    Chamada:

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

    Exemplo:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/periods/key/2021-08-01/perceptions/summary?group=MP

    Resposta:

    {
      "summary": [
             {
              "document_id": 123456789,
              "society": "ML",
              "legal_document_number": "0011A012345678",
              "user_fiscal_condition": "Responsable inscripto sin incumplimientos",
              "amount": 229314.11,
              "regimen_tax_type": "MLA_RE_IVA_N",
              "regimen_tax_type_description": "Percepción de IVA nuevos del régimen 
      especial",
              "taxable_amount": 22931410.96,
              "aliquot": 1.00,
                 "coefficient": 1.0000,
                 "perception_charge_number": 1123456789,
                 "tax_type": "CRGI",
                 "tax_type_description": 
      "Percepción Impuesto al Valor Agregado nuevos",
                 "bill_date": "2021-11-29",
                 "status": "APPLIED",
                 "status_description": "Aplicado"
            "tax_ids": [123345678,233455678]  
             }
      ],
      "errors": []
      }


    Campos de resposta

    • summary: informação do resumo.

      • document_id: identificador do documento.
      • society: sociedade. Valores possíveis ML | MP.
      • legal_document_number: número do documento.
      • user_fiscal_condition: condição fiscal do usuário.
      • amount: total a pagar dentro do período consultado.
      • regimen_tax_type: regime do tipo de imposto.
      • regimen_tax_type_description: descrição internacionalizada do regime do tipo de imposto.
      • taxable_amount: base tributária.
      • aliquot: valor da alíquota.
      • coefficient: coeficiente que impacta no cálculo do imposto.
      • perception_charge_number: número de cobrança de percepção.
      • tax_type: tipo de imposto.
      • tax_type_description: descrição internacionalizada do tipo de imposto.
      • bill_date: data de faturamento.
      • status: estado do resumo.
      • status_description: descrição internacionalizada do estado.
      • tax_ids: tipos de impostos.

    Detalhe de percepções

    Permite obter o detalhe de uma determinada percepção.Para percepções de Mercado Livre a partir do código de percepção e número de documento. Para percepções de Mercado Pago a partir do código de percepção, número de documento e identificador fiscal.

    Notas:
    - Mercado Pago: com o campo tax_type, document_id e tax_id se acessa o detalhe da percepção e do documento indicado nos filtros. Mercado Livre: com o campo tax_type e document_id se acessa o detalhe da percepção e do documento indicado nos filtros.
    - Ambos campos são obtidos do endpoint Resumo de percepções.
    - Os campos de resultados variam de acordo ao tax_type consultado: Régimen General, Régimen Especial, Régimen Tucumán.

    Mercado Livre

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details

    Exemplo (Regime geral):

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/ML/perceptions/details?document_id=333555777&tax_type=CIVA&offset=1&limit=2

    Resposta (Regime geral):

    {
       "offset": 0,
       "limit": 150,
       "total": 4241,
       "results": [
           {
               "detail_id": 12345678,
               "date_created": "2021-10-30",
               "taxable_amount": 2660.0,
               "aliquot": 3.0,
               "tax_amount": 79.8,
               "transaction_detail": "CV",
               "transaction_detail_description": "Cargo por venta",
               "charge_bonified_id": null,
               "amount": 2660.0,
               "gross_amount": 3218.6,
               "detail_type": "CHARGE",
               "detail_type_description": "Cargo"
           }],
       "errors": []
    }

    Mercado Pago

    Chamada:

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details

    Exemplo (Regime geral):

    curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/billing/integration/group/MP/perceptions/details?document_id=333555777&tax_type=CIVAMP&tax_id=12345&offset=1&limit=2

    Resposta (Regime geral):

    {
       "offset": 0,
       "limit": 150,
       "total": 5,
       "results": [
           {
               "detail_id": 1114444,
               "date_created": "2021-10-30",
               "taxable_amount": 154.93,
               "aliquot": 3.0,
               "tax_amount": 4.6479,
               "movement_id": "1234567",
               "reference_id": 1234567,
               "transaction_detail": "CCMP",
               "transaction_detail_description": "Cargo de MercadoPago",
               "amount": 154.93,
               "gross_amount": 187.46,
               "detail_type": "CHARGE",
               "detail_type_description": "Cargo"
           }],
       "errors": []
    }


    Campos de resposta

    Para Mercado Livre e para uma percepção de Regime geral retornam os seguintes dados:

    • detail_id: identificador do detalhe.
    • date_created: data de criação.
    • taxable_amount: base tributária.
    • aliquot: valor da alíquota.
    • tax_amount: importe do imposto.
    • transaction_detai: detalhe da transacção.
    • transaction_detail_description: descrição internacionalizada de detalhe da transacção.
    • charge_bonified_id: identificador da cobrança que bonifica no caso que o cargo seja um bônus.
    • amount: valor da percepção.
    • gross_amount: valor bruto da percepção.
    • gross_amount: detail_type: tipo de detalhe a que aplica a percepção.
    • gross_amount: detail_type_description: descrição do tipo de detalhe ao que aplica a percepção.


    Para Mercado livre e para uma percepção do Regime Especial se informam também os seguintes dados:

    • publish_number: número da publicação.
    • publish_title: título da publicação.
    • sale_date: data de venda.
    • sale_number: número de venda.
    • buyer_name: número do comprador.
    • buyer_state_name: estado do comprador.


    Para Mercado Livre e para uma percepção do Regime Tucumán se informa também o seguinte dado:

    • coefficient: coeficiente com que se calcula o importe do imposto.


    Para Mercado Pago se informam também os seguintes dados:

    • movement_id: número de movimento.
    • reference_id: operação relacionada.


    Código de resposta HTTP

    206 – Partial content: em alguns casos, os endpoints devolverão o código 206 – Partial content. Isso acontece quando a solicitação para alguns dos dados falha, servirá para informá-lo de que você receberá uma resposta incompleta (por exemplo, desconto de um detalhe).Os erros serão exibidos no campo de erros da resposta do endpoint.


    Estrutura do campo erros:

    "errors": [
           {
               "index": 3,
               "error_type": "PARTIAL_CONTENT",
               "messages": "An error occurred while retrieving the information. Try        
       again"    
           },
    ]


    Descrição dos campos:

    • index: posição do objeto que não pode ser recuperado.
    • date_created: tipo de erro.
    • taxable_amount: descrição de erro.
    • Nota:
      Aplica a todos endpoints, exceto o download de documento legal e do relatório de detalhe de conciliação de relatório em formato XLSX e CSV.



      Erros

      Os erros esperados que podem ocorrer na aplicação serão retornados tendo a seguinte estrutura:

      {
         "timestamp": string($date-time),
         "status": integer($int32),
         "type": string,
         "message": string,
      
        "path": string,
         "errors": {
      
      <*>: string }
      }
      • timestamp: informa a data e hora que foi gerado o erro.
      • status: informa o código de erro retornado.
      • type: código de erro de aplicação. Valores possíveis:
        • ABUSE_PREVENTION_ERROR
        • AUTHENTICATION_ERROR
        • AUTHORIZATION_ERROR
        • BAD_REQUEST_ERROR
        • VALIDATION_ERROR
        • TYPE_MISMATCH_ERROR
        • INTERNAL_ERROR
        • MISSING_PARAMETER_ERROR
        • METHOD_NOT_ALLOWED_ERROR
        • NOT_FOUND_ERROR

      • message: mostra uma mensagem de erro.
      • path: informa o endpoint que foi consumido.
      • errors: informa os erros ocorridos.

      • Exemplo:

        {
           "timestamp": "2021-07-07T21:21:09.72319Z",
           "status": 422,
           "type": "TYPE_MISMATCH_ERROR",
           "message": "Type mismatch error.",
           "path": "/periods",
           "errors": {
               "group": "Invalid format for value "
           }
        }