본문으로 건너뛰기

REST API 가이드

OOZOO PAY REST API의 요청/응답 형식과 공통 규칙을 안내합니다.

Endpoint​

모든 API 요청은 아래 Base URL을 사용합니다.

https://api.oozoopay.com

전체 요청 URL은 Base URL에 API 경로를 결합하여 구성합니다.

https://api.oozoopay.com/api/invoices
테스트 환경

별도의 샌드박스 환경은 제공되지 않습니다. 테스트가 필요한 경우 가맹점 대시보드에서 테스트 모드 프로젝트를 생성하여 블록체인 테스트넷 환경에서 연동을 검증할 수 있습니다.

요청 형식​

항목값
ProtocolHTTPS (TLS 1.2 이상)
Content-Typeapplication/json; charset=utf-8
인코딩UTF-8

모든 요청에는 인증 헤더(X-Client-Key, X-Timestamp, X-Signature)가 포함되어야 합니다.

응답 형식​

모든 응답은 JSON 형식이며, 아래 구조를 따릅니다.

단일 리소스 응답​

{
  "id": "invoice-uuid",
  "status": "PENDING",
  "price": "100.00",
  "unit": "usd",
  "createdAt": "2024-01-29T12:00:00Z"
}

목록 응답​

{
  "items": [
    {
      "id": "invoice-uuid",
      "status": "CONFIRMED"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

에러 응답​

{
  "success": false,
  "code": "INVALID_SIGNATURE",
  "message": "Invalid signature"
}

에러 응답에는 code 필드가 포함되어 있으며, 이를 기반으로 에러 유형을 구분할 수 있습니다. 전체 에러 코드 목록은 에러 코드 문서를 참고하시기 바랍니다.

HTTP 상태 코드​

코드설명
200 OK요청 성공
201 Created리소스 생성 성공
400 Bad Request잘못된 요청 (파라미터 오류)
401 Unauthorized인증 실패 (서명 오류, 만료된 키)
404 Not Found리소스를 찾을 수 없음
409 Conflict리소스 상태 충돌
500 Internal Server Error서버 내부 오류

페이지네이션​

목록 조회 API는 페이지 기반 페이지네이션을 지원합니다. 아래 Query Parameter를 사용하여 페이지를 지정할 수 있습니다.

파라미터타입기본값설명
pagenumber1페이지 번호 (1부터 시작)
limitnumber20페이지당 항목 수 (최대 100)

응답의 meta 객체에 페이지네이션 정보가 포함됩니다.

필드타입설명
totalnumber전체 항목 수
pagenumber현재 페이지 번호
limitnumber페이지당 항목 수
totalPagesnumber전체 페이지 수
hasNextboolean다음 페이지 존재 여부
hasPrevboolean이전 페이지 존재 여부