n8n-nodes-mpesa-mozambique

Community Nodes para integração com a API do M-Pesa Moçambique no n8n.

Visão Geral

Este pacote fornece nodes personalizados para n8n que permitem integração completa com a API do M-Pesa Moçambique, incluindo:

• Autenticação: Obtenção e validação de tokens de acesso
• Pagamentos C2B: Cliente para Negócio
• Pagamentos B2C: Negócio para Cliente
• Pagamentos B2B: Negócio para Negócio
• Consulta de Transações: Verificação de status
• Reversão: Estorno de transações
• Consulta de Clientes: Obtenção de nomes de clientes

Instalação

Via npm

npm install n8n-nodes-mpesa-mozambique

Via n8n Community Nodes

1. Acesse as configurações do n8n
2. Vá para "Community Nodes"
3. Instale o pacote: n8n-nodes-mpesa-mozambique

Configuração

Credenciais

Antes de usar os nodes, configure as credenciais do M-Pesa:

1. No n8n, vá para Credentials > Create New
2. Selecione M-Pesa API
3. Preencha os campos:
   • Environment: Sandbox ou Production
   • API Key: Sua chave API do portal M-Pesa
   • Public Key: Sua chave pública do portal M-Pesa
   • Service Provider Code: Seu código de provedor (shortcode)
   • Initiator Identifier: Identificador para operações autenticadas
   • Security Credential: Credencial de segurança

Obtenção das Credenciais

1. Acesse o Portal do Desenvolvedor M-Pesa
2. Crie uma conta ou faça login
3. Crie uma nova aplicação
4. Obtenha as credenciais necessárias

Nodes Disponíveis

1. M-Pesa Auth

Gerencia autenticação com a API M-Pesa.

Operações:

• Get Access Token: Obter token de acesso
• Validate Credentials: Validar credenciais

Exemplo de uso:

{
  "operation": "getToken",
  "tokenExpiry": 60
}

2. M-Pesa C2B Payment

Processa pagamentos de cliente para negócio.

Parâmetros obrigatórios:

• Transaction Reference
• Customer MSISDN (formato: 258XXXXXXXXX)
• Amount
• Third Party Reference

Exemplo de uso:

{
  "transactionReference": "BILL001",
  "customerMSISDN": "258843330333",
  "amount": "100.00",
  "thirdPartyReference": "REF123456"
}

3. M-Pesa B2C Payment

Processa pagamentos de negócio para cliente.

Parâmetros obrigatórios:

• Transaction Reference
• Customer MSISDN
• Amount
• Third Party Reference

Exemplo de uso:

{
  "transactionReference": "SALARY001",
  "customerMSISDN": "258843330333",
  "amount": "500.00",
  "thirdPartyReference": "SAL123456"
}

4. M-Pesa B2B Payment

Processa pagamentos entre negócios.

Parâmetros obrigatórios:

• Transaction Reference
• Amount
• Third Party Reference
• Primary Party Code (origem)
• Receiver Party Code (destino)

Exemplo de uso:

{
  "transactionReference": "TRANSFER001",
  "amount": "1000.00",
  "thirdPartyReference": "B2B123456",
  "primaryPartyCode": "171717",
  "receiverPartyCode": "979797"
}

5. M-Pesa Query Transaction

Consulta status de transações.

Parâmetros obrigatórios:

• Third Party Reference
• Query Reference (TransactionID, ThirdPartyReference ou ConversationID)

Exemplo de uso:

{
  "thirdPartyReference": "REF123456",
  "queryReference": "5C1400CVRO",
  "queryType": "transactionId"
}

6. M-Pesa Reversal

Reverte transações processadas.

Parâmetros obrigatórios:

• Transaction ID
• Third Party Reference
• Initiator Identifier
• Security Credential

Exemplo de uso:

{
  "transactionID": "49XCDF6",
  "thirdPartyReference": "REF123456",
  "reversalType": "full"
}

7. M-Pesa Query Customer

Consulta nome de clientes.

Parâmetros obrigatórios:

• Customer MSISDN
• Third Party Reference

Exemplo de uso:

{
  "customerMSISDN": "258843330333",
  "thirdPartyReference": "QRY123456"
}

Exemplos de Workflows

Workflow 1: Pagamento C2B com Verificação

{
  "nodes": [
    {
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook"
    },
    {
      "name": "M-Pesa C2B Payment",
      "type": "n8n-nodes-mpesa-mozambique.mPesaC2BPayment",
      "credentials": {
        "mPesaApi": "mpesa-credentials"
      }
    },
    {
      "name": "Query Transaction Status",
      "type": "n8n-nodes-mpesa-mozambique.mPesaQueryTransaction",
      "credentials": {
        "mPesaApi": "mpesa-credentials"
      }
    }
  ]
}

Workflow 2: Processamento de Salários B2C

{
  "nodes": [
    {
      "name": "Schedule Trigger",
      "type": "n8n-nodes-base.scheduleTrigger"
    },
    {
      "name": "Google Sheets",
      "type": "n8n-nodes-base.googleSheets"
    },
    {
      "name": "M-Pesa B2C Payment",
      "type": "n8n-nodes-mpesa-mozambique.mPesaB2CPayment",
      "credentials": {
        "mPesaApi": "mpesa-credentials"
      }
    }
  ]
}

Tratamento de Erros

Todos os nodes incluem tratamento de erros robusto:

Códigos de Resposta Comuns

• INS-0: Sucesso
• INS-2: Chave API inválida
• INS-5: Transação cancelada pelo cliente
• INS-6: Transação falhou
• INS-10: Transação duplicada
• INS-2006: Saldo insuficiente
• INS-2051: MSISDN inválido

Exemplo de Resposta de Erro

{
  "output_ResponseCode": "INS-2051",
  "output_ResponseDesc": "MSISDN invalid",
  "success": false,
  "error": "MSISDN inválido: 123456789. Deve estar no formato 258XXXXXXXXX"
}

Validações

MSISDN (Número de Telefone)

• Formato: 258XXXXXXXXX (12 dígitos)
• Exemplo válido: 258843330333

Valores Monetários

• Devem ser números positivos
• Formato: "10.00" ou "10"

Referências

• Máximo 20 caracteres
• Devem ser únicas por transação

Funcionalidades Avançadas

Auto-geração de Referências

Todos os nodes de pagamento e consulta suportam auto-geração de referências:

{
  "autoGenerateReference": true
}

Modo de Continuação em Erro

Configure continueOnFail para processar itens mesmo com erros:

{
  "continueOnFail": true
}

Ambientes

Sandbox (Desenvolvimento)

• URL: https://api.sandbox.vm.co.mz
• Use para testes e desenvolvimento

Production (Produção)

• URL: https://api.mpesa.vm.co.mz
• Use apenas para transações reais

Suporte

Para suporte e questões:

1. Consulte a documentação oficial do M-Pesa
2. Abra uma issue no repositório GitHub
3. Entre em contato com o suporte M-Pesa

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Contribuição

Contribuições são bem-vindas! Por favor:

1. Faça fork do repositório
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Abra um Pull Request

Changelog

v1.0.0

• Implementação inicial
• Suporte para todas as APIs M-Pesa principais
• Validações robustas
• Tratamento de erros completo
• Documentação completa