# 문자 발신번호 (/docs/sender-numbers)

## 문자 발신번호

문자(SMS·LMS·MMS)는 계정에 등록해 승인된 발신번호로만 보낼 수 있습니다.
승인되지 않은 번호를 `From` 으로 보내면 `400 from_not_registered` 로 거절됩니다.

발신번호는 콘솔 「문자 › 문자 발신번호」, REST API, MCP 에서 관리합니다. 어디서 등록해도 같은 목록에 들어갑니다.

| 하는 일 | REST API | MCP 도구 |
| --- | --- | --- |
| 목록 조회 | [`GET /sender-numbers`](/docs/api/sendernumbers/listSenderNumbers) | `list_sender_numbers` |
| 등록 | [`POST /sender-numbers`](/docs/api/sendernumbers/createSenderNumber) | `register_sender_number` |
| 삭제 | [`DELETE /sender-numbers/{senderNumberId}`](/docs/api/sendernumbers/deleteSenderNumber) | `delete_sender_number` |

OAuth 토큰으로 호출할 때 조회는 `read:messages`, 등록·삭제는 `write:messages` 권한이 필요합니다.

## 번호를 발급하면 자동으로 등록됩니다

070번호·대표번호를 발급하면 회선 수 한도 안에서 바로 문자 발신번호로 등록됩니다.
발급 응답의 `smsSender` 에 결과가 실립니다.

```json
"smsSender": { "registered": true, "senderNumberId": "cmh1sn0000001" }
```

```json
"smsSender": { "registered": false, "reason": "sender_number_limit_reached" }
```

`registered` 가 `false` 여도 번호 발급은 성공입니다. 그 번호로는 아직 문자를 보낼 수 없으며, `reason` 을 해결한 뒤 등록 API 로 등록할 수 있습니다.

## 등록

```bash
curl -X POST https://api.claw-ops.com/v1/accounts/$ACCOUNT_ID/sender-numbers \
  -H "Authorization: Bearer $CLAWOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "070-5236-1008"}'
```

- 이 계정이 한국AI통신에서 개통한 070번호·대표번호만 등록할 수 있습니다.
- 등록하면 바로 승인되어 발송에 쓸 수 있습니다.
- 한 번에 한 번호씩 등록합니다.
- 번호는 하이픈·`+82` 형식 모두 입력할 수 있습니다.
- 이미 등록된 번호면 `409 sender_number_already_registered` 를 돌려줍니다. 이 경우 번호는 이미 발송에 쓸 수 있는 상태입니다.
- 다른 통신사업자 명의의 대표번호는 지금 문자 발신번호로 등록할 수 없습니다.

## 회선 수 한도

070번호·대표번호 발신번호는 명의(개인은 본인확인 정보, 법인은 사업자등록번호)마다 등록할 수 있는 회선 수가 정해져 있습니다.

| 명의 | 070번호·대표번호 |
| --- | --- |
| 개인 | 5회선 |
| 법인 | 종사자 수 이내 |

- 같은 명의로 다른 계정에 등록한 번호도 함께 셉니다.
- 승인 대기 중인 번호도 회선 수에 듭니다.
- 법인은 콘솔에서 종사자 수 증빙을 올려 확인받기 전까지 등록할 수 없습니다.
- 관리번호(최종이용자에게 배정한 번호)는 최종이용자 명의로 따로 셉니다.

목록 조회 응답의 `limit` 에서 이 계정 명의의 사용 회선 수(`used`)와 한도(`limit`), 도달 여부(`reached`)를 볼 수 있습니다.

## 목록 조회 응답

```json
{
  "senderNumbers": [
    { "id": "cmh1sn0000001", "number": "07052361008", "type": "070",
      "verificationMethod": "own_provisioned", "status": "approved",
      "createdAt": "2026-10-20T07:02:11.000Z" }
  ],
  "grace": [
    { "number": "07052753809", "expiresAt": "2026-11-03T14:59:59.000Z" }
  ],
  "limit": { "used": 1, "limit": 5, "reached": false }
}
```

| 필드 | 내용 |
| --- | --- |
| `senderNumbers` | 등록된 발신번호. `approved` 는 발송에 쓸 수 있고, `pending` 은 승인 대기입니다. |
| `grace` | 등록하지 않았지만 유예 기간이라 `expiresAt` 전까지 보낼 수 있는 번호입니다. 계속 쓰려면 만료 전에 등록하세요. |
| `limit` | 070번호·대표번호 회선 수 한도입니다. 명의를 확인할 수 없으면 `null` 이고, `limit` 이 `null` 이면 한도가 아직 정해지지 않았습니다. |

## 삭제

- 삭제하면 그 번호로는 바로 문자를 보낼 수 없고, 회선 수 한도에서도 빠집니다.
- 유예 기간인 번호도 삭제하면 유예가 함께 끝납니다.
- 번호 자체는 반납되지 않습니다. 전화는 그대로 쓸 수 있습니다.
- API·MCP 로는 한국AI통신에서 개통한 번호(`verificationMethod` 가 `own_provisioned`)만 삭제할 수 있습니다. 다른 발신번호는 콘솔에서 삭제합니다.

## 발신번호 범위를 지정한 API 키

발신번호 범위를 지정한 API 키는 발신번호를 조회만 할 수 있습니다.

- 목록에는 그 키의 범위 안 번호만 보입니다.
- 등록·삭제는 `403 api_key_sender_numbers_restricted` 로 거절됩니다.
- 등록·삭제는 범위를 지정하지 않은 API 키나 콘솔에서 하세요.

## 오류 코드

| HTTP | `code` | 뜻 |
| --- | --- | --- |
| `400` | `VALIDATION` | `number` 가 번호 형식이 아닙니다. |
| `403` | `api_key_sender_numbers_restricted` | 발신번호 범위를 지정한 API 키로 등록·삭제했습니다. |
| `404` | `sender_number_not_account_number` | 이 계정이 개통한 번호가 아닙니다. |
| `404` | `sender_number_not_found` | 삭제할 발신번호가 없습니다. |
| `409` | `sender_number_already_registered` | 이미 등록된 발신번호입니다. |
| `409` | `sender_number_limit_unknown` | 한도가 정해지지 않았습니다(법인 종사자 수 증빙 전). |
| `409` | `sender_number_holder_unresolved` | 명의를 확인할 수 없습니다. |
| `409` | `sender_number_not_deletable_via_api` | API 로 삭제할 수 없는 발신번호입니다. 콘솔에서 삭제하세요. |
| `422` | `sender_number_limit_reached` | 명의별 회선 수 한도에 도달했습니다. |
| `422` | `sender_number_not_registrable` | 한국AI통신에서 개통한 070번호·대표번호가 아닙니다. |