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 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. En Buscar un número en tu lista se explica cómo consultarlo.

Los ejemplos de API leen tu clave de BIRD_API_KEY, su host regional 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}:

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:

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 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. 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. 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:

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 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, 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:

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, o descarga los bytes directamente con GET /v1/compliance/attachments/{attachment_id}.

Envía todas las respuestas

Presenta las respuestas con POST /v1/compliance/submissions. 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 <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> y <ATTACHMENT_ID>. El ejemplo muestra tres de las respuestas que pide un formulario:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<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 explica qué se guarda.

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 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, 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 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: corrígelo en su lugar, como se explica en 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. Para ver cómo se valoró cada respuesta, lee el envío con GET /v1/compliance/submissions/{submission_id} 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. 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:

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. 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, 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:

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. Cuando se presentan las respuestas, el número nuevo muestra under_review con su submission_id. Comprar y liberar un número trata el pedido en sí.

Reutilizar una identidad de empresa

Usa GET /v1/compliance/identities/{identity_id} 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} o elimínala con DELETE /v1/compliance/identities/{identity_id}. 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 explica cómo obtener ese registro y consultar antes su precio.

Cuando se rechaza una solicitud

Errores explica el cuerpo de la respuesta de error y su remediation.

Próximos pasos

• Descripción general de los números
• Comprar y liberar un número
• Gestionar tus números de teléfono
• Migrar de Telserv a Bird