API · MCP 문서

기본 주소 https://baropin.app · 시간은 UTC RFC 3339 · JSON UTF-8 · 키는 콘솔 [API · MCP]에서 만들어요.

흐름

POST /v1/verification-requests 로 요청 → queued
중계폰이 준비되면 armed (15초 안에 안 되면 failed)
대상 사이트에서 인증 문자 요청
번호가 오면 result_ready → POST …/consume 로 한 번 받기 → consumed
로그인 결과는 POST …/outcome 로 따로 알려 주세요(중계 완료 ≠ 로그인 성공)

queued → armed → result_ready → consumed
활성 상태 → cancelled | expired | failed | ambiguous

MCP

주소 https://baropin.app/mcp (Streamable HTTP) · 헤더 Authorization: Bearer bp_live_…

{
  "mcpServers": {
    "baropin": { "type": "http", "url": "https://baropin.app/mcp",
                 "headers": { "Authorization": "Bearer bp_live_…" } }
  }
}

도구	설명
`list_accounts`	키로 쓸 수 있는 몰 계정
`request_code`	대기 요청 생성 + 중계폰 준비(armed) 대기
`wait_for_code`	최대 20초 도착 대기 (반복 호출)
`get_code`	번호 1회 받기 — 키에 "AI에 번호 직접 전달 허용"이 켜진 경우만
`cancel_request`	요청 취소
`list_devices`	중계폰 연결 상태

REST API

모든 요청에 Authorization: Bearer bp_live_…. 변경 요청은 Idempotency-Key 를 지원해요(같은 키·다른 본문은 409). URL 에 키를 넣지 마세요.

메서드·경로	권한	설명
`GET /v1/accounts`	-	쓸 수 있는 몰 계정
`POST /v1/verification-requests`	requests:create	202 queued. 충돌 409, 정책 403, 한도 429
`GET /v1/verification-requests/{id}`	requests:read	상태 (번호 없음)
`GET /v1/verification-requests/{id}/wait?timeout=20`	requests:read	상태가 바뀌거나 최대 20초 후 응답
`POST /v1/verification-requests/{id}/consume`	results:consume	200 번호. 준비 전 409, 만료 410. Idempotency-Key 필수
`POST /v1/verification-requests/{id}/cancel`	requests:cancel	취소 (멱등)
`POST /v1/verification-requests/{id}/outcome`	requests:read	`{"outcome":"succeeded\|rejected\|unknown"}`
`GET /v1/devices`	devices:read	중계폰 상태 (전화번호 없음)

curl -X POST https://baropin.app/v1/verification-requests \
  -H "Authorization: Bearer bp_live_…" \
  -H "Idempotency-Key: job-20261019-001" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"acc_…","purpose":"order_sync","ttl_seconds":120,
       "delivery":{"webhook_endpoint_id":"wh_…"}}'

HTTP 202
{ "id": "vr_…", "status": "queued", "version": 1,
  "expires_at": "2026-10-19T02:02:00Z", "next_action": "wait_until_armed" }

curl -X POST https://baropin.app/v1/verification-requests/vr_…/consume \
  -H "Authorization: Bearer bp_live_…" -H "Idempotency-Key: consume-vr_…-worker01"

HTTP 200
{ "request_id": "vr_…", "status": "consumed", "code": "482913",
  "expires_at": "…", "target_code_expiry": "unknown" }

같은 키로 30초 안에 다시 소비하면 같은 응답을 돌려줘요. 그 뒤는 410 RESULT_UNAVAILABLE. 다른 키로는 409 ALREADY_CONSUMED. TTL 30~180초(기본 120초)는 바로핀 보관 시간이며 대상 서비스 코드의 실제 유효시간을 보장하지 않아요.

오류

{ "error": { "code": "AMBIGUOUS_REQUEST", "message": "…", "retryable": false, "trace_id": "tr_…" } }

400 VALIDATION_ERROR · 401 INVALID_CREDENTIALS · 403 POLICY_DENIED / CONSENT_REVOKED · 404 NOT_FOUND · 409 COLLISION_ACTIVE / RESULT_NOT_READY / ALREADY_CONSUMED / AMBIGUOUS_REQUEST / DEVICE_NOT_READY / IDEMPOTENCY_CONFLICT · 410 REQUEST_EXPIRED / RESULT_UNAVAILABLE · 429 RATE_LIMITED / PLAN_LIMIT_REACHED (Retry-After) · 503 TEMPORARY_UNAVAILABLE. 한도: 키당 30회/분, 조직 생성 60회/분, 같은 발신번호 그룹의 활성 요청 1개.

웹훅

이벤트: verification.armed, result_ready, consumed, ambiguous, expired, cancelled, failed, policy.revoked. 본문에 번호는 없어요. 순서는 보장하지 않으니 request_version 이 낮으면 현재 상태를 조회하세요.

X-BaroPIN-Event-Id: evt_…
X-BaroPIN-Timestamp: 1792375208
X-BaroPIN-Key-Id: whkey_01
X-BaroPIN-Signature: v1=HEX

signed_payload = timestamp + "." + event_id + "." + raw_body
signature = HMAC_SHA256(webhook_secret, signed_payload)

raw body 로 서명을 상수 시간 비교하고, 시계 오차 ±5분을 확인하고, event_id 로 중복을 걸러 2xx 를 빨리 돌려주세요. 실패하면 5초·20초·60초·5분·30분·2시간·6시간·24시간에 다시 보내요. HTTPS·443 포트·공인 주소만 등록할 수 있어요.