Casos de uso

O comando /mp-integrate é o ponto de entrada principal do plugin realizar uma integração por agentes de IA. Por meio de uma interação conversacional, é detectado automaticamente o produto e o país mencionados na sua mensagem e gerado o código de integração necessário, sem que você precise buscar documentação.

É possível criar fluxos de integrações para os sete países que o Mercado Pago opera (Argentina, Brasil, México, Chile, Colômbia, Peru e Uruguai) e para os principais produtos integráveis, como Checkout API, Checkout Pro, Código QR e Mercado Pago Point.

Para começar, execute o comando seguido de uma descrição do que você precisa integrar. Quanto mais contexto você incluir, mais específico será o código que você recebe. Veja alguns exemplos:

plain
/mp-integrate quero integrar o Checkout Pro no Brasil

plain
/mp-integrate preciso cobrar com QR Code no Brasil para meu app de varejo

plain
/mp-integrate como adiciono assinaturas mensais para meus usuários no México

Ao final da execução, o plugin entrega:

• Código de integração: implementação adaptada à linguagem ou framework que você indicou no comando. É possível pedir versões em outras linguagens na mesma sessão.
• Snippets de configuração: inicialização do SDK ou estrutura de chamadas à API para o produto selecionado.
• Exemplos de payloads: corpos de requisição com os parâmetros relevantes para o produto e o país.
• Orientação sobre parâmetros: indicação de quais campos são obrigatórios ou opcionais e exemplos de valores.

O /mp-integrate funciona em dois modos distintos de acordo com o estado de autenticação da sua sessão:

O comando /mp-webhooks permite configurar, simular e diagnosticar as notificações Webhooks do Mercado Pago dentro da sessão com agente de IA. Para usá-lo, é necessário que faça a autenticação através do /mp-connect.

É possível executar os seguintes subcomandos:

• /mp-webhooks configure: registra a URL HTTPS do seu endpoint e os tópicos de eventos que deseja receber, como order, topic_claims_integration_wh ou topic_chargebacks_wh.
• /mp-webhooks simulate: envia uma notificação de teste ao endpoint configurado para validar que a assinatura HMAC-SHA256 está sendo processada corretamente.
• /mp-webhooks status: verifica o status do registro e identifica problemas de URL ou tópico.
• /mp-webhooks diagnose: diagnostica falhas de assinatura e entrega das notificações.

O plugin cobre as duas etapas para preparar seu ambiente de testes: obter cartões de teste com /mp-test-cards e criar usuários com saldo com /mp-test-setup.

Comece executando /mp-test-cards para obter os cartões de teste disponíveis para o seu país. Este comando não requer autenticação.

plain
/mp-test-cards

No formulário de pagamento de teste, o nome do titular determina o resultado da simulação, por isso siga o padrão de APRO (aprovado), FUND (saldo insuficiente), CONT (pendente), SECU (CVV inválido) e EXPI (cartão expirado). No campo de DNI , use o número de documento 12345678.

Após configurar seus cartões de teste, execute o comando /mp-test-setup para criar um usuário vendedor e um comprador com credenciais de teste e saldo disponível. Este comando só funciona após autenticação OAuth (/mp-connect).

plain
/mp-test-setup

O resultado esperado é ter seus usuários disponíveis para iniciar os testes.

O comando /mp-review analisa o código da sua integração a partir de um checklist de qualidade e um padrão mínimo de segurança de 9 critérios do Mercado Pago para gerar um relatório de implementação com ações sugeridas para melhorar o seu desenvolvimento. Este comando requer uma sessão ativa, por isso execute o /mp-connect antes de usar.

O relatório de implementação é organizado em 5 seções:

1. Verificado: itens do checklist já implementados corretamente.
2. Necessita atenção: implementações parciais que precisam de ajustes.
3. Bloqueadores: falhas críticas que impedem de subir em produção.
4. Próximos passos: melhorias opcionais para elevar a qualidade da sua integração.
5. Pontuação e veredito: resultado final se aprovado, aprovado com ressalvas ou bloqueado.

O /mp-review também detecta Access TokensChave privada da aplicação, utilizada no backend para autenticar as chamadas à API do Mercado Pago. Você pode acessá-la em Suas integrações > Detalhes da aplicação > Credenciais. expostos no código-fonte e identifica chamadas diretas ao endpoint /v1/payments que podem se beneficiar de migração para a API de Orders.

O /mp-integrate migrate escaneia o projeto, identifica padrões de API de Intenção de Pagamento (legacy) de Mercado Pago Point e/ou Código QR e gera o arquivo migration-proposal.md com o detalhamento completo das mudanças e as instruções de migração para a API de Orders.

O arquivo de proposta de migração cobre os principais pontos de adequação à API de Orders, como:

• Campos de state para status;
• Tópicos de notificação de merchant_order e point_integration_wh para orders;
• Campo external_reference com hifens;
• Remoção do header X-Allow-Cancelable-Status;
• Inclusão de MP_WEBHOOK_SECRET no .env.example.

Após revisar e aplicar as mudanças propostas, execute /mp-review para validar que a integração migrada atende ao checklist de qualidade antes de subir em produção.