---
title: "Registra un remitente SMS mediante la API"
description: "Reclama un remitente SMS, crea su registro para un país, comprueba antes el precio y los fondos del monedero, y presenta la documentación del registro mediante la API."
canonical: "https://bird.com/es-es/documentacion/guides/sms/sender-registration-api"
---

# 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](/docs/guides/authentication) 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](#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](/docs/api/regions) 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`](/docs/api/reference/get-billing-resolved-price) y [`GET /v1/organization/billing/wallets`](/docs/api/reference/list-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](/docs/ai/mcp-server#how-the-handshake-works). 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:

```bash
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`](/docs/api/reference/list-workspace-sms-senders) o [`GET /v1/sms/senders/{sender_id}`](/docs/api/reference/get-workspace-sms-sender). Si hace falta, crea uno con [`POST /v1/sms/senders`](/docs/api/reference/create-workspace-sms-sender).
2. Lee [`GET /v1/sms/senders/{sender_id}/requirements`](/docs/api/reference/list-workspace-sms-sender-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](#comprobar-los-precios-de-registro-y-los-fondos-del-monedero) y después llama a [`POST /v1/sms/senders/{sender_id}/registrations`](/docs/api/reference/create-workspace-sms-sender-registration) 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`](/docs/api/reference/get-workspace-compliance-requirements), usando `sms_sender` como `subject_kind` y el registro como `subject_id`:

```bash
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](/docs/guides/numbers/ownership-paperwork#read-what-the-country-asks-for) explica cada uno, y [Subir cada documento](/docs/guides/numbers/ownership-paperwork#upload-each-document) trata los archivos que pide un campo `document`. Presenta todas las respuestas con [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), indicando el registro como sujeto:

```bash
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](/docs/guides/numbers/ownership-paperwork#submit-every-answer). 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}`](/docs/api/reference/get-workspace-compliance-submission), 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`](/docs/api/reference/update-workspace-compliance-submission), como muestra [Corregir una respuesta rechazada](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer).

## Próximos pasos

- [Presenta la documentación de titularidad de un número](/docs/guides/numbers/ownership-paperwork)
- [ID de remitente SMS](/docs/guides/sms/senders)

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer)
- [SMS](/sms-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms)