> For the complete documentation index, see [llms.txt](https://docs.smsfire.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smsfire.com.br/apis-v2/sms/consulta-status.md).

# Consulta Status

Veja detalhes de como consultar o status de uma ou mais mensagens.

A partir deste serviço você poderá consultar o status individual ou em lote das mensagens enviadas via API. Recomendável para situações onde o recebimento por [*webhook* ](/apis-v2/sms.md#webhooks)tenha falhado por algum motivo.

Para que evite-se requisições desnecessárias recomendamos o registro de *endpoint* como *webhook*. Dessa forma, logo que recebermos atualizações dos status das mensagens dos nossos agregadores e operadoras, elas serão repassadas ao seu *endpoint* imediatamente.

{% hint style="danger" %}
Fique atento quanto ao [rate-limit](/apis-v2/rate-limiter.md) de requisições para o correto funcionamento da API.
{% endhint %}

## Consulta individual

<mark style="color:blue;">`GET`</mark> `https://api-v2.smsfire.com.br/sms/status/:id`

Informe o `id` da mensagem que é dado no *callback* das requisições ou então `customId` que é informado na requisição de envio da mensagem.

**Atenção:** Campos com \* (asterisco) são obrigatórios

#### Path Parameters

| Name                                 | Type   | Description                                          |
| ------------------------------------ | ------ | ---------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | string | `id` ou `customId` da mensagem. (Max. 40 caracteres) |

#### Headers

| Name                                            | Type   | Description    |
| ----------------------------------------------- | ------ | -------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Basic \<Token> |

{% tabs %}
{% tab title="200 Objeto JSON" %}

```scheme
{
  "id": 000001,
  "customId": "fire0001",
  "campaignId": 001,
  "cost": 0.12,
  "parts": 1,
  "country": "55",
  "ip": "200.200.20.200",
  "phone": "5511944556677",
  "carrier": "Claro",
  "statusCode": 2,
  "statusName": "DELIVERED",
  "statusDate": "2021-07-19T20:58:57-0300",
  "sentDate": "2021-07-19T20:58:35-0300"
}
```

{% endtab %}
{% endtabs %}

### Exemplo de requisição

* Consulta por `id`

`GET - https://api-v2.smsfire.com.br/sms/status/000001`

* Consulta por `customId`

`GET - https://api-v2.smsfire.com.br/sms/status/fire0001`

## Consulta múltipla

<mark style="color:green;">`POST`</mark> `https://api-v2.smsfire.com.br/sms/status/search`

Realize consulta de múltiplas mensagens ao informar seus respectivos `id` e/ou `customId`

**Atenção:** Campos com \* (asterisco) são obrigatórios

#### Headers

| Name                                            | Type   | Description      |
| ----------------------------------------------- | ------ | ---------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Basic \<Token>   |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json |

#### Request Body

| Name      | Type  | Description              |
| --------- | ----- | ------------------------ |
| customIds | array | `customId` das mensagens |
| ids       | array | `Id` das mensagens       |

{% tabs %}
{% tab title="200 Array do objeto JSON" %}

```scheme
[
  {
    "id": 00001,
    "customId": "fire00001",
    "campaignId": 001,
    "cost": 0.12,
    "parts": 1,
    "country": "55",
    "ip": "127.1.1.0",
    "phone": "5511944556677",
    "carrier": "Oi",
    "statusCode": 2,
    "statusName": "DELIVERED",
    "statusDate": "2021-07-20T10:00:48-0300",
    "sentDate": "2021-07-20T10:00:00-0300"
  },
  {
    "id": 00002,
    "customId": "fire00002",
    "campaignId": 001,
    "cost": 0.12,
    "parts": 1,
    "country": "55",
    "ip": "127.1.1.0",
    "phone": "5511955667722",
    "carrier": "Tim",
    "statusCode": 2,
    "statusName": "DELIVERED",
    "statusDate": "2021-07-20T10:00:48-0300",
    "sentDate": "2021-07-20T10:00:00-0300"
  },
]
```

{% endtab %}
{% endtabs %}

### Exemplo de requisição

```c
curl --request POST \
  --url http://api-v2.smsfire.com.br/sms/status/search \
  --header 'Authorization: Basic <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": ["0001"],	"customIds":["fire0002"] }'
```

Os parâmetros `ids` e `customIds` são independentes, ou seja, você poderá consultar mensagens informando valores distintos em cada um deles ou em apenas um deles.

{% hint style="info" %}
A consulta retornará no máximo 200 itens.
{% endhint %}

## Campos JSON do status

Detalhamento dos tipos de cada um dos campos dados no response das consultas [individuais ](/apis-v2/sms/consulta-status.md#consulta-individual)ou [múltiplas](/apis-v2/sms/consulta-status.md#consulta-multipla)

{% hint style="info" %}
A API retornará o código **`HTTP 204 No Content`** quando não encontrar a mensagem pesquisada e o corpo da resposta será vazio.
{% endhint %}

| Campo        | Tipo             | Descrição                                         |
| ------------ | ---------------- | ------------------------------------------------- |
| `id`         | *int*            | Id da mensagem                                    |
| `customId`   | *string \| null* | Id personalizado fornecido pelo cliente           |
| `campaignId` | *int*            | Id da campanha vinculada a mensagem               |
| `cost`       | *float*          | Tarifa cobrada por cada parte da mensagem         |
| `parts`      | *int*            | Número de partes da mensagem                      |
| `country`    | *string*         | Prefixo do país do destinatário                   |
| `ip`         | *string*         | Ip de onde a mensagem foi enviada                 |
| `phone`      | *string*         | Telefone do destinatário em formato internacional |
| `carrier`    | *string \| null* | Nome da operadora                                 |
| `statusCode` | *int*            | Código do status atual da mensagem                |
| `statusName` | *string*         | Nome do status atual da mensagem                  |
| `statusDate` | *string*         | Data da última atualização do status (ISO8601)    |
| `sentDate`   | *string*         | Data do envio da mensagem (ISO8601)               |

> A formatação do JSON apresentada neste serviço é exatamente a mesma da que enviaremos via [Webhooks ](/apis-v2/sms.md#webhooks)em *Callback* ou *DLR* quando configurados.
