# 증명서 발급 (/docs/api/certificates/createCertificateRequest)
**POST /v1/accounts/{accountId}/certificate-requests**
```json
{
  "operationId": "createCertificateRequest",
  "summary": "증명서 발급",
  "description": "번호마다 증명서 PDF 를 바로 발급한다. 지금 종류는 `telecom_subscription`(통신서비스 이용증명원)뿐이다.\n\n- **발급 대상**: 한국AI통신이 개통한 070·대표번호만. 그 밖의 번호는 `422` 와 번호별 `blockers`.\n- **전부 아니면 전무**: 번호 하나라도 막히면 아무것도 발급하지 않는다.\n- **미리보기**: `dryRun: true` 면 같은 판정만 하고 `200` 으로 결과를 돌려준다.\n- **멱등**: 같은 `idempotencyKey` 재요청은 `200` 으로 1회차 결과.\n- **한도**: 계정당 하루(KST) 20장. 넘으면 `429` + `Retry-After`(다음 자정까지 초).\n- 문서의 「인입 연락처」는 요청자의 본인확인 휴대폰 번호다. API 키 요청은 계정 소유자의 번호.",
  "tags": [
    "Certificates"
  ],
  "parameters": [
    {
      "name": "accountId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "계정 ID",
      "example": "AC1a2b3c4d"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "description": "증명서 발급 요청. `type` 이 종류를 정한다 — 지금은 `telecom_subscription`(통신서비스 이용증명원)뿐이다.\n\n**발급 대상은 한국AI통신이 개통한 070·대표번호뿐이다.** 모바일 게이트웨이 번호, 발신번호 표기·문자\n발신번호로 등록한 타사 번호는 `number_not_carrier_issued` 로 막힌다.",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "telecom_subscription"
              ],
              "example": "telecom_subscription"
            },
            "numbers": {
              "type": "array",
              "minItems": 1,
              "maxItems": 10,
              "items": {
                "type": "string"
              },
              "description": "증명할 번호(1~10개). 번호마다 문서 1장.",
              "example": [
                "07012340001",
                "15880000"
              ]
            },
            "submitTo": {
              "type": "string",
              "maxLength": 40,
              "description": "제출처. 문서의 「제출처」 칸에 찍힌다.",
              "example": "예시 문자서비스"
            },
            "purpose": {
              "type": "string",
              "enum": [
                "external_service",
                "government",
                "internal",
                "other"
              ],
              "default": "other",
              "example": "external_service"
            },
            "deliveryEmail": {
              "type": "string",
              "format": "email",
              "description": "주면 발급 직후 PDF 를 이 주소로 보내고, 문서의 「발송방법」 칸에 찍힌다.",
              "example": "ops@example.com"
            },
            "idempotencyKey": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255,
              "description": "같은 키로 다시 요청하면 새로 발급하지 않고 1회차 결과를 `200` 으로 돌려준다.\n같은 키를 **다른 요청**에 쓰면 `422 idempotency_key_reused`.",
              "example": "cert-2026-10-16-001"
            },
            "dryRun": {
              "type": "boolean",
              "default": false,
              "description": "true 면 판정만 하고 아무것도 만들지 않는다(채번·원장·발송 없음).",
              "example": false
            }
          },
          "required": [
            "type",
            "numbers"
          ]
        },
        "example": {
          "type": "telecom_subscription",
          "numbers": [
            "07012340001"
          ],
          "submitTo": "예시 문자서비스",
          "purpose": "external_service",
          "deliveryEmail": "ops@example.com",
          "idempotencyKey": "cert-2026-10-16-001"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "멱등 재요청(1회차 결과, CertificateRequest) 또는 dryRun 결과(CertificateDryRunResponse)",
      "content": {
        "application/json": {
          "schema": {
            "oneOf": [
              {
                "type": "object",
                "description": "발급 요청 하나. 요청 1건에서 번호마다 증명서 1장이 나온다.",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "요청 코드",
                    "example": "CERT-7Q2K9D"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "telecom_subscription"
                    ],
                    "example": "telecom_subscription"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "pending",
                      "issued",
                      "voided",
                      "rejected"
                    ],
                    "example": "issued"
                  },
                  "channel": {
                    "type": "string",
                    "enum": [
                      "console",
                      "case",
                      "email",
                      "api"
                    ],
                    "example": "api"
                  },
                  "numbers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "07012340001"
                    ]
                  },
                  "submitTo": {
                    "type": "string",
                    "nullable": true,
                    "example": "예시 문자서비스"
                  },
                  "purpose": {
                    "type": "string",
                    "enum": [
                      "external_service",
                      "government",
                      "internal",
                      "other"
                    ],
                    "example": "external_service"
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-10-16T01:02:03.000Z"
                  },
                  "certificates": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "발급한 증명서 한 장. 목록 항목과 단건 조회가 같은 모양이다.\n문서 내용은 발급 시점 값으로 고정돼 있어 계정 정보가 나중에 바뀌어도 그대로다.",
                      "properties": {
                        "certificateNumber": {
                          "type": "string",
                          "description": "발급번호 KAT-YYYYMMDD-NNNN(날짜 = KST 발급일)",
                          "example": "KAT-20261016-0001"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "telecom_subscription"
                          ],
                          "example": "telecom_subscription"
                        },
                        "title": {
                          "type": "string",
                          "description": "발급 당시 문서 제목",
                          "example": "통신서비스 이용증명원"
                        },
                        "holder": {
                          "type": "object",
                          "description": "문서에 찍힌 명의. 사업자 계정은 상호·사업자등록번호, 개인 계정은 그 번호에 연결된 본인확인\n명의다. 관리번호(발급 링크로 최종이용자에게 배정한 번호)는 계정과 관계없이 최종이용자 명의다 —\n법인은 발급 때 확인한 상호·사업자등록번호, 개인은 본인확인 명의. 개인의 생년월일은 **가려서**\n돌려준다(원문은 PDF 에만 있다).",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "business",
                                "personal"
                              ],
                              "example": "business"
                            },
                            "name": {
                              "type": "string",
                              "example": "주식회사 예시"
                            },
                            "registrationNumber": {
                              "type": "string",
                              "description": "사업자등록번호(사업자일 때만)",
                              "example": "123-45-67890"
                            },
                            "birthDate": {
                              "type": "string",
                              "description": "가린 생년월일(개인일 때만)",
                              "example": "1980-**-**"
                            }
                          },
                          "required": [
                            "type",
                            "name"
                          ]
                        },
                        "subject": {
                          "type": "object",
                          "description": "telecom_subscription(통신서비스 이용증명원)이 증명하는 대상 — 번호와 가입일.",
                          "properties": {
                            "number": {
                              "type": "string",
                              "description": "저장형 번호(하이픈 없음)",
                              "example": "07012340001"
                            },
                            "numberType": {
                              "type": "string",
                              "enum": [
                                "internet_phone",
                                "representative_number"
                              ],
                              "description": "internet_phone = 070 인터넷전화, representative_number = 대표번호(15xx·16xx·18xx)",
                              "example": "internet_phone"
                            },
                            "subscriptionDate": {
                              "type": "string",
                              "format": "date",
                              "description": "이 계정이 이 번호를 처음 배정받은 날(KST)",
                              "example": "2026-08-14"
                            }
                          },
                          "required": [
                            "number",
                            "numberType",
                            "subscriptionDate"
                          ]
                        },
                        "issueDate": {
                          "type": "string",
                          "format": "date",
                          "example": "2026-10-16"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "issued",
                            "revoked"
                          ],
                          "example": "issued"
                        },
                        "revokedAt": {
                          "type": "string",
                          "format": "date-time",
                          "nullable": true,
                          "example": null
                        },
                        "revokedReason": {
                          "type": "string",
                          "nullable": true,
                          "example": null
                        },
                        "pdfSha256": {
                          "type": "string",
                          "nullable": true,
                          "description": "PDF 파일의 SHA-256(hex). 받은 파일과 대조할 수 있다.",
                          "example": "3b5f0c1e9a7d4b2e8f6a1c0d9e8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"
                        },
                        "pdfPath": {
                          "type": "string",
                          "description": "PDF 다운로드 경로(이 API 의 GET …/pdf)",
                          "example": "/v1/accounts/AC1a2b3c4d/certificates/KAT-20261016-0001/pdf"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time",
                          "example": "2026-10-16T01:02:03.000Z"
                        }
                      },
                      "required": [
                        "certificateNumber",
                        "type",
                        "title",
                        "holder",
                        "subject",
                        "issueDate",
                        "status",
                        "revokedAt",
                        "revokedReason",
                        "pdfSha256",
                        "pdfPath",
                        "createdAt"
                      ]
                    }
                  },
                  "delivery": {
                    "type": "object",
                    "nullable": true,
                    "description": "생성 응답에서만 — deliveryEmail 을 줬을 때의 발송 결과",
                    "properties": {
                      "email": {
                        "type": "string",
                        "example": "ops@example.com"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "queued",
                          "sent",
                          "failed"
                        ],
                        "example": "sent"
                      },
                      "error": {
                        "type": "string",
                        "nullable": true,
                        "description": "발송하지 못한 이유(하루 발송 한도 초과 등). 발급 자체는 성공했다.",
                        "example": null
                      },
                      "deliveryIds": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "example": [
                          "clx9dlv00001"
                        ]
                      }
                    }
                  }
                },
                "required": [
                  "id",
                  "type",
                  "status",
                  "channel",
                  "numbers",
                  "submitTo",
                  "purpose",
                  "createdAt",
                  "certificates"
                ]
              },
              {
                "type": "object",
                "description": "dryRun 결과 — 번호마다 발급 가능 여부, 찍힐 명의, 막힘 사유.",
                "properties": {
                  "dryRun": {
                    "type": "boolean",
                    "example": true
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "telecom_subscription"
                    ],
                    "example": "telecom_subscription"
                  },
                  "eligible": {
                    "type": "boolean",
                    "description": "모든 번호가 발급 가능하면 true",
                    "example": false
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "number": {
                          "type": "string",
                          "example": "07012340001"
                        },
                        "eligible": {
                          "type": "boolean",
                          "example": false
                        },
                        "holder": {
                          "type": "object",
                          "allOf": [
                            {
                              "type": "object",
                              "description": "문서에 찍힌 명의. 사업자 계정은 상호·사업자등록번호, 개인 계정은 그 번호에 연결된 본인확인\n명의다. 관리번호(발급 링크로 최종이용자에게 배정한 번호)는 계정과 관계없이 최종이용자 명의다 —\n법인은 발급 때 확인한 상호·사업자등록번호, 개인은 본인확인 명의. 개인의 생년월일은 **가려서**\n돌려준다(원문은 PDF 에만 있다).",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "business",
                                    "personal"
                                  ],
                                  "example": "business"
                                },
                                "name": {
                                  "type": "string",
                                  "example": "주식회사 예시"
                                },
                                "registrationNumber": {
                                  "type": "string",
                                  "description": "사업자등록번호(사업자일 때만)",
                                  "example": "123-45-67890"
                                },
                                "birthDate": {
                                  "type": "string",
                                  "description": "가린 생년월일(개인일 때만)",
                                  "example": "1980-**-**"
                                }
                              },
                              "required": [
                                "type",
                                "name"
                              ]
                            }
                          ],
                          "nullable": true
                        },
                        "subject": {
                          "type": "object",
                          "allOf": [
                            {
                              "type": "object",
                              "description": "telecom_subscription(통신서비스 이용증명원)이 증명하는 대상 — 번호와 가입일.",
                              "properties": {
                                "number": {
                                  "type": "string",
                                  "description": "저장형 번호(하이픈 없음)",
                                  "example": "07012340001"
                                },
                                "numberType": {
                                  "type": "string",
                                  "enum": [
                                    "internet_phone",
                                    "representative_number"
                                  ],
                                  "description": "internet_phone = 070 인터넷전화, representative_number = 대표번호(15xx·16xx·18xx)",
                                  "example": "internet_phone"
                                },
                                "subscriptionDate": {
                                  "type": "string",
                                  "format": "date",
                                  "description": "이 계정이 이 번호를 처음 배정받은 날(KST)",
                                  "example": "2026-08-14"
                                }
                              },
                              "required": [
                                "number",
                                "numberType",
                                "subscriptionDate"
                              ]
                            }
                          ],
                          "nullable": true
                        },
                        "blockers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                            "properties": {
                              "number": {
                                "type": "string",
                                "description": "422 응답의 blockers 에만 있다",
                                "example": "07012340002"
                              },
                              "code": {
                                "type": "string",
                                "enum": [
                                  "number_not_owned",
                                  "number_not_carrier_issued",
                                  "business_info_incomplete",
                                  "identity_unverified",
                                  "account_restricted",
                                  "business_recheck_pending",
                                  "holder_is_personal"
                                ],
                                "example": "number_not_carrier_issued"
                              },
                              "message": {
                                "type": "string",
                                "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                              }
                            },
                            "required": [
                              "code",
                              "message"
                            ]
                          }
                        }
                      },
                      "required": [
                        "number",
                        "eligible",
                        "holder",
                        "subject",
                        "blockers"
                      ]
                    }
                  }
                },
                "required": [
                  "dryRun",
                  "type",
                  "eligible",
                  "items"
                ]
              }
            ]
          }
        }
      }
    },
    "201": {
      "description": "발급됨. `Location` 이 요청 리소스를 가리킨다.",
      "headers": {
        "Location": {
          "schema": {
            "type": "string",
            "example": "/v1/accounts/AC1a2b3c4d/certificate-requests/CERT-7Q2K9D"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "발급 요청 하나. 요청 1건에서 번호마다 증명서 1장이 나온다.",
            "properties": {
              "id": {
                "type": "string",
                "description": "요청 코드",
                "example": "CERT-7Q2K9D"
              },
              "type": {
                "type": "string",
                "enum": [
                  "telecom_subscription"
                ],
                "example": "telecom_subscription"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "issued",
                  "voided",
                  "rejected"
                ],
                "example": "issued"
              },
              "channel": {
                "type": "string",
                "enum": [
                  "console",
                  "case",
                  "email",
                  "api"
                ],
                "example": "api"
              },
              "numbers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "07012340001"
                ]
              },
              "submitTo": {
                "type": "string",
                "nullable": true,
                "example": "예시 문자서비스"
              },
              "purpose": {
                "type": "string",
                "enum": [
                  "external_service",
                  "government",
                  "internal",
                  "other"
                ],
                "example": "external_service"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-16T01:02:03.000Z"
              },
              "certificates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "발급한 증명서 한 장. 목록 항목과 단건 조회가 같은 모양이다.\n문서 내용은 발급 시점 값으로 고정돼 있어 계정 정보가 나중에 바뀌어도 그대로다.",
                  "properties": {
                    "certificateNumber": {
                      "type": "string",
                      "description": "발급번호 KAT-YYYYMMDD-NNNN(날짜 = KST 발급일)",
                      "example": "KAT-20261016-0001"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "telecom_subscription"
                      ],
                      "example": "telecom_subscription"
                    },
                    "title": {
                      "type": "string",
                      "description": "발급 당시 문서 제목",
                      "example": "통신서비스 이용증명원"
                    },
                    "holder": {
                      "type": "object",
                      "description": "문서에 찍힌 명의. 사업자 계정은 상호·사업자등록번호, 개인 계정은 그 번호에 연결된 본인확인\n명의다. 관리번호(발급 링크로 최종이용자에게 배정한 번호)는 계정과 관계없이 최종이용자 명의다 —\n법인은 발급 때 확인한 상호·사업자등록번호, 개인은 본인확인 명의. 개인의 생년월일은 **가려서**\n돌려준다(원문은 PDF 에만 있다).",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "business",
                            "personal"
                          ],
                          "example": "business"
                        },
                        "name": {
                          "type": "string",
                          "example": "주식회사 예시"
                        },
                        "registrationNumber": {
                          "type": "string",
                          "description": "사업자등록번호(사업자일 때만)",
                          "example": "123-45-67890"
                        },
                        "birthDate": {
                          "type": "string",
                          "description": "가린 생년월일(개인일 때만)",
                          "example": "1980-**-**"
                        }
                      },
                      "required": [
                        "type",
                        "name"
                      ]
                    },
                    "subject": {
                      "type": "object",
                      "description": "telecom_subscription(통신서비스 이용증명원)이 증명하는 대상 — 번호와 가입일.",
                      "properties": {
                        "number": {
                          "type": "string",
                          "description": "저장형 번호(하이픈 없음)",
                          "example": "07012340001"
                        },
                        "numberType": {
                          "type": "string",
                          "enum": [
                            "internet_phone",
                            "representative_number"
                          ],
                          "description": "internet_phone = 070 인터넷전화, representative_number = 대표번호(15xx·16xx·18xx)",
                          "example": "internet_phone"
                        },
                        "subscriptionDate": {
                          "type": "string",
                          "format": "date",
                          "description": "이 계정이 이 번호를 처음 배정받은 날(KST)",
                          "example": "2026-08-14"
                        }
                      },
                      "required": [
                        "number",
                        "numberType",
                        "subscriptionDate"
                      ]
                    },
                    "issueDate": {
                      "type": "string",
                      "format": "date",
                      "example": "2026-10-16"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "issued",
                        "revoked"
                      ],
                      "example": "issued"
                    },
                    "revokedAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true,
                      "example": null
                    },
                    "revokedReason": {
                      "type": "string",
                      "nullable": true,
                      "example": null
                    },
                    "pdfSha256": {
                      "type": "string",
                      "nullable": true,
                      "description": "PDF 파일의 SHA-256(hex). 받은 파일과 대조할 수 있다.",
                      "example": "3b5f0c1e9a7d4b2e8f6a1c0d9e8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"
                    },
                    "pdfPath": {
                      "type": "string",
                      "description": "PDF 다운로드 경로(이 API 의 GET …/pdf)",
                      "example": "/v1/accounts/AC1a2b3c4d/certificates/KAT-20261016-0001/pdf"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2026-10-16T01:02:03.000Z"
                    }
                  },
                  "required": [
                    "certificateNumber",
                    "type",
                    "title",
                    "holder",
                    "subject",
                    "issueDate",
                    "status",
                    "revokedAt",
                    "revokedReason",
                    "pdfSha256",
                    "pdfPath",
                    "createdAt"
                  ]
                }
              },
              "delivery": {
                "type": "object",
                "nullable": true,
                "description": "생성 응답에서만 — deliveryEmail 을 줬을 때의 발송 결과",
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "ops@example.com"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "queued",
                      "sent",
                      "failed"
                    ],
                    "example": "sent"
                  },
                  "error": {
                    "type": "string",
                    "nullable": true,
                    "description": "발송하지 못한 이유(하루 발송 한도 초과 등). 발급 자체는 성공했다.",
                    "example": null
                  },
                  "deliveryIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "clx9dlv00001"
                    ]
                  }
                }
              }
            },
            "required": [
              "id",
              "type",
              "status",
              "channel",
              "numbers",
              "submitTo",
              "purpose",
              "createdAt",
              "certificates"
            ]
          }
        }
      }
    },
    "400": {
      "description": "입력 오류 (`invalid_input`)",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "인증 실패",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "접근 권한 없음 (OIDC 토큰은 scope 필요)",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "422": {
      "description": "- `certificate_not_eligible`: 발급할 수 없는 번호가 있다. 응답의 `blockers` 에 번호별 사유.\n- `idempotency_key_reused`: 같은 키를 다른 요청에 썼다.\n- `unsupported_characters`: 증명서 글꼴에 없는 문자(한자 등)가 상호·이름·주소에 있다. 한글·영문으로 바꾼 뒤 다시 요청.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "하루 발급 한도 초과 (`daily_quota_exceeded`)",
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer"
          },
          "description": "다음 KST 자정까지 남은 초"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "503": {
      "description": "PDF 를 만들지 못함 (`render_unavailable`). 발급번호는 쓰이지 않았다. `Retry-After` 뒤 다시 시도.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```