> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Enviar mensajes SMS > Envía SMS a uno o varios números. Puedes escribir el texto al momento o elegir una plantilla. ## OpenAPI ````yaml /es/sms-api/api-reference/openapi-sms.json post /v1/sms/messages openapi: 3.0.3 info: title: Notifique API. SMS description: >- Envíe SMS, consulte la entrega y vea mensajes recibidos. Autentíquese con `Authorization: Bearer sk_live_...` o `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Producción security: - ntfSmsBearerAuth: [] - ntfSmsApiKeyHeader: [] tags: - name: SMS description: Enviar SMS, consultar estado y ver mensajes recibidos. paths: /v1/sms/messages: post: tags: - SMS summary: Enviar mensajes SMS description: >- Envía SMS a uno o varios números. Puedes escribir el texto al momento o elegir una plantilla. operationId: ntfSms_postV1SmsSend parameters: - name: Idempotency-Key in: header required: false description: >- Clave única para evitar envíos duplicados. Alternativa: x-idempotencia-clave. schema: type: string - name: x-idempotency-key in: header required: false description: Clave única para idempotencia (alternativa a Idempotency-Key). schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfSms_SendSmsRequest' examples: text: summary: Texto value: to: - '5511999999999' - '5521988887777' type: text payload: message: ¡Hola! SMS de prueba. schedule: sendAt: '2025-12-31T14:00:00.000Z' options: priority: high webhook: url: https://api.tudominio.com/hooks/sms-events secret: secreto_hmac_opcional metadata: orderId: '12345' source: checkout template: summary: Plantilla del workspace value: to: - '5511999999999' type: template payload: templateId: tpl_abc123 variables: code: '482910' name: María responses: '202': description: SMS aceptados. En cola para envío inmediato o programado. content: application/json: schema: $ref: '#/components/schemas/NtfSms_SendSmsResponse' examples: queued: summary: Envío inmediato value: success: true data: status: QUEUED count: 2 messageIds: - clxx123... - clxx456... smsIds: - clxx123... - clxx456... scheduled: summary: Programado value: success: true data: status: SCHEDULED count: 2 messageIds: - clxx123... - clxx456... smsIds: - clxx123... - clxx456... scheduledAt: '2025-12-31T14:00:00.000Z' '400': description: >- Validación: `to` vacío o inválido, `payload.message` vacío, mensaje con menos de 9 o más de 160 caracteres (`code`: SMS_MESSAGE_TOO_SHORT), `type` inválido, `payload.templateId` ausente cuando `type` es template, contenido bloqueado por política (`UNSAFE_SMS_CONTENT`), teléfono inválido o programación más allá del plan. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' examples: invalidPhone: summary: Teléfono no válido value: success: false error: Bad Request message: 'Invalid phone at position 1: Invalid format' details: - field: to message: Invalid format code: BAD_REQUEST messageTooShort: summary: Mensaje con menos de 9 caracteres. value: success: false error: Bad Request message: SMS message must be at least 9 characters. code: SMS_MESSAGE_TOO_SHORT details: - field: payload.message message: SMS message must be at least 9 characters. '401': description: Clave API faltante o no válida. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' '402': description: >- Plan/prueba caducado, saldo/créditos insuficientes o límite de gasto de clave API. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' example: success: false error: Payment Required message: Trial ended or plan expired. Choose a plan to continue. code: WORKSPACE_BLOCKED '403': description: >- Alcance insuficiente (sms:enviar), créditos/plan insuficientes (PLAN_LIMIT_CREDITS) o programación no permitida (PLAN_LIMIT_SCHEDULING). content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' example: success: false error: Forbidden message: Insufficient credits or plan required. code: PLAN_LIMIT_CREDITS '429': description: Rate limit excedido. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' components: schemas: NtfSms_SendSmsRequest: type: object required: - to - type - payload properties: to: type: array items: type: string minItems: 1 maxItems: 100 description: 'Uno o más números en formato internacional (ej.: 5511999999999).' type: type: string enum: - text - template description: >- Use `text` para mensaje libre o `template` para una plantilla del workspace. payload: type: object description: >- Cuerpo del mensaje: texto libre o datos de la plantilla (ID y variables). schedule: type: object properties: sendAt: type: string format: date-time description: >- Fecha/hora en ISO 8601 para programar el envío. Depende del plan. options: type: object properties: priority: type: string enum: - high - normal - low default: normal description: >- Prioridad: `high` utiliza la cola de prioridad de SMS de Redis y la cola de prioridad de entrega de webhooks; `normal`/`low` utilizan las colas predeterminadas. webhook: type: object description: >- Webhook solo para este envío: los eventos (`sms.*`) de este lote se PUBLICAN en esta URL HTTPS en lugar de los webhooks configurados en el espacio de trabajo. required: - url properties: url: type: string format: uri maxLength: 2048 secret: type: string description: >- Opcional. Secreto HMAC (encabezado `X-Notifique-Signature`, el mismo valor predeterminado que los webhooks del espacio de trabajo). autoReplyText: type: string maxLength: 160 description: >- Texto enviado automáticamente (1×) cuando el destinatario responde al SMS (MO correlacionado). Cargue 1 SMS. Requiere MO de devolución (webhook) configurado en el proveedor de SMS. metadata: type: object additionalProperties: type: string description: >- Cadena → metadatos de cadena por envío, persistidos en `SmsLog.metadata`. Respete los límites de carga útil de la API. NtfSms_SendSmsResponse: type: object required: - success - data properties: success: type: boolean example: true data: type: object required: - status - count - messageIds properties: status: type: string enum: - QUEUED - SCHEDULED description: EN COLA = envío inmediato; PROGRAMADO = programado. count: type: integer description: Número de mensajes SMS creados. messageIds: type: array items: type: string description: >- ID canónicos (cuid) para realizar consultas mediante GET /v1/sms/messages/{id} o cancelar mediante POST /v1/sms/messages/{id}/cancel (cuando esté programado). smsIds: type: array items: type: string description: Alias ​​de compatibilidad para messageIds. Mismo valor. scheduledAt: type: string format: date-time description: >- Presente cuando se programa el estado; fecha/hora de programación en ISO 8601. NtfSms_ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: >- Etiqueta de error de estilo HTTP (por ejemplo, no autorizado, solicitud incorrecta, no encontrada). message: type: string description: >- Mensaje legible por humanos para usuarios finales (localizado a través de Accept-Language/x-locale cuando corresponda). code: type: string description: >- Código API v1 estable (enumeración). Siempre presente en los errores. Úselo con el estado HTTP para decidir reintentar o corregir. Ver [Respuestas de error](/es/guides/conceitos/resposta-de-erros). details: type: array items: type: object properties: field: type: string message: type: string description: Listado de errores de validación por campo. required: - success - error - message - code securitySchemes: ntfSmsBearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Clave API sin autorización de encabezado. Ejemplo: `Authorization: Bearer sk_live_xxxxx` ntfSmsApiKeyHeader: type: apiKey in: header name: x-api-key description: 'Clave API sin encabezado x-api-key. Ejemplo: `x-api-key: sk_live_xxxxx`' ````