Documentação do Mercado Livre

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

Documentação do

Última atualização em 25/03/2024

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