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 utilizada no backend para autenticar as solicitações às APIs do Mercado Pago. Nunca deve ser compartilhada nem exposta no frontend.Mais informações sobre 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.