문서에 없는 제약의 출처

외부 마켓 API 연동을 준비하면서 공식 Q&A 를 전수로 훑었다. 새로 올라온 수십 건을 검토해 QNA.md 에 이미 파악해 둔 것과 대조했고 새 정보만 뽑아냈다.

Open Table of contents

발견 1 — 두 개의 기본 경로
주의 — 오류 메시지가 원인을 안 가리키는 경우
발견 2 — 전체 치환과 두 예외
발견 3 — 되돌릴 수 없는 필드와 수치 제약
판단 기준 — 사전 검증이 줄이는 왕복
근거의 검증
정리

발견 1 — 두 개의 기본 경로

첫 번째로 나온 것은 base_url 이 하나가 아니라는 사실이었다. client_type 에 따라 서로 다른 경로를 써야 하고 일반 판매자는 그중 하나로 고정된다.

이것이 문서에 정리돼 있지 않고 개별 답변에만 흩어져 있었다. 연동을 시작할 때 가장 먼저 확정할 값이 가장 찾기 어려운 자리에 있었던 셈이다.

주의 — 오류 메시지가 원인을 안 가리키는 경우

경로를 틀렸을 때 무엇이 돌아오는지가 함정이었다. 401 계열이 아니라 400 이나 403 계열의 응답이 온다.

그러면 권한 문제로 읽고 계정 설정을 뒤지게 되는데 실제 원인은 엉뚱하게도 경로 쪽이다. 오류와 원인이 어긋나는 조합을 아는 것과 모르는 것의 차이가 며칠이 된다. 이런 항목은 사전 검증으로 막을 수 없어 문서에 적는 수밖에 없다.

발견 2 — 전체 치환과 두 예외

상품 수정 규칙도 나왔다. PUT /products 의 원칙은 전체 치환이라 안 넣은 필드는 지워지지만 detail_html 과 images 두 필드만 예외로 생략하면 기존 값이 유지된다.

ProductRequestBuilder 에 이 차이가 반영돼야 한다. 예외인 두 필드까지 매번 채워 보내면 상세 내용을 다시 만들어야 하고 불필요한 왕복이 생긴다. 원칙과 예외가 함께 적혀 있지 않으면 원칙만 보고 전부 채운다.

sale_status 도 비슷했다. 필드가 있으니 아무 값이나 넣을 수 있을 것 같지만 설정 가능한 값은 두 개뿐이고 나머지는 관리 화면에서만 바뀐다.

발견 3 — 되돌릴 수 없는 필드와 수치 제약

한 번 설정하면 못 바꾸는 필드가 있다는 것도 확인했다. release_date 는 한 번 넣으면 변경이 불가하고 preorder 상품은 수정 자체가 안 된다.

이걸 모르고 넣으면 나중에 못 고치므로 처음 등록할 때 신중해야 하는 필드를 미리 아는 것이 중요했다. 되돌릴 수 있는 필드와 없는 필드를 갈라 두면 어디에 확인을 넣을지가 정해진다.

등록할 때 걸리는 수치 제약도 하나씩 목록으로 뽑았다.

할인 금액 환산    최대 1천만원
옵션가            판매가의 최대 50%
재고              최대 99,999,999
조합형 옵션       옵션가 0원·재고 1개 이상인 기본 옵션이 최소 1개 필수

마지막 항목이 특이했다. 조합형 옵션에는 기본으로 쓸 옵션이 하나 있어야 하고 이 조건을 모르면 옵션을 다 만들고도 등록이 거부된다.

판단 기준 — 사전 검증이 줄이는 왕복

두 가지 방법이 있었는데 이 목록을 문서에만 두고 거부 응답을 보며 고치는 것과 ProductRule 사전 검증 코드에 넣는 것이다. 뒤쪽을 골랐다. 이유는 사전 검증이 없으면 보내고 거부당하고 읽고 고쳐서 다시 보내는 왕복이 생겨서다. 대신 마켓 규격이 바뀌면 문서와 코드를 둘 다 고쳐야 하는 것을 감수했다.

특히 대량 등록에서 차이가 큰데 1,000건 중 50건이 걸리면 사전 검증이 없을 때 50번을 왕복하게 된다. 잘못된 요청에 페널티가 붙는 API에서는 그것이 다음 요청을 막는다.

반면 앞의 경로 문제나 계정 관련 항목은 코드로 막을 수 없는 종류였다. 스토어 양도양수가 일어나면 기존 client_id 가 자동 삭제돼 연동이 통째로 죽는데 그 과정에서 아무 예고가 없다. 이런 것은 RUNBOOK.md 에 재발급 절차를 넣어 두는 것이 유일한 대응이다. 제약을 모을 때 코드에 넣을 것과 문서에 넣을 것을 갈라야 목록이 실제로 쓰인다.

근거의 검증

이 목록을 신뢰할 수 있는지도 따져서 QNA.md 의 각 항목에 원문 답변을 인용으로 붙여 근거를 남겼다.

Q&A에는 사용자 추측도 섞여 있어 공식 답변만 근거로 삼았고 기존에 파악한 것과 대조해 새로 알게 된 것만 추렸다. 대조하지 않으면 목록이 커지는데도 새 정보는 안 늘어난다.

정리

base_url 이 둘 이상일 수 있으므로 어느 것을 쓸지 먼저 확정한다
경로가 틀리면 엉뚱한 오류가 나서 원인을 못 찾는다
오류와 원인이 어긋나는 조합을 아는 것과 모르는 것의 차이가 크다
PUT 수정이 전체 치환이면 예외 필드를 따로 확인한다
필드가 있다고 아무 값이나 넣을 수 있는 것이 아니다
한 번 설정하면 못 바꾸는 필드를 미리 안다
수치 제약을 사전 검증에 반영하면 실패 왕복이 준다
코드에 넣을 것과 문서에 넣을 것을 갈라야 목록이 쓰인다