--- title: "Migrar de Telserv a Bird" description: "Mueve una integración con la API de socio de Telserv a la Bird API, asocia cada grupo de operaciones con su llamada en Bird y consulta cómo se realiza cada tarea en Bird." canonical: "https://bird.com/es-es/documentacion/guides/numbers/migrate/telserv" --- # Migrar de Telserv a Bird Esta guía es para integraciones que llaman a la API de socio de Telserv, V1 o V2, para comprar, enrutar y liberar números, y que ahora migran a la Bird API. La Bird API sirve a todos los productos de Bird, así que sus operaciones de números y voz siguen las convenciones propias de Bird en lugar de las de Telserv. La mayoría de las funciones que usa tu integración tienen una llamada equivalente en Bird. Los endpoints, payloads, identificadores y la autenticación son distintos, así que planifica reescribir la integración. Donde Bird hace una tarea de forma diferente, esta guía muestra cómo. Esta guía es un trabajo en curso. Cubre lo que Bird hace hoy y crece a medida que avanza la migración. Si una operación de Telserv que usas no aparece aquí, aún necesita alcance y trabajo antes de poder añadirse; consulta con tu contacto de migración. ## Antes de empezar - Una organización de Bird con verificación de identidad completada, que la primera compra de número requiere. - Una [clave de API](/docs/api/authentication) con los alcances que usan las recetas: `numbers` con nivel de escritura para números y pedidos, `compliance` con nivel de escritura para las operaciones independientes de documentación de titularidad, y `voice_management` con nivel de escritura para trunks de SIP, números de voz y números verificados. La llamada de prueba también necesita `voice:write`, y la lectura de tramos de llamada necesita `voice:read`. - Saldo del monedero. Los pedidos se cobran del monedero. [Cuando un pedido es rechazado](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) explica los rechazos `402` y `412`. Los números que tu integración gestiona en Telserv no necesitan comprarse de nuevo. Una vez que tus números se trasladan a tu espacio de trabajo de Bird, aparecen en [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Tu contacto de migración confirma cuándo ocurre. Para obtener el identificador `nda_` de un número trasladado, búscalo con `GET /v1/numbers?number=` indicando los dígitos con su código de país, y guarda el `id` como `NUMBER_ID`. Los ejemplos leen tu clave de `BIRD_API_KEY` y su [host regional](/docs/api/regions) de `BIRD_API_URL`: `https://eu1.platform.bird.com` para una clave de `bk_eu1_`, o `https://us1.platform.bird.com` para una clave de `bk_us1_`. Las demás variables, como `TRUNK_ID` y `NUMBER_ID`, contienen un identificador de una respuesta anterior; cada paso indica cuál establece. ## Qué cambia en el contrato | Área | API de socio de Telserv | Bird API | | ------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Autenticación | Cabecera `X-ApiKey` (V2) o parámetro `apiKey` (V1), verificados contra tu lista de IPs permitidas | `Authorization: Bearer` con una clave API cuyos alcances nombran las áreas de producto que puede usar. La lista de IPs permitidas es opcional: configúrala en **IP restrictions** de la clave en [**Claves API**](https://bird.com/dashboard/w/api-keys) | | Identificadores | Enteros. Comprar un número le asigna un nuevo `id` | TypeIDs con prefijo como `nda_`, `nor_`, `vnu_` y `spt_`. Un número conserva su id `nda_` mientras esté asignado a ti | | Números de teléfono | Dígitos sin `+` inicial | E.164 con el `+` inicial | | Paginación | Desplazamientos `start` y `limit`, hasta 1000 por página | Cursores: `limit` hasta 100 (por defecto 25), luego `starting_after` con el valor de `next_cursor` de la página anterior. Consulta [Paginación](/docs/api/pagination) | | Errores | `errorCode` nombra una clase de excepción, y `403` cubre un recurso inexistente y muchos errores de validación | `error.code` es un código `E` estable con una página de documentación y, cuando se conoce una recuperación, un `remediation`. Un recurso inexistente responde `404`, una precondición no cumplida `412`, y una entrada no válida `422` con detalles de campo. Consulta [Errores](/docs/guides/errors) | | Entornos | LIVE y SANDBOX, cada uno con sus propias claves | Un solo entorno. Cada pedido compra y cobra un número real, y cada llamada de prueba es una llamada real | | Reintentos | Sin clave de idempotencia | Un encabezado `Idempotency-Key` en las escrituras. La misma clave y cuerpo reproducen la primera respuesta con `Idempotency-Replay: true`; la misma clave con un cuerpo diferente responde `409`. Consulta [Idempotencia](/docs/guides/idempotency) | La Bird API rechaza un parámetro de consulta que no reconoce con `422` y [`E01029`](/docs/api/errors/E01029). Elimina de tus solicitudes los filtros exclusivos de Telserv como `city` en lugar de enviarlos tal cual. ## Dos identificadores para un mismo número Un número con capacidad de voz asignado a tu espacio de trabajo tiene dos registros, cada uno con su propio identificador: - La asignación, devuelta por [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). Su `id` empieza por `nda_` para un número dedicado y por `nal_` para uno compartido, y el `number_id` de un pedido es el identificador `nda_` del número que compró. Úsala para leer, nombrar y referenciar el número, y para liberar uno dedicado. - El registro de voz, `vnu_`, devuelto por [`GET /v1/voice/numbers`](/docs/api/reference/list-voice-numbers). Úsalo para leer y cambiar adónde van las llamadas entrantes del número. Un número sin capacidad de voz, como un número solo de SMS, no tiene registro de voz. Las operaciones de voz rechazan un identificador `nda_` o `nal_` con `422`. Para encontrar el registro de voz de un número, lista los números de voz con `search` configurado con los dígitos del número y toma la entrada cuyo `provider.number_id` sea igual al `id` de la asignación. [Enrutar un número a tu trunk SIP](#enrutar-un-número-a-tu-trunk-sip) muestra la solicitud, y [Gestión de tus números de teléfono](/docs/guides/numbers/managing-numbers#find-the-voice-record-that-routes-a-number) cubre la búsqueda. El `GET /numbers/{dnisId}` de Telserv se convierte en dos lecturas en Bird: la asignación para el estado y la documentación de titularidad, y el registro de voz para la ruta. ## Correspondencia de operaciones de Telserv con Bird Cada tabla lista una tarea, la llamada de Telserv que la realizaba y la llamada de Bird que la realiza ahora. Las notas debajo de cada tabla cubren lo que cambia en la solicitud o la respuesta. ### Compra | Tarea | Telserv | Bird | | ----------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | Buscar números en venta | `GET /shop` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers) | | Consultar un número | `GET /shop/{stockDnisId}` | [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number) | | Comprar un número | `POST /shop/{stockDnisId}` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | | Reservar un número | `POST /shop/{stockDnisId}/reserve`, `GET /shop/reserved` | [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order) | - **Búsqueda.** `country_code` es obligatorio, así que una búsqueda cubre un solo país. `prefix` recibe los dígitos nacionales después del código de país: el `prefix=3170` de Telserv pasa a ser `country_code=NL&prefix=70`. Filtra por código de área con `prefix` en lugar de `city`, y por `number_type` y `capabilities` en lugar de `productId`. - **Documentación en los resultados de búsqueda.** Cada resultado incluye `ownership_registration_required` en lugar del filtro `excludeNumbersRequireVerification`. Un valor `true` significa que el número se factura desde la compra, pero no envía SMS ni cursa llamadas de voz entrantes o salientes hasta que se apruebe su documentación. - **Consultar un número.** Se direcciona por su número E.164. - **Precios.** Telserv devolvía `pricing.staticPricing` en las lecturas detalladas de un número y de un producto. En Bird, cada resultado de búsqueda incluye el precio para tu organización en `pricing`: `setup_price` en lugar de `nrc`, y `recurring_price` por `recurring_period` en lugar de `mrc`, con `intervals_per_charge` para indicar cuántos períodos cubre un cargo. [Buscar y comprar un número con tu referencia](#buscar-y-comprar-un-número-con-tu-referencia) describe los campos de precio. - **Comprar.** Envía `number` y un `reference` opcional. El pedido se paga desde tu monedero. La mayoría de los pedidos responden `201`; un pedido que espera a un operador responde `202`, y lo consultas periódicamente. - **Reservar.** Hacer el pedido del número lo reserva. Consulta un candidato primero y luego haz el pedido. ### Números | Tarea | Telserv | Bird | | ------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Listar tus números | `GET /numbers` | [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) | | Leer un número | `GET /numbers/{dnisId}` | [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) con el id `nda_` o `nal_` de la asignación, y [`GET /v1/voice/numbers/{number_id}`](/docs/api/reference/get-voice-number) con el id `vnu_` del registro de voz | | Modificar un número | `PATCH /numbers/{dnisId}` | [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number) con el id `nda_` o `nal_` de la asignación, y [`PATCH /v1/voice/numbers/{number_id}`](/docs/api/reference/update-voice-number) con el id `vnu_` del registro de voz | | Liberar un número | `DELETE /numbers/{dnisId}?requestedCancelDate=` | [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) al final del período pagado, o [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) ahora, ambos con el id `nda_` de la asignación | - **Listar.** La lista contiene los números que tienes asignados ahora. Un número liberado que pediste en Bird sigue visible a través de su pedido en [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders). [Conciliar tus números](#conciliar-tus-números) describe los filtros. - **Leer.** El estado, la documentación de titularidad y el precio están en la asignación, y la ruta está en el registro de voz. El objeto `pricing` de la asignación, con `recurring_price` por `recurring_period` y `intervals_per_charge`, reemplaza a `pricing.staticPricing.mrc`, y la lista también lo incluye, mientras que `GET /numbers` de Telserv no lo hacía. - **Modificar.** `name` y `reference` están en la asignación, y la ruta está en el registro de voz. Configura un códec forzado y un límite de llamadas simultáneas en tu equipo SIP. `destinationDistributionType` pasa a ser `priority` de gateway en el trunk SIP: `FailOver` asigna a cada gateway un `priority` diferente, y `RoundRobin` les asigna el mismo. - **Liberar.** `DELETE` conserva el número hasta el final del período que ya pagaste y lo libera entonces. `POST …/release` lo libera de inmediato. Ninguno acepta una fecha. [Liberar un número](#liberar-un-número) muestra ambas solicitudes. ### Destinos y perfiles | Tarea | Telserv | Bird | | ------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enviar llamadas al equipo SIP | `POST /numbers/{dnisId}/destinations` | [`POST /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/create-voice-trunk-gateway), luego enrutar `trunk` | | Reenviar llamadas a un teléfono | `POST /numbers/{dnisId}/destinations` | Enrutar `forward` | | Dejar de recibir llamadas | `DELETE /numbers/{dnisId}/destinations` | Enrutar `reject` | | Leer perfiles de destino | `GET /destinationprofiles`, `GET /destinationprofiles/{id}` | [`GET /v1/voice/trunks`](/docs/api/reference/list-voice-trunks) y [`GET /v1/voice/trunks/{trunk_id}/gateways`](/docs/api/reference/list-voice-trunk-gateways) | | Aplicar un perfil a un número | `POST /numbers/{dnisId}/destinations/profile` | Enrutar `trunk` con `trunk_id` | - **Equipo SIP.** Un gateway pertenece al trunk y atiende cada número enrutado hacia él, así que los números que necesitan listas de destino distintas necesitan trunks distintos. `sortOrder` se convierte en `priority`. Aplica el tiempo de timbre y las ventanas horarias en tu equipo SIP. - **Reenvío.** Establece `forward_to` y `forward_as`. `forward_to` debe ser uno de tus [números verificados](/docs/guides/voice/caller-ids); un número no verificado responde `412` con [`E21053`](/docs/api/errors/E21053). `forward_as` elige qué número muestra la llamada reenviada como identificador de quien llama. Un número tiene una sola ruta a la vez, así que para recurrir desde el equipo SIP a un número de teléfono, reenvía la llamada desde tu equipo SIP. - **Dejar de recibir llamadas.** El número rechaza llamadas hasta que lo enrutes de nuevo. Para mantener un destino permanente en lugar de un perfil predeterminado, enruta el número a un trunk que contenga tus gateways predeterminados. - **Perfiles.** `distributionType` pasa a ser `priority`: `FailOver` asigna a cada gateway un `priority` diferente, y `RoundRobin` les asigna el mismo. La distribución se configura por trunk, así que los números que necesitan distribución diferente necesitan trunks diferentes. El placeholder `{dnis}` pasa a ser `{number}` en `destination_format`, y un `prefixCLIP` pasa a ser el texto antes de `{number}` en `origination_format`. - **Aplicar un perfil.** Un trunk se identifica por su identificador `spt_`, mientras que Telserv identificaba un perfil por nombre. ### Documentos y datos de usuario final | Tarea | Telserv | Bird | | ----------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Consultar los requisitos | `GET /products/conditions`, `GET /masterdata/productconditions` | [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements) para el número, o con `program` y sin `subject_id` para el formulario que un país exige antes de que tengas un número | | Subir un documento | `POST /numbers/{dnisId}/documents` | [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment) y, después, cita el adjunto en el envío. Consulta [Presentar la documentación de titularidad](#presentar-la-documentación-de-titularidad) | | Enviar datos de usuario final | `POST /numbers/{dnisId}/enduserdata` | [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), con los documentos, en una sola solicitud. Consulta [Presentar la documentación de titularidad](#presentar-la-documentación-de-titularidad) | | Sustituir un documento | `POST /numbers/{dnisId}/documents` de nuevo | [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission) con las respuestas rechazadas o caducadas | | Consultar el progreso de la documentación | `GET /numbers/{dnisId}/documents` | `ownership` en [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number), y el envío para ver el veredicto de cada respuesta | - **Requisitos.** El catálogo de condiciones de Telserv cubría todos los productos a la vez; Bird lee un formulario cada vez. Pide los requisitos de un número con `subject_kind=number`, su identificador `nda_` como `subject_id` y su `country_code`, o lee un formulario antes de comprar con `program` establecido en el tipo de número y sin `subject_id`. Cada entrada de `fields` sustituye a una condición o etiqueta de usuario final de Telserv: su `key` es la clave bajo la que respondes, y `data_type` `document` marca una que requiere un archivo. - **Documentos.** Sube el archivo como `multipart/form-data` en lugar de un `fileContent` en base64; [Sube cada documento](/docs/guides/numbers/ownership-paperwork#upload-each-document) lista los archivos aceptados. Subir el mismo archivo dos veces devuelve el mismo adjunto. Una subida por sí sola no presenta nada: lo presenta el envío que cita su `attachment_id`. - **Datos de usuario final y documentos juntos.** Telserv aceptaba cada documento en su propia llamada, y los datos de usuario final como una lista de etiquetas en otra. Bird acepta todas las respuestas, escritas y documentos, en un solo envío, y no hay borradores: la solicitud presenta las respuestas para su revisión. Después sigue `ownership.next`, que indica el reenvío de correcciones y un envío nuevo solo cuando hace falta ([Envía todas las respuestas](/docs/guides/numbers/ownership-paperwork#submit-every-answer)). - **Sustituciones.** Envía solo las respuestas que sustituyes; las demás conservan su revisión. Telserv aceptaba un archivo nuevo para una condición mientras el número estaba pendiente de verificación, y ese archivo reiniciaba la revisión de la condición. Bird sustituye una respuesta rechazada, caducada o aún no aportada, y rechaza una que sigue en revisión o ya está aceptada, salvo una respuesta marcada como `editable_for_verifier_repair` mientras haya abierta una corrección que hayamos solicitado ([Corregir una respuesta rechazada](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer)). - **Progreso.** `ownership.status` y `ownership.next` informan del estado del número. Cada respuesta tiene su propio `state`, y una rechazada incluye el `reason` del revisor. Bird también envía cada resultado por correo electrónico a los propietarios de tu organización y a la persona que presentó o corrigió el envío por última vez. `ownership` suele ser `null` cuando el número no requiere documentación. [Presentar la documentación de titularidad](#presentar-la-documentación-de-titularidad) muestra las solicitudes, y [Presentar la documentación de titularidad de un número](/docs/guides/numbers/ownership-paperwork) cubre todo el flujo, incluida la presentación desde el panel y junto con el pedido. ### Productos y datos maestros | Tarea | Telserv | Bird | | ------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Explorar productos | `GET /products`, `GET /products/{productId}` | [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers), que requiere `country_code` y devuelve los números a la venta en ese único país. Bird no tiene un catálogo global de productos, y nada corresponde a `productId`. Ninguna API lista los países y tipos de número a la venta; la página de [precios de números de teléfono](/pricing/numbers) lista los precios estándar de Bird por país. | Cada resultado de búsqueda describe su producto con `number_type`, `capabilities` y `ownership_registration_required`, y lleva el precio para tu organización en lugar del `pricing.staticPricing` del producto (`nrc` y `mrc`). Los precios estándar de Bird están en la página de [precios de números de teléfono](/pricing/numbers). El `sessionPricing` por minuto de Telserv no tiene equivalente en estas lecturas; las tarifas de voz están en la página de [precios de voz](/pricing/voice). Los tipos de número de Telserv se corresponden con el `number_type` de Bird de esta forma: | `numberType` de Telserv | Bird `number_type` | | ----------------------- | ------------------------------------- | | `DID` | `local` o `national`, según el número | | `FreePhone` | `toll_free` | | `Mobile` | `mobile` | ## Qué funciona de forma diferente hoy Estas tareas de Telserv se realizan de forma diferente en Bird. Planifícalas antes de mover una integración que dependa de alguna. - **Documentación.** Presenta los documentos y los datos de usuario final de un número en un solo envío, sin borradores, y corrige las respuestas rechazadas con un reenvío de datos. - **Reservas.** Pide el número cuando lo hayas elegido; el pedido lo reserva. - **Ajustes de llamada por número.** Aplica un códec forzado, un límite de llamadas simultáneas, tiempo de timbre y ventanas horarias en tu equipo SIP. - **Fecha de liberación.** Bird libera un número al final de su período pagado o de inmediato, no en una fecha que tú elijas. Conserva en tu lado las fechas de cancelación que enviaste a Telserv y actúa sobre cada una cuando llegue el momento. - **Saldo del monedero.** Consulta el saldo y recárgalo en el panel. ## Buscar y comprar un número con tu referencia Busca en un solo país. Combina `number_type`, `capabilities` y `prefix` para acotar los resultados: ```bash curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Cada resultado incluye un objeto `pricing` con el precio que tu organización paga por el número, neto de impuestos y en tu moneda de facturación, con los precios que hayas acordado con Bird ya aplicados: - `setup_price` se cobra una vez al pedir el número. Una tarifa publicada de cero tiene un `amount` de `"0"`. El campo en sí es `null` cuando no hay tarifa de alta, y también siempre que `recurring_price` sea `null`, porque ese número no se puede pedir. - `recurring_price` es la tarifa por `recurring_period`. - `intervals_per_charge` indica cuántos `recurring_period` factura un solo cargo. El cargo recurrente antes de impuestos es `recurring_price` multiplicado por `intervals_per_charge`, y se cobra cuando el número se asigna a tu espacio de trabajo y en cada renovación; la tarifa de alta es aparte. En un pedido que espera a un operador, la asignación se produce cuando el pedido se completa. La [referencia de API](/docs/api/reference/list-available-numbers) muestra un resultado de ejemplo. Un resultado con `pricing.recurring_price: null` no indica un precio recurrente. [Contacta con ventas](/contact-sales) para obtener un precio para ese país y tipo de número antes de hacer el pedido. El panel y API usan el mismo precio de la organización, incluida la conversión a tu moneda de facturación. Una lectura de precio no fija una cotización: los cambios de tarifa o de tipo de cambio antes de un cobro posterior pueden modificar su importe. Si la consulta falla, la búsqueda devuelve `503` con [`E14009`](/docs/api/errors/E14009). Reintenta la lectura con retroceso exponencial; un fallo de consulta nunca significa que el número no cueste nada. Para confirmar un candidato y su precio antes de pedirlo, léelo con `GET /v1/numbers/available/{number}`. Un `404` significa que ya no está a la venta. Pide el número con la referencia que usabas en Telserv y elige una clave de idempotencia que conserves para cualquier reintento de esta compra: ```bash curl --request POST "$BIRD_API_URL/v1/numbers/orders" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: order-CUST-778812" \ --data '{"number": "+31612345678", "reference": "CUST-778812"}' ``` Una respuesta `201` tiene `status: completed` y un `number_id`, el identificador `nda_` del número. Consérvalo como `NUMBER_ID`. Una respuesta `202` significa que el pedido espera a un operador: [consulta el pedido](/docs/guides/numbers/buying-numbers#poll-an-order-that-did-not-finish) hasta que su `status` sea `completed` o `failed`. Una tarifa de alta ya cobrada no se reembolsa si el pedido falla después. La referencia se asigna al número cuando el pedido se completa. Admite hasta 100 caracteres y no necesita ser única. Reintentar un pedido de un número que tu espacio de trabajo ya tiene asignado devuelve el pedido existente, así que un reintento no cobra dos veces. [Comprar y liberar un número](/docs/guides/numbers/buying-numbers#when-an-order-is-refused) explica los rechazos. Para establecer o cambiar una referencia más adelante, envía `reference` (y opcionalmente `name`) a `PATCH /v1/numbers/{number_id}`. Envía `null` para borrar un campo. ## Comprobar que un número puede cursar llamadas Un número cuyo `status` es `pending_ownership_registration` está asignado y facturado, pero no envía SMS y rechaza las llamadas de voz entrantes y salientes hasta que se apruebe su documentación de titularidad. Antes de enrutar un número o hacerle una llamada de prueba, léelo con [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) y comprueba que `status` sea `active`. Si está pendiente, [presenta la documentación de titularidad](#presentar-la-documentación-de-titularidad). [El estado de un número asignado](/docs/guides/numbers/overview#the-status-of-an-allocated-number) explica cada valor. Los ejemplos siguientes usan un número móvil neerlandés. Comprueba el `status` de tu propio número del mismo modo, sea cual sea su país. ## Presentar la documentación de titularidad Telserv recibía la documentación de un número con un `POST /numbers/{dnisId}/documents` por documento y un `POST /numbers/{dnisId}/enduserdata` para todas las etiquetas. Bird recibe ambos en un solo envío, después de que subas los documentos. 1. Lee el `country_code` del número y guárdalo como `COUNTRY_CODE`. El comando lo extrae con `jq`; léelo manualmente si no usas `jq`: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` 2. Lee lo que exige el país del número. Cada entrada de `fields` tiene el `key` bajo el que respondes, un `data_type` y `required`, que indica si debes responderla. Guarda el `program` que indica la respuesta como `PROGRAM`: ```bash curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Un `422` con [`E19001`](/docs/api/errors/E19001) significa que no hay formulario de titularidad para ese país. 3. Sube cada documento que pida un campo `document`, como archivo en lugar de `fileContent` en base64. Guarda el `id` de la respuesta, el identificador `tca_` del adjunto, como `ATTACHMENT_ID`: ```bash curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --form "file=@registration-certificate.pdf" ``` 4. Envía todas las respuestas a la vez: una entrada por cada campo cuyo `required` sea `true`, y por cada campo opcional para el que tengas una respuesta real, con los datos de usuario final como `value` y cada documento como `attachment_id`. Omite un campo opcional en lugar de inventarle un valor. El ejemplo muestra dos respuestas; añade el resto de las obligatorias antes de enviarlo. Esta solicitud presenta las respuestas para su revisión. Guarda el `id` de la respuesta, el identificador `csb_` del envío, como `SUBMISSION_ID`: ```bash curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ownership-CUST-778812" \ --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}' ``` Una respuesta `201` devuelve el envío. Un `422` no presenta nada: corrige el cuerpo y envíalo con una clave de idempotencia nueva, porque la clave reproduce el rechazo. [Enviar todas las respuestas](/docs/guides/numbers/ownership-paperwork#submit-every-answer) explica cada rechazo. 5. Cuando un revisor rechaza una respuesta, reemplaza solo esa respuesta, como describe [Corregir una respuesta rechazada](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer): ```bash curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ownership-fix-1-CUST-778812" \ --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}' ``` Para presentar la documentación al comprar, envía el mismo `answers` en el bloque `compliance` de `POST /v1/numbers/orders`. Ese pedido usa el alcance `numbers` existente con nivel de escritura, también cuando incluye documentación. Sigue la revisión con `ownership.status` en [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number). Las respuestas son una declaración legal hecha en nombre de tu empresa, así que presenta solo respuestas que haya confirmado alguien responsable de ellas. [Presentar la documentación de titularidad de un número](/docs/guides/numbers/ownership-paperwork) explica cada solicitud, la revisión y la presentación junto con el pedido. ## Enrutar un número a tu trunk SIP Un número nuevo no tiene ruta propia, así que sigue la [ruta predeterminada](/docs/guides/voice/receiving-calls#set-a-default-route) de tu espacio de trabajo. Esa ruta empieza como `reject`, pero en un espacio de trabajo que ya configuró una, el número nuevo responde las llamadas según ella en cuanto se asigna. Para entregar sus llamadas a tu equipo, crea un trunk SIP con las llamadas entrantes activadas, añádele un gateway y apunta el número al trunk. [Trunks SIP](/docs/guides/voice/sip-trunks) explica cómo conectar tu equipo al trunk. 1. Crea el trunk con las llamadas entrantes activadas. Guarda el `id` de la respuesta, el identificador `spt_` del trunk, como `TRUNK_ID`: ```bash curl --request POST "$BIRD_API_URL/v1/voice/trunks" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: trunk-production-pbx" \ --data '{"name": "Production PBX", "inbound_enabled": true}' ``` 2. Añade un gateway. Por defecto, el gateway recibe los números marcado y llamante en E.164 con su `+`. Si tu equipo espera números sin el `+`, como hacía el placeholder `{dnis}` de Telserv, establece `destination_format` para el número marcado y `origination_format` para el número llamante a `{number}`: ```bash curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: gateway-pbx-primary" \ --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}' ``` Para conmutación por error, añade un segundo gateway; [Lo que necesita un gateway](/docs/guides/voice/receiving-calls#what-a-gateway-needs) explica `priority` y los formatos de número. Crear el mismo gateway otra vez sin una clave de idempotencia responde `409` con [`E21047`](/docs/api/errors/E21047). 3. Busca el registro de voz del número. Busca con los dígitos del número y toma el `id` de la entrada cuyo `provider.number_id` sea el `id` de la asignación. Guárdalo como `VOICE_NUMBER_ID`: ```bash curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` 4. Apunta el número al trunk: ```bash curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}' ``` Una respuesta `200` muestra la nueva ruta. Un trunk con las llamadas entrantes desactivadas responde `412` con [`E21052`](/docs/api/errors/E21052). Desactivar las llamadas entrantes en un trunk, o eliminarlo, devuelve cada número enrutado a él a la ruta predeterminada de tu espacio de trabajo, y volver a activarlas no restaura esas rutas. [Entregar llamadas a un trunk SIP](/docs/guides/voice/receiving-calls#deliver-calls-to-a-sip-trunk) explica esto y las rutas `trunk`, `forward` y `reject`. ## Conciliar tus números Recorre la lista con el tamaño de página más grande. Pasa el `next_cursor` de cada página como `NEXT_CURSOR` para leer la siguiente, hasta que `next_cursor` sea `null`. La lista no devuelve un conteo total. ```bash curl "$BIRD_API_URL/v1/numbers?limit=100" \ --header "Authorization: Bearer $BIRD_API_KEY" curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Los filtros de lista de Telserv se corresponden con los de Bird así: | Filtro de Telserv en `GET /numbers` | Filtro de Bird en `GET /v1/numbers` | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number`, que coincide con el inicio del número | `prefix` sin `country_code`, que coincide con los dígitos desde el inicio del número completo | | `prefix`, que equivale al código de acceso y de área, como `3170` | `country_code` con `prefix` establecido en los dígitos nacionales: `country_code=NL&prefix=70` | | `reference` con un valor parcial | `search`, que coincide con parte del número, nombre o referencia, sin distinguir mayúsculas | | `reference` con un valor exacto entrecomillado | `reference`, que devuelve los números con esa referencia exacta. La coincidencia distingue mayúsculas y minúsculas | | Novedad en Bird | `number` devuelve un número completo indicado con su código de país, con o sin `+` o `00`: `+31612345678`, `31612345678` y `0031612345678` encuentran el mismo número | [Buscar un número en tu lista](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) detalla cada filtro. Cada entrada incluye `pricing`, con `recurring_price` por `recurring_period` y `intervals_per_charge`. A menos que el precio esté fijado para el número, `recurring_price` es la tarifa actual de tu organización, y cada renovación cobra la tarifa vigente en el momento de renovar, por lo que un cargo ya facturado puede diferir de ella. [Listar todos los números que tienes](/docs/guides/numbers/managing-numbers#list-every-number-you-hold) explica en qué moneda se cobra cada número, cuándo `pricing` o sus precios son `null` y qué hacer cuando `pricing.error` está definido. Un número liberado desaparece de esta lista, y leerlo por `number_id` responde `404`. Si lo pediste en Bird, su pedido completado permanece en [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders). ## Liberar un número Ambas solicitudes se aplican a un número dedicado, por su identificador `nda_`; un número compartido se rechaza con [`E14002`](/docs/api/errors/E14002). Para conservar el número hasta el final del período que ya pagaste, cancélalo: ```bash curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: cancel-CUST-778812" ``` Una respuesta `202` devuelve el número con `releases_at`, el final de su período pagado. El número conserva su estado actual hasta entonces, su suscripción no se renueva y se libera en ese momento. Pedirlo de nuevo devuelve el mismo `releases_at`, y una cancelación no se puede deshacer. Un número sin suscripción asociada se libera de inmediato, y la respuesta es `200` con el `status` del número establecido en `released`. Para liberar el número ahora, incluido uno ya programado para cancelación: ```bash curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Idempotency-Key: release-CUST-778812" ``` Una respuesta `204` significa que el número está liberado, con efecto inmediato. El resto del período actual no se reembolsa. Mientras un pago de renovación del número esté vencido, ambas solicitudes responden `409` con [`E03015`](/docs/api/errors/E03015) hasta que se pague. Ninguna solicitud acepta una fecha, así que conserva en tu lado el calendario que enviaste a Telserv como `requestedCancelDate`. Para conservar un número hasta su fecha, cancélalo cuando la fecha caiga dentro de su período de facturación actual: se libera cuando ese período termina, en la fecha o después. Para liberarlo exactamente en la fecha, libéralo ese día. [Liberar un número](/docs/guides/numbers/managing-numbers#release-a-number) explica qué hace cada solicitud con el número, sus cargos y un reintento. ## Hacer una llamada de prueba a tu número Para verificar una ruta de extremo a extremo, haz una llamada al número desde otro número que tu espacio de trabajo pueda presentar como identificador de llamante. El país del número debe estar habilitado en tus [destinos de voz](/docs/guides/voice/destinations), o la llamada no se completa. La solicitud de abajo ejecuta una secuencia en línea que cuelga cuando la llamada es respondida, así que no se necesita una secuencia guardada. Realiza una llamada real, y se aplican los cargos normales de llamada. Guarda la solicitud como `test-call.json`. Pon en `from` el identificador de llamante que presentas, un número propio o [verificado](/docs/guides/voice/caller-ids) de tu espacio de trabajo, y en `to` el número que quieres probar: ```json { "from": "+31612345679", "to": "+31612345678", "sequence": { "definition": { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "entry", "type": "trigger.start_call", "type_version": 1, "config": {}, "input": {}, "connections": { "event": { "node_id": "end", "port": "input" } } }, { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} } ] }, "entry_node_id": "entry", "trigger_data": {} } } ``` Envíala: ```bash curl --request POST "$BIRD_API_URL/v1/voice/calls" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \ --data-binary @test-call.json ``` Asigna a `TEST_CALL_KEY` un valor nuevo en cada prueba, y reutilízalo cuando reintentes la misma prueba tras agotarse el tiempo de espera o tras un resultado ambiguo: la misma clave y solicitud en un plazo de tres horas reproducen la primera aceptación en lugar de realizar una segunda llamada. Una respuesta `202` acepta la llamada y devuelve su `initial_leg_id`. La aceptación no demuestra que la llamada se conectó: lee el tramo con [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg), o lista los tramos realizados al número con [`GET /v1/voice/legs`](/docs/api/reference/list-voice-legs) y su filtro `to`, y comprueba que tu equipo recibió la llamada. [Crear una llamada de voz](/docs/guides/voice/create-calls) cubre los requisitos de identificador de llamante y destino, y las reglas de reintento. ## Próximos pasos - [Comprar y liberar un número](/docs/guides/numbers/buying-numbers) - [Gestionar tus números de teléfono](/docs/guides/numbers/managing-numbers) - [Presentar la documentación de titularidad de un número](/docs/guides/numbers/ownership-paperwork) - [Recibir llamadas](/docs/guides/voice/receiving-calls) - [Trunks SIP](/docs/guides/voice/sip-trunks) - [Idempotencia](/docs/guides/idempotency) ## Related resources - [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer) - [SMS numbers](/sms-api/features/numbers) (product) - [Number types](/docs/guides/numbers/number-types) (docs) [Get an implementation brief](/learn/workspace?topic=phone-numbers)