@cmarket/partner-sdk 43.0.2 โ†’ 44.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (797) hide show
  1. package/README.md +4 -4
  2. package/api/embed-api.ts +2 -2
  3. package/api/oauth-api.ts +2 -2
  4. package/api/partner-api-api.ts +2 -2
  5. package/api/products-api.ts +2 -2
  6. package/api/webhooks-api.ts +2 -2
  7. package/api/well-known-api.ts +2 -2
  8. package/api.ts +2 -2
  9. package/base.ts +2 -2
  10. package/common.ts +2 -2
  11. package/configuration.ts +2 -2
  12. package/dist/api/embed-api.d.ts +2 -2
  13. package/dist/api/embed-api.js +2 -2
  14. package/dist/api/oauth-api.d.ts +2 -2
  15. package/dist/api/oauth-api.js +2 -2
  16. package/dist/api/partner-api-api.d.ts +2 -2
  17. package/dist/api/partner-api-api.js +2 -2
  18. package/dist/api/products-api.d.ts +2 -2
  19. package/dist/api/products-api.js +2 -2
  20. package/dist/api/webhooks-api.d.ts +2 -2
  21. package/dist/api/webhooks-api.js +2 -2
  22. package/dist/api/well-known-api.d.ts +2 -2
  23. package/dist/api/well-known-api.js +2 -2
  24. package/dist/api.d.ts +2 -2
  25. package/dist/api.js +2 -2
  26. package/dist/base.d.ts +2 -2
  27. package/dist/base.js +2 -2
  28. package/dist/common.d.ts +2 -2
  29. package/dist/common.js +2 -2
  30. package/dist/configuration.d.ts +2 -2
  31. package/dist/configuration.js +2 -2
  32. package/dist/esm/api/embed-api.d.ts +2 -2
  33. package/dist/esm/api/embed-api.js +2 -2
  34. package/dist/esm/api/oauth-api.d.ts +2 -2
  35. package/dist/esm/api/oauth-api.js +2 -2
  36. package/dist/esm/api/partner-api-api.d.ts +2 -2
  37. package/dist/esm/api/partner-api-api.js +2 -2
  38. package/dist/esm/api/products-api.d.ts +2 -2
  39. package/dist/esm/api/products-api.js +2 -2
  40. package/dist/esm/api/webhooks-api.d.ts +2 -2
  41. package/dist/esm/api/webhooks-api.js +2 -2
  42. package/dist/esm/api/well-known-api.d.ts +2 -2
  43. package/dist/esm/api/well-known-api.js +2 -2
  44. package/dist/esm/api.d.ts +2 -2
  45. package/dist/esm/api.js +2 -2
  46. package/dist/esm/base.d.ts +2 -2
  47. package/dist/esm/base.js +2 -2
  48. package/dist/esm/common.d.ts +2 -2
  49. package/dist/esm/common.js +2 -2
  50. package/dist/esm/configuration.d.ts +2 -2
  51. package/dist/esm/configuration.js +2 -2
  52. package/dist/esm/index.d.ts +2 -2
  53. package/dist/esm/index.js +2 -2
  54. package/dist/esm/models/acceptance-result-response-dto.d.ts +2 -2
  55. package/dist/esm/models/acceptance-result-response-dto.js +2 -2
  56. package/dist/esm/models/acknowledge-product-receipt200-response.d.ts +2 -2
  57. package/dist/esm/models/acknowledge-product-receipt200-response.js +2 -2
  58. package/dist/esm/models/acknowledge-products-request-dto.d.ts +2 -2
  59. package/dist/esm/models/acknowledge-products-request-dto.js +2 -2
  60. package/dist/esm/models/api-catalog-dto.d.ts +2 -2
  61. package/dist/esm/models/api-catalog-dto.js +2 -2
  62. package/dist/esm/models/api-catalog-entry-dto.d.ts +2 -2
  63. package/dist/esm/models/api-catalog-entry-dto.js +2 -2
  64. package/dist/esm/models/api-catalog-link-dto.d.ts +2 -2
  65. package/dist/esm/models/api-catalog-link-dto.js +2 -2
  66. package/dist/esm/models/authorization-server-metadata-dto.d.ts +2 -2
  67. package/dist/esm/models/authorization-server-metadata-dto.js +2 -2
  68. package/dist/esm/models/award-method-public.d.ts +2 -2
  69. package/dist/esm/models/award-method-public.js +2 -2
  70. package/dist/esm/models/award-registered-v2-response-dto.d.ts +2 -2
  71. package/dist/esm/models/award-registered-v2-response-dto.js +2 -2
  72. package/dist/esm/models/award-reverted-v2-response-dto.d.ts +2 -2
  73. package/dist/esm/models/award-reverted-v2-response-dto.js +2 -2
  74. package/dist/esm/models/bid-acceptance-dto.d.ts +2 -2
  75. package/dist/esm/models/bid-acceptance-dto.js +2 -2
  76. package/dist/esm/models/bid-attachment-input-dto.d.ts +2 -2
  77. package/dist/esm/models/bid-attachment-input-dto.js +2 -2
  78. package/dist/esm/models/bid-bond-dto.d.ts +2 -2
  79. package/dist/esm/models/bid-bond-dto.js +2 -2
  80. package/dist/esm/models/bid-cancelled-response-dto.d.ts +2 -2
  81. package/dist/esm/models/bid-cancelled-response-dto.js +2 -2
  82. package/dist/esm/models/bid-contact-dto.d.ts +2 -2
  83. package/dist/esm/models/bid-contact-dto.js +2 -2
  84. package/dist/esm/models/bid-contacts-dto.d.ts +2 -2
  85. package/dist/esm/models/bid-contacts-dto.js +2 -2
  86. package/dist/esm/models/bid-contract-document-dto.d.ts +2 -2
  87. package/dist/esm/models/bid-contract-document-dto.js +2 -2
  88. package/dist/esm/models/bid-delivery-terms-dto.d.ts +2 -2
  89. package/dist/esm/models/bid-delivery-terms-dto.js +2 -2
  90. package/dist/esm/models/bid-detail-response-dto.d.ts +2 -2
  91. package/dist/esm/models/bid-detail-response-dto.js +2 -2
  92. package/dist/esm/models/bid-document-dto.d.ts +2 -2
  93. package/dist/esm/models/bid-document-dto.js +2 -2
  94. package/dist/esm/models/bid-failed-v2-response-dto.d.ts +2 -2
  95. package/dist/esm/models/bid-failed-v2-response-dto.js +2 -2
  96. package/dist/esm/models/bid-item-dto.d.ts +2 -2
  97. package/dist/esm/models/bid-item-dto.js +2 -2
  98. package/dist/esm/models/bid-lifecycle-dto.d.ts +2 -2
  99. package/dist/esm/models/bid-lifecycle-dto.js +2 -2
  100. package/dist/esm/models/bid-manager-dto.d.ts +2 -2
  101. package/dist/esm/models/bid-manager-dto.js +2 -2
  102. package/dist/esm/models/bid-payment-terms-dto.d.ts +2 -2
  103. package/dist/esm/models/bid-payment-terms-dto.js +2 -2
  104. package/dist/esm/models/bid-product-dto.d.ts +2 -2
  105. package/dist/esm/models/bid-product-dto.js +2 -2
  106. package/dist/esm/models/bid-public-status.d.ts +2 -2
  107. package/dist/esm/models/bid-public-status.js +2 -2
  108. package/dist/esm/models/bid-registered-response-dto.d.ts +2 -2
  109. package/dist/esm/models/bid-registered-response-dto.js +2 -2
  110. package/dist/esm/models/bid-result-participant-attachment-dto.d.ts +2 -2
  111. package/dist/esm/models/bid-result-participant-attachment-dto.js +2 -2
  112. package/dist/esm/models/bid-result-participant-dto.d.ts +2 -2
  113. package/dist/esm/models/bid-result-participant-dto.js +2 -2
  114. package/dist/esm/models/bid-results-response-dto.d.ts +2 -2
  115. package/dist/esm/models/bid-results-response-dto.js +2 -2
  116. package/dist/esm/models/bid-settlement-line-item-dto.d.ts +2 -2
  117. package/dist/esm/models/bid-settlement-line-item-dto.js +2 -2
  118. package/dist/esm/models/bid-settlement-participant-dto.d.ts +2 -2
  119. package/dist/esm/models/bid-settlement-participant-dto.js +2 -2
  120. package/dist/esm/models/bid-settlement-response-dto.d.ts +2 -2
  121. package/dist/esm/models/bid-settlement-response-dto.js +2 -2
  122. package/dist/esm/models/bid-statement-response-dto.d.ts +2 -2
  123. package/dist/esm/models/bid-statement-response-dto.js +2 -2
  124. package/dist/esm/models/bid-summary-dto.d.ts +2 -2
  125. package/dist/esm/models/bid-summary-dto.js +2 -2
  126. package/dist/esm/models/bid-type-public.d.ts +2 -2
  127. package/dist/esm/models/bid-type-public.js +2 -2
  128. package/dist/esm/models/bid-updated-response-dto.d.ts +2 -2
  129. package/dist/esm/models/bid-updated-response-dto.js +2 -2
  130. package/dist/esm/models/cancel-bid-request-dto.d.ts +2 -2
  131. package/dist/esm/models/cancel-bid-request-dto.js +2 -2
  132. package/dist/esm/models/cancel-bid200-response.d.ts +2 -2
  133. package/dist/esm/models/cancel-bid200-response.js +2 -2
  134. package/dist/esm/models/card-payment-request-response-dto.d.ts +2 -2
  135. package/dist/esm/models/card-payment-request-response-dto.js +2 -2
  136. package/dist/esm/models/complete-acceptance-request-dto.d.ts +2 -2
  137. package/dist/esm/models/complete-acceptance-request-dto.js +2 -2
  138. package/dist/esm/models/complete-acceptance200-response.d.ts +2 -2
  139. package/dist/esm/models/complete-acceptance200-response.js +2 -2
  140. package/dist/esm/models/complete-invoice200-response.d.ts +2 -2
  141. package/dist/esm/models/complete-invoice200-response.js +2 -2
  142. package/dist/esm/models/complete-upload-request-dto.d.ts +2 -2
  143. package/dist/esm/models/complete-upload-request-dto.js +2 -2
  144. package/dist/esm/models/contract-restriction-confirm-input-dto.d.ts +2 -2
  145. package/dist/esm/models/contract-restriction-confirm-input-dto.js +2 -2
  146. package/dist/esm/models/create-bid-request-dto.d.ts +3 -3
  147. package/dist/esm/models/create-bid-request-dto.js +2 -2
  148. package/dist/esm/models/create-card-payment-dto.d.ts +2 -2
  149. package/dist/esm/models/create-card-payment-dto.js +2 -2
  150. package/dist/esm/models/create-card-payment-request-dto.d.ts +2 -2
  151. package/dist/esm/models/create-card-payment-request-dto.js +2 -2
  152. package/dist/esm/models/create-card-payment200-response.d.ts +2 -2
  153. package/dist/esm/models/create-card-payment200-response.js +2 -2
  154. package/dist/esm/models/create-embed-launch201-response.d.ts +2 -2
  155. package/dist/esm/models/create-embed-launch201-response.js +2 -2
  156. package/dist/esm/models/create-external-contract-documents-request-dto.d.ts +2 -2
  157. package/dist/esm/models/create-external-contract-documents-request-dto.js +2 -2
  158. package/dist/esm/models/create-external-contract-documents-response-dto.d.ts +2 -2
  159. package/dist/esm/models/create-external-contract-documents-response-dto.js +2 -2
  160. package/dist/esm/models/create-file-upload-url201-response.d.ts +2 -2
  161. package/dist/esm/models/create-file-upload-url201-response.js +2 -2
  162. package/dist/esm/models/create-upload-url-request-dto.d.ts +2 -2
  163. package/dist/esm/models/create-upload-url-request-dto.js +2 -2
  164. package/dist/esm/models/create-webhook-endpoint-request-dto.d.ts +2 -2
  165. package/dist/esm/models/create-webhook-endpoint-request-dto.js +2 -2
  166. package/dist/esm/models/create-webhook-endpoint201-response.d.ts +2 -2
  167. package/dist/esm/models/create-webhook-endpoint201-response.js +2 -2
  168. package/dist/esm/models/delivery-date-type-public.d.ts +2 -2
  169. package/dist/esm/models/delivery-date-type-public.js +2 -2
  170. package/dist/esm/models/delivery-method-public.d.ts +2 -2
  171. package/dist/esm/models/delivery-method-public.js +2 -2
  172. package/dist/esm/models/embed-bid-prefill-dto.d.ts +2 -2
  173. package/dist/esm/models/embed-bid-prefill-dto.js +2 -2
  174. package/dist/esm/models/embed-bid-prefill-item-dto.d.ts +2 -2
  175. package/dist/esm/models/embed-bid-prefill-item-dto.js +2 -2
  176. package/dist/esm/models/embed-bid-prefill-manager-dto.d.ts +2 -2
  177. package/dist/esm/models/embed-bid-prefill-manager-dto.js +2 -2
  178. package/dist/esm/models/embed-launch-request-dto.d.ts +2 -2
  179. package/dist/esm/models/embed-launch-request-dto.js +2 -2
  180. package/dist/esm/models/embed-launch-response-dto.d.ts +2 -2
  181. package/dist/esm/models/embed-launch-response-dto.js +2 -2
  182. package/dist/esm/models/excellent-procurement-public.d.ts +2 -2
  183. package/dist/esm/models/excellent-procurement-public.js +2 -2
  184. package/dist/esm/models/external-contract-document-item-dto.d.ts +2 -2
  185. package/dist/esm/models/external-contract-document-item-dto.js +2 -2
  186. package/dist/esm/models/external-contract-documents-response-dto.d.ts +2 -2
  187. package/dist/esm/models/external-contract-documents-response-dto.js +2 -2
  188. package/dist/esm/models/external-contract-item-dto.d.ts +2 -2
  189. package/dist/esm/models/external-contract-item-dto.js +2 -2
  190. package/dist/esm/models/external-contract-snapshot-dto.d.ts +2 -2
  191. package/dist/esm/models/external-contract-snapshot-dto.js +2 -2
  192. package/dist/esm/models/external-document-inputs-dto.d.ts +2 -2
  193. package/dist/esm/models/external-document-inputs-dto.js +2 -2
  194. package/dist/esm/models/file-meta-response-dto.d.ts +2 -2
  195. package/dist/esm/models/file-meta-response-dto.js +2 -2
  196. package/dist/esm/models/file-uploaded-response-dto.d.ts +2 -2
  197. package/dist/esm/models/file-uploaded-response-dto.js +2 -2
  198. package/dist/esm/models/generated-external-contract-document-dto.d.ts +2 -2
  199. package/dist/esm/models/generated-external-contract-document-dto.js +2 -2
  200. package/dist/esm/models/get-bid-settlement200-response.d.ts +2 -2
  201. package/dist/esm/models/get-bid-settlement200-response.js +2 -2
  202. package/dist/esm/models/get-bid-statement200-response.d.ts +2 -2
  203. package/dist/esm/models/get-bid-statement200-response.js +2 -2
  204. package/dist/esm/models/get-bid200-response.d.ts +2 -2
  205. package/dist/esm/models/get-bid200-response.js +2 -2
  206. package/dist/esm/models/get-file-meta200-response.d.ts +2 -2
  207. package/dist/esm/models/get-file-meta200-response.js +2 -2
  208. package/dist/esm/models/get-supplier-card-payable-v2200-response.d.ts +2 -2
  209. package/dist/esm/models/get-supplier-card-payable-v2200-response.js +2 -2
  210. package/dist/esm/models/get-webhook-endpoint200-response.d.ts +2 -2
  211. package/dist/esm/models/get-webhook-endpoint200-response.js +2 -2
  212. package/dist/esm/models/green-product-public.d.ts +2 -2
  213. package/dist/esm/models/green-product-public.js +2 -2
  214. package/dist/esm/models/health-controller-check200-response.d.ts +2 -2
  215. package/dist/esm/models/health-controller-check200-response.js +2 -2
  216. package/dist/esm/models/health-response-dto.d.ts +2 -2
  217. package/dist/esm/models/health-response-dto.js +2 -2
  218. package/dist/esm/models/hierarchical-region-dto.d.ts +2 -2
  219. package/dist/esm/models/hierarchical-region-dto.js +2 -2
  220. package/dist/esm/models/introspect-request-dto.d.ts +2 -2
  221. package/dist/esm/models/introspect-request-dto.js +2 -2
  222. package/dist/esm/models/introspection-response-dto.d.ts +2 -2
  223. package/dist/esm/models/introspection-response-dto.js +2 -2
  224. package/dist/esm/models/invalid-param-dto.d.ts +2 -2
  225. package/dist/esm/models/invalid-param-dto.js +2 -2
  226. package/dist/esm/models/invoice-completed-response-dto.d.ts +2 -2
  227. package/dist/esm/models/invoice-completed-response-dto.js +2 -2
  228. package/dist/esm/models/invoice-split-response-dto.d.ts +2 -2
  229. package/dist/esm/models/invoice-split-response-dto.js +2 -2
  230. package/dist/esm/models/legal-mandatory-public.d.ts +2 -2
  231. package/dist/esm/models/legal-mandatory-public.js +2 -2
  232. package/dist/esm/models/list-bid-results200-response.d.ts +2 -2
  233. package/dist/esm/models/list-bid-results200-response.js +2 -2
  234. package/dist/esm/models/list-bids200-response-meta.d.ts +2 -2
  235. package/dist/esm/models/list-bids200-response-meta.js +2 -2
  236. package/dist/esm/models/list-bids200-response.d.ts +2 -2
  237. package/dist/esm/models/list-bids200-response.js +2 -2
  238. package/dist/esm/models/list-products200-response.d.ts +2 -2
  239. package/dist/esm/models/list-products200-response.js +2 -2
  240. package/dist/esm/models/list-webhook-deliveries-response-dto.d.ts +2 -2
  241. package/dist/esm/models/list-webhook-deliveries-response-dto.js +2 -2
  242. package/dist/esm/models/list-webhook-deliveries200-response.d.ts +2 -2
  243. package/dist/esm/models/list-webhook-deliveries200-response.js +2 -2
  244. package/dist/esm/models/list-webhook-endpoints200-response.d.ts +2 -2
  245. package/dist/esm/models/list-webhook-endpoints200-response.js +2 -2
  246. package/dist/esm/models/mark-bid-failed-request-dto.d.ts +2 -2
  247. package/dist/esm/models/mark-bid-failed-request-dto.js +2 -2
  248. package/dist/esm/models/mark-bid-failed201-response.d.ts +2 -2
  249. package/dist/esm/models/mark-bid-failed201-response.js +2 -2
  250. package/dist/esm/models/oauth-error-response-dto.d.ts +2 -2
  251. package/dist/esm/models/oauth-error-response-dto.js +2 -2
  252. package/dist/esm/models/on-bid-award-reverted-request.d.ts +2 -2
  253. package/dist/esm/models/on-bid-award-reverted-request.js +2 -2
  254. package/dist/esm/models/on-bid-awarded-request.d.ts +2 -2
  255. package/dist/esm/models/on-bid-awarded-request.js +2 -2
  256. package/dist/esm/models/on-bid-canceled-request.d.ts +2 -2
  257. package/dist/esm/models/on-bid-canceled-request.js +2 -2
  258. package/dist/esm/models/on-bid-closed-request.d.ts +2 -2
  259. package/dist/esm/models/on-bid-closed-request.js +2 -2
  260. package/dist/esm/models/on-bid-failed-request.d.ts +2 -2
  261. package/dist/esm/models/on-bid-failed-request.js +2 -2
  262. package/dist/esm/models/on-ping-request.d.ts +2 -2
  263. package/dist/esm/models/on-ping-request.js +2 -2
  264. package/dist/esm/models/partner-webhook-delivery-status.d.ts +2 -2
  265. package/dist/esm/models/partner-webhook-delivery-status.js +2 -2
  266. package/dist/esm/models/partner-webhook-endpoint-status.d.ts +2 -2
  267. package/dist/esm/models/partner-webhook-endpoint-status.js +2 -2
  268. package/dist/esm/models/partner-webhook-event-type.d.ts +2 -2
  269. package/dist/esm/models/partner-webhook-event-type.js +2 -2
  270. package/dist/esm/models/payment-method-public.d.ts +2 -2
  271. package/dist/esm/models/payment-method-public.js +2 -2
  272. package/dist/esm/models/preconditions-dto.d.ts +2 -2
  273. package/dist/esm/models/preconditions-dto.js +2 -2
  274. package/dist/esm/models/problem-details-dto.d.ts +6 -2
  275. package/dist/esm/models/problem-details-dto.js +2 -2
  276. package/dist/esm/models/product-receipt-response-dto.d.ts +2 -2
  277. package/dist/esm/models/product-receipt-response-dto.js +2 -2
  278. package/dist/esm/models/product-response-dto.d.ts +2 -2
  279. package/dist/esm/models/product-response-dto.js +2 -2
  280. package/dist/esm/models/protected-resource-metadata-dto.d.ts +2 -2
  281. package/dist/esm/models/protected-resource-metadata-dto.js +2 -2
  282. package/dist/esm/models/register-award-request-dto.d.ts +2 -2
  283. package/dist/esm/models/register-award-request-dto.js +2 -2
  284. package/dist/esm/models/register-award201-response.d.ts +2 -2
  285. package/dist/esm/models/register-award201-response.js +2 -2
  286. package/dist/esm/models/register-bid201-response.d.ts +2 -2
  287. package/dist/esm/models/register-bid201-response.js +2 -2
  288. package/dist/esm/models/register-semo-contract-request-dto.d.ts +2 -2
  289. package/dist/esm/models/register-semo-contract-request-dto.js +2 -2
  290. package/dist/esm/models/request-invoice-split-request-dto.d.ts +2 -2
  291. package/dist/esm/models/request-invoice-split-request-dto.js +2 -2
  292. package/dist/esm/models/request-invoice-split200-response.d.ts +2 -2
  293. package/dist/esm/models/request-invoice-split200-response.js +2 -2
  294. package/dist/esm/models/retiree-roster-input-dto.d.ts +2 -2
  295. package/dist/esm/models/retiree-roster-input-dto.js +2 -2
  296. package/dist/esm/models/retiree-roster-row-dto.d.ts +2 -2
  297. package/dist/esm/models/retiree-roster-row-dto.js +2 -2
  298. package/dist/esm/models/revert-award-request-dto.d.ts +2 -2
  299. package/dist/esm/models/revert-award-request-dto.js +2 -2
  300. package/dist/esm/models/revert-award200-response.d.ts +2 -2
  301. package/dist/esm/models/revert-award200-response.js +2 -2
  302. package/dist/esm/models/revoke-request-dto.d.ts +2 -2
  303. package/dist/esm/models/revoke-request-dto.js +2 -2
  304. package/dist/esm/models/semo-contract-registered-response-dto.d.ts +2 -2
  305. package/dist/esm/models/semo-contract-registered-response-dto.js +2 -2
  306. package/dist/esm/models/semo-contract-taxinvoice-status-response-dto.d.ts +2 -2
  307. package/dist/esm/models/semo-contract-taxinvoice-status-response-dto.js +2 -2
  308. package/dist/esm/models/send-webhook-test-event200-response.d.ts +2 -2
  309. package/dist/esm/models/send-webhook-test-event200-response.js +2 -2
  310. package/dist/esm/models/statement-document-dto.d.ts +2 -2
  311. package/dist/esm/models/statement-document-dto.js +2 -2
  312. package/dist/esm/models/statement-product-dto.d.ts +2 -2
  313. package/dist/esm/models/statement-product-dto.js +2 -2
  314. package/dist/esm/models/supplier-card-payable-response-dto.d.ts +2 -2
  315. package/dist/esm/models/supplier-card-payable-response-dto.js +2 -2
  316. package/dist/esm/models/supplier-tax-type.d.ts +2 -2
  317. package/dist/esm/models/supplier-tax-type.js +2 -2
  318. package/dist/esm/models/token-request-dto.d.ts +2 -2
  319. package/dist/esm/models/token-request-dto.js +2 -2
  320. package/dist/esm/models/token-response-dto.d.ts +2 -2
  321. package/dist/esm/models/token-response-dto.js +2 -2
  322. package/dist/esm/models/update-bid-request-dto.d.ts +3 -3
  323. package/dist/esm/models/update-bid-request-dto.js +2 -2
  324. package/dist/esm/models/update-bid200-response.d.ts +2 -2
  325. package/dist/esm/models/update-bid200-response.js +2 -2
  326. package/dist/esm/models/update-webhook-endpoint-request-dto.d.ts +2 -2
  327. package/dist/esm/models/update-webhook-endpoint-request-dto.js +2 -2
  328. package/dist/esm/models/upload-file-request-dto.d.ts +2 -2
  329. package/dist/esm/models/upload-file-request-dto.js +2 -2
  330. package/dist/esm/models/upload-file201-response.d.ts +2 -2
  331. package/dist/esm/models/upload-file201-response.js +2 -2
  332. package/dist/esm/models/upload-url-created-response-dto.d.ts +2 -2
  333. package/dist/esm/models/upload-url-created-response-dto.js +2 -2
  334. package/dist/esm/models/webhook-bid-event-data.d.ts +2 -2
  335. package/dist/esm/models/webhook-bid-event-data.js +2 -2
  336. package/dist/esm/models/webhook-delivery-dto.d.ts +2 -2
  337. package/dist/esm/models/webhook-delivery-dto.js +2 -2
  338. package/dist/esm/models/webhook-endpoint-dto.d.ts +2 -2
  339. package/dist/esm/models/webhook-endpoint-dto.js +2 -2
  340. package/dist/esm/models/webhook-endpoint-with-secret-dto.d.ts +2 -2
  341. package/dist/esm/models/webhook-endpoint-with-secret-dto.js +2 -2
  342. package/dist/esm/models/webhook-event-envelope.d.ts +2 -2
  343. package/dist/esm/models/webhook-event-envelope.js +2 -2
  344. package/dist/esm/models/webhook-ping-event-data.d.ts +2 -2
  345. package/dist/esm/models/webhook-ping-event-data.js +2 -2
  346. package/dist/esm/models/webhook-test-result-dto.d.ts +2 -2
  347. package/dist/esm/models/webhook-test-result-dto.js +2 -2
  348. package/dist/index.d.ts +2 -2
  349. package/dist/index.js +2 -2
  350. package/dist/models/acceptance-result-response-dto.d.ts +2 -2
  351. package/dist/models/acceptance-result-response-dto.js +2 -2
  352. package/dist/models/acknowledge-product-receipt200-response.d.ts +2 -2
  353. package/dist/models/acknowledge-product-receipt200-response.js +2 -2
  354. package/dist/models/acknowledge-products-request-dto.d.ts +2 -2
  355. package/dist/models/acknowledge-products-request-dto.js +2 -2
  356. package/dist/models/api-catalog-dto.d.ts +2 -2
  357. package/dist/models/api-catalog-dto.js +2 -2
  358. package/dist/models/api-catalog-entry-dto.d.ts +2 -2
  359. package/dist/models/api-catalog-entry-dto.js +2 -2
  360. package/dist/models/api-catalog-link-dto.d.ts +2 -2
  361. package/dist/models/api-catalog-link-dto.js +2 -2
  362. package/dist/models/authorization-server-metadata-dto.d.ts +2 -2
  363. package/dist/models/authorization-server-metadata-dto.js +2 -2
  364. package/dist/models/award-method-public.d.ts +2 -2
  365. package/dist/models/award-method-public.js +2 -2
  366. package/dist/models/award-registered-v2-response-dto.d.ts +2 -2
  367. package/dist/models/award-registered-v2-response-dto.js +2 -2
  368. package/dist/models/award-reverted-v2-response-dto.d.ts +2 -2
  369. package/dist/models/award-reverted-v2-response-dto.js +2 -2
  370. package/dist/models/bid-acceptance-dto.d.ts +2 -2
  371. package/dist/models/bid-acceptance-dto.js +2 -2
  372. package/dist/models/bid-attachment-input-dto.d.ts +2 -2
  373. package/dist/models/bid-attachment-input-dto.js +2 -2
  374. package/dist/models/bid-bond-dto.d.ts +2 -2
  375. package/dist/models/bid-bond-dto.js +2 -2
  376. package/dist/models/bid-cancelled-response-dto.d.ts +2 -2
  377. package/dist/models/bid-cancelled-response-dto.js +2 -2
  378. package/dist/models/bid-contact-dto.d.ts +2 -2
  379. package/dist/models/bid-contact-dto.js +2 -2
  380. package/dist/models/bid-contacts-dto.d.ts +2 -2
  381. package/dist/models/bid-contacts-dto.js +2 -2
  382. package/dist/models/bid-contract-document-dto.d.ts +2 -2
  383. package/dist/models/bid-contract-document-dto.js +2 -2
  384. package/dist/models/bid-delivery-terms-dto.d.ts +2 -2
  385. package/dist/models/bid-delivery-terms-dto.js +2 -2
  386. package/dist/models/bid-detail-response-dto.d.ts +2 -2
  387. package/dist/models/bid-detail-response-dto.js +2 -2
  388. package/dist/models/bid-document-dto.d.ts +2 -2
  389. package/dist/models/bid-document-dto.js +2 -2
  390. package/dist/models/bid-failed-v2-response-dto.d.ts +2 -2
  391. package/dist/models/bid-failed-v2-response-dto.js +2 -2
  392. package/dist/models/bid-item-dto.d.ts +2 -2
  393. package/dist/models/bid-item-dto.js +2 -2
  394. package/dist/models/bid-lifecycle-dto.d.ts +2 -2
  395. package/dist/models/bid-lifecycle-dto.js +2 -2
  396. package/dist/models/bid-manager-dto.d.ts +2 -2
  397. package/dist/models/bid-manager-dto.js +2 -2
  398. package/dist/models/bid-payment-terms-dto.d.ts +2 -2
  399. package/dist/models/bid-payment-terms-dto.js +2 -2
  400. package/dist/models/bid-product-dto.d.ts +2 -2
  401. package/dist/models/bid-product-dto.js +2 -2
  402. package/dist/models/bid-public-status.d.ts +2 -2
  403. package/dist/models/bid-public-status.js +2 -2
  404. package/dist/models/bid-registered-response-dto.d.ts +2 -2
  405. package/dist/models/bid-registered-response-dto.js +2 -2
  406. package/dist/models/bid-result-participant-attachment-dto.d.ts +2 -2
  407. package/dist/models/bid-result-participant-attachment-dto.js +2 -2
  408. package/dist/models/bid-result-participant-dto.d.ts +2 -2
  409. package/dist/models/bid-result-participant-dto.js +2 -2
  410. package/dist/models/bid-results-response-dto.d.ts +2 -2
  411. package/dist/models/bid-results-response-dto.js +2 -2
  412. package/dist/models/bid-settlement-line-item-dto.d.ts +2 -2
  413. package/dist/models/bid-settlement-line-item-dto.js +2 -2
  414. package/dist/models/bid-settlement-participant-dto.d.ts +2 -2
  415. package/dist/models/bid-settlement-participant-dto.js +2 -2
  416. package/dist/models/bid-settlement-response-dto.d.ts +2 -2
  417. package/dist/models/bid-settlement-response-dto.js +2 -2
  418. package/dist/models/bid-statement-response-dto.d.ts +2 -2
  419. package/dist/models/bid-statement-response-dto.js +2 -2
  420. package/dist/models/bid-summary-dto.d.ts +2 -2
  421. package/dist/models/bid-summary-dto.js +2 -2
  422. package/dist/models/bid-type-public.d.ts +2 -2
  423. package/dist/models/bid-type-public.js +2 -2
  424. package/dist/models/bid-updated-response-dto.d.ts +2 -2
  425. package/dist/models/bid-updated-response-dto.js +2 -2
  426. package/dist/models/cancel-bid-request-dto.d.ts +2 -2
  427. package/dist/models/cancel-bid-request-dto.js +2 -2
  428. package/dist/models/cancel-bid200-response.d.ts +2 -2
  429. package/dist/models/cancel-bid200-response.js +2 -2
  430. package/dist/models/card-payment-request-response-dto.d.ts +2 -2
  431. package/dist/models/card-payment-request-response-dto.js +2 -2
  432. package/dist/models/complete-acceptance-request-dto.d.ts +2 -2
  433. package/dist/models/complete-acceptance-request-dto.js +2 -2
  434. package/dist/models/complete-acceptance200-response.d.ts +2 -2
  435. package/dist/models/complete-acceptance200-response.js +2 -2
  436. package/dist/models/complete-invoice200-response.d.ts +2 -2
  437. package/dist/models/complete-invoice200-response.js +2 -2
  438. package/dist/models/complete-upload-request-dto.d.ts +2 -2
  439. package/dist/models/complete-upload-request-dto.js +2 -2
  440. package/dist/models/contract-restriction-confirm-input-dto.d.ts +2 -2
  441. package/dist/models/contract-restriction-confirm-input-dto.js +2 -2
  442. package/dist/models/create-bid-request-dto.d.ts +3 -3
  443. package/dist/models/create-bid-request-dto.js +2 -2
  444. package/dist/models/create-card-payment-dto.d.ts +2 -2
  445. package/dist/models/create-card-payment-dto.js +2 -2
  446. package/dist/models/create-card-payment-request-dto.d.ts +2 -2
  447. package/dist/models/create-card-payment-request-dto.js +2 -2
  448. package/dist/models/create-card-payment200-response.d.ts +2 -2
  449. package/dist/models/create-card-payment200-response.js +2 -2
  450. package/dist/models/create-embed-launch201-response.d.ts +2 -2
  451. package/dist/models/create-embed-launch201-response.js +2 -2
  452. package/dist/models/create-external-contract-documents-request-dto.d.ts +2 -2
  453. package/dist/models/create-external-contract-documents-request-dto.js +2 -2
  454. package/dist/models/create-external-contract-documents-response-dto.d.ts +2 -2
  455. package/dist/models/create-external-contract-documents-response-dto.js +2 -2
  456. package/dist/models/create-file-upload-url201-response.d.ts +2 -2
  457. package/dist/models/create-file-upload-url201-response.js +2 -2
  458. package/dist/models/create-upload-url-request-dto.d.ts +2 -2
  459. package/dist/models/create-upload-url-request-dto.js +2 -2
  460. package/dist/models/create-webhook-endpoint-request-dto.d.ts +2 -2
  461. package/dist/models/create-webhook-endpoint-request-dto.js +2 -2
  462. package/dist/models/create-webhook-endpoint201-response.d.ts +2 -2
  463. package/dist/models/create-webhook-endpoint201-response.js +2 -2
  464. package/dist/models/delivery-date-type-public.d.ts +2 -2
  465. package/dist/models/delivery-date-type-public.js +2 -2
  466. package/dist/models/delivery-method-public.d.ts +2 -2
  467. package/dist/models/delivery-method-public.js +2 -2
  468. package/dist/models/embed-bid-prefill-dto.d.ts +2 -2
  469. package/dist/models/embed-bid-prefill-dto.js +2 -2
  470. package/dist/models/embed-bid-prefill-item-dto.d.ts +2 -2
  471. package/dist/models/embed-bid-prefill-item-dto.js +2 -2
  472. package/dist/models/embed-bid-prefill-manager-dto.d.ts +2 -2
  473. package/dist/models/embed-bid-prefill-manager-dto.js +2 -2
  474. package/dist/models/embed-launch-request-dto.d.ts +2 -2
  475. package/dist/models/embed-launch-request-dto.js +2 -2
  476. package/dist/models/embed-launch-response-dto.d.ts +2 -2
  477. package/dist/models/embed-launch-response-dto.js +2 -2
  478. package/dist/models/excellent-procurement-public.d.ts +2 -2
  479. package/dist/models/excellent-procurement-public.js +2 -2
  480. package/dist/models/external-contract-document-item-dto.d.ts +2 -2
  481. package/dist/models/external-contract-document-item-dto.js +2 -2
  482. package/dist/models/external-contract-documents-response-dto.d.ts +2 -2
  483. package/dist/models/external-contract-documents-response-dto.js +2 -2
  484. package/dist/models/external-contract-item-dto.d.ts +2 -2
  485. package/dist/models/external-contract-item-dto.js +2 -2
  486. package/dist/models/external-contract-snapshot-dto.d.ts +2 -2
  487. package/dist/models/external-contract-snapshot-dto.js +2 -2
  488. package/dist/models/external-document-inputs-dto.d.ts +2 -2
  489. package/dist/models/external-document-inputs-dto.js +2 -2
  490. package/dist/models/file-meta-response-dto.d.ts +2 -2
  491. package/dist/models/file-meta-response-dto.js +2 -2
  492. package/dist/models/file-uploaded-response-dto.d.ts +2 -2
  493. package/dist/models/file-uploaded-response-dto.js +2 -2
  494. package/dist/models/generated-external-contract-document-dto.d.ts +2 -2
  495. package/dist/models/generated-external-contract-document-dto.js +2 -2
  496. package/dist/models/get-bid-settlement200-response.d.ts +2 -2
  497. package/dist/models/get-bid-settlement200-response.js +2 -2
  498. package/dist/models/get-bid-statement200-response.d.ts +2 -2
  499. package/dist/models/get-bid-statement200-response.js +2 -2
  500. package/dist/models/get-bid200-response.d.ts +2 -2
  501. package/dist/models/get-bid200-response.js +2 -2
  502. package/dist/models/get-file-meta200-response.d.ts +2 -2
  503. package/dist/models/get-file-meta200-response.js +2 -2
  504. package/dist/models/get-supplier-card-payable-v2200-response.d.ts +2 -2
  505. package/dist/models/get-supplier-card-payable-v2200-response.js +2 -2
  506. package/dist/models/get-webhook-endpoint200-response.d.ts +2 -2
  507. package/dist/models/get-webhook-endpoint200-response.js +2 -2
  508. package/dist/models/green-product-public.d.ts +2 -2
  509. package/dist/models/green-product-public.js +2 -2
  510. package/dist/models/health-controller-check200-response.d.ts +2 -2
  511. package/dist/models/health-controller-check200-response.js +2 -2
  512. package/dist/models/health-response-dto.d.ts +2 -2
  513. package/dist/models/health-response-dto.js +2 -2
  514. package/dist/models/hierarchical-region-dto.d.ts +2 -2
  515. package/dist/models/hierarchical-region-dto.js +2 -2
  516. package/dist/models/introspect-request-dto.d.ts +2 -2
  517. package/dist/models/introspect-request-dto.js +2 -2
  518. package/dist/models/introspection-response-dto.d.ts +2 -2
  519. package/dist/models/introspection-response-dto.js +2 -2
  520. package/dist/models/invalid-param-dto.d.ts +2 -2
  521. package/dist/models/invalid-param-dto.js +2 -2
  522. package/dist/models/invoice-completed-response-dto.d.ts +2 -2
  523. package/dist/models/invoice-completed-response-dto.js +2 -2
  524. package/dist/models/invoice-split-response-dto.d.ts +2 -2
  525. package/dist/models/invoice-split-response-dto.js +2 -2
  526. package/dist/models/legal-mandatory-public.d.ts +2 -2
  527. package/dist/models/legal-mandatory-public.js +2 -2
  528. package/dist/models/list-bid-results200-response.d.ts +2 -2
  529. package/dist/models/list-bid-results200-response.js +2 -2
  530. package/dist/models/list-bids200-response-meta.d.ts +2 -2
  531. package/dist/models/list-bids200-response-meta.js +2 -2
  532. package/dist/models/list-bids200-response.d.ts +2 -2
  533. package/dist/models/list-bids200-response.js +2 -2
  534. package/dist/models/list-products200-response.d.ts +2 -2
  535. package/dist/models/list-products200-response.js +2 -2
  536. package/dist/models/list-webhook-deliveries-response-dto.d.ts +2 -2
  537. package/dist/models/list-webhook-deliveries-response-dto.js +2 -2
  538. package/dist/models/list-webhook-deliveries200-response.d.ts +2 -2
  539. package/dist/models/list-webhook-deliveries200-response.js +2 -2
  540. package/dist/models/list-webhook-endpoints200-response.d.ts +2 -2
  541. package/dist/models/list-webhook-endpoints200-response.js +2 -2
  542. package/dist/models/mark-bid-failed-request-dto.d.ts +2 -2
  543. package/dist/models/mark-bid-failed-request-dto.js +2 -2
  544. package/dist/models/mark-bid-failed201-response.d.ts +2 -2
  545. package/dist/models/mark-bid-failed201-response.js +2 -2
  546. package/dist/models/oauth-error-response-dto.d.ts +2 -2
  547. package/dist/models/oauth-error-response-dto.js +2 -2
  548. package/dist/models/on-bid-award-reverted-request.d.ts +2 -2
  549. package/dist/models/on-bid-award-reverted-request.js +2 -2
  550. package/dist/models/on-bid-awarded-request.d.ts +2 -2
  551. package/dist/models/on-bid-awarded-request.js +2 -2
  552. package/dist/models/on-bid-canceled-request.d.ts +2 -2
  553. package/dist/models/on-bid-canceled-request.js +2 -2
  554. package/dist/models/on-bid-closed-request.d.ts +2 -2
  555. package/dist/models/on-bid-closed-request.js +2 -2
  556. package/dist/models/on-bid-failed-request.d.ts +2 -2
  557. package/dist/models/on-bid-failed-request.js +2 -2
  558. package/dist/models/on-ping-request.d.ts +2 -2
  559. package/dist/models/on-ping-request.js +2 -2
  560. package/dist/models/partner-webhook-delivery-status.d.ts +2 -2
  561. package/dist/models/partner-webhook-delivery-status.js +2 -2
  562. package/dist/models/partner-webhook-endpoint-status.d.ts +2 -2
  563. package/dist/models/partner-webhook-endpoint-status.js +2 -2
  564. package/dist/models/partner-webhook-event-type.d.ts +2 -2
  565. package/dist/models/partner-webhook-event-type.js +2 -2
  566. package/dist/models/payment-method-public.d.ts +2 -2
  567. package/dist/models/payment-method-public.js +2 -2
  568. package/dist/models/preconditions-dto.d.ts +2 -2
  569. package/dist/models/preconditions-dto.js +2 -2
  570. package/dist/models/problem-details-dto.d.ts +6 -2
  571. package/dist/models/problem-details-dto.js +2 -2
  572. package/dist/models/product-receipt-response-dto.d.ts +2 -2
  573. package/dist/models/product-receipt-response-dto.js +2 -2
  574. package/dist/models/product-response-dto.d.ts +2 -2
  575. package/dist/models/product-response-dto.js +2 -2
  576. package/dist/models/protected-resource-metadata-dto.d.ts +2 -2
  577. package/dist/models/protected-resource-metadata-dto.js +2 -2
  578. package/dist/models/register-award-request-dto.d.ts +2 -2
  579. package/dist/models/register-award-request-dto.js +2 -2
  580. package/dist/models/register-award201-response.d.ts +2 -2
  581. package/dist/models/register-award201-response.js +2 -2
  582. package/dist/models/register-bid201-response.d.ts +2 -2
  583. package/dist/models/register-bid201-response.js +2 -2
  584. package/dist/models/register-semo-contract-request-dto.d.ts +2 -2
  585. package/dist/models/register-semo-contract-request-dto.js +2 -2
  586. package/dist/models/request-invoice-split-request-dto.d.ts +2 -2
  587. package/dist/models/request-invoice-split-request-dto.js +2 -2
  588. package/dist/models/request-invoice-split200-response.d.ts +2 -2
  589. package/dist/models/request-invoice-split200-response.js +2 -2
  590. package/dist/models/retiree-roster-input-dto.d.ts +2 -2
  591. package/dist/models/retiree-roster-input-dto.js +2 -2
  592. package/dist/models/retiree-roster-row-dto.d.ts +2 -2
  593. package/dist/models/retiree-roster-row-dto.js +2 -2
  594. package/dist/models/revert-award-request-dto.d.ts +2 -2
  595. package/dist/models/revert-award-request-dto.js +2 -2
  596. package/dist/models/revert-award200-response.d.ts +2 -2
  597. package/dist/models/revert-award200-response.js +2 -2
  598. package/dist/models/revoke-request-dto.d.ts +2 -2
  599. package/dist/models/revoke-request-dto.js +2 -2
  600. package/dist/models/semo-contract-registered-response-dto.d.ts +2 -2
  601. package/dist/models/semo-contract-registered-response-dto.js +2 -2
  602. package/dist/models/semo-contract-taxinvoice-status-response-dto.d.ts +2 -2
  603. package/dist/models/semo-contract-taxinvoice-status-response-dto.js +2 -2
  604. package/dist/models/send-webhook-test-event200-response.d.ts +2 -2
  605. package/dist/models/send-webhook-test-event200-response.js +2 -2
  606. package/dist/models/statement-document-dto.d.ts +2 -2
  607. package/dist/models/statement-document-dto.js +2 -2
  608. package/dist/models/statement-product-dto.d.ts +2 -2
  609. package/dist/models/statement-product-dto.js +2 -2
  610. package/dist/models/supplier-card-payable-response-dto.d.ts +2 -2
  611. package/dist/models/supplier-card-payable-response-dto.js +2 -2
  612. package/dist/models/supplier-tax-type.d.ts +2 -2
  613. package/dist/models/supplier-tax-type.js +2 -2
  614. package/dist/models/token-request-dto.d.ts +2 -2
  615. package/dist/models/token-request-dto.js +2 -2
  616. package/dist/models/token-response-dto.d.ts +2 -2
  617. package/dist/models/token-response-dto.js +2 -2
  618. package/dist/models/update-bid-request-dto.d.ts +3 -3
  619. package/dist/models/update-bid-request-dto.js +2 -2
  620. package/dist/models/update-bid200-response.d.ts +2 -2
  621. package/dist/models/update-bid200-response.js +2 -2
  622. package/dist/models/update-webhook-endpoint-request-dto.d.ts +2 -2
  623. package/dist/models/update-webhook-endpoint-request-dto.js +2 -2
  624. package/dist/models/upload-file-request-dto.d.ts +2 -2
  625. package/dist/models/upload-file-request-dto.js +2 -2
  626. package/dist/models/upload-file201-response.d.ts +2 -2
  627. package/dist/models/upload-file201-response.js +2 -2
  628. package/dist/models/upload-url-created-response-dto.d.ts +2 -2
  629. package/dist/models/upload-url-created-response-dto.js +2 -2
  630. package/dist/models/webhook-bid-event-data.d.ts +2 -2
  631. package/dist/models/webhook-bid-event-data.js +2 -2
  632. package/dist/models/webhook-delivery-dto.d.ts +2 -2
  633. package/dist/models/webhook-delivery-dto.js +2 -2
  634. package/dist/models/webhook-endpoint-dto.d.ts +2 -2
  635. package/dist/models/webhook-endpoint-dto.js +2 -2
  636. package/dist/models/webhook-endpoint-with-secret-dto.d.ts +2 -2
  637. package/dist/models/webhook-endpoint-with-secret-dto.js +2 -2
  638. package/dist/models/webhook-event-envelope.d.ts +2 -2
  639. package/dist/models/webhook-event-envelope.js +2 -2
  640. package/dist/models/webhook-ping-event-data.d.ts +2 -2
  641. package/dist/models/webhook-ping-event-data.js +2 -2
  642. package/dist/models/webhook-test-result-dto.d.ts +2 -2
  643. package/dist/models/webhook-test-result-dto.js +2 -2
  644. package/docs/CreateBidRequestDto.md +1 -1
  645. package/docs/PartnerApiApi.md +40 -40
  646. package/docs/ProblemDetailsDto.md +2 -0
  647. package/docs/ProductsApi.md +2 -2
  648. package/docs/UpdateBidRequestDto.md +1 -1
  649. package/index.ts +2 -2
  650. package/models/acceptance-result-response-dto.ts +2 -2
  651. package/models/acknowledge-product-receipt200-response.ts +2 -2
  652. package/models/acknowledge-products-request-dto.ts +2 -2
  653. package/models/api-catalog-dto.ts +2 -2
  654. package/models/api-catalog-entry-dto.ts +2 -2
  655. package/models/api-catalog-link-dto.ts +2 -2
  656. package/models/authorization-server-metadata-dto.ts +2 -2
  657. package/models/award-method-public.ts +2 -2
  658. package/models/award-registered-v2-response-dto.ts +2 -2
  659. package/models/award-reverted-v2-response-dto.ts +2 -2
  660. package/models/bid-acceptance-dto.ts +2 -2
  661. package/models/bid-attachment-input-dto.ts +2 -2
  662. package/models/bid-bond-dto.ts +2 -2
  663. package/models/bid-cancelled-response-dto.ts +2 -2
  664. package/models/bid-contact-dto.ts +2 -2
  665. package/models/bid-contacts-dto.ts +2 -2
  666. package/models/bid-contract-document-dto.ts +2 -2
  667. package/models/bid-delivery-terms-dto.ts +2 -2
  668. package/models/bid-detail-response-dto.ts +2 -2
  669. package/models/bid-document-dto.ts +2 -2
  670. package/models/bid-failed-v2-response-dto.ts +2 -2
  671. package/models/bid-item-dto.ts +2 -2
  672. package/models/bid-lifecycle-dto.ts +2 -2
  673. package/models/bid-manager-dto.ts +2 -2
  674. package/models/bid-payment-terms-dto.ts +2 -2
  675. package/models/bid-product-dto.ts +2 -2
  676. package/models/bid-public-status.ts +2 -2
  677. package/models/bid-registered-response-dto.ts +2 -2
  678. package/models/bid-result-participant-attachment-dto.ts +2 -2
  679. package/models/bid-result-participant-dto.ts +2 -2
  680. package/models/bid-results-response-dto.ts +2 -2
  681. package/models/bid-settlement-line-item-dto.ts +2 -2
  682. package/models/bid-settlement-participant-dto.ts +2 -2
  683. package/models/bid-settlement-response-dto.ts +2 -2
  684. package/models/bid-statement-response-dto.ts +2 -2
  685. package/models/bid-summary-dto.ts +2 -2
  686. package/models/bid-type-public.ts +2 -2
  687. package/models/bid-updated-response-dto.ts +2 -2
  688. package/models/cancel-bid-request-dto.ts +2 -2
  689. package/models/cancel-bid200-response.ts +2 -2
  690. package/models/card-payment-request-response-dto.ts +2 -2
  691. package/models/complete-acceptance-request-dto.ts +2 -2
  692. package/models/complete-acceptance200-response.ts +2 -2
  693. package/models/complete-invoice200-response.ts +2 -2
  694. package/models/complete-upload-request-dto.ts +2 -2
  695. package/models/contract-restriction-confirm-input-dto.ts +2 -2
  696. package/models/create-bid-request-dto.ts +3 -3
  697. package/models/create-card-payment-dto.ts +2 -2
  698. package/models/create-card-payment-request-dto.ts +2 -2
  699. package/models/create-card-payment200-response.ts +2 -2
  700. package/models/create-embed-launch201-response.ts +2 -2
  701. package/models/create-external-contract-documents-request-dto.ts +2 -2
  702. package/models/create-external-contract-documents-response-dto.ts +2 -2
  703. package/models/create-file-upload-url201-response.ts +2 -2
  704. package/models/create-upload-url-request-dto.ts +2 -2
  705. package/models/create-webhook-endpoint-request-dto.ts +2 -2
  706. package/models/create-webhook-endpoint201-response.ts +2 -2
  707. package/models/delivery-date-type-public.ts +2 -2
  708. package/models/delivery-method-public.ts +2 -2
  709. package/models/embed-bid-prefill-dto.ts +2 -2
  710. package/models/embed-bid-prefill-item-dto.ts +2 -2
  711. package/models/embed-bid-prefill-manager-dto.ts +2 -2
  712. package/models/embed-launch-request-dto.ts +2 -2
  713. package/models/embed-launch-response-dto.ts +2 -2
  714. package/models/excellent-procurement-public.ts +2 -2
  715. package/models/external-contract-document-item-dto.ts +2 -2
  716. package/models/external-contract-documents-response-dto.ts +2 -2
  717. package/models/external-contract-item-dto.ts +2 -2
  718. package/models/external-contract-snapshot-dto.ts +2 -2
  719. package/models/external-document-inputs-dto.ts +2 -2
  720. package/models/file-meta-response-dto.ts +2 -2
  721. package/models/file-uploaded-response-dto.ts +2 -2
  722. package/models/generated-external-contract-document-dto.ts +2 -2
  723. package/models/get-bid-settlement200-response.ts +2 -2
  724. package/models/get-bid-statement200-response.ts +2 -2
  725. package/models/get-bid200-response.ts +2 -2
  726. package/models/get-file-meta200-response.ts +2 -2
  727. package/models/get-supplier-card-payable-v2200-response.ts +2 -2
  728. package/models/get-webhook-endpoint200-response.ts +2 -2
  729. package/models/green-product-public.ts +2 -2
  730. package/models/health-controller-check200-response.ts +2 -2
  731. package/models/health-response-dto.ts +2 -2
  732. package/models/hierarchical-region-dto.ts +2 -2
  733. package/models/introspect-request-dto.ts +2 -2
  734. package/models/introspection-response-dto.ts +2 -2
  735. package/models/invalid-param-dto.ts +2 -2
  736. package/models/invoice-completed-response-dto.ts +2 -2
  737. package/models/invoice-split-response-dto.ts +2 -2
  738. package/models/legal-mandatory-public.ts +2 -2
  739. package/models/list-bid-results200-response.ts +2 -2
  740. package/models/list-bids200-response-meta.ts +2 -2
  741. package/models/list-bids200-response.ts +2 -2
  742. package/models/list-products200-response.ts +2 -2
  743. package/models/list-webhook-deliveries-response-dto.ts +2 -2
  744. package/models/list-webhook-deliveries200-response.ts +2 -2
  745. package/models/list-webhook-endpoints200-response.ts +2 -2
  746. package/models/mark-bid-failed-request-dto.ts +2 -2
  747. package/models/mark-bid-failed201-response.ts +2 -2
  748. package/models/oauth-error-response-dto.ts +2 -2
  749. package/models/on-bid-award-reverted-request.ts +2 -2
  750. package/models/on-bid-awarded-request.ts +2 -2
  751. package/models/on-bid-canceled-request.ts +2 -2
  752. package/models/on-bid-closed-request.ts +2 -2
  753. package/models/on-bid-failed-request.ts +2 -2
  754. package/models/on-ping-request.ts +2 -2
  755. package/models/partner-webhook-delivery-status.ts +2 -2
  756. package/models/partner-webhook-endpoint-status.ts +2 -2
  757. package/models/partner-webhook-event-type.ts +2 -2
  758. package/models/payment-method-public.ts +2 -2
  759. package/models/preconditions-dto.ts +2 -2
  760. package/models/problem-details-dto.ts +6 -2
  761. package/models/product-receipt-response-dto.ts +2 -2
  762. package/models/product-response-dto.ts +2 -2
  763. package/models/protected-resource-metadata-dto.ts +2 -2
  764. package/models/register-award-request-dto.ts +2 -2
  765. package/models/register-award201-response.ts +2 -2
  766. package/models/register-bid201-response.ts +2 -2
  767. package/models/register-semo-contract-request-dto.ts +2 -2
  768. package/models/request-invoice-split-request-dto.ts +2 -2
  769. package/models/request-invoice-split200-response.ts +2 -2
  770. package/models/retiree-roster-input-dto.ts +2 -2
  771. package/models/retiree-roster-row-dto.ts +2 -2
  772. package/models/revert-award-request-dto.ts +2 -2
  773. package/models/revert-award200-response.ts +2 -2
  774. package/models/revoke-request-dto.ts +2 -2
  775. package/models/semo-contract-registered-response-dto.ts +2 -2
  776. package/models/semo-contract-taxinvoice-status-response-dto.ts +2 -2
  777. package/models/send-webhook-test-event200-response.ts +2 -2
  778. package/models/statement-document-dto.ts +2 -2
  779. package/models/statement-product-dto.ts +2 -2
  780. package/models/supplier-card-payable-response-dto.ts +2 -2
  781. package/models/supplier-tax-type.ts +2 -2
  782. package/models/token-request-dto.ts +2 -2
  783. package/models/token-response-dto.ts +2 -2
  784. package/models/update-bid-request-dto.ts +3 -3
  785. package/models/update-bid200-response.ts +2 -2
  786. package/models/update-webhook-endpoint-request-dto.ts +2 -2
  787. package/models/upload-file-request-dto.ts +2 -2
  788. package/models/upload-file201-response.ts +2 -2
  789. package/models/upload-url-created-response-dto.ts +2 -2
  790. package/models/webhook-bid-event-data.ts +2 -2
  791. package/models/webhook-delivery-dto.ts +2 -2
  792. package/models/webhook-endpoint-dto.ts +2 -2
  793. package/models/webhook-endpoint-with-secret-dto.ts +2 -2
  794. package/models/webhook-event-envelope.ts +2 -2
  795. package/models/webhook-ping-event-data.ts +2 -2
  796. package/models/webhook-test-result-dto.ts +2 -2
  797. package/package.json +1 -1
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -58,7 +58,7 @@ export interface CreateBidRequestDto {
58
58
  */
59
59
  'items': Array<BidItemDto>;
60
60
  /**
61
- * ์ด ์˜ˆ์‚ฐ๊ธˆ์•ก(์›). items ํ•ฉ๊ณ„ ๋Œ€์‹  ๋ณ„๋„ totalBudget์œผ๋กœ override ํ•  ๋•Œ ์‚ฌ์šฉ.
61
+ * ์ด ์˜ˆ์‚ฐ๊ธˆ์•ก(์›, **๋ถ€๊ฐ€์„ธ ํฌํ•จ**). ์ƒ๋žตํ•˜๋ฉด ํ’ˆ๋ชฉ ํ•ฉ๊ณ„(๋‹จ๊ฐ€ ร— ์ˆ˜๋Ÿ‰)๊ฐ€ ๋ฐฐ์ •์˜ˆ์‚ฐ์ด ๋ฉ๋‹ˆ๋‹ค. ๋‚™์ฐฐ๊ธˆ์•ก๋„ ๋ถ€๊ฐ€์„ธ ํฌํ•จ ๊ธˆ์•ก์ด๋ผ ๋‘ ๊ฐ’์€ ๊ฐ™์€ ์ถ•์ž…๋‹ˆ๋‹ค โ€” ๊ณต๊ธ‰๊ฐ€์•ก(๋ถ€๊ฐ€์„ธ ๋ณ„๋„)์„ ๋ณด๋‚ด๋ฉด ์ ˆ๊ฐ์•ก์ด ์‹ค์ œ๋ณด๋‹ค ํฌ๊ฒŒ ๊ณ„์‚ฐ๋ฉ๋‹ˆ๋‹ค. (`/v1`์€ ์ด ํ•„๋“œ๋ฅผ ๋ถ€๊ฐ€์„ธ **๋ณ„๋„**๋กœ ๋ฐ›์•„ ์„œ๋ฒ„๊ฐ€ 10%๋ฅผ ๊ฐ€์‚ฐํ•ฉ๋‹ˆ๋‹ค. ๋‘ ํ‘œ๋ฉด์˜ ์ถ•์ด ๋‹ค๋ฅด๋ฏ€๋กœ v1์—์„œ ์˜ฎ๊ฒจ์˜ฌ ๋•Œ ๊ฐ’์„ ๊ทธ๋Œ€๋กœ ์“ฐ์ง€ ๋งˆ์„ธ์š”.)
62
62
  */
63
63
  'totalBudget'?: number;
64
64
  /**
@@ -2,9 +2,9 @@
2
2
  /* eslint-disable */
3
3
  /**
4
4
  * CMARKET V6 Partner API
5
- * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
5
+ * ์™ธ๋ถ€ ERP ์—ฐ๋™์šฉ RESTful API. ## ์ธ์ฆ OAuth2 Bearer JWT (`client_credentials` ํ”Œ๋กœ์šฐ). `/oauth/token`์—์„œ ํ† ํฐ์„ ๋ฐœ๊ธ‰๋ฐ›์•„ `Authorization: Bearer <token>` ํ—ค๋”๋กœ ์‹ค์œผ์„ธ์š”. ## ๊ถŒํ•œ โ€” ๋‘ ๊ฐœ์˜ ๋…๋ฆฝ๋œ ์ถ• `403`์„ ๋งŒ๋‚ฌ๋‹ค๋ฉด ๋‘˜ ์ค‘ ์–ด๋А ์ถ•์— ๊ฑธ๋ฆฐ ๊ฒƒ์ธ์ง€ ๋จผ์ € ๊ตฌ๋ถ„ํ•˜์„ธ์š”. - **์Šค์ฝ”ํ”„** = *๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋‚˜*. ํ† ํฐ์— ๋ถ€์—ฌ๋œ `bids:read`ยท`contracts:write` ๋“ฑ์ž…๋‹ˆ๋‹ค. ๋ฏธ๋ณด์œ  ์‹œ `โ€ฆ/insufficient-scope`. - **๋Œ€ํ–‰ ๋ฒ”์œ„** = *๋ˆ„๊ตฌ์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋‹ค๋ฃฐ ์ˆ˜ ์žˆ๋‚˜*. API ํ‚ค ์„ค์ •์ด๋ฉฐ ์Šค์ฝ”ํ”„๋กœ ํ‘œํ˜„๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„ ๋ฐ–์ด๋ฉด ์Šค์ฝ”ํ”„์™€ ๋ฌด๊ด€ํ•˜๊ฒŒ 403์ž…๋‹ˆ๋‹ค. ๋Œ€ํ–‰ ๋ฒ”์œ„๋Š” ํ‚ค๋งˆ๋‹ค ๋‘˜ ์ค‘ ํ•˜๋‚˜๋กœ ์„ค์ •๋ฉ๋‹ˆ๋‹ค โ€” **์†Œ์† ๊ทธ๋ฃน ์ „์›**(๊ธฐ๊ด€ ํ‚ค. ์‚ฌ์—…์ฒ˜ยท๋ถ€์„œ ๊ณ„์ •์ด ์ƒˆ๋กœ ์ƒ๊ฒจ๋„ ์ž๋™ ํฌํ•จ) ๋˜๋Š” **์ง€์ • ๋ฐœ์ฃผ๊ธฐ๊ด€ ๋ชฉ๋ก**(๊ณ„์•ฝ์œผ๋กœ ํ•ฉ์˜๋œ ๋ชฉ๋ก). ๋ฒ”์œ„๋ฅผ ๋„“ํ˜€์•ผ ํ•˜๋ฉด ์Šค์ฝ”ํ”„๊ฐ€ ์•„๋‹ˆ๋ผ ํ‚ค ์„ค์ • ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜์„ธ์š”. ## ์„ฑ๊ณต ์‘๋‹ต ๋ด‰ํˆฌ `/v2`์˜ ๋ชจ๋“  2xx ๋ณธ๋ฌธ์€ `{ \"data\": โ€ฆ }`์ž…๋‹ˆ๋‹ค. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค๋“  ๋ชฉ๋ก์ด๋“  ๊ฐ™์Šต๋‹ˆ๋‹ค. **๋ชฉ๋ก์€ `data`๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  `meta`๊ฐ€ ํ•ญ์ƒ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค** โ€” `{ \"data\": [...], \"meta\": { \"nextCursor\": \"Mg==\", \"hasMore\": true } }`. ๋‹จ์ผ ๋ฆฌ์†Œ์Šค ์‘๋‹ต์—๋Š” `meta`๊ฐ€ ๋‚˜๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ด‰ํˆฌ๋ฅผ ์“ฐ์ง€ ์•Š๋Š” ํ‘œ๋ฉด์€ ๋‘˜์ž…๋‹ˆ๋‹ค. `/oauth/_*`์™€ `/.well-known/_*`๋Š” ๊ฐ๊ฐ RFC 6749ยทRFC 8414ยทRFC 9728์ด ์ตœ์ƒ์œ„ ํ•„๋“œ๋ฅผ ๊ทœ์ •ํ•˜๊ณ , ํŒŒ์ผ ๋‚ด์šฉ ์‘๋‹ต์€ ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹™๋‹ˆ๋‹ค. ์—๋Ÿฌ ์‘๋‹ต์—๋Š” ๋ด‰ํˆฌ๋ฅผ ์”Œ์šฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค โ€” ์•„๋ž˜ problem+json์ด ๋‹จ๋…์œผ๋กœ ์ฑ…์ž„์ง‘๋‹ˆ๋‹ค. ## ์กฐ๊ฑด๋ถ€ ์š”์ฒญ (ETag) `/v2`์˜ ๋ชจ๋“  `GET` ์‘๋‹ต์— weak `ETag`(`W/\"โ€ฆ\"`)๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ๋ฐ›์€ ๊ฐ’์„ ๋‹ค์Œ ์š”์ฒญ์˜ `If-None-Match` ํ—ค๋”๋กœ ๋˜๋ณด๋‚ด๋ฉด, ๋‚ด์šฉ์ด ๊ทธ๋Œ€๋กœ์ผ ๋•Œ `304 Not Modified`๋ฅผ ๋ณธ๋ฌธ ์—†์ด ๋ฐ›์Šต๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜๊ธฐ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋ฉฐ ๊ฐ™์€ ์ž์›์„ ๋ฐ˜๋ณต ์กฐํšŒํ•˜๋Š” ์—ฐ๋™์ด๋ผ๋ฉด ์ด ํ—ค๋” ํ•˜๋‚˜๋กœ ์ „์†ก๋Ÿ‰์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. ## ์—๋Ÿฌ (RFC 9457 problem+json) ๋ชจ๋“  ์—๋Ÿฌ ์‘๋‹ต์€ `application/problem+json`์ž…๋‹ˆ๋‹ค. **HTTP status + `type` URI** ๋กœ ๋ถ„๊ธฐํ•˜์„ธ์š”. - `retryable`(boolean): ์ž๋™ ์žฌ์‹œ๋„ ์•ˆ์ „ ์—ฌ๋ถ€. `true`(429ยท5xx transient)๋ฉด backoff ํ›„ ์žฌ์‹œ๋„ํ•˜๊ณ , `false`๋ฉด ์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•ฉ๋‹ˆ๋‹ค. - `traceId`: ์š”์ฒญ ์ถ”์  id. `X-Correlation-Id` ์‘๋‹ต ํ—ค๋”์™€ ๊ฐ™์€ ๊ฐ’์ž…๋‹ˆ๋‹ค โ€” ๋ฌธ์˜ํ•  ๋•Œ ์ด ๊ฐ’์„ ์ฒจ๋ถ€ํ•˜์„ธ์š”. - `correlationId`: `traceId`์™€ ๊ฐ™์€ ๊ฐ’์˜ ์˜› ์ด๋ฆ„. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์œผ๋กœ ํ•จ๊ป˜ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ์ƒˆ ์—ฐ๋™์€ `traceId`๋ฅผ ์ฝ์œผ์„ธ์š”. - `invalid-params`: ๊ฒ€์ฆ ์‹คํŒจ(400 `โ€ฆ/validation-failed`) ์‹œ ์œ„๋ฐ˜ ํ•„๋“œ ๊ฒฝ๋กœ ๋ชฉ๋ก(RFC 9457 ํ™•์žฅ, ๊ฐ’ ์—†์Œ). - `code`: ์กฐ๋‹ฌํ”Œ๋žซํผ์ด ์š”์ฒญ์„ ๊ฑฐ๋ถ€ํ•œ **์‚ฌ์œ  ์ฝ”๋“œ**(`โ€ฆ/upstream-*` ์‘๋‹ต์— ํ•จ๊ป˜ ์˜ต๋‹ˆ๋‹ค). `type`์€ ์ƒํƒœ ์ˆ˜์ค€์ด๊ณ  `detail`์€ ๊ณ ์ • ๋ฌธ๊ตฌ๋ผ, ๋ฌด์—‡์„ ๊ณ ์ณ์•ผ ํ•˜๋Š”์ง€๋Š” ์ด ๊ฐ’์ด ์•Œ๋ ค ์ค๋‹ˆ๋‹ค โ€” ์˜ˆ: `BID_INVALID_BID_DATE_RANGE`(๋งˆ๊ฐ์ด ์‹œ์ž‘๋ณด๋‹ค ์ด๋ฆ„), `BID_DUPLICATE_PURCHASE_NO`(๊ฐ™์€ ์กฐ๋‹ฌ๋ฒˆํ˜ธ์˜ ๊ณต๊ณ ๊ฐ€ ์ง„ํ–‰ ์ค‘). ์•ˆ์ • ์‹๋ณ„์ž์ด๋ฏ€๋กœ ๋ฌธ์ž์—ด๋กœ ๋ถ„๊ธฐํ•ด๋„ ๋ฉ๋‹ˆ๋‹ค. `type`์€ `https://problems.cmarket.io/partner/<slug>` ํ˜•ํƒœ์˜ **์•ˆ์ • ์‹๋ณ„์ž**์ž…๋‹ˆ๋‹ค. RFC 9457 ยง3.1.1์ด ํ—ˆ์šฉํ•˜๋Š” ๋Œ€๋กœ ์ด URI๋Š” **์—ญ์ฐธ์กฐ(dereference)๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ธŒ๋ผ์šฐ์ €๋กœ ์—ด์ง€ ๋ง๊ณ  ๋ฌธ์ž์—ด ๋น„๊ต๋กœ๋งŒ ์“ฐ์„ธ์š”. slug ๋ชฉ๋ก๊ณผ ์˜๋ฏธ๋Š” ๊ฐ ์—”๋“œํฌ์ธํŠธ์˜ ์‘๋‹ต ์„ค๋ช…์— status ๋ณ„๋กœ ์ ํ˜€ ์žˆ์Šต๋‹ˆ๋‹ค. ### ๋ฉฑ๋“ฑ์„ฑ ์œ„๋ฐ˜: 409์™€ 422์˜ ์ฐจ์ด - `409` `โ€ฆ/idempotency-key-conflict` โ€” ๊ฐ™์€ ํ‚ค์˜ **์› ์š”์ฒญ์ด ์•„์ง ์ฒ˜๋ฆฌ ์ค‘**์ž…๋‹ˆ๋‹ค. ์ž ์‹œ ๋’ค ๊ฐ™์€ ํ‚ค๋กœ ๋‹ค์‹œ ๋ถ€๋ฅด๋ฉด ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. - `422` `โ€ฆ/idempotency-key-reused` โ€” ๊ฐ™์€ ํ‚ค๋ฅผ **๋‹ค๋ฅธ body** ๋กœ ๋ณด๋ƒˆ์Šต๋‹ˆ๋‹ค. ์žฌ์‹œ๋„ํ•ด๋„ ์˜์›ํžˆ ๊ฐ™์€ ์‹คํŒจ์ด๋‹ˆ ์ƒˆ ํ‚ค๋ฅผ ์“ฐ๊ฑฐ๋‚˜ body๋ฅผ ๋˜๋Œ๋ฆฌ์„ธ์š”. ## Rate Limit ์ „์—ญ **60 ์š”์ฒญ/๋ถ„ per `client_id`**, ํ† ํฐ ๋ฐœ๊ธ‰(`/oauth/token`)์€ **5 ์š”์ฒญ/๋ถ„** ์ž…๋‹ˆ๋‹ค. ์ดˆ๊ณผ ์‹œ `429`(`type: โ€ฆ/too-many-requests`). ์ฟผํ„ฐ๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ๊ธฐ๋กœ ํ•จ๊ป˜ ๋‚˜๊ฐ‘๋‹ˆ๋‹ค โ€” ์‹ ๊ทœ ์—ฐ๋™์€ ํ‘œ์ค€ ํ•„๋“œ๋ฅผ ์“ฐ์„ธ์š”. - **ํ‘œ์ค€**(`draft-ietf-httpapi-ratelimit-headers`, Structured Fields): `RateLimit-Policy: \"default\";q=60;w=60` (์ •์ฑ…) ยท `RateLimit: \"default\";r=59;t=42` (์ž”๋Ÿ‰ r, ๋ฆฌ์…‹๊นŒ์ง€ t ์ดˆ) - **๋ ˆ๊ฑฐ์‹œ**(๊ด€์šฉ): `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. ๊ธฐ์กด ์—ฐ๋™ ํ˜ธํ™˜์„ ์œ„ํ•ด ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. `429` ์—์„œ๋Š” `Retry-After`(์ดˆ)๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€๋Ÿ‰ ๋™๊ธฐํ™”(ํ’ˆ๋ชฉ ๋‹จ์œ„ ๋ฐ˜๋ณต ๋“ฑ๋ก ๋“ฑ)๋Š” `Retry-After` ๋งŒํผ backoff ํ›„ ์žฌ์‹œ๋„ํ•˜์„ธ์š”. ## ์ถ”์  ์š”์ฒญ์— `X-Correlation-Id` ํ—ค๋”๋ฅผ ์‹ค์œผ๋ฉด ๊ทธ๋Œ€๋กœ echo ๋˜๊ณ , ์—†์œผ๋ฉด ์„œ๋ฒ„๊ฐ€ ๋ฐœ๊ธ‰ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‘๋‹ต(์„ฑ๊ณต/์—๋Ÿฌ)์— `X-Correlation-Id`๊ฐ€ ์‹ค๋ฆฝ๋‹ˆ๋‹ค. ## ์ „๋ฐฉํ˜ธํ™˜ โ€” ๋ชจ๋ฅด๋Š” ํ•„๋“œ์™€ ๊ฐ’์—์„œ ๊นจ์ง€์ง€ ์•Š๊ฒŒ ๋‹ค์Œ ์…‹์€ breaking ๋ณ€๊ฒฝ์œผ๋กœ ๋ณด์ง€ ์•Š์œผ๋ฉฐ minor ๋ฆด๋ฆฌ์Šค์—์„œ ์˜ˆ๊ณ  ์—†์ด ์ผ์–ด๋‚ฉ๋‹ˆ๋‹ค. ์ด ์ „์ œ๋กœ ๊ตฌํ˜„ํ•˜์„ธ์š”. - **์„ ํƒ ํ•„๋“œ ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”. ์—„๊ฒฉ ํŒŒ์„œ(unknown key ๊ฑฐ๋ถ€)๋ฅผ ์“ฐ์ง€ ๋งˆ์„ธ์š”. - **enum ๊ฐ’ ์ถ”๊ฐ€**: ์ƒํƒœยท๋‚™์ฐฐ๋ฐฉ๋ฒ• ๋“ฑ์— ์ƒˆ ๊ฐ’์ด ์ƒ๊น๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ๊ฐ’์„ ๋งŒ๋‚˜๋ฉด ์˜ˆ์™ธ๋ฅผ ๋˜์ง€์ง€ ๋ง๊ณ  ์›๋ฌธ ๋ฌธ์ž์—ด์„ ๋ณด์กดํ•˜์„ธ์š”. - **problem `type` slug ์ถ”๊ฐ€**: ๋ชจ๋ฅด๋Š” slug์€ **HTTP status๋กœ ํด๋ฐฑ**ํ•ด ๋ถ„๊ธฐํ•˜์„ธ์š”. ## ๋ฒ„์ „ ์ˆ˜๋ช…(deprecation/sunset) - **_/v2** breaking ๋ณ€๊ฒฝ์€ CHANGELOG SemVer(major bump)์™€ `Deprecation`/`Sunset` ํ—ค๋”๋กœ ํ†ต์ง€ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ—ค๋”๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”.
6
6
  *
7
- * The version of the OpenAPI document: 43.0.2
7
+ * The version of the OpenAPI document: 44.0.0
8
8
  * Contact: semo.io.kr@gmail.com
9
9
  *
10
10
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).