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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mercuri.cx/mercuri-docs-pt/caracteristicas/introducao-mercuri-api/mercuri-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.