Mercuri API

Enviar Mensagem WhatsApp/SMS – Mercuri API

Endpoint

POST https://api.mercuri.cx/v1/send_message

• Endpoint da API para envio de mensagens WhatsApp.

---

Headers

{
 'Content-Type': 'application/json',
 'Authorization': `Bearer ${bearerToken}`
}

• Content-Type → Formato JSON para o corpo da requisição.

• Authorization → Use seu token de API Mercuri.

Request (Payload)

WhatsApp

{
   "phoneNumberId":"635894262943892",
    "channel":"whatsapp",
    "recipient":"[phone]",
    "message":{
        "type":"template",
        "template":{
            // "templateId":"1777667316490397",
            "templateId":"2020796801660936",
            "parameters":[
                {
                    "otpCode":"112233",
                    "businessPhoneNumber":"[phone]"
                    "firstName" : "JJ",
                    "lastName" : "Thomson",
                    "businessName" : "Mercuri",
                    "orderNumber" : "100ABCD45",
                    "orderTotal" : "1000",
                    "expirationTime":"2025-07-24T09:55:28.613Z",
                    "couponCode":"ABCD35"
                }
            ]
        }
    },
    "country":"US",
    "saveToInbox":true
}
}

SMS

Descrição dos Campos:

Campo	Descrição
phoneNumberId	ID do número WhatsApp Business/SMS (remetente). Siga estes passos para obter seu ID de número de telefone.
channel	"whatsapp" ou "sms"
recipient	Número de telefone do cliente (destinatário)
message.type	"template" – tipo de mensagem
message.template.templateId	ID do template aprovado para WhatsApp/SMS. Siga estes passos para obter seu ID de template.
message.template.parameters	Array de objetos com campos (OTP, nomes, informações do pedido, etc.)
country	Código do país do cliente. Se o número de telefone do recipient não incluir código do país, Mercuri usará este código padrão (ex.: "US").
saveToInbox	true para salvar a mensagem na inbox do Mercuri

---

Resposta

1. Falha na Validação – Número de Destinatário Inválido (422)

Causa: O formato do número do destinatário é inválido ou falta código do país.

{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_RECIPIENT_PHONE_NUMBER", 
            "message": "Número de telefone do destinatário inválido: 8971476855 (país: US)." 
        } 
    ] 
}

2. Falha na Validação – Formato de Payload Incorreto (422)

• Causa: parameters deve ser um array, mas um objeto foi enviado.

• Solução: Coloque os parâmetros dentro de [ ].

{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_REQUEST_PAYLOAD", 
            "message": "message.template.parameters: Entrada inválida: esperado array, recebido objeto" 
        } 
    ] 
} 

Falha na Validação – Template ID Ausente

• Causa: templateId está ausente ou não foi passado como string.

• Solução: Certifique-se de fornecer templateId e colocá-lo entre aspas.

{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_REQUEST_PAYLOAD", 
            "message": "message.template.templateId: Entrada inválida: esperado string, recebido undefined" 
        } 
    ] 
} 

3. Template Não Encontrado (400)

• Causa: O templateId fornecido não existe.

• Solução: Verifique seu templateId no dashboard.

{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "API_TRIGGER_FAILED", 
    "errors": [ 
        { 
            "code": "WHATSAPP_TEMPLATE_NOT_FOUND", 
            "message": "Template do WhatsApp não encontrado." 
        } 
    ] 
} 

4. Resposta de Sucesso (200)

• Descrição: Mensagem enviada com sucesso.

• messageId: ID único atribuído pelo WhatsApp.

• status: Será "success" se tudo funcionar.

{ 
    "messageId": "wamid.HBgMOTE5OTAxNzU4NzM4FQIAERgSRkRCNjYzMTY1QkMxNzcyMjM4AA==", 
    "status": "success", 
    "errorCode": null, 
    "errors": null 
} 

---

Visão Geral do Fluxo

1. Seu sistema prepara o payload com informações dinâmicas do cliente/pedido.

2. Envia uma requisição POST para a Mercuri API.

3. Mercuri processa o payload e entrega a mensagem.

4. A API retorna uma resposta ao seu sistema para rastreamento de sucesso/erro.