# 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**

```json
{
 '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)

{% tabs %}
{% tab title="WhatsApp" %}
{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}
{% endtab %}

{% tab title="SMS" %}
{% code overflow="wrap" lineNumbers="true" %}

```
{
    "phoneNumberId":"PNa088af00e524f523394578e7b6c6966b",
    "channel":"sms",
    "recipient":"+15078009250",
    "message":{
        "type":"template",
        "template":{
            "templateId":"54b3cf77-82fd-4547-88b4-90f26d8d0310",
            "parameters":[
                {
                    "otpCode":"112233",
                    "businessPhoneNumber":"+919986347648",
                    "firstName" : "JJ",
                    "lastName" : "Thomson",
                    "businessName" : "Mercuri",
                    "orderNumber" : "100ABCD45",
                    "orderTotal" : "1000",
                    
                    "expirationTime":"2025-07-24T09:55:28.613Z",
                    "couponCode":"ABCD35"
                }
            ]
        }
    },
    "saveToInbox":true
```

{% endcode %}
{% endtab %}
{% endtabs %}

**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.

```javascript
{ 
    "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 `[ ]`.

```javascript
{ 
    "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.

```javascript
{ 
    "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.

```javascript
{ 
    "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.

```javascript
{ 
    "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.