사용자와 지갑 계정 생성

TIP

먼저 Wallet 튜토리얼의 wallet_request 준비를 완료하고 같은 셸에서 예제를 실행합니다.

OOLIN의 USER 계정은 고객 지갑의 잔액을 나타내며 입금 주소, 출금, 원장 항목의 소유자입니다. 고객 시스템에서 안정적으로 유지되는 식별자를 uid로 사용합니다.

연결과 서버 시각 확인

상태와 서버 시각 API는 인증 없이 호출할 수 있습니다.

curl -sS "$WALLET_BASE_URL/health" | jq
curl -sS "$WALLET_BASE_URL/time" | jq

/health는 프로세스에 연결할 수 있음을 확인할 뿐 모든 DB·체인 의존성의 정상 상태를 보장하지 않습니다. 준비 상태를 검사할 때는 인증이 필요한 업무 API도 함께 확인하십시오. 호출 서버 시각은 서버와 5분 이내로 유지합니다.

기존 계정 조회

POST /accounts는 멱등 API가 아닙니다. 새로 생성하기 전에 고객 uid로 기존 계정을 조회합니다.

export CUSTOMER_UID='user-tutorial-001'
wallet_request GET "/users/$CUSTOMER_UID/accounts" | jq

의도한 활성 USER 계정이 이미 있다면 재사용합니다.

export ACCOUNT_ID='{existing-active-user-account-id}'

반환된 실제 ID로 바꾸고 아래 생성 단계는 건너뜁니다. 여러 계정이 있으면 고객사에 저장된 연결 정보를 기준으로 선택합니다. 기존 계정이 잠금·비활성 상태라면 추가 계정을 만들어 우회하지 않고 원인을 확인합니다.

고객 계정 생성

의도한 계정이 없을 때만 실행합니다. 생성 응답이 유실되면 같은 uid로 계정 목록을 다시 확인하고, 확인 없이 생성 요청을 반복하지 않습니다.

account_body="$(jq -nc \
  --arg uid "$CUSTOMER_UID" \
  '{uid:$uid,account_type:"USER",metadata:{source:"wallet-tutorial"}}')"

account_response="$(wallet_request POST '/accounts' "$account_body")"
printf '%s\n' "$account_response" | jq

export ACCOUNT_ID="$(printf '%s' "$account_response" | jq -r '.data.account_id')"
wallet_request GET "/accounts/$ACCOUNT_ID" | jq

CUSTOMER_UID와 ACCOUNT_ID를 한 쌍으로 영구 저장합니다. 입금이나 출금을 허용하기 전에 반환된 account_type과 status를 검증합니다.

운영 적용 규칙

• ACCOUNT_ID만으로 고객 신원을 증명하지 않고 고객사 백엔드에서 권한을 확인합니다.
• 같은 고객에 대한 계정 생성 요청이 동시에 실행되지 않도록 막습니다.
• 고객과 계정의 연결 정보를 트랜잭션으로 저장합니다.
• 잠금 또는 비활성 계정에서는 새로운 자금 이동을 허용하지 않습니다.

다음: 입금 주소 발급