> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar um SMS

> Envie uma mensagem SMS global e acompanhe seu status final de entrega.

## O que é

A API de SMS envia uma mensagem de texto para um número de telefone. Use-a para notificações,
alertas, atualizações transacionais e outras comunicações baseadas em texto.

## Antes de começar

* Armazene sua chave de API da YCloud em `YCLOUD_API_KEY`.
* Formate o número do destinatário no formato E.164.
* Registre um `senderId` aprovado quando o destino exigir.
* Forneça uma `signature` aprovada para mensagens enviadas à China continental.

## Como funciona

Envie a mensagem com `POST /sms`. Uma resposta bem-sucedida significa que a YCloud aceitou
a requisição. Isso não garante a entrega final.

A YCloud atualiza a mensagem de `accepted` para um status posterior como `sent`,
`delivered`, `undelivered` ou `failed`. Receba essas mudanças através do
webhook `sms.message.updated` ou recupere registros de SMS com `GET /sms`.

## Requisição

`POST /sms`

### Campos da requisição

| Campo | Obrigatório | Descrição |
| - | - | - |
| `to` | Sim | Número de telefone do destinatário no formato E.164. |
| `text` | Sim | Corpo da mensagem de texto. |
| `senderId` | Não | Sender ID aprovado usado para a mensagem. A disponibilidade varia conforme o destino. |
| `signature` | Condicional | Assinatura aprovada para a China continental. A YCloud a envolve em `【】` e a antecede à mensagem. |
| `externalId` | Não | Sua referência única para reconciliar a mensagem com um registro interno. |
| `callbackUrl` | Não | URL de relatório de entrega por mensagem. Use endpoints de webhook para novas integrações. |

### Exemplo de requisição

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/sms \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315551111",
    "text": "Your verification code is 123456.",
    "externalId": "login-10001"
  }'
```

## Resposta

Uma resposta bem-sucedida retorna o objeto de SMS criado. Armazene seu `id` para
correlacionar atualizações de entrega e recuperar a mensagem depois.

### Exemplo de resposta

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MESSAGE_ID",
  "to": "+16315551111",
  "text": "Your verification code is 123456.",
  "regionCode": "US",
  "totalSegments": 1,
  "status": "accepted",
  "externalId": "login-10001",
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

### Campos da resposta

| Campo | Descrição |
| - | - |
| `id` | ID da mensagem na YCloud. Armazene-o para recuperação e correlação de eventos. |
| `status` | Estado atual de entrega. `accepted` significa que a requisição foi aceita, não entregue. |
| `totalSegments` | Número de segmentos de SMS usados pela mensagem. |
| `totalPrice` | Preço total da mensagem quando disponível. |
| `currency` | Moeda do preço no padrão ISO 4217. |
| `errorCode` | Código de falha quando a mensagem é inentregável. |
| `createTime` | Horário de criação da mensagem no formato RFC 3339. |
| `updateTime` | Horário da última atualização de status de entrega. |
| `externalId` | A referência fornecida na requisição. |

## Status de entrega

Inscreva-se em `sms.message.updated` para mudanças de status de saída. Inscreva-se em
`sms.inbound.received` se sua conta recebe respostas de SMS.

Use `GET /sms` para reconciliar registros por horário de criação ou ID da mensagem.

## Limites e solução de problemas

* A disponibilidade de Sender ID e as regras de conteúdo variam conforme o destino.
* Mensagens longas podem usar múltiplos segmentos de SMS e custar mais.
* Não repita uma requisição aceita sem uma estratégia de idempotência. Uma requisição
  repetida pode enviar uma mensagem duplicada.
* Use o `id` retornado e o `externalId` ao investigar um problema de entrega.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.