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 28/04/2025

Enviar dados fiscais

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'  
-H "content-type:application/json" 
http://api.mercadolibre.com/items/fiscal_information

JSON para configurar um produto

{
	"sku": "QW123",
	"title": "Iphone 7",
	"type": "single",
	"measurement_unit": "UN",
	"cost": 3000.00,
	"tax_information": {
		"ncm": "39263000",
		"origin_type": "reseller",
		"origin_detail": "2",
		"tax_rule_id": 651,  // ID do grupo de regras, apenas para Regime Normal, para Simples Nacional deixar em branco
		"csosn": "500",
		"cest": "0100500",
		"fci": "A3F1D0A2-16CB-4DF1-816E-F062A515035B",
		"ex_tipi": "01",
		"ean": "4242002824628",
        "med_anvisa_code": "ISENTO",
        "med_exemption_reason": "Exemption reason",
        "net_weight": 123.000,
        "gross_weight": 123.000	
	}
}

Descrição dos campos:

- sku: código do produto.

- title: descrição do produto.

- type: tipo do anúncio. Indica se o anúncio é um kit (bundle), ou seja se é composto por 2 ou mais itens ou se o anúncio é unitário (single).

- measurement_unit: unidade de medida (UN, litros, quilos).

- cost: custo do produto.

- tax_information: dados utilizados para cálculo de alíquotas necessários de acordo com a legislação brasileira, é composto por:

  • ncm: nomenclatura comum da mercosul.
  • origin_type: tipo de origem do produto (fabricação própria, nacional, importacao direta, importado adquirido no Brasil).
  • origin_detail: detalhe da origem do produto.
  • tax_rule_id: ID do grupo de regras tributárias cadastradas anteriormente (deve ser fornecido apenas para Regime Normal, para Simples Nacional deixar em branco).
  • csosn: código de situação da operação do simples nacional (deve ser fornecido apenas para Regime Simples Nacional, para Regime Normal deixar em branco).
  • cest: código especificador da substituição tributária.
  • fci: ficha de conteúdo importação.
  • ex_tipi: exceção tributária.
  • ean: european article number. Em português: número de artigo europeu. O código é formado por uma série de barras verticais escaneadas e uma sequência numérica.
  • med_anvisa_code: código da Anvisa se o código NCM for de medicamento (NCMs que começam com 3001, 3002, 3003, 3004, 3005 e 3006).
  • med_exemption_reason: motivo de isenção deve ser preenchido somente no caso em que o campo med_anvisa_code for preenchido com a palavra ISENTO.
  • net_weight: peso líquido (quilo).
  • gross_weight: peso bruto (quilo).

Considerações:

- O campo csosn deve ser enviado somente para sellers Regime Simples Nacional.

- O campo measurement_unit é opcional.

- O campo ex_tipi é opcional.

- O campo fci é opcional, mas pode ser preenchido somente quando o campo origin_detail for 3, 5 ou 8.

- O campo original_type pode receber os seguintes valores: manufacturer, reseller, imported.

- O campo med_anvisa_code pode ser preenchido somente com a palavra ISENTO ou com valor numérico de até 13 dígitos, e no caso de ser um valor numérico com menos de 13 dígitos o campo é automaticamente preenchido com zeros a esquerda até completar 13 dígitos.

- O campo med_exemption_reason pode ser preenchido com texto de até 255 carácteres.

- Os campos med_anvisa_code e med_exemption_reason possuem a seguinte relação:

  • Caso o campo med_anvisa_code seja preenchido com a palavra ISENTO então o campo med_exemption_reason é obrigatório.
  • Caso o campo med_anvisa_code seja um valor numérico então o campo med_exemption_reason não deve ser preenchido.

- O campo net_weight é opcional e pode ser preenchido com valor numérico de até 13 casas antes da vírgula e até 3 casas depois da vírgula.

- O campo gross_weight é opcional e pode ser preenchido com valor numérico de até 13 casas antes da vírgula e até 3 casas depois da vírgula.


Resposta:

Status code: 201 - Created


Body:

{
  "seller_id": "359450559",
  "sku": "QW123",
  "title": "Iphone 7",
  "type": "single",
   "measurement_unit": "UN",
  "tax_information": {
      "ncm": "30012090",
      "origin_type": "reseller",
      "origin_detail": "2",
      "csosn": "500",
      "cest": "0100500",
       "fci": "A3F1D0A2-16CB-4DF1-816E-F062A515035B",
       "ex_tipi": "01",
      "ean": "4242002824628",
      "tax_rule_id": 651,
      "empty": false,
      "med_anvisa_code": "ISENTO",
      "med_exemption_reason": "Exemption reason",
      "net_weight": 123.000,
      "gross_weight": 123.000
  },
  "cost": 3000,
  "measurement_unit": "UN",
  "register_type": "final"
}

Resposta:

Status code: 400 - Bad Request

Acontece quando algum dado obrigatório não foi preenchido ou quando algum dado está inválido.


Body:

{
    "message": "Many errors. 1 embedded errors, see errorlist property for details",
    "error_code": "json_validation_error",
    "fields": [
        {
            "field": "tax_information.ncm",
            "message": "tax_information.ncm is required.",
            "error_code": "10027"
        }
    ]
}

Atualizar os dados fiscais

Os dados enviados podem ser atualizados assim:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'  -H"content-type:
  application/json" http://api.mercadolibre.com/items/fiscal_information/$SKU_ID -d '
  {   
      "title": "Iphone X",
      "type": "single",					
      "measurement_unit": "UN",
      "cost":  5000.00,
      "tax_information": {						
          "ncm": "30012090",
          "origin_type": "reseller",
          "origin_detail": "2",
          "tax_rule_id": 651,
          "csosn": "500",
          "cest": "0100500",						
          "fci": "A3F1D0A2-16CB-4DF1-816E-F062A515035B",	
          "ex_tipi": "01",
          "ean": "4242002824628",
          "med_anvisa_code": "ISENTO",
          "med_exemption_reason": "Exemption reason",
          "net_weight": 123.000,
          "gross_weight": 123.000						
  },
  "cost": 5000.00,
  "measurement_unit": "UN",
  "register_type": "final"
  }

Resposta:

Status code: 200 - OK


Body:

{
      "seller_id": "359450559",
      "sku": "QW123",
      "title": "Iphone X",
      "type": "single",
      "measurement_unit": "UN",
      "tax_information": {						
         "ncm": "30012090",
          "origin_type": "reseller",
          "origin_detail": "2",
          "csosn": "500",
          "cest": "0100500",
          "fci": "A3F1D0A2-16CB-4DF1-816E-F062A515035B",
          "ex_tipi": "01",
          "ean": "4242002824628",
          "tax_rule_id": 651,
          "empty": false,
          "med_anvisa_code": "ISENTO",
          "med_exemption_reason": "Exemption reason",
          "net_weight": 123.000,
          "gross_weight": "123.000						
     },
      "cost": 5000,
      "measurement_unit": "UN",
      "register_type": "final"						
  } 

Resposta:

Status code: 400 - Bad Request

Acontece quando algum dado obrigatório não foi preenchido ou quando algum dado está inválido.


Body:

{
    "message": "Many errors. 1 embedded errors, see errorlist property for details",
    "error_code": "json_validation_error",
    "fields": [
        {
            "field": "tax_information.fci",
            "message": "A valid FCI is required in order to create this SKU",
            "error_code": "10294"
        }
    ]
}

Atualização parcial dos dados fiscais

Os dados enviados podem ser atualizados assim:

curl -X PATCH -H 'Authorization: Bearer $ACCESS_TOKEN'  -H"content-type:application/json" http://api.mercadolibre.com/items/fiscal_information/$SKU_ID -d '
{
        "tax_rule_id": 655,
}

Resposta:

Status code: 200 - OK


Body:

{
  "seller_id": "359450559",
  "sku": "QW123",
  "title": "Iphone X",
  "type": "single",
  "measurement_unit": "UN",
  "tax_information": {
      "ncm": "30012090",
      "origin_type": "reseller",
      "origin_detail": "2",
      "csosn": "500",
      "cest": "0100500",
      "fci": "A3F1D0A2-16CB-4DF1-816E-F062A515035B",
      "ex_tipi": "01",
      "ean": "4242002824628",
      "tax_rule_id": 4,
      "empty": false,
      "med_anvisa_code": "ISENTO",
      "med_exemption_reason": "Exemption reason",
      "net_weight": 123.000,
      "gross_weight": 123.000
  },
  "cost": 5000,
  "measurement_unit": "UN",
  "register_type": "final"
}

Resposta:

Status code: 400 - Bad Request

Acontece quando algum dado está inválido.


Body:

{
    "message": "The tax_rule_id field must be numeric",
    "error_code": "400 BAD_REQUEST"
}
Nota:
A atualização parcial está disponível apenas para os campos: cost, measurement_unit, fci, ex_tipi, tax_rule_id, med_anvisa_code, med_exemption_reason.

Consultar dados fiscais cadastrados por SKU

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/items/fiscal_information/$SKU

Resposta:

Status code: 404 - NOT FOUND

Acontece quando o sku informado não existe.


Body:

{
    "message": "Sku not found by sku: QW124 and caller.id: 359450559",
    "error_code": "404 NOT_FOUND"
}


Consultar dados fiscais cadastrados por item

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/items/$ITEM_ID/fiscal_information/detail

Resposta:

Status code: 404 - NOT FOUND

Acontece quando o item informado não existe.


Body:

{
    "message": "Item not found.",
    "error_code": "10095"
}

Configurar de kit 

Um kit é configurado com a finalidade do vendedor ter dois produtos no mesmo anúncio e precisa informar quanto é a porcentagem de cada produto deste kit que sairá na nota.

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H"content-type:application/json" http://api.mercadolibre.com/items/fiscal_information -d '
{
    "sku": "KIT-QW123-QW456",
    "title": "Kit Iphone 7 + Capinha",
    "type": "bundle",
    "register_type": "final",
    "bundle": [
        {
            "sku": "QW123",
            "quantity": 1,
            "percentage_share": 90
        },
        {
            "sku": "QW456",
            "quantity": 1,
            "percentage_share": 10
        }
    ]
}

Resposta:

Status code: 201 - Created


Body:

{
    "seller_id": "359450559",
    "sku": "KIT-QW123-QW456",
    "title": "Kit Iphone 7 + Capinha",
    "type": "bundle",
    "bundle": [
        {
            "sku": "QW123",
            "quantity": 1,
            "percentage_share": 90
        },
        {
            "sku": "QW456",
            "quantity": 1,
            "percentage_share": 10
        }
    ],
    "register_type": "final"
}

Resposta:

Status code: 400 - BAD REQUEST

Acontece quando um sku informado não existe ou quando tem um sku repetido no kit


Body:

{
    "message": "Many errors. 3 embedded errors, see errorlist property for details",
    "error_code": "json_validation_error",
    "fields": [
        {
            "field": "bundle",
            "message": "More than one element with sku QW124 found.",
            "error_code": "10084"
        },
        {
            "field": "bundle",
            "message": "Sku QW124 not found.",
            "error_code": "10086"
        },
        {
            "field": "bundle",
            "message": "Sku QW124 not found.",
            "error_code": "10086"
        }
    ]
}

Vinculando um sku (produto ou kit) a um anúncio

Notas:

Com o objetivo de aprimorar nossas funcionalidades, estamos implementando uma atualização no Faturador para suportar a emissão de notas fiscais no contexto de User Products (UP) em MLB. Esta mudança é projetada para preservar a compatibilidade com os contratos já em vigor, garantindo que não haja impactos significativos para os integradores.

Detalhes da Implementação

  • Cadastro de Dados Fiscais:
    • O procedimento padrão permite o cadastro de dados fiscais por item individualmente.
    • Com a introdução de User Products, essa funcionalidade será expandida. Agora, ao cadastrar dados fiscais em um único item, nosso sistema replicará automaticamente esses dados para todos os "itens irmãos" dentro do mesmo User Product.
    • Essa replicação segue uma lógica similar à já existente para alterações entre itens do mesmo grupo UP.

Considerações

  • Continuidade e Compatibilidade:
    • Não é necessário realizar alterações nos contratos atuais de integração.
    • O comportamento de replicação de dados dentro de um User Product é consistente com práticas já estabelecidas internamente.

Quando o item não possui variação é opcional passar o campo variation_id igual a vazio, neste caso o variation_id pode ser passado como null, isto é, o campo não precisa ser informando:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H"content-type:application/json" http://api.mercadolibre.com/items/fiscal_information/items
{
    "sku": "QW123",
    "item_id": "MLB1177001951",
    "variation_id": ""
}

Resposta:

Status code: 201 - Created


Body:

{
    "sku": "QW123",
    "item_id": "MLB1177001951",
    "variation_id": "",
    "create_date": "2019-02-11T09:33:16.506",
    "update_date": "2019-02-11T09:33:16.507",
    "status": "active"
}

Resposta:

Status code: 404 - NOT FOUND

Acontece quando o item informado não existe ou não pertence ao seller informado


Body:

{
    "message": "Item not found or does not belong to this seller.",
    "error_code": "10095"
}

Resposta:

Status code: 400 - BAD REQUEST

Acontece quando o sku informado não existe


Body:

{
    "message": "Sku not found by sku: QW124 and caller.id: 493344569",
    "error_code": "10086"
}
Notas:
- Vale ressaltar onde, uma vez que estes dados são cadastrados, mesmo se um PUT no atributo SELLER_SKU a nível item for executado, sendo com outro valor ou deixando em branco, este sku com os dados fiscais, permanecerá vinculado ao item.
- O campo variation_id, pode ser usado caso o SKU for a nível variação, se o item não tiver variação o campo pode ser enviado em branco.

Consultar se a publicação pode ser faturada

Este recurso permite identificar se uma determinada publicação tem todos os dados necessários para que nosso faturador emita a nota da venda. É possível fazer a buscar pela publicação ou por variações:


Busca por publicação:

Chamada:

curl --location --request GET 'https://api.mercadolibre.com/can_invoice/items/$ITEM_ID \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Exemplo:

curl --location --request GET 'https://api.mercadolibre.com/can_invoice/items/MLB1984512046 \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Resposta:

{
   "item_id": "MLB1984512046",
   "seller_id": "809726122",
   "variation_id": "",
   "status": true
}
Nota:
Caso busque por uma publicação com variações, ela só terá o status = true quando todas as variações estejam aptas. Caso contrário, é necessário identificar qual variação está sem os dados fiscais ou com os dados incorretos e alterar.

Busca por variação:

Chamada:

curl --location --request GET 'https://api.mercadolibre.com/can_invoice/items/$ITEM_IDvariations/$VARIATION_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Exemplo:

curl --location --request GET 'https://api.mercadolibre.com/can_invoice/items/MLB1398143045/variations/$VARIATION_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Resposta:

{
   "item_id": "MLB1984512046",
   "seller_id": "809726122",
   "variation_id": "94754627308",
   "status": true
}

O campo status indica se o item está apto para ser faturado.


Seguinte: Envío de inscrições estaduais.