증명서 발급

POST

https://api.claw-ops.com/v1/accounts/:accountId/certificate-requests

POST

/v1/accounts/:accountId/certificate-requests

curl -X POST https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/certificate-requests \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "type": "telecom_subscription",
  "numbers": [
    "07012340001"
  ],
  "submitTo": "예시 문자서비스",
  "purpose": "external_service",
  "deliveryEmail": "ops@example.com",
  "idempotencyKey": "cert-2026-10-16-001"
}'

{
  "certificates": [
    {
      "certificateNumber": "KAT-20261016-0001",
      "createdAt": "2026-10-16T01:02:03.000Z",
      "holder": {
        "birthDate": "1980-**-**",
        "name": "주식회사 예시",
        "registrationNumber": "123-45-67890",
        "type": "business"
      },
      "issueDate": "2026-10-16",
      "pdfPath": "/v1/accounts/AC1a2b3c4d/certificates/KAT-20261016-0001/pdf",
      "pdfSha256": "3b5f0c1e9a7d4b2e8f6a1c0d9e8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b",
      "revokedAt": null,
      "revokedReason": null,
      "status": "issued",
      "subject": {
        "number": "07012340001",
        "numberType": "internet_phone",
        "subscriptionDate": "2026-08-14"
      },
      "title": "통신서비스 이용증명원",
      "type": "telecom_subscription"
    }
  ],
  "channel": "api",
  "createdAt": "2026-10-16T01:02:03.000Z",
  "delivery": {
    "deliveryIds": [
      "clx9dlv00001"
    ],
    "email": "ops@example.com",
    "error": null,
    "status": "sent"
  },
  "id": "CERT-7Q2K9D",
  "numbers": [
    "07012340001"
  ],
  "purpose": "external_service",
  "status": "issued",
  "submitTo": "예시 문자서비스",
  "type": "telecom_subscription"
}

번호마다 증명서 PDF 를 바로 발급한다. 지금 종류는 telecom_subscription(통신서비스 이용증명원)뿐이다.

발급 대상: 한국AI통신이 개통한 070·대표번호만. 그 밖의 번호는 422 와 번호별 blockers.
전부 아니면 전무: 번호 하나라도 막히면 아무것도 발급하지 않는다.
미리보기: dryRun: true 면 같은 판정만 하고 200 으로 결과를 돌려준다.
멱등: 같은 idempotencyKey 재요청은 200 으로 1회차 결과.
한도: 계정당 하루(KST) 20장. 넘으면 429 + Retry-After(다음 자정까지 초).
문서의 「인입 연락처」는 요청자의 본인확인 휴대폰 번호다. API 키 요청은 계정 소유자의 번호.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Request

This endpoint expects an object.

typeenumRequired

Allowed values:

numberslist of stringsRequired

증명할 번호(1~10개). 번호마다 문서 1장.

submitTostringOptional<=40 characters

제출처. 문서의 「제출처」 칸에 찍힌다.

purposeenumOptionalDefaults to other

Allowed values:

deliveryEmailstringOptionalformat: "email"

주면 발급 직후 PDF 를 이 주소로 보내고, 문서의 「발송방법」 칸에 찍힌다.

idempotencyKeystringOptional1-255 characters

같은 키로 다시 요청하면 새로 발급하지 않고 1회차 결과를 200 으로 돌려준다. 같은 키를 다른 요청에 쓰면 422 idempotency_key_reused.

dryRunbooleanOptionalDefaults to false

true 면 판정만 하고 아무것도 만들지 않는다(채번·원장·발송 없음).

Response

멱등 재요청(1회차 결과, CertificateRequest) 또는 dryRun 결과(CertificateDryRunResponse)

CertificateRequestobject

발급 요청 하나. 요청 1건에서 번호마다 증명서 1장이 나온다.

CertificateDryRunResponseobject

dryRun 결과 — 번호마다 발급 가능 여부, 찍힐 명의, 막힘 사유.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error