# Mercuri API

### **Enviar Mensaje de WhatsApp/SMS – Mercuri API**

### Endpoint

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

* El endpoint de la API para enviar mensajes de WhatsApp.

***

### Headers

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

### 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 %}

**Descripciones de Campos:**

| Campo                       | Descripción                                                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phoneNumberId               | ID del número de WhatsApp Business / SMS (remitente). \<sub>*Sigue estos pasos para obtener tu phone number ID.*\</sub>                                     |
| channel                     | `"whatsapp"` o `"sms"`                                                                                                                                      |
| recipient                   | Número de teléfono del cliente (receptor)                                                                                                                   |
| message.type                | `"template"` – tipo de mensaje                                                                                                                              |
| message.template.templateId | ID de plantilla de WhatsApp/SMS aprobado. \<sub>*Sigue estos pasos para obtener tu template ID.*\</sub>                                                     |
| message.template.parameters | Arreglo de objetos con campos (OTP, nombres, información del pedido, etc.)                                                                                  |
| country                     | Código de país del cliente. Si el número en `recipient` **no incluye código de país**, Mercuri **usará por defecto este código de país** (ejemplo: `"US"`). |
| saveToInbox                 | `true` para guardar el mensaje en la bandeja de entrada de Mercuri                                                                                          |

### Response

**1. Error de Validación – Número de Destinatario Inválido (422)**

**Causa**: El formato del número del destinatario es inválido o falta el código de país.

{% code title="Status: 422" overflow="wrap" lineNumbers="true" %}

```javascript
 { 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_RECIPIENT_PHONE_NUMBER", 
            "message": "Invalid recipient phone number: 8971476855 (country: US)." 
        } 
    ] 
}

```

{% endcode %}

**2. Error de Validación – Formato Incorrecto del Payload (422)**

* **Causa**: `parameters` debe ser un **array**, pero se envió un objeto.
* **Solución**: Encierra `parameters` dentro de `[ ]`.

{% code title="Status: 422" overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_REQUEST_PAYLOAD", 
            "message": "message.template.parameters: Invalid input: expected array, received 
object" 
        } 
    ] 
} 
 
```

{% endcode %}

**Error de Validación – Falta Template ID**

* **Causa**: Falta `templateId` o no se envió como cadena de texto.
* **Solución**: Asegúrate de que `templateId` esté presente y entre comillas.

{% code title="Status ; 422" overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "VALIDATION_FAILED", 
    "errors": [ 
        { 
            "code": "INVALID_REQUEST_PAYLOAD", 
            "message": "message.template.templateId: Invalid input: expected string, received 
undefined" 
        } 
    ] 
} 
```

{% endcode %}

**3. Template No Encontrado (400)**

* **Causa**: El `templateId` proporcionado no existe.
* **Solución**: Revisa tu `templateId` en el dashboard.

{% code title="Status : 400" overflow="wrap" lineNumbers="true" %}

```javascript
{ 
    "messageId": null, 
    "status": "failed", 
    "errorCode": "API_TRIGGER_FAILED", 
    "errors": [ 
        { 
            "code": "WHATSAPP_TEMPLATE_NOT_FOUND", 
            "message": "WhatsApp template not found." 
        } 
    ] 
} 
```

{% endcode %}

4. **Respuesta Exitosa (200)**

* **Descripción**: El mensaje fue enviado con éxito.
* `messageId`: ID único asignado por WhatsApp.
* `status`: Será `"success"` si todo funciona correctamente.

{% code title="Status : 200" overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

***

#### **Descripción del Flujo**

1. Tu sistema prepara el payload con la información dinámica del cliente/pedido.
2. Envía una solicitud POST a la Mercuri API.
3. Mercuri procesa el payload y entrega el mensaje.
4. La API devuelve una respuesta a tu sistema para el seguimiento de éxito/error.