플레이오토 API 실전 연동: 주문 수집부터 커스텀 주문 등록까지 - 이커머스 운영 자동화

소형 쇼핑몰을 운영하다 보면 플레이오토 화면만으로 처리하기 어려운 케이스가 생긴다.
대표적으로 견적서 기반 커스텀 주문 등록, 자체 운영 도구와의 데이터 연동, 클레임 수집 자동화가 있다.

이럴 때 플레이오토 OpenAPI를 직접 활용하면 반복 업무를 줄이고 운영 자동화 범위를 크게 넓힐 수 있다.
이 글에서는 플레이오토 API 인증 방식, 주문 수집, 그리고 견적서를 신규 주문으로 등록하는 흐름까지 실제 구현 관점에서 정리한다.

플레이오토 OpenAPI란?

플레이오토는 주문 관리, 발주, 재고, 정산 데이터를 외부 시스템과 연동할 수 있는 REST API를 제공한다.
처음에는 문서만으로 구조를 파악하기 어려운 부분도 있지만, 핵심 엔드포인트만 이해하면 충분히 실무에 활용할 수 있다.

플레이오토 API로 할 수 있는 대표적인 작업은 다음과 같다.

쇼핑몰별 주문 수집 (채널/상태 필터링 포함)
신규 주문 등록
주문 상태 업데이트
클레임(반품/교환) 자동 수집

시작 전 준비

필요한 것은 다음과 같다.

– 플레이오토 계정
– 플레이오토 개발자센터 계정
– API Key
– Authorization Token

API Key와 Authorization Token은 플레이오토 관리자 화면의 API 관리 메뉴에서 발급할 수 있다.
발급받은 값은 요청 헤더에 함께 포함해야 한다.

발급받은 값은 모든 요청의 헤더에 포함한다:

http

x-api-key: your_api_key
Authorization: Token eyJhbGci...
```

> 토큰은 별도 발급 API 없이 관리자 페이지에서 직접 발급받는 방식이다. JWT 기반이며 만료 시 관리자 페이지에서 재발급 필요하다.

---

## 1단계 — 주문 수집

**엔드포인트:**
```
POST https://openapi.playauto.io/api/orders

요청 예제:

json

{
  "start": 0,
  "length": 500,
  "date_type": "wdate",
  "sdate": "2026-03-01",
  "edate": "2026-03-26",
  "status": ["신규주문"],
  "orderby": "wdate desc",
  "search_type": "partial"
}

주요 파라미터 설명:

파라미터	설명
`date_type`	날짜 기준 — `wdate`(수집일), `ord_time`(주문일), `pay_time`(결제일), `ord_status_mdate`(상태변경일)
`status`	주문 상태 필터 — `["신규주문"]`, `["ALL"]`, `["반품요청", "교환요청"]` 등 배열로 전달
`start` / `length`	페이지네이션 — 최대 3000건 단위
`shop_cd`	특정 쇼핑몰만 필터 — 옥션: A001, 지마켓: A006, 11번가: A112
`bundle_yn`	true면 묶음번호 기준 그룹핑, false면 단건 주문 기준

페이지네이션 처리:

한 번에 최대 3000건까지 조회 가능하다. 전체 건수(recordsTotal)가 더 많으면 start 값을 이전 length만큼 증가시켜 반복 호출한다. 연속 호출 시 Rate Limit(초당 3회)에 걸릴 수 있으므로 호출 사이 350ms 딜레이를 넣는 것을 권장한다.

json

// 1회차
{ "start": 0, "length": 3000 }

// 2회차
{ "start": 3000, "length": 3000 }
```

429 응답(Rate Limit)이 오면 1초 대기 후 재시도, 401 응답이 오면 토큰 만료이므로 재발급 후 재시도하는 로직을 구현해두는 것이 좋다.

**응답에서 주로 쓰는 필드:**

| 필드 | 설명 |
|---|---|
| `uniq` | 주문 고유번호 |
| `shop_ord_no` | 쇼핑몰 주문번호 |
| `shop_sale_name` | 상품명 |
| `c_sale_cd` | 판매자관리코드 |
| `pay_amt` | 실결제금액 |
| `shop_supply_price` | 쇼핑몰 공급가 |
| `ord_status` | 주문 상태 |
| `to_name` / `to_addr1` | 수령자 정보 |
| `claim_fault_type` | 귀책 구분 (SELLER/CUSTOMER/SHOP/LOGISTICS/ETC) |
| `api_read_status` | API 수집 여부 (NONE/CALLED/EDITED) |

---

## 2단계 — 커스텀 견적서를 신규 주문으로 등록

이게 핵심이다. 플레이오토 화면에서 수동으로 주문을 입력하는 대신, 견적서 승인 즉시 API로 자동 등록하면 반복 업무가 사라진다.

**엔드포인트:**
```
POST https://openapi.playauto.io/api/order/add
```

실패 시 아래 엔드포인트로 재시도:
```
POST https://openapi.playauto.io/api/orders/add

요청 예제:

json

{
  "shop_cd": "Z000",
  "shop_ord_no": "EST-2026-0001",
  "order_name": "홍길동",
  "order_htel": "010-1234-5678",
  "to_name": "홍길동",
  "to_htel": "010-1234-5678",
  "to_addr1": "서울시 강남구 테헤란로 123",
  "to_addr2": "456호",
  "to_zipcd": "06234",
  "shop_sale_name": "커스텀 상품명",
  "sale_cnt": 1,
  "sales": 150000,
  "ship_method": "선결제",
  "ship_cost": 0,
  "ord_time": "2026-03-26 10:00:00",
  "pay_time": "2026-03-26 10:00:00"
}

shop_cd: Z000은 플레이오토 내 직접입력 채널 코드다. 커스텀 주문 등록 시 이 값을 사용한다.

상품 옵션(opts) 구조:

견적서에 품목이 여러 개라면 opts 배열로 전달한다:

json

{
  "opts": [
    {
      "opt_name": "상품명 / 옵션명",
      "sale_price": 50000,
      "sale_cnt": 2,
      "c_sale_cd": "판매자관리코드"
    }
  ]
}
```

`c_sale_cd`를 정확히 전달하면 플레이오토 내 SKU 매칭이 자동으로 이루어진다.

**주문번호(`shop_ord_no`) 전략:**

동일한 주문번호로 재등록하면 중복이 발생한다. 견적서 ID + 타임스탬프 조합으로 고유값을 생성하는 것을 권장한다:
```
EST-{견적서ID}-{timestamp}

수정 시에는 기존 등록 때 받은 bundle_no를 그대로 사용한다.

실제 운영에서 겪은 문제들

1. 채널마다 다른 데이터 품질

생각보다 많은 채널이 정확한 데이터를 내려보내지 않는다.

카페24: shop_supply_price(공급가)가 0으로 내려온다. 카페24 자체 API를 별도 연동하거나, 내부 상품 DB(product_master)에 base_price를 등록해두고 c_sale_cd 기준으로 보완하는 방식으로 처리해야 한다. 동일 코드에 번들/단품이 혼재한 경우 최솟값을 사용하면 단품 가격이 적용된다.
오늘의집: 데이터 수정이 불가능하다. 오류가 있으면 오늘의집에 직접 문의해야 한다.
N배송(네이버): 별도 데이터가 내려오지 않는 경우가 있다. 네이버 커머스 API가 잘 정비되어 있으므로 직접 연동하는 것도 좋은 방법이다.
쿠팡: 가장 골치 아픈 케이스다. 쿠팡은 API 키를 하나만 제공하는데, 플레이오토를 이용하면 그 키를 플레이오토가 사용하게 된다. 별도 자체 연동이 사실상 불가능하다.

이 문제 때문에 결국 내부 상품 마스터와 판매자관리코드 기준 정규화가 중요해진다.

2. 마스터 상품코드 정규화 문제

채널마다 상품코드 체계가 다르다. 옥션 코드, 스마트스토어 코드, 자사 판매자관리코드가 제각각이다. 플레이오토 API를 제대로 활용하려면 c_sale_cd(판매자관리코드) 기준으로 전체 상품 코드를 정규화하는 것이 첫 번째 과제다. 이 작업 없이는 원가 매칭, 재고 관리, 정산 자동화 모두 불안정해진다.

3. 중복 주문 등록

견적서 번호(shop_ord_no)를 unique key로 관리하지 않으면 동일 주문이 중복 등록될 수 있다. 등록 전 반드시 중복 체크 후 등록(/add) / 수정(/edit) 분기 처리할 것. 응답의 uniq와 bundle_no를 내부 DB에 저장해두면 이후 수정 시 활용할 수 있다.

4. 클레임 자동 수집 시 중복 CS 생성

반품/교환 상태 주문을 주기적으로 수집해 CS 케이스를 자동 생성할 때, shop_ord_no + shop_sale_name 조합으로 중복 체크를 하지 않으면 같은 건이 여러 번 생성된다. 수집 전 반드시 중복 여부를 확인하는 로직이 필요하다.

마무리

플레이오토 OpenAPI는 공식 문서가 불친절하지만 인증 → 주문 수집 → 주문 등록 흐름만 파악하면 운영 자동화 범위를 크게 넓힐 수 있다. 특히 견적서 → 주문 자동 등록 흐름은 B2B 커스텀 주문이 많은 쇼핑몰에서 반복 업무를 크게 줄여준다.

문의 응답도 빠른 편이라 막히는 부분은 플레이오토 고객센터에 바로 문의하는 것을 추천한다.

다음 글에서는 플레이오토 클레임 API로 CS 케이스를 자동 수집하는 방법을 다룰 예정이다.

플레이오토 OpenAPI란?

시작 전 준비

실제 운영에서 겪은 문제들

마무리

댓글 남기기 응답 취소