--- title: "Presenta la documentación de titularidad de un número" description: "Presenta la documentación de titularidad que un país exige para un número de teléfono, desde el panel o con la API, sigue su revisión y corrige las respuestas rechazadas." canonical: "https://bird.com/es-es/documentacion/guides/numbers/ownership-paperwork" --- # Presenta la documentación de titularidad de un número Algunos países exigen saber quién es el titular de un número antes de que pueda cursar tráfico. Hasta que se acepte esa documentación y se complete el registro del número, el número está asignado a ti y se te factura, pero su `status` es `pending_ownership_registration`: no cursa llamadas de voz entrantes ni salientes y no envía SMS. El número cursa tráfico cuando su `status` es `active` y su `ownership.blocked_at` es `null`. Presentas la documentación desde el panel o con la API, y ambas vías usan los mismos requisitos, las mismas reglas de revisión y el mismo proceso de registro. El campo `ownership.next` del número indica cada paso, incluido cuándo presentar una nueva solicitud. Las respuestas que presentas son una declaración legal hecha en nombre de tu empresa. Una vez aceptadas, se transmiten al operador o al regulador de ese país con el nombre de la empresa que describen. Por eso, confírmalas con la persona responsable antes de presentarlas y no dejes que un proceso automatizado presente respuestas que nadie ha revisado. ## Antes de empezar - Para presentar desde el panel, tu rol en el espacio de trabajo debe permitir editar los datos de cumplimiento normativo. Sin ese permiso, el número muestra su estado de titularidad, pero no el botón para presentar. - Para presentar mediante los endpoints independientes de cumplimiento normativo, necesitas una [clave de API](/docs/guides/authentication) con el ámbito `compliance` en nivel de escritura. Una clave con nivel de lectura puede consultar los requisitos y el progreso de la revisión, pero no presentar. Para leer el número también necesitas el ámbito `numbers` en nivel de lectura. En el selector de claves del panel, `compliance` está en **Compliance**. - El identificador `nda_` del número, obtenido de [`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers). En [Buscar un número en tu lista](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) se explica cómo consultarlo. Los ejemplos de API leen tu clave de `BIRD_API_KEY`, su [host regional](/docs/api/regions) de `BIRD_API_URL` y el identificador del número de `NUMBER_ID`. Cada paso posterior indica la variable que define. Los comandos `jq` extraen un campo de una respuesta; si no usas `jq`, lee el campo manualmente. ## Comprueba si un número necesita documentación Lee el número con [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number): ```bash curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Guarda el `country_code` del número como `COUNTRY_CODE`; tanto la lectura de requisitos como el envío lo necesitan: ```bash COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \ --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code) ``` `ownership` es `null` cuando el país del número no exige documentación. También es `null` cuando no pudimos leer el progreso de la documentación y el número no tiene ningún bloqueo registrado; en ese caso, vuelve a leer el número. En los demás casos contiene: - `status`: `needs_input` significa que faltan respuestas o que hay que corregirlas, `under_review` significa que tus respuestas están en revisión, `approval_pending` significa que la documentación se aceptó y el registro sigue pendiente; las llamadas y los SMS salientes siguen bloqueados mientras `blocked_at` tenga valor. `approved` significa que el registro está aprobado, aunque las llamadas y los SMS salientes siguen bloqueados mientras `blocked_at` tenga valor. `not_required` significa que no se pide nada más. `rejected` significa que el envío se cerró o que venció un plazo de corrección, y ya no admite más correcciones. Contacta con soporte para que lo reabran. `unknown` significa que no se pudo leer el estado; vuelve a leer el número. - `next`: los pasos que hacen avanzar la documentación, en orden. Un paso `wait` significa que ahora no se te pide nada. Vuelve a leerlo después de cada cambio. - `submission_id`: el envío más reciente del número, cuando ya existe alguno. - `blocked_at`: cuándo empezó el bloqueo por titularidad, o `null` cuando ya se ha levantado. El bloqueo impide las llamadas de voz entrantes y salientes y los SMS salientes. [El estado de un número asignado](/docs/guides/numbers/overview#the-status-of-an-allocated-number) explica cómo se relaciona `ownership` con el `status` propio del número. ## Presentar la documentación desde el panel 1. Abre el número desde la página [**Numbers**](https://bird.com/dashboard/w/numbers). Su fila **Ownership** muestra el estado de la documentación y los pasos siguientes. 2. Cuando el estado sea **Details needed**, selecciona **Update ownership details**. Se abre el formulario **Prove ownership of this number**. 3. Elige la empresa titular del número o describe una nueva; después responde a cada elemento y sube los documentos que pida. Los elementos que ofrecen un formulario en blanco incluyen un enlace para que lo descargues, lo completes y lo vuelvas a subir. 4. Selecciona **Submit answers**. La fila **Ownership** pasa a **Under review**. Si un revisor rechaza una respuesta, la fila vuelve a **Details needed**: selecciona de nuevo **Update ownership details**, corrige las respuestas que muestra el formulario y, para enviarlas, selecciona **Update ownership details** al final del formulario. Si todavía no hay formulario para el país del número, la página del formulario muestra **Ownership form unavailable**. Ponte en contacto con el equipo de soporte para solicitarlo para ese país. ## Presentar la documentación con la API Para presentar la documentación con la API, consulta qué pide el país, sube cada documento, envía todas las respuestas a la vez y luego consulta el número para seguir la revisión. ### Consulta qué pide el país Consulta los requisitos del número con [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements). Establece `subject_kind` en `number`, `subject_id` en el identificador `nda_` del número y `country_code` en el `COUNTRY_CODE` propio del número: ```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" ``` La respuesta indica el `program` con el que se registra el número, que depende de su tipo de número; guárdalo como `PROGRAM`. También enumera en `fields` cada elemento que debes responder, en el orden en que deben presentarse. Para cada campo: - `key` es la clave con la que envías la respuesta. - `data_type` indica cómo responderlo. Un campo `document` admite un archivo subido; todos los demás tipos admiten una cadena, así que un número se envía como `"1500"` y un sí o no como `"true"`. Un campo `enum` acepta uno de sus `options`. - `required` indica si la aprobación depende de él, y `help_text` describe cómo es una respuesta válida. - `max_items` aparece en los campos que admiten más de una respuesta. - `template_url` enlaza un formulario en blanco para descargarlo, completarlo y volver a subirlo, cuando el campo lo tiene. - `state` indica en qué punto está el elemento: `not_supplied` antes de que respondas y después `supplied`, `in_review`, `approved` o `rejected`, con el `reason` del revisor en un elemento rechazado. Una respuesta aceptada puede pasar más adelante a `expired` y entonces debes aportarla de nuevo; `not_applicable` marca un elemento que no se aplica a tu caso. `submission_id` es `null` hasta que presentas la documentación. `needs_input` es `true` mientras algún elemento esté pendiente de ti. Un `422` con [`E19001`](/docs/api/errors/E19001) significa que todavía no tenemos formulario de titularidad para ese país. Ponte en contacto con soporte para solicitarlo. ### Sube cada documento Sube cada archivo que pida un campo `document` con [`POST /v1/compliance/attachments`](/docs/api/reference/create-compliance-attachment), como cuerpo `multipart/form-data` con los bytes en una parte `file`. 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" ``` Se aceptan archivos PNG, JPEG y PDF de hasta 10 MB, y el tipo se determina a partir del contenido del archivo. Una respuesta `201` devuelve el nuevo adjunto. Si vuelves a subir el mismo archivo, se devuelve el primer adjunto con `200`, así que reintentar una subida no crea un duplicado. Un adjunto que ninguna solicitud cita caduca a los siete días. El `download_url` del adjunto es un enlace firmado válido durante 24 horas desde que obtuviste el adjunto. Para conseguir uno nuevo, lista tus adjuntos con [`GET /v1/compliance/attachments`](/docs/api/reference/list-compliance-attachments), o descarga los bytes directamente con [`GET /v1/compliance/attachments/{attachment_id}`](/docs/api/reference/get-compliance-attachment). ### Envía todas las respuestas Presenta las respuestas con [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission). Envía `subject_kind` y `subject_id`, el `program` que indicó la lectura de requisitos y el `country_code` del número. En `answers`, envía una entrada por cada campo cuyo `required` sea `true` y una por cada campo opcional para el que tengas una respuesta real; omite un campo opcional en lugar de inventarle un valor. Un campo con tipo recibe `value`, un campo de documento recibe `attachment_id` y un campo con `max_items` recibe `values` o `attachment_ids`. Guarda el cuerpo como `submission.json`, con tus valores en lugar de ``, ``, `` y ``. El ejemplo muestra tres de las respuestas que pide un formulario: ```json { "subject_kind": "number", "subject_id": "", "program": "", "country_code": "", "answers": [ { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }, { "key": "business_registration_number", "value": "90012768" }, { "key": "business_registration_certificate", "attachment_id": "" } ] } ``` Envíalo con un `Idempotency-Key`. Reutiliza la clave solo para reintentar el mismo cuerpo: un rechazo puede quedar guardado y repetirse, así que, tras un `422`, corrige el cuerpo y envíalo con una clave nueva. [Idempotencia](/docs/guides/idempotency) explica qué se guarda. ```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-$NUMBER_ID" \ --data-binary @submission.json ``` No hay borradores: esta solicitud presenta las respuestas para su revisión, así que debe incluir todas las respuestas obligatorias. Si omites un campo obligatorio o el formulario rechaza una respuesta, recibes un `422` con [`E01001`](/docs/api/errors/E01001) y una entrada en `details` por cada campo, indicado en `param`, y no se presenta nada. Una respuesta `201` devuelve la solicitud con todas sus respuestas. Guarda su `id`, el identificador `csb_` de la solicitud, como `SUBMISSION_ID`. Una empresa que describe tu espacio de trabajo es una identidad. Crea una en el **Identity Center** del panel o con [`POST /v1/compliance/identities`](/docs/api/reference/create-compliance-identity), enviando su `name` visible. Un envío de número también puede incluir un `identity` en línea en lugar de un `identity_id`. El `identity_id` de la respuesta del envío indica la nueva identidad, que `POST /v1/compliance/identities` devuelve como `id`; reutilízala para números posteriores en lugar de crear otra. Para presentar la documentación en nombre de una identidad, añade su `identity_id`, y las respuestas que guarda completan las que omitas. [`GET /v1/compliance/identities`](/docs/api/reference/list-compliance-identities) enumera las identidades de empresa. Las respuestas de un solo valor que presentas se guardan en la identidad sea cual sea la decisión de la revisión, de modo que el siguiente envío que la indique parte de ellas; los documentos y las respuestas de varios valores se piden de nuevo cada vez. Usa una identidad por empresa: si presentas documentación para varios clientes finales, da a cada uno su propia identidad; de lo contrario, las respuestas aprobadas de un cliente completarán las de otro. Sigue `ownership.next` en lugar de volver a presentar la documentación. Un número tiene un envío por cada versión del formulario de su país, así que, si vuelves a presentarla mientras ese envío está abierto, recibes `409` con [`E19009`](/docs/api/errors/E19009): corrígelo en su lugar, como se explica en [Corregir una respuesta rechazada](#corregir-una-respuesta-rechazada). Cuando reabrimos un envío cerrado tras un cambio en el formulario, `next` pide un envío nuevo a `POST /v1/compliance/submissions`. ### Seguir la revisión Cada respuesta se revisa por separado. Vuelve a leer el número y comprueba `ownership.status` y `ownership.next`, como en [Comprobar si un número necesita documentación](#comprueba-si-un-número-necesita-documentación). Para ver cómo se valoró cada respuesta, lee el envío con [`GET /v1/compliance/submissions/{submission_id}`](/docs/api/reference/get-workspace-compliance-submission) o vuelve a leer los requisitos: cada campo incluye su `state` y, si se rechaza, su `reason`. Cuando termina una revisión, enviamos el resultado por correo electrónico a los propietarios de tu organización y, si existe, a la última persona registrada que presentó o corrigió el envío. Una primera presentación con una clave API se notifica a los propietarios. Una corrección posterior con una clave API mantiene como destinataria a la persona registrada anteriormente. Tu integración conoce el resultado leyendo `ownership.status`. ### Corregir una respuesta rechazada Envía las respuestas de sustitución a [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission). Incluye solo las respuestas que sustituyes; las demás se mantienen como están. Toma el `submission_id` del `ownership` del número o de la lectura de requisitos: ```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-$NUMBER_ID" \ --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}' ``` Una respuesta `200` devuelve el envío con tus sustituciones, que vuelven a revisión. Cuando ya no queda ninguna respuesta obligatoria rechazada, caducada o pendiente, el `ownership.status` del número vuelve a `under_review`. Sustituye las respuestas cuyo `state` sea `rejected`, `expired` o `not_supplied`. Si pedimos una corrección después de aceptar tus respuestas, también puedes sustituir una respuesta cuyo `editable_for_verifier_repair` sea `true` hasta que se cierre esa corrección. Una respuesta en cualquier otro estado, como una que sigue en revisión o que se aceptó fuera de una corrección que pedimos, devuelve `422` con [`E19003`](/docs/api/errors/E19003). Un documento de sustitución es una subida nueva: súbelo primero y envía su `attachment_id`. ## Presentar la documentación con el pedido Si conoces las respuestas cuando compras el número, envíalas en el bloque `compliance` del pedido en [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order), con la misma estructura `answers` que usa el envío. Para leer lo que pide el país antes de tener el número, llama a la lectura de requisitos sin `subject_id`, con `COUNTRY_CODE` y `NUMBER_TYPE` establecidos en el `country_code` y el `number_type` del número en [`GET /v1/numbers/available`](/docs/api/reference/list-available-numbers): ```bash curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \ --header "Authorization: Bearer $BIRD_API_KEY" ``` Un pedido con un bloque `compliance` usa el ámbito `numbers` que ya tiene el pedido, con nivel de escritura. Una vez aceptado el pedido, se completa en cualquier caso: si se rechaza la presentación del bloque `compliance`, el número sigue siendo tuyo y presentas la documentación con `POST /v1/compliance/submissions`, como en [Enviar todas las respuestas](#envía-todas-las-respuestas). Cuando se presentan las respuestas, el número nuevo muestra `under_review` con su `submission_id`. [Comprar y liberar un número](/docs/guides/numbers/buying-numbers) trata el pedido en sí. ## Reutilizar una identidad de empresa Usa [`GET /v1/compliance/identities/{identity_id}`](/docs/api/reference/get-compliance-identity) para leer la empresa y sus respuestas guardadas. Las respuestas guardadas pueden incluir un `state` de revisión, `reason` y `decided_at`; un valor sin decisión de revisión puede omitir su estado. Cambia el nombre de la empresa con [`PATCH /v1/compliance/identities/{identity_id}`](/docs/api/reference/update-compliance-identity) o elimínala con [`DELETE /v1/compliance/identities/{identity_id}`](/docs/api/reference/delete-compliance-identity). Las lecturas necesitan `compliance:read`; la creación, el cambio de nombre y la eliminación necesitan `compliance:write`. Para verificar la propia empresa, crea primero la identidad. Lee los requisitos con `subject_kind=identity`, su identificador `cid_` como `subject_id`, `program=business` y `country_code=ZZ`. Presenta la documentación para esa misma identidad. Una identidad en línea en un envío de número no sustituye este flujo de verificación de identidad. La revisión usa los datos de empresa que envías, los contactos declarados y las pruebas de verificación. Presentar la documentación con una clave de API o desde el panel no establece una relación comercial distinta. Mantén los datos de contacto exactos y aporta las pruebas que pide el formulario. ## Presentar la documentación para un remitente SMS La documentación de un remitente SMS usa las mismas solicitudes de requisitos, archivos adjuntos, envío y corrección, con el registro del remitente como objeto. [Registra un remitente SMS con API](/docs/guides/sms/sender-registration-api) explica cómo obtener ese registro y consultar antes su precio. ## Cuando se rechaza una solicitud | Respuesta | Qué significa | Qué hacer | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `403` con `E02035` | En una escritura de cumplimiento independiente, la clave no tiene el ámbito `compliance` o solo lo tiene con nivel de lectura. | Usa una clave con `compliance` con nivel de escritura. | | `422` con `E19001` | Todavía no tenemos un formulario de titularidad para el país del número. | Contacta con el soporte para solicitar ese país. | | `422` con `E19013` | La lectura de requisitos no incluía `subject_id` ni `program`. | Envía el identificador `nda_` del número, o `program` si consultas los requisitos antes de comprarlo. | | `422` con `E01001` | En el envío falta un campo obligatorio o hay una respuesta no válida. | Corrige cada campo indicado en `details` y vuelve a enviar el envío completo con una nueva clave de idempotencia. | | `409` con `E19009` | El número ya tiene un envío para su formulario actual. | Sustituye las respuestas que lo necesiten con la solicitud de reenvío de respuestas. | | `409` con `E01009` | La solicitud de reenvío apunta a un envío cerrado. | Contacta con soporte. Si lo reabrimos, presenta lo que indique `ownership.next`. | | `422` con `E19003` | Un reemplazo apunta a una respuesta que está en revisión o que se aceptó fuera de una corrección que solicitamos. | Reemplaza solo las respuestas cuyo `state` sea `rejected`, `expired` o `not_supplied`. | | `404` con `E01008` | El número no está en este espacio de trabajo, o `country_code` no es el país del número. | Envía el `country_code` que indica `GET /v1/numbers/{number_id}`. | [Errores](/docs/guides/errors) explica el cuerpo de la respuesta de error y su `remediation`. ## Próximos pasos - [Descripción general de los números](/docs/guides/numbers/overview) - [Comprar y liberar un número](/docs/guides/numbers/buying-numbers) - [Gestionar tus números de teléfono](/docs/guides/numbers/managing-numbers) - [Migrar de Telserv a Bird](/docs/guides/numbers/migrate/telserv) ## 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)