Registra un remitente SMS mediante la API

Algunos países solo entregan SMS desde un remitente registrado para ellos. Mediante la API reclamas el remitente, creas su registro para el país de destino y presentas la documentación que pide ese registro, los mismos pasos que sigue el panel. Un registro puede cobrar una tarifa de alta en cuanto se crea, así que comprueba antes el precio y tu monedero.

Antes de empezar

• Una clave de API con sms_management con nivel de escritura para crear remitentes y registros, y compliance con nivel de escritura para presentar su documentación.
• Para comprobar antes los precios y los fondos del monedero, un token OAuth de usuario delegado, como se describe en Comprobar los precios de registro y los fondos del monedero. Una clave de API no puede leer la facturación de la organización.

Los ejemplos leen tu clave de BIRD_API_KEY, su host regional de BIRD_API_URL, el país de destino de COUNTRY_CODE y el identificador scr_ del registro de REGISTRATION_ID cuando lo tengas.

Comprobar los precios de registro y los fondos del monedero

Para mostrar la misma información de precios y monedero que el panel, usa GET /v1/organization/billing/prices/resolve y GET /v1/organization/billing/wallets. Estas lecturas requieren un token OAuth de usuario delegado con org:billing:read. Las claves de API del espacio de trabajo, las claves maestras de la organización y los tokens de cuentas de servicio no pueden conceder este permiso de facturación de la organización.

Usa el descubrimiento de recursos protegidos de OAuth y los metadatos del servidor de autorización para obtener issuer, registration_endpoint, authorization_endpoint y token_endpoint, como se describe en Descubrimiento de OAuth. Registra tu propio cliente público de OAuth en el registration_endpoint descubierto e indica client_name, redirect_uris y token_endpoint_auth_method: "none". Envía al usuario al authorization_endpoint descubierto con ese client_id, response_type=code, tu redirect_uri registrado, un state nuevo, scope=org:billing:read, un code_challenge derivado de tu verificador y code_challenge_method=S256. En la pantalla de consentimiento, el usuario selecciona un espacio de trabajo de la organización prevista y concede org:billing:read si su rol lo permite. Valida state con el valor que enviaste y iss con el emisor obtenido en el descubrimiento; después, canjea el código en el token_endpoint descubierto con grant_type=authorization_code, el code devuelto, client_id, el mismo redirect_uri y el code_verifier original. Usa el token de acceso resultante como BIRD_OAUTH_TOKEN. Respeta su expires_in; guarda el token de actualización de forma segura y sustitúyelo tras cada actualización correcta. Haz los intentos de actualización de uno en uno, porque cada token de actualización solo puede usarse una vez. Vuelve a autorizar cuando la concesión de actualización caduque o se revoque.

El token queda vinculado al espacio de trabajo seleccionado y a su organización; las lecturas de facturación se aplican a esa organización. X-Organization-Id no puede cambiarlo a otra organización; repite la autorización para esa organización. Indica el host regional de forma explícita al configurar un SDK con este token.

Para un remitente SMS alfanumérico, obtén el precio de alta de su registro indicando el país de destino:

curl --get "$BIRD_API_URL/v1/organization/billing/prices/resolve" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN" \
  --data-urlencode 'product_slug=sms_sender_registration' \
  --data-urlencode "dimensions[country_code]=$COUNTRY_CODE" \
  --data-urlencode 'dimensions[sender_type]=alphanumeric'

curl "$BIRD_API_URL/v1/organization/billing/wallets" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN"

Obtén product_slug=sms_sender con las mismas dimensiones para el precio recurrente. Para hacer la misma comprobación de saldo que el panel, suma el gross_price.amount de la respuesta de alta al primer cargo recurrente, que es el gross_price.amount de la respuesta recurrente multiplicado por su intervals_per_charge. Compara ese total con balance del monedero en data cuyo currency_code coincide con el gross_price.currency_code de ambos precios. Usa aritmética decimal sin redondear los importes devueltos. Si el total supera el saldo, la diferencia es lo que te falta; recarga el monedero o revisa el acuerdo de crédito de tu organización antes de crear el registro. En su comprobación final de solvencia, el servidor también tiene en cuenta cualquier límite de crédito. Estas lecturas muestran los precios y fondos vigentes; no reservan fondos ni aprueban ningún registro.

Obtener el registro para el que presentar la documentación

1. Busca el remitente con GET /v1/sms/senders o GET /v1/sms/senders/{sender_id}. Si hace falta, crea uno con POST /v1/sms/senders.
2. Lee GET /v1/sms/senders/{sender_id}/requirements para el destino. Sigue sus pasos next. Si te pide crear un registro, comprueba su precio como se indica en Comprobar los precios de registro y los fondos del monedero y después llama a POST /v1/sms/senders/{sender_id}/registrations con country_code.
3. Vuelve a leer los requisitos del remitente y guarda el registration_id (scr_) de la fila como REGISTRATION_ID y su program como PROGRAM. Presenta la documentación solo cuando el has_compliance_requirements de la fila sea true; cuando sea false, el registro no necesita ningún envío o lo gestiona un programa específico, así que sigue en su lugar el next de la fila. Los programas específicos, como la verificación de números gratuitos y 10DLC, tienen sus propios pasos.

Para leer remitentes necesitas sms_management:read; para crear remitentes y registros necesitas sms_management:write. Para presentar su documentación también necesitas compliance:write.

Presentar la documentación del registro

Esta sección se aplica a los registros cuyo has_compliance_requirements es true.

Consulta lo que pide el registro con GET /v1/compliance/requirements, usando sms_sender como subject_kind y el registro como subject_id:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=sms_sender&subject_id=$REGISTRATION_ID&country_code=$COUNTRY_CODE&program=$PROGRAM" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Los campos se interpretan igual que para un número; Consultar lo que pide el país explica cada uno, y Subir cada documento trata los archivos que pide un campo document. Presenta todas las respuestas con POST /v1/compliance/submissions, indicando el registro como sujeto:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sender-$REGISTRATION_ID" \
  --data '{
    "subject_kind": "sms_sender",
    "subject_id": "'"$REGISTRATION_ID"'",
    "program": "'"$PROGRAM"'",
    "country_code": "'"$COUNTRY_CODE"'",
    "answers": [{ "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }]
  }'

El ejemplo muestra una sola respuesta; envía una entrada por cada campo cuyo required sea true y por cada campo opcional para el que tengas una respuesta real, como explica Enviar todas las respuestas. Una respuesta 201 devuelve el envío; guarda su csb_ id. Un remitente no tiene campo ownership, así que sigue la revisión leyendo el envío con GET /v1/compliance/submissions/{submission_id}, cuyas respuestas incluyen su state y, si se rechazan, un reason, o volviendo a leer los requisitos del remitente para ver el estado del registro. Sustituye las respuestas rechazadas con POST /v1/compliance/submissions/{submission_id}/resupply, como muestra Corregir una respuesta rechazada.

Próximos pasos

• Presenta la documentación de titularidad de un número
• ID de remitente SMS