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

# 자체 번호 가져오기(VoIP, API)

> Twilio 또는 Telnyx(또는 모든 SIP 트렁크)를 연결하고 기존 계정에서 전화번호를 가져옵니다.

프로토타이핑에는 데모 번호로 충분하지만, 운영 트래픽에는 자체 VoIP 제공업체를 통해 보유한 번호를 사용해야 합니다. 이 가이드에서는 **자격 증명 테스트 → 연결 생성 → 번호 가져오기 → 확인**의 3단계 흐름을 안내합니다.

<Note>
  대시보드의 **연결 → VoIP** (`/dashboard/voip-connections`)에서 이 전체 흐름의 가이드 버전을 사용할 수 있습니다. 여기에는 계정 생성 및 API 키 설정을 안내하는 Telnyx 가이드 설정, 기존 계정 연결 경로, AI 설정 가이드 생성기가 포함된 수동 SIP 양식이 있습니다.
</Note>

## 지원 제공업체

| 제공업체       | `provider` ID | 참고 사항                                                |
| ---------- | ------------- | ---------------------------------------------------- |
| Twilio     | `twilio`      | API 키 + 시크릿                                          |
| Telnyx     | `telnyx`      | API 키, 가이드 온보딩 사용 가능 (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire`  | **출시 예정** — 현재는 수동 SIP를 통해 연결                        |
| Vonage     | `vonage`      | **출시 예정** — 현재는 수동 SIP를 통해 연결                        |
| 수동 SIP     | `manual`      | 모든 SIP 트렁크 — 자체 구성 사용                                |

## 1. 자격 증명 테스트

저장된 VoIP 연결을 생성하기 전에 제공업체 자격 증명을 확인하여 정상 작동하는지 검증합니다. 이 요청은 생성 단계에 전달할 `verification_evidence_id`를 반환하므로, 테스트에 대해 자격 증명 비용이 중복 청구되지 않습니다.

```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
  }
}
```

검사 중 하나라도 실패하면 응답 `status`는 `fail`이 되며, `checks`에 실패한 단계가 표시됩니다. 제공업체 측 구성(트렁크 할당, IP 허용 목록, 발신 권한)을 수정한 후 다시 시도합니다.

## 2. 연결 생성

방금 받은 `verification_evidence_id`를 전달합니다.

```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..."
  }'
```

응답은 `status="connected"` 상태의 [VoipConnection 객체](/api-reference/voip-connections#connection-object)입니다. 자격 증명은 서버 측에 저장되며 이후 GET 요청에서 일반 텍스트로 반환되지 않습니다. 교체하려면 새 `test`를 실행하고 새 증거와 함께 PATCH합니다.

## 3. 번호 나열 및 가져오기

자격 증명에서 볼 수 있고 아직 ThunderPhone 조직에 포함되지 않은 번호를 확인합니다.

```bash theme={null}
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

그런 다음 원하는 번호를 가져옵니다.

```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"]}'
```

가져온 각 번호는 조직 내에서 `source="voip"` 및 `status="provisioning"` 상태의 [전화번호 리소스](/api-reference/phone-numbers)가 됩니다.

## 4. 가져온 각 번호 확인

가져오면 번호가 *사용 가능*으로 등록됩니다. 실제로 해당 번호로 통화를 라우팅하려면 왕복 확인(인바운드 수신 확인 + 아웃바운드 승인 확인)이 필요합니다.

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

성공하면 `voip_verification_status`가 `verified`로 변경되고 번호는 `status="active"` 상태가 됩니다. 실패하면 응답에서 실패한 항목을 명시합니다. 이를 수정하고(대개 제공업체 대시보드에서 트렁크 할당이 누락된 경우) 다시 호출합니다.

## 5. 에이전트 할당 및 통화 수신

번호를 확인한 후에는 데모 번호와 동일한 방식으로 인바운드/아웃바운드 에이전트를 할당합니다. [인바운드 통화 처리](/ko/guides/handle-inbound-calls) 및 [아웃바운드 통화 발신](/ko/guides/place-outbound-calls)을 참조하세요.

## 자격 증명 교체

제공업체 키가 교체되면 테스트 후 업데이트 흐름을 다시 실행합니다.

```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"
  }'
```

연결은 그대로 유지되므로 번호를 다시 가져올 필요가 없습니다.

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="VoIP 연결 참조" icon="phone-volume" href="/api-reference/voip-connections">
    연결, 증거 및 가져오기 응답의 모든 필드입니다.
  </Card>

  <Card title="전화번호 참조" icon="phone" href="/api-reference/phone-numbers">
    에이전트 할당, 조직 간 이전, 번호 해제를 수행합니다.
  </Card>

  <Card title="아웃바운드 통화 발신" icon="arrow-up-right" href="/ko/guides/place-outbound-calls">
    이제 번호를 소유했으므로 아웃바운드 통화를 시작합니다.
  </Card>
</CardGroup>