Guía: números

English version: Guide: numbers.

Un número (DID) se registra en tu cuenta antes de que las llamadas y los textos puedan usarlo como remitente. Esta página cubre el registro, la lista de lanzamiento y el paso 10DLC para los SMS de EE. UU. Las formas están en la Referencia de la API.

Registra un número que posees

curl -s -X POST $API/v1/dids \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"e164": "+13125550123", "labels": ["collections"], "notes": "main outbound line"}'

• e164 es único por cuenta (409 conflict si se repite) e inmutable tras crearlo; npa se deriva de los números +1 si se omite.
• La superficie del cliente sólo crea filas origin: customer. El inventario de la plataforma lo crea el operador.
• La attestation STIR/SHAKEN que envíes se acepta y se ignora: sólo la registra la plataforma.
• Crear exige una clave dd_ o una sesión account_admin (403 role_forbidden para un member). Leer está abierto a toda sesión.
• Una clave de prueba no llega a ningún operador: las rutas que compran números o aprovisionan operadores responden 403 test_environment.

Lee la salud y completa la lista de lanzamiento

Objetivo	Endpoint
Listar / consultar números	GET /v1/dids, GET /v1/dids/{id}
Cambiar estado (active, quarantine, retired) o metadatos	PATCH /v1/dids/{id}
Retirar (las filas nunca se borran)	DELETE /v1/dids/{id}
Salud calculada del CDR	GET /v1/dids/{id}/health
La lista de lanzamiento y sus pasos manuales	GET /v1/dids/{id}/launch-checklist, POST /v1/dids/{id}/launch-checklist/{step}/confirmations
Tickets del operador	GET / POST /v1/dids/{id}/carrier-tickets

Un número en quarantine no es marcable (422 number_quarantined).

Mensajes de texto de EE. UU.: marca y campaña (10DLC)

Un texto desde un número local de EE. UU. sale sólo por un número asignado a una campaña aprobada:

1. Registra una marca — POST /v1/messaging/brands — y espera a que su estado sea approved (POST …/brands/{id}/refresh lo vuelve a leer).
2. Registra una campaña para esa marca — POST /v1/messaging/campaigns con brand_id, use_case, description, message_flow y sample_messages (409 brand_not_approved si no).
3. Asigna el número — POST /v1/messaging/campaigns/{id}/numbers.

Hasta entonces POST /v1/sms/messages responde 422 sms_10dlc_campaign_required con cero llamadas al proveedor. Los remitentes gratuitos (toll-free) y las regiones distintas de us no pasan por 10DLC. La cuota del primer mes de la campaña del proveedor se carga a tu saldo al costo como una línea messaging_fee.

Números en el sandbox

El sandbox no usa tus números: sus cuatro destinos son fijos; ver límites y números de prueba.