> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Usa tus propios números (VoIP, API)
> Conecta Twilio o Telnyx — o cualquier troncal SIP — e importa números de teléfono desde tu cuenta existente.
Los números de demostración son adecuados para crear prototipos, pero el tráfico de producción debe
usar números que posees a través de tu propio proveedor de VoIP. Esta guía te muestra
el flujo de tres pasos: **probar credenciales → crear
conexión → importar números → verificar**.
El panel tiene un recorrido guiado de todo este flujo en
**Conexiones → VoIP** (`/dashboard/voip-connections`): una
configuración guiada de Telnyx que te acompaña en la creación de la cuenta y las claves de API, una
ruta para conectar una cuenta existente y un formulario manual de SIP con un generador de guías de configuración con IA.
## Proveedores compatibles
| Proveedor | ID de `provider` | Notas |
| ---------- | ---------------- | ----------------------------------------------------------------------------- |
| Twilio | `twilio` | Clave de API + secreto |
| Telnyx | `telnyx` | Clave de API; incorporación guiada disponible (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire` | **Próximamente** — conéctate mediante SIP manual hoy |
| Vonage | `vonage` | **Próximamente** — conéctate mediante SIP manual hoy |
| SIP manual | `manual` | Cualquier troncal SIP — usa tu propia configuración |
## 1. Probar las credenciales
Antes de crear una conexión VoIP persistente, prueba las credenciales del proveedor
para confirmar que funcionan. Esto devuelve un
`verification_evidence_id` que pasas al paso de creación para que no se cobren dos veces
las credenciales por las pruebas.
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "telnyx",
"credentials": { "apiKey": "KEY...", "connectionId": "123456" },
"sip_config": { "domain": "acme.sip.telnyx.com" }
}'
```
```json Response theme={null}
{
"status": "pass",
"verification_evidence_id": "b9a2...",
"suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
"checks": {
"credentials_valid": true,
"inbound_reachable": true,
"outbound_authorized": true
}
}
```
Si alguna verificación falla, el `status` de la respuesta será `fail` y `checks`
mostrará qué paso falló. Corrige la configuración del proveedor
(asignación de troncal, lista de IP permitidas, autorización de llamadas salientes) y vuelve a intentarlo.
## 2. Crear la conexión
Pasa el `verification_evidence_id` que acabas de obtener:
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/voip-connections \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Telnyx Main",
"provider": "telnyx",
"setup_method": "api_key",
"credentials": { "apiKey": "KEY...", "connectionId": "123456" },
"sip_config": { "domain": "acme.sip.telnyx.com" },
"verification_evidence_id": "b9a2..."
}'
```
La respuesta es un [objeto VoipConnection](/api-reference/voip-connections#connection-object)
con `status="connected"`. Las credenciales se almacenan en el servidor y nunca
se devuelven en texto sin formato mediante solicitudes GET posteriores; para rotarlas, ejecuta un nuevo
`test` y PATCH con la nueva evidencia.
## 3. Listar e importar números
Revisa los números visibles para tus credenciales que aún no estén
en una organización de ThunderPhone:
```bash theme={null}
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Luego importa los que quieras:
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"numbers": ["+15550001234", "+15550009999"]}'
```
Cada importación se convierte en un [recurso de número telefónico](/api-reference/phone-numbers)
en tu organización con `source="voip"` y `status="provisioning"`.
## 4. Verifica cada número importado
La importación registra el número como *disponible*; para enrutar llamadas
a través de él se necesita una verificación de ida y vuelta (comprobación de marcado entrante +
sondeo de autorización saliente).
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Si se realiza correctamente, `voip_verification_status` cambia a `verified` y el
número pasa a tener `status="active"`. Si falla, la respuesta especifica
qué falló; corrígelo (a menudo es una asignación de troncal faltante en el
panel del proveedor) y vuelve a llamar.
## 5. Asigna agentes y atiende una llamada
Con el número verificado, asigna agentes entrantes/salientes de la
misma forma que con un número de demostración. Consulta
[Gestionar llamadas entrantes](/es/guides/handle-inbound-calls) y
[Realizar llamadas salientes](/es/guides/place-outbound-calls).
## Rotación de credenciales
Cuando se rota una clave de proveedor, vuelve a ejecutar el flujo de prueba y actualización:
```bash theme={null}
# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credentials": { "apiKey": "NEW_KEY..." },
"verification_evidence_id": "fresh-evidence-id"
}'
```
La conexión se mantiene; no es necesario volver a importar los números.
***
## Próximos pasos
Todos los campos de las respuestas de conexión, evidencia e importación.
Asigna agentes, transfiere entre organizaciones y libera números.
Ahora que eres propietario del número, comienza a realizar llamadas salientes.