Programa Decola e Benefício de Reputação

Fluxo técnico

Notificações

Atualmente, os vendedores são notificados por e-mail, notificações e novidades no Mercado Livre. Utilize a api de novidades (/communications/notices) para que os vendedores sejam avisados via sua integração assim que forem convidados a participar. Em breve, habilitaremos um novo tópico de notificações.

Consultar reputação

Primeiro, recomendamos consultar a reputação do vendedor para garantir que ele se enquadra em algum programa. Se o vendedor possui reputação sem cor, vermelha, laranja ou amarela, utilize os seguintes endpoints.
Vendedores com reputação verde (id: 4_light_green ou 5_green) estão excluídos de participar.

Chamada:

curl -X GET -H 'Authorization: Bearer Token' https://api.mercadolivre.com/users/$USER_ID

Resposta:

{
  "id": 123456,
  ...
  "seller_reputation": {
      "level_id": null,
      "power_seller_status": null,
      "transactions": {
          ...
          },
          "total": 8
      }
  ...
}

Conhecer detalhes do Programa

O vendedor habilitado para participar de um programa pode obter informações detalhadas sobre a proteção, garantia, limites e dinheiro disponível no Mercado Ads.

Chamada:

curl -X GET -H 'Authorization: Bearer Token' 
https://api.mercadolibre.com/users/reputation/seller_recovery/status

Resposta:

{
    "seller_id": 1234567,
    "current_level": "newbie",
    "status": "AVAILABLE",
    "type": "NEWBIE_GRNTEE",
    "site_id": "MLA",
    "protection_limits": {
        "max_issues_allowed": 5,
        "protection_days_limit": 365
    },
    "guarantee_limits": {
        "guarantee_price": "$45.000",
        "advertising_amount": 45000
    },
    "guarantee_detail": {
        "guarantee_status": "OFF"
    },
    "is_renewal": false
}

Campos da resposta

seller_id: ID do vendedor.

status: Estado atual da proteção. Valores possíveis:

• AVAILABLE: proteção habilitada.
• ACTIVE: proteção ativada.
• UNAVAILABLE: proteção não disponível.
• FINISHED_BY_DATE: proteção finalizada por data.
• FINISHED_BY_ISSUES: proteção finalizada por problemas.
• FINISHED_BY_LEVEL: proteção finalizada por cor recuperada.
• FINISHED_BY_USER: proteção cancelada pelo vendedor.
• FINISHED: proteção finalizada por várias razões.

type: tipo de proteção: Programa de Decola (NEWBIE_GRNTEE) ou Benefício de Reputação (RECOVERY_GRNTEE).
site_id: país.

protection_limits: limites de proteção.

• max_issues_allowed: quantidade máxima de problemas permitidos.
• protection_days_limit: duração (dias) da proteção.

guarantee_limits: limites de garantia.

• guarantee_price: valor da garantia.
• advertising_amount: valor do bônus no Mercado Ads. Aplica-se somente ao programa Decola (NEWBIE_GRNTEE).

protection_detail: detalhes sobre a proteção atual.

• warning: alerta sobre a finalização da proteção.
• reactivated: indica se a proteção foi reativada.
• init_date: data de início da proteção.
• end_date: data de finalização da proteção.
• protection_days: dias de proteção válidos.
• start_level: cor do vendedor ao iniciar a proteção.
• end_level: cor do vendedor ao terminar a proteção.

sales_detail: detalhes das vendas durante a proteção.

• orders_qty: quantidade de ordens vendidas.
• total_issues: problemas do vendedor.
• claims_qty: quantidade de reclamações.
• cancel_qty: quantidade de cancelamentos.
• delay_qty: quantidade de envios atrasados.

guarantee_detail: detalhes sobre a garantia.

• guarantee_status: estado da garantia.
• guarantee_end_date: data de finalização da garantia.
• guarantee_buffer: duração do buffer para avaliar a garantia.
• guarantee_release_amount: valor da reserva de garantia.
• guarantee_charge_amount: valor da cobrança de garantia.

Ativar programa

Antes de ativar o programa, o vendedor deve depositar o valor informado anteriormente em sua conta do Mercado Pago ou reservar esse valor caso já tenha dinheiro na conta. Caso você não tenha o dinheiro disponível, você receberá um erro ao ativar o programa. Assim que o vendedor ativa o programa (opt-in), o período de proteção começa.

Chamada:

curl -X POST -H 'Authorization: Bearer Token' -H 'Content-Type: application/json'
https://api.mercadolibre.com/users/reputation/seller_recovery/activate

Resposta:

{
  "message": "ok"
}

Desativar Programa

Em qualquer momento, o vendedor poderá solicitar seu cancelamento e enviar o seguinte parâmetro obrigatório: cancellation_reason: motivo do cancelamento do programa (obrigatório para o Programa Startup, não é necessário para o Benefício de Reputação). Valores possíveis:

• business_not_ready: meu negócio não está pronto.
• program_not_useful: o programa não foi útil.
• need_money: preciso do dinheiro.
• goal_achieved: já atingi meu objetivo.
• without_reason: sem razão.

Exemplo:

curl -X PUT -H 'Authorization: Bearer Token' -H 'Content-Type: application/json'-D 
{
    "cancellation_reason" : "goal_achieved"
}
https://api.mercadolibre.com/users/reputation/seller_recovery/cancel_guarantee

Resposta:

{
   "message": "ok"
}

Baixar Domiciliação Legal

Integradores com usuários (vendedores) do México e da Colômbia são legalmente obrigados a mostrar aos vendedores desses países a opção de baixar a domiciliamento legal, podendo ser uma versão preliminar ou completa.

Parâmetro obrigatório

type: é o tipo de domiciliamento legal que você pode baixar. Valores possíveis:

• preview: só é possível chamar no modo de visualização se a proteção estiver no estado AVAILABLE e a garantia estiver no estado OFF.
• complete: uma vez que o vendedor tenha ativado a proteção do programa (seja Decola ou Benefício de Reputação), pode baixar o documento completo. Só é possível se a proteção estiver no estado ACTIVE ou FINISHED_BY_*.

Chamada:

curl -X GET -H 'Authorization: Bearer Token' 
https://api.mercadolibre.com/users/reputation/seller_recovery/legal-document?type=(PREVIEW|COMPLETE)

Resposta:

{
    "document": "JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVyc2lvbiAvMS41Ci9QYWdlcyAyIDAgUgovTmFtZXMgMyAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL01vZERhdGUgKEQ6MjAyNDA5MTkxN"
}

Por segurança, a resposta será um tipo de dados codificado em base64, que você pode decodificar usando um script python e obter o pdf.
Exemplo:

import base64

# The base64 string you provided
base64_data = ""  

# Add the proper padding if necessary
base64_data = base64_data.rstrip('=')  # Remove any previous padding, if there is any
padding_needed = len(base64_data) % 4
if padding_needed:
    base64_data += '=' * (4 - padding_needed)

# Decode the base64 string
pdf_data = base64.b64decode(base64_data)

# Save the binary data as a PDF file
with open('output.pdf', 'wb') as pdf_file:
    pdf_file.write(pdf_data)

print("PDF saved as output.pdf")

Para ativar esses programas em usuários de teste, envie-nos 2 usuários de teste com reputação nula (sem cor) via Suporte e ativaremos um programa em cada um deles.

Siguiente: Reputación de vendedores.