Recursos Cross
Confira os principais recursos das nossas APIs![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentação do
Você pode usar esta documentação para as seguintes unidades de negócio:
Envio de nota fiscal de venda
Assinatura de notificações
Lembre-se que o desenvolvimento deve estar assinado às notificações de “shipments”; deverá fazê-lo desde MyApps. Revise nossa documentação para conhecer como trabalhar com notificações. Começará a receber notificações depois de gerada uma venda na plataforma e confirmado o pagamento. Exemplo de notificação
{
"resource": "/shipments/139876",
"user_id": 1234,
"topic": "shipments",
"received": "2011-10-19T16:38:34.425Z",
"sent" : "2011-10-19T16:40:34.425Z",
}
Consultar status do envio
Conhecendo o ID do envio, poderá realizar o GET para o recurso de shipments para obter toda a informação dele:
curl -H "x-format-new:true" -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID
Confirmando que o envio tenha status "ready_to_ship" e substatus "invoice_pending", você deverá enviar o XML da nota.
Billing Info
No recurso/shipments são derivados diferentes recursos que oferecem a informação necessária para que o vendedor determine a logística. O recurso billing_info permite obter a informação fiscal dos diferentes atores que operam no envio do produto.
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/billing_info
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/26474580996/billing_info
{
"receiver": {
"id": 154808171,
"document": {
"id": "CPF",
"value": "02972404475"
},
"additional_documents": []
},
"senders": [{
"id": 168777350,
"document": {
"id": "CNPJ",
"value": "21611372000396"
},
"additional_documents": [{
"id": "IE",
"value": "421038162111"
}]
}],
"carrier": {
"document": {
"id": "CNPJ",
"value": "20121850000317"
},
"additional_documents": []
}
}
Considerações:
- Dentro de cada “additional_documents” pode vir uma lista de outros documentos que podem ser requeridos.
- Caso seja necessário obter a informação dos produtos que são enviados, se utilizarão os recursos shipments/{id}/items e /items/{id}.
- Em cumprimento a Nota técnica NT2020.006, o CNPJ que deve ser utilizado como sendo o do intermediador da transação (Mercado Livre) pode ser obtido através do Mercado Livre, no rodapé da página.
Enviar nota fiscal eletrônica
Com todas informações disponíveis, assim que o status e substatus estiverem confirmados, você deverá enviar o XML da nota assim:
curl -s -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/xml' -d '<?xml version="1.0" encoding="UTF-8"?>
<nfeProc versao="4.00" xmlns="http://www.portalfiscal.inf.br/nfe">
...
</nfeProc>' "https://api.mercadolibre.com/shipments/{id}/invoice_data/?siteId=$SITE_ID"
Consultar a nota fiscal enviada
Você pode consultar o XML enviado:
curl -H GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID/invoice_data?siteId=MLB
Atualizar nota fiscal eletrônica
Agora, se quiser alterar alguma informação dos dados fiscais já enviados, um PUT deve ser enviado assim:
curl -s -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/xml' -d '<?xml version="1.0" encoding="UTF-8"?>
<nfeProc versao="4.00" xmlns="http://www.portalfiscal.inf.br/nfe">
...
</nfeProc>' "https://api.mercadolibre.com/shipment_invoice/{invoice_id}/?siteId=$SITE_ID"
Referências de código de erro
Error_code | Mensagem de erro | Descrição | Possível solução |
---|---|---|---|
shipment_invoice_already_saved | shipment invoice already saved | Já existe uma nota fiscal salva para o envio informado. | Para que a nota fiscal possa ser salva, o envio necessita estar no substatus de invoice_pending, para verificar se o envio se encontra nesse substatus, consulte /shipments/{shipment_id}, ou consulte se já não foi salva a nota fiscal para o envio informado através do endpoint /shipments/{id}/invoice_data. |
duplicated_fiscal_key | fiscal key has already been used | Já existe uma nota fiscal salva com a chave fiscal informada. | O número de chave fiscal da nota precisa ser único. |
wrong_invoice_date | NFe date must be greater than the sale date. | A data informada na nota fiscal é inválida. | Verifique a data informada. |
wrong_sender_zipcode | NFe sender zipcode must be the same as the sale zipcode. | O CEP do vendedor informado na nota fiscal é inválido ou nulo. | Verifique o CEP do vendedor informado. |
wrong_receiver_zipcode | NFe receiver zipcode must be the same as the sale zipcode. | O CEP do comprador informado na nota fiscal é inválido ou nulo. | Verifique o CEP do comprador informado. |
wrong_receiver_cnpj | NFe receiver CNPJ must be the same as the sale CNPJ. | O CNPJ do comprador informado na nota fiscal é inválido ou nulo. | Verifique o CNPJ do comprador informado. |
wrong_receiver_cpf | NFe receiver CPF must be the same as the sale CPF. | O CPF do comprador informado na nota fiscal é inválido ou nulo. | Verifique o CPF do comprador informado. |
wrong_receiver_state_tax | NFe receiver state tax must be the same as the sale state tax. | A Inscrição Estadual do comprador informada na nota fiscal é inválida ou nula. | Verifique a Inscrição Estadual do comprador informada. |
invalid_user | You are not allowed to perform this operation on the resource Shipment $shipmentId | Você não tem permissão para realizar operações no envio informado. | Verifique o número de envio informado e se você tem permissões sobre ele. |
seller_not_allowed_to_import_nfe | Seller not allowed to import nfe $callerId | Você não tem permissão para realizar a importação de NF-e | Verifique se você tem permissão para importar notas fiscais ou use nosso emissor de notas fiscais. |
shipment_invoice_should_contain_company_state_tax_id | shipment invoice should contain company_state_tax_id | A Inscrição Estadual do comprador não foi informada na nota fiscal. | Verifique a Inscrição Estadual do comprador informada. |
invalid_state_tax_id | Invalid state tax id | A Inscrição Estadual do comprador informada na nota fiscal é inválida ou nula. | Verifique a Inscrição Estadual do comprador informada. |
invalid_operation_for_site_id | Invalid operation for site id: $siteId | Operação inválida para a região informada. | Só é permitida a execução de operações para o site MLB. |
error_parse_invoice_data | $json | Erro ao converter dados da nota fiscal para json. | Verifique se a nota fiscal foi informada de forma correta. |
invalid_parameter | Body cannot contain id | A nota fiscal informada não contém o número de identificação. | Verifique o número de identificação na nota fiscal informada. |
invalid_caller_id | Invalid caller id | Caller Id informado é inválido ou não foi informado. | Verifique se o Caller Id está sendo informado ao realizar o request. |
sender_ie_not_found | Seller CNPJ not registered on SEFAZ as tax payer | O CNPJ do vendedor não está cadastrado na Sefaz como contribuinte ou está bloqueado. | Não é possível informar a NF-e porque seus dados cadastrados no Mercado Livre são diferentes dos que você tem cadastrados na SEFAZ. Revise o CNPJ, a Inscrição Estadual (IE) e o estado (UF). Corrija as informações do seu cadastro no Mercado Livre e tente novamente. |
invalid_sender_ie_for_state | Invalid seller state registry for registered state | A inscrição estadual do vendedor é inválida para o estado cadastrado. | Não é possível informar a NF-e porque seu dado de IE cadastrado no Mercado Livre está incorreto para o estado cadastrado no endereço. Revise o CNPJ, a Inscrição Estadual (IE) e o estado (UF). Corrija as informações do seu cadastro no Mercado Livre e tente novamente. |
invalid_sender_ie | Issue an NF-e with the correct State Registration (IE) because the information provided, %s, is different from the one on Mercado Livre: %s. The state (UF) of the NF-e must also be the same as the one used in your registration. | A inscrição estadual do vendedor é diferente da cadastrada junto à Sefaz. | Não é possível informar a NF-e porque seus dados cadastrados no Mercado Livre são diferentes dos que você tem cadastrados na SEFAZ. Revise a Inscrição Estadual (IE). Corrija as informações do seu cadastro no Mercado Livre e tente novamente. |
invalid_sender_cnpj | Issue an NF-e with the correct CNPJ because the one entered, %s, is different from what is on Mercado Livre: %s. | O CNPJ do vendedor é diferente do cadastrado junto à Sefaz. | Não é possível informar a NF-e porque seus dados cadastrados no Mercado Livre são diferentes dos que você tem cadastrados na SEFAZ. Revise o CNPJ. Corrija as informações do seu cadastro no Mercado Livre, e tente novamente. |
different_state_nfe_shipment_origin | Emit state from XML is different to shipment origin address state | A UF da nota é diferente do estado de origem do envio. | Não é possível informar a NF-e porque a UF do XML da nota é diferente da UF onde o envio foi gerado. Corrija as informações do XML e tente novamente. |
nfe_order_value_divergence | The NFe value does not equal the purchase value. | O valor da nota fiscal diverge do valor total dos itens do pedido. | O valor da NF-e é diferente do valor da venda. Confira os valores preenchidos como preço, descontos e frete e emita uma nova nota com o valor corrigido. |
wrong_invoice_type | Invoices with ISSQN are not allowed. | Nota fiscal de serviço ou contém valor de ISSQN. | Emita uma NF-e de venda para seus produtos. Notas fiscais de serviços não são aceitas no Mercado Livre. |
unexpected_error_post_biller | The file has invalid XML. Check the XML and try again. | XML inválido ou com campos incorretos. | Envie o XML no formato aprovado pelo emissor de nota fiscal e validado pelo governo. |
shipment_already_being_processed | We're already processing a request for shipment_id:%s. | Foi enviada mais de uma requisição ao mesmo tempo. | Aguarde o processamento da primeira requisição. |
batch_nfe_not_supported | NFe cannot have batch layout. | Não é possível informar nota fiscal com formato em lote. | Envie o XML de uma nota fiscal individual. |
nfe_layout_not_supported | NFe layout not supported. | Não é possível informar nota fiscal com esse formato. | Enviar XML de uma nota fiscal no formato aprovado pelo emissor fiscal e validado pelo governo do seu estado, seguindo a estrutura correta do XML com as tags: , , |
nf_already_generated | A NF-e dessa venda já foi gerada pelo Faturador e por isso não é possível importar outra nota. | Já existe uma NFe emitida pelo faturador. | Verifique o status da NFe. Caso a NFe esteja anulada ou inutilizada, emitir novamente pelo faturador. |
internal_error | An internal error has occurred | Houve um erro interno | Aguarde e tente novamente. |
invalid_shipment | Shipment status is wrong | O shipment se encontra em um status em que a importação da NF-e não é aceita | Verifique o status do shipment antes de enviar a NF-e. |
invalid_nfe | NFe receiver must be to valid | Os dados do destinatário são inválidos ou não está corretamente preenchidos | Verifique os dados do destinário na NFe. Caso necessário, envie uma nova NFe para a Sefaz para carregar na API. |
malformed_XML | Malformed XML | O arquivo XML enviado possui algum erro de sintax ou estrutura | Revise e corrija o XML para carregar novamente na API. Utilize um validador de NFe da Sefaz caso necessário. |