Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 14/03/2023

Mensagens adicionais

Essa funcionalidade permite que o vendedor configure as mensagens conforme os cenários fiscais de suas vendas, de modo que ele declare ao Fisco os seus benefícios e/ou suas exceções fiscais como isenção de impostos e alíquotas diferenciadas ou até mesmo uma mensagem personalizada para cada região que a venda é feita.

Nota:

O limite máximo é de 30 mensagens adicionais cadastradas.

Configurar mensagem

O recurso para configurar uma mensagem permite que, além do texto, o vendedor configure alguns filtros para que a mensagem seja exibida.

Chamada:

curl --location --request POST 'https://api.mercadolibre.com/users/$USER_ID/invoices/fiscal_rules/v2/additional-messages' \
--header 'Content-Type: application/json' 'Authorization: Bearer $ACCESS_TOKEN'\
--data-raw '{
    "title": "$TITLE",
    "message": "$MESSAGE",
    "type": "custom_with_filter",
    "filters": [
        {
            "name": "$NAME",
            "operation": "$OPERATION",
            "value": "$VALUE"
        }
    ]

Exemplo:

curl --location --request POST 'https://api.mercadolibre.com/users/123456/invoices/fiscal_rules/v2/additional-messages' \
--header 'Content-Type: application/json' 'Authorization: Bearer $ACCESS_TOKEN'\
--data-raw '{
    "title": "Mensagem custom POST",
    "message": "Sua nota fiscal número: $ORIGIN_NUMERO_NF, possui o total de tributos IBPT no valor de R$: $IBPT_TOTAL_VALUE e o valor da taxa destinada para o fundo de combate à pobreza foi de R$: $ICMS_VFCPUFDEST",
    "type": "custom_with_filter",
    "filters": [
        {
            "name": "transactiontype",
            "operation": "eq",
            "value": "SALE"
        }
    ]

Resposta:

{
    "id": 20777,
    "issuer": 123456,
    "title": "Mensagem custom POST",
    "message": "Sua nota fiscal número: $ORIGIN_NUMERO_NF, possui o total de tributos IBPT no valor de R$: $IBPT_TOTAL_VALUE e o valor da taxa destinada para o fundo de combate à pobreza foi de R$: $ICMS_VFCPUFDEST",
    "type": "custom_with_filter",
    "filters": [
        {
            "name": "transactiontype",
            "operation": "eq",
            "value": "SALE"
        }
    ]
}

Campos da chamada

title: Título da mensagem (Limite máximo 255 caracteres, campo obrigatório);
message: Texto da mensagem (Limite máximo de 500 caracteres, incluindo as tag's, campo obrigatório);

- custom: Mensagem padrão, que será aplicada em todas as notas de vendas, (não é necessário preencher o campo filters);
- custom_with_filter: Modelo de mensagem, que possibilita realizar customizações diferentes, usando os filtros.

filters: Lista de filtros que devem estar, todos, consistente com a nota para que a mensagem seja aplicada. Cada filters é composto pelo seguintes campos:

- name: Nome "sistêmico" do filtro (Lista de todos os nomes dos filtros suportados está abaixo);
- operation: Tipos de operação que será realizada para verificar a consistência entre o dado desejado e o dado presente na nota fiscal (lista completa de operadores disponíveis abaixo);
- value: Valor esperado a ser utilizado para verificar a consistência com o valor presente na nota.

Tag

Também é possível personalizar a sua mensagem adicional incluindo valores de alguns campos presentes na própria nota, para tal deve adicionar no texto da mensagem a tag equivalente à informação desejada.

$EXTERNAL_ORDER_ID: Número externo da Ordem;
$IBPT_ALIQUOT: Alíquota ibpt; percentual de vtottrib em relação ao total;
$IBPT_ITEM_VALUE: Valor do ibpt do item (vibpt);
$IBPT_TOTAL_VALUE: Valor total de atributos (vtottrib);
$ICMS_PICMSUFDEST: Alíquota do ICMS do estado de destino (picmsufdest);
$ICMS_VBC: Valor da base de cálculo do icms (vbc);
$ICMS_VFCPUFDEST: Valor da taxa do fundo de combate à pobreza do estado de destino(vfcpufdest);
$ICMS_VICMSDIF: Valor do ICMS Diferido (vicmsdif);
$ICMS_VICMSUFDEST: Valor do ICMS Interestadual para a UF de destino (vicmsufdest);
$ICMS_VICMSUFREMET: Valor do ICMS Interestadual para a UF do remetente (vicmsufremet);
$ICMS_VICMSDESON: Valor do ICMS de desoneração (vicmsdeson);
$ORIGIN_DATA_DE_EMISSAO: Data de emissão da nota original;
$ORIGIN_NUMERO_NF: Numero da nota original;
$VIPIDEVOL: Total do IPI devolvido.

Exemplo:

Cadastro da mensagem: "Sua nota fiscal número: $ORIGIN_NUMERO_NF, possui o total de tributos IBPT no valor de R$: $IBPT_TOTAL_VALUE e o valor da taxa destinada para o fundo de combate à pobreza foi de R$: $ICMS_VFCPUFDEST ".
Mensagem adicionada na nota fiscal: "Sua nota fiscal número: 0001234567890, possui o total de tributos IBPT no valor de R$: 100,00 e o valor da taxa destinada para o fundo de combate à pobreza foi de R$: 2,00".

Exemplo de requisição:

{
      "id": "123",
      "issuer":"1234567890",
      "title": "default-message",
      "message": "Sua nota fiscal número: $ORIGIN_NUMERO_NF, possui o total de tributos IBPT no valor de R$: $IBPT_TOTAL_VALUE e o valor da taxa destinada para o fundo de combate à pobreza foi de R$: $ICMS_VFCPUFDEST",
      "type": "custom",
      "filters": 
   [
        {
          "name": "transactiontype",
          "operation": "eq",
          "value": "SALE",
        }
   ]
}

Filtros

O filtro é utilizado para realizar uma validação entre um dado desejado e o dado da nota.
O sistema possui os seguintes filtros:

transactiontype: Realiza validação entre o tipo da nota fiscal.

- Valores suportados: SALE, GIFT, INBOUND, DEVOLUTION, INBOUND_DEVOLUTION, INBOUND_RETURN, SYMBOLIC_INBOUND, SYMBOLIC_INBOUND_RETURN, SALE_RETURN, SALE_DEVOLUTION, PURCHASE, REMOVAL, SYMBOLIC_REMOVAL, INBOUND_SUPPLIER_RETURN, SHIPPING, SHIPPING_RETURN, ADJUSTMENT.

customertype: Realiza a validação do tipo do comprador, sendo TAXPAYER para compradores com CNPJ e NON_TAXPAYER compradores de pessoas físicas.

- Valores suportados: TAXPAYER, NON_TAXPAYER.

recipientstate: Realiza validação do estado do comprador.

- Valores suportados: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SE, SP, TO.

sellerregime: Realiza validação do modelo fiscal do vendedor.

- Valores suportados: SIMPLES, NORMAL.

sellerstate: Realiza validação do estado do vendedor.

- Valores suportados: AC, AL, AM, AP, BA, CE, DF, ES, GO, MA, MG, MS, MT, PA, PB, PE, PI, PR, RJ, RN, RO, RR, RS, SC, SE, SP, TO.

origindetail: Valida se a nota possui ao menos um produto com origem desejada.

- Valores suportados: Integer 0 até 8 (Apenas números).

Código	Origem
0	NAC
1	IMP
2	IMP	3	IMP	4	NAC	5	NAC	6	NAC	7	NAC	8	IMP

sku: Valida se a nota possui ao menos um produto com o SKU desejado.

- Valores suportados: Valores suportados: String livre.

nmc: Valida se a nota possui ao menos um produto com o NCM desejado.

- Valores suportados: String livre.

icmscst: Valida se a nota possui ao menos um produto com CST do ICMS desejado.