Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Enviar dados fiscais
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN'
-H "content-type:application/json"
http://api.mercadolibre.com/items/fiscal_informationJSON 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"
}Consultar dados fiscais cadastrados por SKU
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/items/fiscal_information/$SKUResposta:
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/detailResposta:
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
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"
}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
}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.