홈 / API 연동 문서

API 연동 문서

버전 v1 · 대리점 및 개발자용

API를 통해 프로그램으로 이 사이트에서 주문하고, 주문을 조회하고, 카드 코드를 받을 수 있어요. 주문 금액은 계정 잔액에서 바로 차감되므로 건별로 결제할 필요가 없습니다.

  1. 계정 가입에서 회원 센터 잔액 충전.
  2. 에서 회원 센터 → API 인터페이스 키 만들기, 그러면 다음을 받게 돼요 AppID 및 Secret, 서버 IP 화이트리스트도 함께 설정하는 것을 권장합니다.
  3. 아래 서명 방식에 따라 API를 호출하세요.
API 주소https://vynqlo.com/api/open/v1
데이터 형식요청과 응답은 모두 JSON이며 UTF-8 인코딩입니다
금액 단위위안 단위, 소수점 둘째 자리까지
호출 빈도키당 초당 최대 10회, 초과 시 다음을 반환합니다 429

서명 방식

모든 요청에 아래 4개의 헤더를 포함해야 합니다:

요청 헤더설명
X-App-Id내 AppID
X-Timestamp현재 Unix 타임스탬프(초), 서버와의 차이가 300초를 넘으면 안 됩니다
X-Nonce랜덤 문자열, 16–32자, 같은 값은 10분 내에 다시 사용할 수 없습니다
X-Sign서명, 계산 방법은 아래 참고

다음 5개 항목을 줄바꿈으로 \n 로 연결해 서명할 문자열을 만드세요:

타임스탬프\n랜덤 문자열\n요청 메서드(대문자)\n요청 경로(쿼리 파라미터 포함)\n요청 본문 원문(GET 요청은 빈 문자열)

다시 Secret HMAC-SHA256을 계산하고 결과를 소문자 16진수로 변환하면 바로 X-Sign。

Python 예제

import hmac, hashlib, json, time, secrets, requests APP_ID = "vq_xxxxxxxxxxxxxxxx" SECRET = "내 Secret" BASE = "https://vynqlo.com/api/open/v1" def call(method, path, body=None): raw = json.dumps(body, ensure_ascii=False, separators=(",", ":")) if body else "" ts, nonce = str(int(time.time())), secrets.token_hex(8) msg = "\n".join([ts, nonce, method, "/api/open/v1" + path, raw]) sign = hmac.new(SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest() headers = {"X-App-Id": APP_ID, "X-Timestamp": ts, "X-Nonce": nonce, "X-Sign": sign, "Content-Type": "application/json"} return requests.request(method, BASE + path, headers=headers, data=raw.encode() or None).json() print(call("GET", "/balance"))

상품 목록

GET /products — 주문 가능한 모든 상품과 내 도매가, 재고를 반환합니다.

{ "code": 0, "data": [ { "sku": "apple.us.25", "name": "Apple 기프트카드 · 미국 $25", "delivery": "code", // code 카드 코드 / link 링크 대리 결제 / username 사용자명 직접 충전 "price": 189.00, "stock": 167, // 링크 대리 결제·사용자명 직접 충전 상품은 null이며 무제한을 의미 "fields": [] // 주문 시 추가로 제출해야 하는 필드, '주문 생성' 참고 } ] }

잔액 조회

GET /balance

{ "code": 0, "data": { "balance": 2380.50 } }

주문 생성

POST /orders — 잔액이 충분하면 즉시 결제되고 처리가 시작됩니다.

매개변수필수설명
sku예상품 코드, 문서 끝의 '상품 코드표' 참고
quantity아니요수량, 기본값 1. 카드 코드 상품은 주문당 최대 10, 그 외 상품은 1만 가능
out_trade_no예내 시스템의 주문번호, 6–64자 영문/숫자. 같은 번호로 중복 제출하면 기존 주문이 그대로 반환되며 중복 결제되지 않습니다
account_email링크 대리 결제 필수고객의 계정 이메일
checkout_url링크 대리 결제 필수공식 결제 링크
username사용자명 직접 충전 필수예: Telegram 사용자명 @name

요청 예제:

{ "sku": "chatgpt.plus.1m", "out_trade_no": "A20261119001",
  "account_email": "user@example.com",
  "checkout_url": "https://chatgpt.com/checkout/..." }

응답 예제:

{
  "code": 0,
  "data": {
    "order_no": "VQ2611190001",
    "out_trade_no": "A20261119001",
    "status": "processing",
    "amount": 169.00,
    "balance": 2211.50
  }
}

주문 조회

GET /orders/{order_no}또는 GET /orders?out_trade_no=내 주문번호

{
  "code": 0,
  "data": {
    "order_no": "VQ2611190002",
    "out_trade_no": "A20261119002",
    "sku": "apple.us.25",
    "quantity": 2,
    "amount": 378.00,
    "status": "delivered",
    "cards": ["XXXX-XXXX-XXXX-XXXX", "YYYY-YYYY-YYYY-YYYY"],
    "created_at": 1795060000,
    "finished_at": 1795060003,
    "remark": ""
  }
}
status의미
processing결제 완료, 처리 중 (대리 결제·직접 충전 주문은 보통 5–30분)
delivered카드 코드 발급 완료, cards 안
completed대리 결제 또는 직접 충전 완료
failed처리 실패, 금액은 잔액으로 환불되었어요. 사유는 다음에서 확인하세요 remark

콜백 알림

회원 센터에서 콜백 주소를 설정하면 주문이 delivered、completed 또는 failed 할 때는 저희가 POST 주문 데이터를 이 주소로 보내며, 내용은 '주문 조회'에서 반환되는 것과 data 와 같습니다.

  • 알림에도 동일하게 포함됩니다 X-App-Id、X-Timestamp、X-Nonce、X-Sign, 서명 방법은 동일하니 서명을 먼저 검증한 후 처리하세요.
  • 처리에 성공하면 HTTP 200과 다음 텍스트를 반환하세요 success. 실패하면 1분, 5분, 15분, 60분 후에 재시도하며 최대 4번까지 시도합니다.
  • 같은 주문에 알림이 여러 번 올 수 있으니 order_no 중복 제거.

오류 코드

code설명
0성공
1001서명이 올바르지 않거나 헤더가 없습니다
1002타임스탬프가 허용 범위를 벗어났습니다
1003Nonce 재사용
1004IP가 화이트리스트에 없습니다
2001상품 코드가 없거나 판매가 종료되었습니다
2002재고 부족
2003필수 필드가 없거나 필드 형식이 올바르지 않습니다
3001잔액 부족
4001주문이 없어요
429호출이 너무 잦습니다

오류 시 반환 형식:{ "code": 3001, "message": "잔액이 부족합니다" }

상품 코드표

가격은 현재 도매가이며, /products API 응답을 기준으로 합니다.

상품 코드 sku상품제공 방식가격