@cmarket/partner-sdk 31.1.1 β†’ 31.3.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 (944) hide show
  1. package/README.md +17 -4
  2. package/api/oauth-api.ts +2 -2
  3. package/api/partner-v1-api.ts +2 -2
  4. package/api/partner-v2-api.ts +10 -10
  5. package/api/webhooks-api.ts +636 -0
  6. package/api/well-known-api.ts +65 -2
  7. package/api.ts +2 -2
  8. package/base.ts +2 -2
  9. package/common.ts +2 -2
  10. package/configuration.ts +2 -2
  11. package/dist/api/oauth-api.d.ts +2 -2
  12. package/dist/api/oauth-api.js +2 -2
  13. package/dist/api/partner-v1-api.d.ts +2 -2
  14. package/dist/api/partner-v1-api.js +2 -2
  15. package/dist/api/partner-v2-api.d.ts +10 -10
  16. package/dist/api/partner-v2-api.js +10 -10
  17. package/dist/api/webhooks-api.d.ts +304 -0
  18. package/dist/api/webhooks-api.js +621 -0
  19. package/dist/api/well-known-api.d.ts +31 -2
  20. package/dist/api/well-known-api.js +61 -2
  21. package/dist/api.d.ts +2 -2
  22. package/dist/api.js +2 -2
  23. package/dist/base.d.ts +2 -2
  24. package/dist/base.js +2 -2
  25. package/dist/common.d.ts +2 -2
  26. package/dist/common.js +2 -2
  27. package/dist/configuration.d.ts +2 -2
  28. package/dist/configuration.js +2 -2
  29. package/dist/esm/api/oauth-api.d.ts +2 -2
  30. package/dist/esm/api/oauth-api.js +2 -2
  31. package/dist/esm/api/partner-v1-api.d.ts +2 -2
  32. package/dist/esm/api/partner-v1-api.js +2 -2
  33. package/dist/esm/api/partner-v2-api.d.ts +10 -10
  34. package/dist/esm/api/partner-v2-api.js +10 -10
  35. package/dist/esm/api/webhooks-api.d.ts +304 -0
  36. package/dist/esm/api/webhooks-api.js +614 -0
  37. package/dist/esm/api/well-known-api.d.ts +31 -2
  38. package/dist/esm/api/well-known-api.js +61 -2
  39. package/dist/esm/api.d.ts +2 -2
  40. package/dist/esm/api.js +2 -2
  41. package/dist/esm/base.d.ts +2 -2
  42. package/dist/esm/base.js +2 -2
  43. package/dist/esm/common.d.ts +2 -2
  44. package/dist/esm/common.js +2 -2
  45. package/dist/esm/configuration.d.ts +2 -2
  46. package/dist/esm/configuration.js +2 -2
  47. package/dist/esm/index.d.ts +2 -2
  48. package/dist/esm/index.js +2 -2
  49. package/dist/esm/models/acceptance-result-response-dto.d.ts +2 -2
  50. package/dist/esm/models/acceptance-result-response-dto.js +2 -2
  51. package/dist/esm/models/acceptance-result-v1-response-dto.d.ts +2 -2
  52. package/dist/esm/models/acceptance-result-v1-response-dto.js +2 -2
  53. package/dist/esm/models/acceptance-status-response-dto.d.ts +2 -2
  54. package/dist/esm/models/acceptance-status-response-dto.js +2 -2
  55. package/dist/esm/models/acknowledge-product-receipt200-response.d.ts +2 -2
  56. package/dist/esm/models/acknowledge-product-receipt200-response.js +2 -2
  57. package/dist/esm/models/acknowledge-products-request-dto.d.ts +2 -2
  58. package/dist/esm/models/acknowledge-products-request-dto.js +2 -2
  59. package/dist/esm/models/acknowledge-products-v1-request-dto.d.ts +2 -2
  60. package/dist/esm/models/acknowledge-products-v1-request-dto.js +2 -2
  61. package/dist/esm/models/api-catalog-dto.d.ts +18 -0
  62. package/dist/esm/models/api-catalog-dto.js +14 -0
  63. package/dist/esm/models/api-catalog-entry-dto.d.ts +30 -0
  64. package/dist/esm/models/api-catalog-entry-dto.js +14 -0
  65. package/dist/esm/models/api-catalog-link-dto.d.ts +25 -0
  66. package/dist/esm/models/api-catalog-link-dto.js +14 -0
  67. package/dist/esm/models/authorization-server-metadata-dto.d.ts +2 -2
  68. package/dist/esm/models/authorization-server-metadata-dto.js +2 -2
  69. package/dist/esm/models/award-method-public.d.ts +2 -2
  70. package/dist/esm/models/award-method-public.js +2 -2
  71. package/dist/esm/models/award-registered-response-dto.d.ts +2 -2
  72. package/dist/esm/models/award-registered-response-dto.js +2 -2
  73. package/dist/esm/models/award-registered-v2-response-dto.d.ts +2 -2
  74. package/dist/esm/models/award-registered-v2-response-dto.js +2 -2
  75. package/dist/esm/models/award-reverted-v2-response-dto.d.ts +2 -2
  76. package/dist/esm/models/award-reverted-v2-response-dto.js +2 -2
  77. package/dist/esm/models/bid-attachment-v1-dto.d.ts +2 -2
  78. package/dist/esm/models/bid-attachment-v1-dto.js +2 -2
  79. package/dist/esm/models/bid-bond-dto.d.ts +2 -2
  80. package/dist/esm/models/bid-bond-dto.js +2 -2
  81. package/dist/esm/models/bid-bond-v1-dto.d.ts +2 -2
  82. package/dist/esm/models/bid-bond-v1-dto.js +2 -2
  83. package/dist/esm/models/bid-cancelled-response-dto.d.ts +2 -2
  84. package/dist/esm/models/bid-cancelled-response-dto.js +2 -2
  85. package/dist/esm/models/bid-contact-dto.d.ts +2 -2
  86. package/dist/esm/models/bid-contact-dto.js +2 -2
  87. package/dist/esm/models/bid-contacts-dto.d.ts +2 -2
  88. package/dist/esm/models/bid-contacts-dto.js +2 -2
  89. package/dist/esm/models/bid-contract-document-dto.d.ts +2 -2
  90. package/dist/esm/models/bid-contract-document-dto.js +2 -2
  91. package/dist/esm/models/bid-contract-documents-batch-v1-request-dto.d.ts +2 -2
  92. package/dist/esm/models/bid-contract-documents-batch-v1-request-dto.js +2 -2
  93. package/dist/esm/models/bid-contract-documents-v1-response-dto.d.ts +2 -2
  94. package/dist/esm/models/bid-contract-documents-v1-response-dto.js +2 -2
  95. package/dist/esm/models/bid-created-response-dto.d.ts +2 -2
  96. package/dist/esm/models/bid-created-response-dto.js +2 -2
  97. package/dist/esm/models/bid-delivery-terms-dto.d.ts +2 -2
  98. package/dist/esm/models/bid-delivery-terms-dto.js +2 -2
  99. package/dist/esm/models/bid-detail-response-dto.d.ts +2 -2
  100. package/dist/esm/models/bid-detail-response-dto.js +2 -2
  101. package/dist/esm/models/bid-document-dto.d.ts +2 -2
  102. package/dist/esm/models/bid-document-dto.js +2 -2
  103. package/dist/esm/models/bid-document-v1-dto.d.ts +2 -2
  104. package/dist/esm/models/bid-document-v1-dto.js +2 -2
  105. package/dist/esm/models/bid-failed-response-dto.d.ts +2 -2
  106. package/dist/esm/models/bid-failed-response-dto.js +2 -2
  107. package/dist/esm/models/bid-failed-v2-response-dto.d.ts +2 -2
  108. package/dist/esm/models/bid-failed-v2-response-dto.js +2 -2
  109. package/dist/esm/models/bid-failure-reason.d.ts +2 -2
  110. package/dist/esm/models/bid-failure-reason.js +2 -2
  111. package/dist/esm/models/bid-item-dto.d.ts +2 -2
  112. package/dist/esm/models/bid-item-dto.js +2 -2
  113. package/dist/esm/models/bid-item-v1-dto.d.ts +2 -2
  114. package/dist/esm/models/bid-item-v1-dto.js +2 -2
  115. package/dist/esm/models/bid-lifecycle-dto.d.ts +2 -2
  116. package/dist/esm/models/bid-lifecycle-dto.js +2 -2
  117. package/dist/esm/models/bid-manager-dto.d.ts +2 -2
  118. package/dist/esm/models/bid-manager-dto.js +2 -2
  119. package/dist/esm/models/bid-manager-v1-dto.d.ts +2 -2
  120. package/dist/esm/models/bid-manager-v1-dto.js +2 -2
  121. package/dist/esm/models/bid-participant-summary-dto.d.ts +2 -2
  122. package/dist/esm/models/bid-participant-summary-dto.js +2 -2
  123. package/dist/esm/models/bid-payment-terms-dto.d.ts +2 -2
  124. package/dist/esm/models/bid-payment-terms-dto.js +2 -2
  125. package/dist/esm/models/bid-product-dto.d.ts +2 -2
  126. package/dist/esm/models/bid-product-dto.js +2 -2
  127. package/dist/esm/models/bid-public-status.d.ts +2 -2
  128. package/dist/esm/models/bid-public-status.js +2 -2
  129. package/dist/esm/models/bid-published-response-dto.d.ts +2 -2
  130. package/dist/esm/models/bid-published-response-dto.js +2 -2
  131. package/dist/esm/models/bid-registered-response-dto.d.ts +6 -2
  132. package/dist/esm/models/bid-registered-response-dto.js +2 -2
  133. package/dist/esm/models/bid-result-participant-attachment-dto.d.ts +2 -2
  134. package/dist/esm/models/bid-result-participant-attachment-dto.js +2 -2
  135. package/dist/esm/models/bid-result-participant-dto.d.ts +2 -2
  136. package/dist/esm/models/bid-result-participant-dto.js +2 -2
  137. package/dist/esm/models/bid-result-v1-attachment-dto.d.ts +2 -2
  138. package/dist/esm/models/bid-result-v1-attachment-dto.js +2 -2
  139. package/dist/esm/models/bid-result-v1-bid-product-info-dto.d.ts +2 -2
  140. package/dist/esm/models/bid-result-v1-bid-product-info-dto.js +2 -2
  141. package/dist/esm/models/bid-result-v1-participant-dto.d.ts +2 -2
  142. package/dist/esm/models/bid-result-v1-participant-dto.js +2 -2
  143. package/dist/esm/models/bid-result-v1-product-dto.d.ts +2 -2
  144. package/dist/esm/models/bid-result-v1-product-dto.js +2 -2
  145. package/dist/esm/models/bid-results-batch-request-dto.d.ts +3 -3
  146. package/dist/esm/models/bid-results-batch-request-dto.js +2 -2
  147. package/dist/esm/models/bid-results-batch-v1-request-dto.d.ts +2 -2
  148. package/dist/esm/models/bid-results-batch-v1-request-dto.js +2 -2
  149. package/dist/esm/models/bid-results-response-dto.d.ts +2 -2
  150. package/dist/esm/models/bid-results-response-dto.js +2 -2
  151. package/dist/esm/models/bid-results-v1-response-dto.d.ts +2 -2
  152. package/dist/esm/models/bid-results-v1-response-dto.js +2 -2
  153. package/dist/esm/models/bid-settlement-line-item-dto.d.ts +2 -2
  154. package/dist/esm/models/bid-settlement-line-item-dto.js +2 -2
  155. package/dist/esm/models/bid-settlement-participant-dto.d.ts +2 -2
  156. package/dist/esm/models/bid-settlement-participant-dto.js +2 -2
  157. package/dist/esm/models/bid-settlement-response-dto.d.ts +2 -2
  158. package/dist/esm/models/bid-settlement-response-dto.js +2 -2
  159. package/dist/esm/models/bid-statement-response-dto.d.ts +2 -2
  160. package/dist/esm/models/bid-statement-response-dto.js +2 -2
  161. package/dist/esm/models/bid-statement-v1-response-dto.d.ts +2 -2
  162. package/dist/esm/models/bid-statement-v1-response-dto.js +2 -2
  163. package/dist/esm/models/bid-status.d.ts +2 -2
  164. package/dist/esm/models/bid-status.js +2 -2
  165. package/dist/esm/models/bid-summary-dto.d.ts +2 -2
  166. package/dist/esm/models/bid-summary-dto.js +2 -2
  167. package/dist/esm/models/bid-updated-response-dto.d.ts +2 -2
  168. package/dist/esm/models/bid-updated-response-dto.js +2 -2
  169. package/dist/esm/models/cancel-bid-request-dto.d.ts +2 -2
  170. package/dist/esm/models/cancel-bid-request-dto.js +2 -2
  171. package/dist/esm/models/cancel-bid200-response.d.ts +2 -2
  172. package/dist/esm/models/cancel-bid200-response.js +2 -2
  173. package/dist/esm/models/card-payment-request-response-dto.d.ts +2 -2
  174. package/dist/esm/models/card-payment-request-response-dto.js +2 -2
  175. package/dist/esm/models/complete-acceptance-request-dto.d.ts +2 -2
  176. package/dist/esm/models/complete-acceptance-request-dto.js +2 -2
  177. package/dist/esm/models/complete-acceptance-v1-request-dto.d.ts +2 -2
  178. package/dist/esm/models/complete-acceptance-v1-request-dto.js +2 -2
  179. package/dist/esm/models/complete-acceptance200-response.d.ts +2 -2
  180. package/dist/esm/models/complete-acceptance200-response.js +2 -2
  181. package/dist/esm/models/complete-invoice200-response.d.ts +2 -2
  182. package/dist/esm/models/complete-invoice200-response.js +2 -2
  183. package/dist/esm/models/contract-document-item-dto.d.ts +2 -2
  184. package/dist/esm/models/contract-document-item-dto.js +2 -2
  185. package/dist/esm/models/contract-documents-regenerated-response-dto.d.ts +2 -2
  186. package/dist/esm/models/contract-documents-regenerated-response-dto.js +2 -2
  187. package/dist/esm/models/contract-restriction-confirm-input-dto.d.ts +2 -2
  188. package/dist/esm/models/contract-restriction-confirm-input-dto.js +2 -2
  189. package/dist/esm/models/create-bid-request-dto.d.ts +2 -2
  190. package/dist/esm/models/create-bid-request-dto.js +2 -2
  191. package/dist/esm/models/create-bid-v1-request-dto.d.ts +2 -2
  192. package/dist/esm/models/create-bid-v1-request-dto.js +2 -2
  193. package/dist/esm/models/create-card-payment-request-dto.d.ts +2 -2
  194. package/dist/esm/models/create-card-payment-request-dto.js +2 -2
  195. package/dist/esm/models/create-card-payment200-response.d.ts +2 -2
  196. package/dist/esm/models/create-card-payment200-response.js +2 -2
  197. package/dist/esm/models/create-external-contract-documents-request-dto.d.ts +2 -2
  198. package/dist/esm/models/create-external-contract-documents-request-dto.js +2 -2
  199. package/dist/esm/models/create-external-contract-documents-response-dto.d.ts +2 -2
  200. package/dist/esm/models/create-external-contract-documents-response-dto.js +2 -2
  201. package/dist/esm/models/create-webhook-endpoint-request-dto.d.ts +2 -2
  202. package/dist/esm/models/create-webhook-endpoint-request-dto.js +2 -2
  203. package/dist/esm/models/create-webhook-endpoint201-response.d.ts +2 -2
  204. package/dist/esm/models/create-webhook-endpoint201-response.js +2 -2
  205. package/dist/esm/models/external-contract-document-item-dto.d.ts +2 -2
  206. package/dist/esm/models/external-contract-document-item-dto.js +2 -2
  207. package/dist/esm/models/external-contract-documents-response-dto.d.ts +2 -2
  208. package/dist/esm/models/external-contract-documents-response-dto.js +2 -2
  209. package/dist/esm/models/external-contract-item-dto.d.ts +2 -2
  210. package/dist/esm/models/external-contract-item-dto.js +2 -2
  211. package/dist/esm/models/external-contract-snapshot-dto.d.ts +2 -2
  212. package/dist/esm/models/external-contract-snapshot-dto.js +2 -2
  213. package/dist/esm/models/external-document-inputs-dto.d.ts +2 -2
  214. package/dist/esm/models/external-document-inputs-dto.js +2 -2
  215. package/dist/esm/models/file-meta-response-dto.d.ts +2 -2
  216. package/dist/esm/models/file-meta-response-dto.js +2 -2
  217. package/dist/esm/models/file-uploaded-response-dto.d.ts +2 -2
  218. package/dist/esm/models/file-uploaded-response-dto.js +2 -2
  219. package/dist/esm/models/file-uploaded-v1-response-dto.d.ts +2 -2
  220. package/dist/esm/models/file-uploaded-v1-response-dto.js +2 -2
  221. package/dist/esm/models/generated-external-contract-document-dto.d.ts +2 -2
  222. package/dist/esm/models/generated-external-contract-document-dto.js +2 -2
  223. package/dist/esm/models/get-bid-acceptance200-response.d.ts +2 -2
  224. package/dist/esm/models/get-bid-acceptance200-response.js +2 -2
  225. package/dist/esm/models/get-bid-results200-response.d.ts +2 -2
  226. package/dist/esm/models/get-bid-results200-response.js +2 -2
  227. package/dist/esm/models/get-bid-settlement200-response.d.ts +2 -2
  228. package/dist/esm/models/get-bid-settlement200-response.js +2 -2
  229. package/dist/esm/models/get-bid-statement200-response.d.ts +2 -2
  230. package/dist/esm/models/get-bid-statement200-response.js +2 -2
  231. package/dist/esm/models/get-bid200-response.d.ts +2 -2
  232. package/dist/esm/models/get-bid200-response.js +2 -2
  233. package/dist/esm/models/get-file-meta200-response.d.ts +2 -2
  234. package/dist/esm/models/get-file-meta200-response.js +2 -2
  235. package/dist/esm/models/get-supplier-card-payable-v2200-response.d.ts +2 -2
  236. package/dist/esm/models/get-supplier-card-payable-v2200-response.js +2 -2
  237. package/dist/esm/models/get-webhook-endpoint200-response.d.ts +2 -2
  238. package/dist/esm/models/get-webhook-endpoint200-response.js +2 -2
  239. package/dist/esm/models/health-controller-check200-response.d.ts +2 -2
  240. package/dist/esm/models/health-controller-check200-response.js +2 -2
  241. package/dist/esm/models/health-response-dto.d.ts +2 -2
  242. package/dist/esm/models/health-response-dto.js +2 -2
  243. package/dist/esm/models/hierarchical-region-dto.d.ts +2 -2
  244. package/dist/esm/models/hierarchical-region-dto.js +2 -2
  245. package/dist/esm/models/hierarchical-region-v1-dto.d.ts +2 -2
  246. package/dist/esm/models/hierarchical-region-v1-dto.js +2 -2
  247. package/dist/esm/models/index.d.ts +12 -0
  248. package/dist/esm/models/index.js +12 -0
  249. package/dist/esm/models/introspect-request-dto.d.ts +2 -2
  250. package/dist/esm/models/introspect-request-dto.js +2 -2
  251. package/dist/esm/models/introspection-response-dto.d.ts +2 -2
  252. package/dist/esm/models/introspection-response-dto.js +2 -2
  253. package/dist/esm/models/invalid-param-dto.d.ts +2 -2
  254. package/dist/esm/models/invalid-param-dto.js +2 -2
  255. package/dist/esm/models/invoice-completed-response-dto.d.ts +2 -2
  256. package/dist/esm/models/invoice-completed-response-dto.js +2 -2
  257. package/dist/esm/models/list-bid-contract-documents200-response.d.ts +2 -2
  258. package/dist/esm/models/list-bid-contract-documents200-response.js +2 -2
  259. package/dist/esm/models/list-bid-participants200-response.d.ts +2 -2
  260. package/dist/esm/models/list-bid-participants200-response.js +2 -2
  261. package/dist/esm/models/list-bid-results200-response.d.ts +2 -2
  262. package/dist/esm/models/list-bid-results200-response.js +2 -2
  263. package/dist/esm/models/list-bids-response-dto.d.ts +2 -2
  264. package/dist/esm/models/list-bids-response-dto.js +2 -2
  265. package/dist/esm/models/list-bids200-response.d.ts +2 -2
  266. package/dist/esm/models/list-bids200-response.js +2 -2
  267. package/dist/esm/models/list-products200-response.d.ts +2 -2
  268. package/dist/esm/models/list-products200-response.js +2 -2
  269. package/dist/esm/models/list-webhook-deliveries-response-dto.d.ts +2 -2
  270. package/dist/esm/models/list-webhook-deliveries-response-dto.js +2 -2
  271. package/dist/esm/models/list-webhook-deliveries200-response.d.ts +2 -2
  272. package/dist/esm/models/list-webhook-deliveries200-response.js +2 -2
  273. package/dist/esm/models/list-webhook-endpoints200-response.d.ts +2 -2
  274. package/dist/esm/models/list-webhook-endpoints200-response.js +2 -2
  275. package/dist/esm/models/mark-bid-failed-request-dto.d.ts +2 -2
  276. package/dist/esm/models/mark-bid-failed-request-dto.js +2 -2
  277. package/dist/esm/models/mark-bid-failed-v1-request-dto.d.ts +2 -2
  278. package/dist/esm/models/mark-bid-failed-v1-request-dto.js +2 -2
  279. package/dist/esm/models/mark-bid-failed201-response.d.ts +2 -2
  280. package/dist/esm/models/mark-bid-failed201-response.js +2 -2
  281. package/dist/esm/models/negotiation-score-v1-dto.d.ts +2 -2
  282. package/dist/esm/models/negotiation-score-v1-dto.js +2 -2
  283. package/dist/esm/models/negotiation-scored-response-dto.d.ts +2 -2
  284. package/dist/esm/models/negotiation-scored-response-dto.js +2 -2
  285. package/dist/esm/models/oauth-error-response-dto.d.ts +2 -2
  286. package/dist/esm/models/oauth-error-response-dto.js +2 -2
  287. package/dist/esm/models/on-bid-award-reverted-request.d.ts +16 -0
  288. package/dist/esm/models/on-bid-award-reverted-request.js +14 -0
  289. package/dist/esm/models/on-bid-awarded-request.d.ts +16 -0
  290. package/dist/esm/models/on-bid-awarded-request.js +14 -0
  291. package/dist/esm/models/on-bid-canceled-request.d.ts +16 -0
  292. package/dist/esm/models/on-bid-canceled-request.js +14 -0
  293. package/dist/esm/models/on-bid-closed-request.d.ts +16 -0
  294. package/dist/esm/models/on-bid-closed-request.js +14 -0
  295. package/dist/esm/models/on-bid-failed-request.d.ts +16 -0
  296. package/dist/esm/models/on-bid-failed-request.js +14 -0
  297. package/dist/esm/models/on-ping-request.d.ts +16 -0
  298. package/dist/esm/models/on-ping-request.js +14 -0
  299. package/dist/esm/models/partner-webhook-delivery-status.d.ts +2 -2
  300. package/dist/esm/models/partner-webhook-delivery-status.js +2 -2
  301. package/dist/esm/models/partner-webhook-endpoint-status.d.ts +2 -2
  302. package/dist/esm/models/partner-webhook-endpoint-status.js +2 -2
  303. package/dist/esm/models/partner-webhook-event-type.d.ts +2 -2
  304. package/dist/esm/models/partner-webhook-event-type.js +2 -2
  305. package/dist/esm/models/preconditions-dto.d.ts +2 -2
  306. package/dist/esm/models/preconditions-dto.js +2 -2
  307. package/dist/esm/models/preconditions-v1-dto.d.ts +2 -2
  308. package/dist/esm/models/preconditions-v1-dto.js +2 -2
  309. package/dist/esm/models/problem-details-dto.d.ts +2 -2
  310. package/dist/esm/models/problem-details-dto.js +2 -2
  311. package/dist/esm/models/product-receipt-response-dto.d.ts +2 -2
  312. package/dist/esm/models/product-receipt-response-dto.js +2 -2
  313. package/dist/esm/models/product-receipt-v1-response-dto.d.ts +2 -2
  314. package/dist/esm/models/product-receipt-v1-response-dto.js +2 -2
  315. package/dist/esm/models/product-response-dto.d.ts +2 -2
  316. package/dist/esm/models/product-response-dto.js +2 -2
  317. package/dist/esm/models/product-v1-response-dto.d.ts +2 -2
  318. package/dist/esm/models/product-v1-response-dto.js +2 -2
  319. package/dist/esm/models/protected-resource-metadata-dto.d.ts +2 -2
  320. package/dist/esm/models/protected-resource-metadata-dto.js +2 -2
  321. package/dist/esm/models/publish-bid200-response.d.ts +2 -2
  322. package/dist/esm/models/publish-bid200-response.js +2 -2
  323. package/dist/esm/models/regenerate-contract-documents201-response.d.ts +2 -2
  324. package/dist/esm/models/regenerate-contract-documents201-response.js +2 -2
  325. package/dist/esm/models/register-award-request-dto.d.ts +2 -2
  326. package/dist/esm/models/register-award-request-dto.js +2 -2
  327. package/dist/esm/models/register-award-v1-request-dto.d.ts +2 -2
  328. package/dist/esm/models/register-award-v1-request-dto.js +2 -2
  329. package/dist/esm/models/register-award201-response.d.ts +2 -2
  330. package/dist/esm/models/register-award201-response.js +2 -2
  331. package/dist/esm/models/register-bid201-response.d.ts +2 -2
  332. package/dist/esm/models/register-bid201-response.js +2 -2
  333. package/dist/esm/models/register-semo-contract-request-dto.d.ts +2 -2
  334. package/dist/esm/models/register-semo-contract-request-dto.js +2 -2
  335. package/dist/esm/models/request-split-invoice-v1-request-dto.d.ts +2 -2
  336. package/dist/esm/models/request-split-invoice-v1-request-dto.js +2 -2
  337. package/dist/esm/models/retiree-roster-input-dto.d.ts +2 -2
  338. package/dist/esm/models/retiree-roster-input-dto.js +2 -2
  339. package/dist/esm/models/retiree-roster-row-dto.d.ts +2 -2
  340. package/dist/esm/models/retiree-roster-row-dto.js +2 -2
  341. package/dist/esm/models/revert-award-request-dto.d.ts +2 -2
  342. package/dist/esm/models/revert-award-request-dto.js +2 -2
  343. package/dist/esm/models/revert-award200-response.d.ts +2 -2
  344. package/dist/esm/models/revert-award200-response.js +2 -2
  345. package/dist/esm/models/revoke-request-dto.d.ts +2 -2
  346. package/dist/esm/models/revoke-request-dto.js +2 -2
  347. package/dist/esm/models/semo-contract-registered-response-dto.d.ts +2 -2
  348. package/dist/esm/models/semo-contract-registered-response-dto.js +2 -2
  349. package/dist/esm/models/semo-contract-taxinvoice-status-response-dto.d.ts +2 -2
  350. package/dist/esm/models/semo-contract-taxinvoice-status-response-dto.js +2 -2
  351. package/dist/esm/models/send-webhook-test-event200-response.d.ts +2 -2
  352. package/dist/esm/models/send-webhook-test-event200-response.js +2 -2
  353. package/dist/esm/models/split-invoice-v1-response-dto.d.ts +2 -2
  354. package/dist/esm/models/split-invoice-v1-response-dto.js +2 -2
  355. package/dist/esm/models/statement-document-dto.d.ts +2 -2
  356. package/dist/esm/models/statement-document-dto.js +2 -2
  357. package/dist/esm/models/statement-product-dto.d.ts +2 -2
  358. package/dist/esm/models/statement-product-dto.js +2 -2
  359. package/dist/esm/models/statement-v1-document-dto.d.ts +2 -2
  360. package/dist/esm/models/statement-v1-document-dto.js +2 -2
  361. package/dist/esm/models/statement-v1-product-dto.d.ts +2 -2
  362. package/dist/esm/models/statement-v1-product-dto.js +2 -2
  363. package/dist/esm/models/submit-negotiation-scores-v1-request-dto.d.ts +2 -2
  364. package/dist/esm/models/submit-negotiation-scores-v1-request-dto.js +2 -2
  365. package/dist/esm/models/supplier-card-payable-response-dto.d.ts +2 -2
  366. package/dist/esm/models/supplier-card-payable-response-dto.js +2 -2
  367. package/dist/esm/models/supplier-tax-type.d.ts +2 -2
  368. package/dist/esm/models/supplier-tax-type.js +2 -2
  369. package/dist/esm/models/token-request-dto.d.ts +2 -2
  370. package/dist/esm/models/token-request-dto.js +2 -2
  371. package/dist/esm/models/token-response-dto.d.ts +2 -2
  372. package/dist/esm/models/token-response-dto.js +2 -2
  373. package/dist/esm/models/update-bid-request-dto.d.ts +2 -2
  374. package/dist/esm/models/update-bid-request-dto.js +2 -2
  375. package/dist/esm/models/update-bid200-response.d.ts +2 -2
  376. package/dist/esm/models/update-bid200-response.js +2 -2
  377. package/dist/esm/models/update-webhook-endpoint-request-dto.d.ts +2 -2
  378. package/dist/esm/models/update-webhook-endpoint-request-dto.js +2 -2
  379. package/dist/esm/models/upload-file-request-dto.d.ts +2 -2
  380. package/dist/esm/models/upload-file-request-dto.js +2 -2
  381. package/dist/esm/models/upload-file-v1-request-dto.d.ts +2 -2
  382. package/dist/esm/models/upload-file-v1-request-dto.js +2 -2
  383. package/dist/esm/models/upload-file201-response.d.ts +2 -2
  384. package/dist/esm/models/upload-file201-response.js +2 -2
  385. package/dist/esm/models/webhook-bid-event-data.d.ts +33 -0
  386. package/dist/esm/models/webhook-bid-event-data.js +14 -0
  387. package/dist/esm/models/webhook-delivery-dto.d.ts +2 -2
  388. package/dist/esm/models/webhook-delivery-dto.js +2 -2
  389. package/dist/esm/models/webhook-endpoint-dto.d.ts +2 -2
  390. package/dist/esm/models/webhook-endpoint-dto.js +2 -2
  391. package/dist/esm/models/webhook-endpoint-with-secret-dto.d.ts +2 -2
  392. package/dist/esm/models/webhook-endpoint-with-secret-dto.js +2 -2
  393. package/dist/esm/models/webhook-event-envelope.d.ts +34 -0
  394. package/dist/esm/models/webhook-event-envelope.js +14 -0
  395. package/dist/esm/models/webhook-ping-event-data.d.ts +20 -0
  396. package/dist/esm/models/webhook-ping-event-data.js +14 -0
  397. package/dist/esm/models/webhook-test-result-dto.d.ts +2 -2
  398. package/dist/esm/models/webhook-test-result-dto.js +2 -2
  399. package/dist/index.d.ts +2 -2
  400. package/dist/index.js +2 -2
  401. package/dist/models/acceptance-result-response-dto.d.ts +2 -2
  402. package/dist/models/acceptance-result-response-dto.js +2 -2
  403. package/dist/models/acceptance-result-v1-response-dto.d.ts +2 -2
  404. package/dist/models/acceptance-result-v1-response-dto.js +2 -2
  405. package/dist/models/acceptance-status-response-dto.d.ts +2 -2
  406. package/dist/models/acceptance-status-response-dto.js +2 -2
  407. package/dist/models/acknowledge-product-receipt200-response.d.ts +2 -2
  408. package/dist/models/acknowledge-product-receipt200-response.js +2 -2
  409. package/dist/models/acknowledge-products-request-dto.d.ts +2 -2
  410. package/dist/models/acknowledge-products-request-dto.js +2 -2
  411. package/dist/models/acknowledge-products-v1-request-dto.d.ts +2 -2
  412. package/dist/models/acknowledge-products-v1-request-dto.js +2 -2
  413. package/dist/models/api-catalog-dto.d.ts +18 -0
  414. package/dist/models/api-catalog-dto.js +15 -0
  415. package/dist/models/api-catalog-entry-dto.d.ts +30 -0
  416. package/dist/models/api-catalog-entry-dto.js +15 -0
  417. package/dist/models/api-catalog-link-dto.d.ts +25 -0
  418. package/dist/models/api-catalog-link-dto.js +15 -0
  419. package/dist/models/authorization-server-metadata-dto.d.ts +2 -2
  420. package/dist/models/authorization-server-metadata-dto.js +2 -2
  421. package/dist/models/award-method-public.d.ts +2 -2
  422. package/dist/models/award-method-public.js +2 -2
  423. package/dist/models/award-registered-response-dto.d.ts +2 -2
  424. package/dist/models/award-registered-response-dto.js +2 -2
  425. package/dist/models/award-registered-v2-response-dto.d.ts +2 -2
  426. package/dist/models/award-registered-v2-response-dto.js +2 -2
  427. package/dist/models/award-reverted-v2-response-dto.d.ts +2 -2
  428. package/dist/models/award-reverted-v2-response-dto.js +2 -2
  429. package/dist/models/bid-attachment-v1-dto.d.ts +2 -2
  430. package/dist/models/bid-attachment-v1-dto.js +2 -2
  431. package/dist/models/bid-bond-dto.d.ts +2 -2
  432. package/dist/models/bid-bond-dto.js +2 -2
  433. package/dist/models/bid-bond-v1-dto.d.ts +2 -2
  434. package/dist/models/bid-bond-v1-dto.js +2 -2
  435. package/dist/models/bid-cancelled-response-dto.d.ts +2 -2
  436. package/dist/models/bid-cancelled-response-dto.js +2 -2
  437. package/dist/models/bid-contact-dto.d.ts +2 -2
  438. package/dist/models/bid-contact-dto.js +2 -2
  439. package/dist/models/bid-contacts-dto.d.ts +2 -2
  440. package/dist/models/bid-contacts-dto.js +2 -2
  441. package/dist/models/bid-contract-document-dto.d.ts +2 -2
  442. package/dist/models/bid-contract-document-dto.js +2 -2
  443. package/dist/models/bid-contract-documents-batch-v1-request-dto.d.ts +2 -2
  444. package/dist/models/bid-contract-documents-batch-v1-request-dto.js +2 -2
  445. package/dist/models/bid-contract-documents-v1-response-dto.d.ts +2 -2
  446. package/dist/models/bid-contract-documents-v1-response-dto.js +2 -2
  447. package/dist/models/bid-created-response-dto.d.ts +2 -2
  448. package/dist/models/bid-created-response-dto.js +2 -2
  449. package/dist/models/bid-delivery-terms-dto.d.ts +2 -2
  450. package/dist/models/bid-delivery-terms-dto.js +2 -2
  451. package/dist/models/bid-detail-response-dto.d.ts +2 -2
  452. package/dist/models/bid-detail-response-dto.js +2 -2
  453. package/dist/models/bid-document-dto.d.ts +2 -2
  454. package/dist/models/bid-document-dto.js +2 -2
  455. package/dist/models/bid-document-v1-dto.d.ts +2 -2
  456. package/dist/models/bid-document-v1-dto.js +2 -2
  457. package/dist/models/bid-failed-response-dto.d.ts +2 -2
  458. package/dist/models/bid-failed-response-dto.js +2 -2
  459. package/dist/models/bid-failed-v2-response-dto.d.ts +2 -2
  460. package/dist/models/bid-failed-v2-response-dto.js +2 -2
  461. package/dist/models/bid-failure-reason.d.ts +2 -2
  462. package/dist/models/bid-failure-reason.js +2 -2
  463. package/dist/models/bid-item-dto.d.ts +2 -2
  464. package/dist/models/bid-item-dto.js +2 -2
  465. package/dist/models/bid-item-v1-dto.d.ts +2 -2
  466. package/dist/models/bid-item-v1-dto.js +2 -2
  467. package/dist/models/bid-lifecycle-dto.d.ts +2 -2
  468. package/dist/models/bid-lifecycle-dto.js +2 -2
  469. package/dist/models/bid-manager-dto.d.ts +2 -2
  470. package/dist/models/bid-manager-dto.js +2 -2
  471. package/dist/models/bid-manager-v1-dto.d.ts +2 -2
  472. package/dist/models/bid-manager-v1-dto.js +2 -2
  473. package/dist/models/bid-participant-summary-dto.d.ts +2 -2
  474. package/dist/models/bid-participant-summary-dto.js +2 -2
  475. package/dist/models/bid-payment-terms-dto.d.ts +2 -2
  476. package/dist/models/bid-payment-terms-dto.js +2 -2
  477. package/dist/models/bid-product-dto.d.ts +2 -2
  478. package/dist/models/bid-product-dto.js +2 -2
  479. package/dist/models/bid-public-status.d.ts +2 -2
  480. package/dist/models/bid-public-status.js +2 -2
  481. package/dist/models/bid-published-response-dto.d.ts +2 -2
  482. package/dist/models/bid-published-response-dto.js +2 -2
  483. package/dist/models/bid-registered-response-dto.d.ts +6 -2
  484. package/dist/models/bid-registered-response-dto.js +2 -2
  485. package/dist/models/bid-result-participant-attachment-dto.d.ts +2 -2
  486. package/dist/models/bid-result-participant-attachment-dto.js +2 -2
  487. package/dist/models/bid-result-participant-dto.d.ts +2 -2
  488. package/dist/models/bid-result-participant-dto.js +2 -2
  489. package/dist/models/bid-result-v1-attachment-dto.d.ts +2 -2
  490. package/dist/models/bid-result-v1-attachment-dto.js +2 -2
  491. package/dist/models/bid-result-v1-bid-product-info-dto.d.ts +2 -2
  492. package/dist/models/bid-result-v1-bid-product-info-dto.js +2 -2
  493. package/dist/models/bid-result-v1-participant-dto.d.ts +2 -2
  494. package/dist/models/bid-result-v1-participant-dto.js +2 -2
  495. package/dist/models/bid-result-v1-product-dto.d.ts +2 -2
  496. package/dist/models/bid-result-v1-product-dto.js +2 -2
  497. package/dist/models/bid-results-batch-request-dto.d.ts +3 -3
  498. package/dist/models/bid-results-batch-request-dto.js +2 -2
  499. package/dist/models/bid-results-batch-v1-request-dto.d.ts +2 -2
  500. package/dist/models/bid-results-batch-v1-request-dto.js +2 -2
  501. package/dist/models/bid-results-response-dto.d.ts +2 -2
  502. package/dist/models/bid-results-response-dto.js +2 -2
  503. package/dist/models/bid-results-v1-response-dto.d.ts +2 -2
  504. package/dist/models/bid-results-v1-response-dto.js +2 -2
  505. package/dist/models/bid-settlement-line-item-dto.d.ts +2 -2
  506. package/dist/models/bid-settlement-line-item-dto.js +2 -2
  507. package/dist/models/bid-settlement-participant-dto.d.ts +2 -2
  508. package/dist/models/bid-settlement-participant-dto.js +2 -2
  509. package/dist/models/bid-settlement-response-dto.d.ts +2 -2
  510. package/dist/models/bid-settlement-response-dto.js +2 -2
  511. package/dist/models/bid-statement-response-dto.d.ts +2 -2
  512. package/dist/models/bid-statement-response-dto.js +2 -2
  513. package/dist/models/bid-statement-v1-response-dto.d.ts +2 -2
  514. package/dist/models/bid-statement-v1-response-dto.js +2 -2
  515. package/dist/models/bid-status.d.ts +2 -2
  516. package/dist/models/bid-status.js +2 -2
  517. package/dist/models/bid-summary-dto.d.ts +2 -2
  518. package/dist/models/bid-summary-dto.js +2 -2
  519. package/dist/models/bid-updated-response-dto.d.ts +2 -2
  520. package/dist/models/bid-updated-response-dto.js +2 -2
  521. package/dist/models/cancel-bid-request-dto.d.ts +2 -2
  522. package/dist/models/cancel-bid-request-dto.js +2 -2
  523. package/dist/models/cancel-bid200-response.d.ts +2 -2
  524. package/dist/models/cancel-bid200-response.js +2 -2
  525. package/dist/models/card-payment-request-response-dto.d.ts +2 -2
  526. package/dist/models/card-payment-request-response-dto.js +2 -2
  527. package/dist/models/complete-acceptance-request-dto.d.ts +2 -2
  528. package/dist/models/complete-acceptance-request-dto.js +2 -2
  529. package/dist/models/complete-acceptance-v1-request-dto.d.ts +2 -2
  530. package/dist/models/complete-acceptance-v1-request-dto.js +2 -2
  531. package/dist/models/complete-acceptance200-response.d.ts +2 -2
  532. package/dist/models/complete-acceptance200-response.js +2 -2
  533. package/dist/models/complete-invoice200-response.d.ts +2 -2
  534. package/dist/models/complete-invoice200-response.js +2 -2
  535. package/dist/models/contract-document-item-dto.d.ts +2 -2
  536. package/dist/models/contract-document-item-dto.js +2 -2
  537. package/dist/models/contract-documents-regenerated-response-dto.d.ts +2 -2
  538. package/dist/models/contract-documents-regenerated-response-dto.js +2 -2
  539. package/dist/models/contract-restriction-confirm-input-dto.d.ts +2 -2
  540. package/dist/models/contract-restriction-confirm-input-dto.js +2 -2
  541. package/dist/models/create-bid-request-dto.d.ts +2 -2
  542. package/dist/models/create-bid-request-dto.js +2 -2
  543. package/dist/models/create-bid-v1-request-dto.d.ts +2 -2
  544. package/dist/models/create-bid-v1-request-dto.js +2 -2
  545. package/dist/models/create-card-payment-request-dto.d.ts +2 -2
  546. package/dist/models/create-card-payment-request-dto.js +2 -2
  547. package/dist/models/create-card-payment200-response.d.ts +2 -2
  548. package/dist/models/create-card-payment200-response.js +2 -2
  549. package/dist/models/create-external-contract-documents-request-dto.d.ts +2 -2
  550. package/dist/models/create-external-contract-documents-request-dto.js +2 -2
  551. package/dist/models/create-external-contract-documents-response-dto.d.ts +2 -2
  552. package/dist/models/create-external-contract-documents-response-dto.js +2 -2
  553. package/dist/models/create-webhook-endpoint-request-dto.d.ts +2 -2
  554. package/dist/models/create-webhook-endpoint-request-dto.js +2 -2
  555. package/dist/models/create-webhook-endpoint201-response.d.ts +2 -2
  556. package/dist/models/create-webhook-endpoint201-response.js +2 -2
  557. package/dist/models/external-contract-document-item-dto.d.ts +2 -2
  558. package/dist/models/external-contract-document-item-dto.js +2 -2
  559. package/dist/models/external-contract-documents-response-dto.d.ts +2 -2
  560. package/dist/models/external-contract-documents-response-dto.js +2 -2
  561. package/dist/models/external-contract-item-dto.d.ts +2 -2
  562. package/dist/models/external-contract-item-dto.js +2 -2
  563. package/dist/models/external-contract-snapshot-dto.d.ts +2 -2
  564. package/dist/models/external-contract-snapshot-dto.js +2 -2
  565. package/dist/models/external-document-inputs-dto.d.ts +2 -2
  566. package/dist/models/external-document-inputs-dto.js +2 -2
  567. package/dist/models/file-meta-response-dto.d.ts +2 -2
  568. package/dist/models/file-meta-response-dto.js +2 -2
  569. package/dist/models/file-uploaded-response-dto.d.ts +2 -2
  570. package/dist/models/file-uploaded-response-dto.js +2 -2
  571. package/dist/models/file-uploaded-v1-response-dto.d.ts +2 -2
  572. package/dist/models/file-uploaded-v1-response-dto.js +2 -2
  573. package/dist/models/generated-external-contract-document-dto.d.ts +2 -2
  574. package/dist/models/generated-external-contract-document-dto.js +2 -2
  575. package/dist/models/get-bid-acceptance200-response.d.ts +2 -2
  576. package/dist/models/get-bid-acceptance200-response.js +2 -2
  577. package/dist/models/get-bid-results200-response.d.ts +2 -2
  578. package/dist/models/get-bid-results200-response.js +2 -2
  579. package/dist/models/get-bid-settlement200-response.d.ts +2 -2
  580. package/dist/models/get-bid-settlement200-response.js +2 -2
  581. package/dist/models/get-bid-statement200-response.d.ts +2 -2
  582. package/dist/models/get-bid-statement200-response.js +2 -2
  583. package/dist/models/get-bid200-response.d.ts +2 -2
  584. package/dist/models/get-bid200-response.js +2 -2
  585. package/dist/models/get-file-meta200-response.d.ts +2 -2
  586. package/dist/models/get-file-meta200-response.js +2 -2
  587. package/dist/models/get-supplier-card-payable-v2200-response.d.ts +2 -2
  588. package/dist/models/get-supplier-card-payable-v2200-response.js +2 -2
  589. package/dist/models/get-webhook-endpoint200-response.d.ts +2 -2
  590. package/dist/models/get-webhook-endpoint200-response.js +2 -2
  591. package/dist/models/health-controller-check200-response.d.ts +2 -2
  592. package/dist/models/health-controller-check200-response.js +2 -2
  593. package/dist/models/health-response-dto.d.ts +2 -2
  594. package/dist/models/health-response-dto.js +2 -2
  595. package/dist/models/hierarchical-region-dto.d.ts +2 -2
  596. package/dist/models/hierarchical-region-dto.js +2 -2
  597. package/dist/models/hierarchical-region-v1-dto.d.ts +2 -2
  598. package/dist/models/hierarchical-region-v1-dto.js +2 -2
  599. package/dist/models/index.d.ts +12 -0
  600. package/dist/models/index.js +12 -0
  601. package/dist/models/introspect-request-dto.d.ts +2 -2
  602. package/dist/models/introspect-request-dto.js +2 -2
  603. package/dist/models/introspection-response-dto.d.ts +2 -2
  604. package/dist/models/introspection-response-dto.js +2 -2
  605. package/dist/models/invalid-param-dto.d.ts +2 -2
  606. package/dist/models/invalid-param-dto.js +2 -2
  607. package/dist/models/invoice-completed-response-dto.d.ts +2 -2
  608. package/dist/models/invoice-completed-response-dto.js +2 -2
  609. package/dist/models/list-bid-contract-documents200-response.d.ts +2 -2
  610. package/dist/models/list-bid-contract-documents200-response.js +2 -2
  611. package/dist/models/list-bid-participants200-response.d.ts +2 -2
  612. package/dist/models/list-bid-participants200-response.js +2 -2
  613. package/dist/models/list-bid-results200-response.d.ts +2 -2
  614. package/dist/models/list-bid-results200-response.js +2 -2
  615. package/dist/models/list-bids-response-dto.d.ts +2 -2
  616. package/dist/models/list-bids-response-dto.js +2 -2
  617. package/dist/models/list-bids200-response.d.ts +2 -2
  618. package/dist/models/list-bids200-response.js +2 -2
  619. package/dist/models/list-products200-response.d.ts +2 -2
  620. package/dist/models/list-products200-response.js +2 -2
  621. package/dist/models/list-webhook-deliveries-response-dto.d.ts +2 -2
  622. package/dist/models/list-webhook-deliveries-response-dto.js +2 -2
  623. package/dist/models/list-webhook-deliveries200-response.d.ts +2 -2
  624. package/dist/models/list-webhook-deliveries200-response.js +2 -2
  625. package/dist/models/list-webhook-endpoints200-response.d.ts +2 -2
  626. package/dist/models/list-webhook-endpoints200-response.js +2 -2
  627. package/dist/models/mark-bid-failed-request-dto.d.ts +2 -2
  628. package/dist/models/mark-bid-failed-request-dto.js +2 -2
  629. package/dist/models/mark-bid-failed-v1-request-dto.d.ts +2 -2
  630. package/dist/models/mark-bid-failed-v1-request-dto.js +2 -2
  631. package/dist/models/mark-bid-failed201-response.d.ts +2 -2
  632. package/dist/models/mark-bid-failed201-response.js +2 -2
  633. package/dist/models/negotiation-score-v1-dto.d.ts +2 -2
  634. package/dist/models/negotiation-score-v1-dto.js +2 -2
  635. package/dist/models/negotiation-scored-response-dto.d.ts +2 -2
  636. package/dist/models/negotiation-scored-response-dto.js +2 -2
  637. package/dist/models/oauth-error-response-dto.d.ts +2 -2
  638. package/dist/models/oauth-error-response-dto.js +2 -2
  639. package/dist/models/on-bid-award-reverted-request.d.ts +16 -0
  640. package/dist/models/on-bid-award-reverted-request.js +15 -0
  641. package/dist/models/on-bid-awarded-request.d.ts +16 -0
  642. package/dist/models/on-bid-awarded-request.js +15 -0
  643. package/dist/models/on-bid-canceled-request.d.ts +16 -0
  644. package/dist/models/on-bid-canceled-request.js +15 -0
  645. package/dist/models/on-bid-closed-request.d.ts +16 -0
  646. package/dist/models/on-bid-closed-request.js +15 -0
  647. package/dist/models/on-bid-failed-request.d.ts +16 -0
  648. package/dist/models/on-bid-failed-request.js +15 -0
  649. package/dist/models/on-ping-request.d.ts +16 -0
  650. package/dist/models/on-ping-request.js +15 -0
  651. package/dist/models/partner-webhook-delivery-status.d.ts +2 -2
  652. package/dist/models/partner-webhook-delivery-status.js +2 -2
  653. package/dist/models/partner-webhook-endpoint-status.d.ts +2 -2
  654. package/dist/models/partner-webhook-endpoint-status.js +2 -2
  655. package/dist/models/partner-webhook-event-type.d.ts +2 -2
  656. package/dist/models/partner-webhook-event-type.js +2 -2
  657. package/dist/models/preconditions-dto.d.ts +2 -2
  658. package/dist/models/preconditions-dto.js +2 -2
  659. package/dist/models/preconditions-v1-dto.d.ts +2 -2
  660. package/dist/models/preconditions-v1-dto.js +2 -2
  661. package/dist/models/problem-details-dto.d.ts +2 -2
  662. package/dist/models/problem-details-dto.js +2 -2
  663. package/dist/models/product-receipt-response-dto.d.ts +2 -2
  664. package/dist/models/product-receipt-response-dto.js +2 -2
  665. package/dist/models/product-receipt-v1-response-dto.d.ts +2 -2
  666. package/dist/models/product-receipt-v1-response-dto.js +2 -2
  667. package/dist/models/product-response-dto.d.ts +2 -2
  668. package/dist/models/product-response-dto.js +2 -2
  669. package/dist/models/product-v1-response-dto.d.ts +2 -2
  670. package/dist/models/product-v1-response-dto.js +2 -2
  671. package/dist/models/protected-resource-metadata-dto.d.ts +2 -2
  672. package/dist/models/protected-resource-metadata-dto.js +2 -2
  673. package/dist/models/publish-bid200-response.d.ts +2 -2
  674. package/dist/models/publish-bid200-response.js +2 -2
  675. package/dist/models/regenerate-contract-documents201-response.d.ts +2 -2
  676. package/dist/models/regenerate-contract-documents201-response.js +2 -2
  677. package/dist/models/register-award-request-dto.d.ts +2 -2
  678. package/dist/models/register-award-request-dto.js +2 -2
  679. package/dist/models/register-award-v1-request-dto.d.ts +2 -2
  680. package/dist/models/register-award-v1-request-dto.js +2 -2
  681. package/dist/models/register-award201-response.d.ts +2 -2
  682. package/dist/models/register-award201-response.js +2 -2
  683. package/dist/models/register-bid201-response.d.ts +2 -2
  684. package/dist/models/register-bid201-response.js +2 -2
  685. package/dist/models/register-semo-contract-request-dto.d.ts +2 -2
  686. package/dist/models/register-semo-contract-request-dto.js +2 -2
  687. package/dist/models/request-split-invoice-v1-request-dto.d.ts +2 -2
  688. package/dist/models/request-split-invoice-v1-request-dto.js +2 -2
  689. package/dist/models/retiree-roster-input-dto.d.ts +2 -2
  690. package/dist/models/retiree-roster-input-dto.js +2 -2
  691. package/dist/models/retiree-roster-row-dto.d.ts +2 -2
  692. package/dist/models/retiree-roster-row-dto.js +2 -2
  693. package/dist/models/revert-award-request-dto.d.ts +2 -2
  694. package/dist/models/revert-award-request-dto.js +2 -2
  695. package/dist/models/revert-award200-response.d.ts +2 -2
  696. package/dist/models/revert-award200-response.js +2 -2
  697. package/dist/models/revoke-request-dto.d.ts +2 -2
  698. package/dist/models/revoke-request-dto.js +2 -2
  699. package/dist/models/semo-contract-registered-response-dto.d.ts +2 -2
  700. package/dist/models/semo-contract-registered-response-dto.js +2 -2
  701. package/dist/models/semo-contract-taxinvoice-status-response-dto.d.ts +2 -2
  702. package/dist/models/semo-contract-taxinvoice-status-response-dto.js +2 -2
  703. package/dist/models/send-webhook-test-event200-response.d.ts +2 -2
  704. package/dist/models/send-webhook-test-event200-response.js +2 -2
  705. package/dist/models/split-invoice-v1-response-dto.d.ts +2 -2
  706. package/dist/models/split-invoice-v1-response-dto.js +2 -2
  707. package/dist/models/statement-document-dto.d.ts +2 -2
  708. package/dist/models/statement-document-dto.js +2 -2
  709. package/dist/models/statement-product-dto.d.ts +2 -2
  710. package/dist/models/statement-product-dto.js +2 -2
  711. package/dist/models/statement-v1-document-dto.d.ts +2 -2
  712. package/dist/models/statement-v1-document-dto.js +2 -2
  713. package/dist/models/statement-v1-product-dto.d.ts +2 -2
  714. package/dist/models/statement-v1-product-dto.js +2 -2
  715. package/dist/models/submit-negotiation-scores-v1-request-dto.d.ts +2 -2
  716. package/dist/models/submit-negotiation-scores-v1-request-dto.js +2 -2
  717. package/dist/models/supplier-card-payable-response-dto.d.ts +2 -2
  718. package/dist/models/supplier-card-payable-response-dto.js +2 -2
  719. package/dist/models/supplier-tax-type.d.ts +2 -2
  720. package/dist/models/supplier-tax-type.js +2 -2
  721. package/dist/models/token-request-dto.d.ts +2 -2
  722. package/dist/models/token-request-dto.js +2 -2
  723. package/dist/models/token-response-dto.d.ts +2 -2
  724. package/dist/models/token-response-dto.js +2 -2
  725. package/dist/models/update-bid-request-dto.d.ts +2 -2
  726. package/dist/models/update-bid-request-dto.js +2 -2
  727. package/dist/models/update-bid200-response.d.ts +2 -2
  728. package/dist/models/update-bid200-response.js +2 -2
  729. package/dist/models/update-webhook-endpoint-request-dto.d.ts +2 -2
  730. package/dist/models/update-webhook-endpoint-request-dto.js +2 -2
  731. package/dist/models/upload-file-request-dto.d.ts +2 -2
  732. package/dist/models/upload-file-request-dto.js +2 -2
  733. package/dist/models/upload-file-v1-request-dto.d.ts +2 -2
  734. package/dist/models/upload-file-v1-request-dto.js +2 -2
  735. package/dist/models/upload-file201-response.d.ts +2 -2
  736. package/dist/models/upload-file201-response.js +2 -2
  737. package/dist/models/webhook-bid-event-data.d.ts +33 -0
  738. package/dist/models/webhook-bid-event-data.js +15 -0
  739. package/dist/models/webhook-delivery-dto.d.ts +2 -2
  740. package/dist/models/webhook-delivery-dto.js +2 -2
  741. package/dist/models/webhook-endpoint-dto.d.ts +2 -2
  742. package/dist/models/webhook-endpoint-dto.js +2 -2
  743. package/dist/models/webhook-endpoint-with-secret-dto.d.ts +2 -2
  744. package/dist/models/webhook-endpoint-with-secret-dto.js +2 -2
  745. package/dist/models/webhook-event-envelope.d.ts +34 -0
  746. package/dist/models/webhook-event-envelope.js +15 -0
  747. package/dist/models/webhook-ping-event-data.d.ts +20 -0
  748. package/dist/models/webhook-ping-event-data.js +15 -0
  749. package/dist/models/webhook-test-result-dto.d.ts +2 -2
  750. package/dist/models/webhook-test-result-dto.js +2 -2
  751. package/docs/ApiCatalogDto.md +20 -0
  752. package/docs/ApiCatalogEntryDto.md +26 -0
  753. package/docs/ApiCatalogLinkDto.md +24 -0
  754. package/docs/BidRegisteredResponseDto.md +2 -0
  755. package/docs/BidResultsBatchRequestDto.md +1 -1
  756. package/docs/OnBidAwardRevertedRequest.md +26 -0
  757. package/docs/OnBidAwardedRequest.md +26 -0
  758. package/docs/OnBidCanceledRequest.md +26 -0
  759. package/docs/OnBidClosedRequest.md +26 -0
  760. package/docs/OnBidFailedRequest.md +26 -0
  761. package/docs/OnPingRequest.md +26 -0
  762. package/docs/PartnerV2Api.md +4 -4
  763. package/docs/WebhookBidEventData.md +27 -0
  764. package/docs/WebhookEventEnvelope.md +27 -0
  765. package/docs/WebhookPingEventData.md +21 -0
  766. package/docs/WebhooksApi.md +385 -0
  767. package/docs/WellKnownApi.md +45 -0
  768. package/index.ts +2 -2
  769. package/models/acceptance-result-response-dto.ts +2 -2
  770. package/models/acceptance-result-v1-response-dto.ts +2 -2
  771. package/models/acceptance-status-response-dto.ts +2 -2
  772. package/models/acknowledge-product-receipt200-response.ts +2 -2
  773. package/models/acknowledge-products-request-dto.ts +2 -2
  774. package/models/acknowledge-products-v1-request-dto.ts +2 -2
  775. package/models/api-catalog-dto.ts +26 -0
  776. package/models/api-catalog-entry-dto.ts +38 -0
  777. package/models/api-catalog-link-dto.ts +31 -0
  778. package/models/authorization-server-metadata-dto.ts +2 -2
  779. package/models/award-method-public.ts +2 -2
  780. package/models/award-registered-response-dto.ts +2 -2
  781. package/models/award-registered-v2-response-dto.ts +2 -2
  782. package/models/award-reverted-v2-response-dto.ts +2 -2
  783. package/models/bid-attachment-v1-dto.ts +2 -2
  784. package/models/bid-bond-dto.ts +2 -2
  785. package/models/bid-bond-v1-dto.ts +2 -2
  786. package/models/bid-cancelled-response-dto.ts +2 -2
  787. package/models/bid-contact-dto.ts +2 -2
  788. package/models/bid-contacts-dto.ts +2 -2
  789. package/models/bid-contract-document-dto.ts +2 -2
  790. package/models/bid-contract-documents-batch-v1-request-dto.ts +2 -2
  791. package/models/bid-contract-documents-v1-response-dto.ts +2 -2
  792. package/models/bid-created-response-dto.ts +2 -2
  793. package/models/bid-delivery-terms-dto.ts +2 -2
  794. package/models/bid-detail-response-dto.ts +2 -2
  795. package/models/bid-document-dto.ts +2 -2
  796. package/models/bid-document-v1-dto.ts +2 -2
  797. package/models/bid-failed-response-dto.ts +2 -2
  798. package/models/bid-failed-v2-response-dto.ts +2 -2
  799. package/models/bid-failure-reason.ts +2 -2
  800. package/models/bid-item-dto.ts +2 -2
  801. package/models/bid-item-v1-dto.ts +2 -2
  802. package/models/bid-lifecycle-dto.ts +2 -2
  803. package/models/bid-manager-dto.ts +2 -2
  804. package/models/bid-manager-v1-dto.ts +2 -2
  805. package/models/bid-participant-summary-dto.ts +2 -2
  806. package/models/bid-payment-terms-dto.ts +2 -2
  807. package/models/bid-product-dto.ts +2 -2
  808. package/models/bid-public-status.ts +2 -2
  809. package/models/bid-published-response-dto.ts +2 -2
  810. package/models/bid-registered-response-dto.ts +6 -2
  811. package/models/bid-result-participant-attachment-dto.ts +2 -2
  812. package/models/bid-result-participant-dto.ts +2 -2
  813. package/models/bid-result-v1-attachment-dto.ts +2 -2
  814. package/models/bid-result-v1-bid-product-info-dto.ts +2 -2
  815. package/models/bid-result-v1-participant-dto.ts +2 -2
  816. package/models/bid-result-v1-product-dto.ts +2 -2
  817. package/models/bid-results-batch-request-dto.ts +3 -3
  818. package/models/bid-results-batch-v1-request-dto.ts +2 -2
  819. package/models/bid-results-response-dto.ts +2 -2
  820. package/models/bid-results-v1-response-dto.ts +2 -2
  821. package/models/bid-settlement-line-item-dto.ts +2 -2
  822. package/models/bid-settlement-participant-dto.ts +2 -2
  823. package/models/bid-settlement-response-dto.ts +2 -2
  824. package/models/bid-statement-response-dto.ts +2 -2
  825. package/models/bid-statement-v1-response-dto.ts +2 -2
  826. package/models/bid-status.ts +2 -2
  827. package/models/bid-summary-dto.ts +2 -2
  828. package/models/bid-updated-response-dto.ts +2 -2
  829. package/models/cancel-bid-request-dto.ts +2 -2
  830. package/models/cancel-bid200-response.ts +2 -2
  831. package/models/card-payment-request-response-dto.ts +2 -2
  832. package/models/complete-acceptance-request-dto.ts +2 -2
  833. package/models/complete-acceptance-v1-request-dto.ts +2 -2
  834. package/models/complete-acceptance200-response.ts +2 -2
  835. package/models/complete-invoice200-response.ts +2 -2
  836. package/models/contract-document-item-dto.ts +2 -2
  837. package/models/contract-documents-regenerated-response-dto.ts +2 -2
  838. package/models/contract-restriction-confirm-input-dto.ts +2 -2
  839. package/models/create-bid-request-dto.ts +2 -2
  840. package/models/create-bid-v1-request-dto.ts +2 -2
  841. package/models/create-card-payment-request-dto.ts +2 -2
  842. package/models/create-card-payment200-response.ts +2 -2
  843. package/models/create-external-contract-documents-request-dto.ts +2 -2
  844. package/models/create-external-contract-documents-response-dto.ts +2 -2
  845. package/models/create-webhook-endpoint-request-dto.ts +2 -2
  846. package/models/create-webhook-endpoint201-response.ts +2 -2
  847. package/models/external-contract-document-item-dto.ts +2 -2
  848. package/models/external-contract-documents-response-dto.ts +2 -2
  849. package/models/external-contract-item-dto.ts +2 -2
  850. package/models/external-contract-snapshot-dto.ts +2 -2
  851. package/models/external-document-inputs-dto.ts +2 -2
  852. package/models/file-meta-response-dto.ts +2 -2
  853. package/models/file-uploaded-response-dto.ts +2 -2
  854. package/models/file-uploaded-v1-response-dto.ts +2 -2
  855. package/models/generated-external-contract-document-dto.ts +2 -2
  856. package/models/get-bid-acceptance200-response.ts +2 -2
  857. package/models/get-bid-results200-response.ts +2 -2
  858. package/models/get-bid-settlement200-response.ts +2 -2
  859. package/models/get-bid-statement200-response.ts +2 -2
  860. package/models/get-bid200-response.ts +2 -2
  861. package/models/get-file-meta200-response.ts +2 -2
  862. package/models/get-supplier-card-payable-v2200-response.ts +2 -2
  863. package/models/get-webhook-endpoint200-response.ts +2 -2
  864. package/models/health-controller-check200-response.ts +2 -2
  865. package/models/health-response-dto.ts +2 -2
  866. package/models/hierarchical-region-dto.ts +2 -2
  867. package/models/hierarchical-region-v1-dto.ts +2 -2
  868. package/models/index.ts +12 -0
  869. package/models/introspect-request-dto.ts +2 -2
  870. package/models/introspection-response-dto.ts +2 -2
  871. package/models/invalid-param-dto.ts +2 -2
  872. package/models/invoice-completed-response-dto.ts +2 -2
  873. package/models/list-bid-contract-documents200-response.ts +2 -2
  874. package/models/list-bid-participants200-response.ts +2 -2
  875. package/models/list-bid-results200-response.ts +2 -2
  876. package/models/list-bids-response-dto.ts +2 -2
  877. package/models/list-bids200-response.ts +2 -2
  878. package/models/list-products200-response.ts +2 -2
  879. package/models/list-webhook-deliveries-response-dto.ts +2 -2
  880. package/models/list-webhook-deliveries200-response.ts +2 -2
  881. package/models/list-webhook-endpoints200-response.ts +2 -2
  882. package/models/mark-bid-failed-request-dto.ts +2 -2
  883. package/models/mark-bid-failed-v1-request-dto.ts +2 -2
  884. package/models/mark-bid-failed201-response.ts +2 -2
  885. package/models/negotiation-score-v1-dto.ts +2 -2
  886. package/models/negotiation-scored-response-dto.ts +2 -2
  887. package/models/oauth-error-response-dto.ts +2 -2
  888. package/models/on-bid-award-reverted-request.ts +28 -0
  889. package/models/on-bid-awarded-request.ts +28 -0
  890. package/models/on-bid-canceled-request.ts +28 -0
  891. package/models/on-bid-closed-request.ts +28 -0
  892. package/models/on-bid-failed-request.ts +28 -0
  893. package/models/on-ping-request.ts +28 -0
  894. package/models/partner-webhook-delivery-status.ts +2 -2
  895. package/models/partner-webhook-endpoint-status.ts +2 -2
  896. package/models/partner-webhook-event-type.ts +2 -2
  897. package/models/preconditions-dto.ts +2 -2
  898. package/models/preconditions-v1-dto.ts +2 -2
  899. package/models/problem-details-dto.ts +2 -2
  900. package/models/product-receipt-response-dto.ts +2 -2
  901. package/models/product-receipt-v1-response-dto.ts +2 -2
  902. package/models/product-response-dto.ts +2 -2
  903. package/models/product-v1-response-dto.ts +2 -2
  904. package/models/protected-resource-metadata-dto.ts +2 -2
  905. package/models/publish-bid200-response.ts +2 -2
  906. package/models/regenerate-contract-documents201-response.ts +2 -2
  907. package/models/register-award-request-dto.ts +2 -2
  908. package/models/register-award-v1-request-dto.ts +2 -2
  909. package/models/register-award201-response.ts +2 -2
  910. package/models/register-bid201-response.ts +2 -2
  911. package/models/register-semo-contract-request-dto.ts +2 -2
  912. package/models/request-split-invoice-v1-request-dto.ts +2 -2
  913. package/models/retiree-roster-input-dto.ts +2 -2
  914. package/models/retiree-roster-row-dto.ts +2 -2
  915. package/models/revert-award-request-dto.ts +2 -2
  916. package/models/revert-award200-response.ts +2 -2
  917. package/models/revoke-request-dto.ts +2 -2
  918. package/models/semo-contract-registered-response-dto.ts +2 -2
  919. package/models/semo-contract-taxinvoice-status-response-dto.ts +2 -2
  920. package/models/send-webhook-test-event200-response.ts +2 -2
  921. package/models/split-invoice-v1-response-dto.ts +2 -2
  922. package/models/statement-document-dto.ts +2 -2
  923. package/models/statement-product-dto.ts +2 -2
  924. package/models/statement-v1-document-dto.ts +2 -2
  925. package/models/statement-v1-product-dto.ts +2 -2
  926. package/models/submit-negotiation-scores-v1-request-dto.ts +2 -2
  927. package/models/supplier-card-payable-response-dto.ts +2 -2
  928. package/models/supplier-tax-type.ts +2 -2
  929. package/models/token-request-dto.ts +2 -2
  930. package/models/token-response-dto.ts +2 -2
  931. package/models/update-bid-request-dto.ts +2 -2
  932. package/models/update-bid200-response.ts +2 -2
  933. package/models/update-webhook-endpoint-request-dto.ts +2 -2
  934. package/models/upload-file-request-dto.ts +2 -2
  935. package/models/upload-file-v1-request-dto.ts +2 -2
  936. package/models/upload-file201-response.ts +2 -2
  937. package/models/webhook-bid-event-data.ts +43 -0
  938. package/models/webhook-delivery-dto.ts +2 -2
  939. package/models/webhook-endpoint-dto.ts +2 -2
  940. package/models/webhook-endpoint-with-secret-dto.ts +2 -2
  941. package/models/webhook-event-envelope.ts +38 -0
  942. package/models/webhook-ping-event-data.ts +26 -0
  943. package/models/webhook-test-result-dto.ts +2 -2
  944. package/package.json +1 -1
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -3,9 +3,9 @@
3
3
  /* eslint-disable */
4
4
  /**
5
5
  * CMARKET V6 Partner API
6
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
6
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
7
7
  *
8
- * The version of the OpenAPI document: 31.1.1
8
+ * The version of the OpenAPI document: 31.3.0
9
9
  * Contact: semo.io.kr@gmail.com
10
10
  *
11
11
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * CMARKET V6 Partner API
3
- * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP status 둜 폴백**ν•˜λ„λ‘ κ΅¬ν˜„ν•  것. ### λ©±λ“±μ„± μœ„λ°˜: 409 와 422 의 차이 - `409` `…/idempotency-key-conflict` β€” 같은 ν‚€μ˜ **원 μš”μ²­μ΄ 아직 처리 쀑**이닀. μž μ‹œ λ’€ 같은 ν‚€λ‘œ λ‹€μ‹œ λΆ€λ₯΄λ©΄ κ·Έ κ²°κ³Όλ₯Ό λ°›λŠ”λ‹€. - `422` `…/idempotency-key-reused` β€” 같은 ν‚€λ₯Ό **λ‹€λ₯Έ body** 둜 λ³΄λƒˆλ‹€. μž¬μ‹œλ„ν•΄λ„ μ˜μ›νžˆ 같은 μ‹€νŒ¨λ‹€. μƒˆ ν‚€λ₯Ό μ“°κ±°λ‚˜ body λ₯Ό 되돌릴 것. ## 레이트 리밋 μ „μ—­ **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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
3
+ * μ™ΈλΆ€ ERP μ—°λ™μš© RESTful API. ## 버전별 인증 - **_/v2** β€” OAuth2 Bearer JWT (`client_credentials` ν”Œλ‘œμš°). `/oauth/token` μ—μ„œ 토큰 λ°œκΈ‰ ν›„ `Authorization: Bearer <token>` 헀더. - **_/v1** β€” V5 μΆ©μ‹€ platform-auth. `X-Platform-Id`(cate_set.api_id) / `X-Platform-Secret`(cate_set.api_secret, MD5-hex) ν—€λ”λ‘œ 전솑. ## κΆŒν•œ β€” 두 개의 λ…λ¦½λœ μΆ• `403` 을 λ§Œλ‚¬λ‹€λ©΄ λ‘˜ 쀑 μ–΄λŠ 좕에 κ±Έλ¦° 것인지 λ¨Όμ € ꡬ뢄할 것. - **μŠ€μ½”ν”„** = *무엇을 ν•  수 μžˆλ‚˜*. 토큰에 λΆ€μ—¬λœ `bids:read`Β·`contracts:write` λ“±. 미보유 μ‹œ `…/insufficient-scope`. - **λŒ€ν–‰ λ²”μœ„** = *λˆ„κ΅¬μ˜ 데이터λ₯Ό λ‹€λ£° 수 μžˆλ‚˜*. API ν‚€ 섀정이며 μŠ€μ½”ν”„λ‘œ ν‘œν˜„λ˜μ§€ μ•ŠλŠ”λ‹€. λ²”μœ„ 밖이면 μŠ€μ½”ν”„μ™€ λ¬΄κ΄€ν•˜κ²Œ 403 이닀. λŒ€ν–‰ λ²”μœ„λŠ” ν‚€λ§ˆλ‹€ λ‘˜ 쀑 ν•˜λ‚˜λ‘œ μ„€μ •λœλ‹€ β€” **μ†Œμ† κ·Έλ£Ή 전원**(κΈ°κ΄€ ν‚€. μ‚¬μ—…μ²˜Β·λΆ€μ„œ 계정이 μƒˆλ‘œ 생겨도 μžλ™ 포함) λ˜λŠ” **μ§€μ • 발주처 λͺ©λ‘**(κ³„μ•½μœΌλ‘œ ν•©μ˜λœ λͺ©λ‘). λ²”μœ„λ₯Ό λ„“ν˜€μ•Ό ν•˜λ©΄ μŠ€μ½”ν”„κ°€ μ•„λ‹ˆλΌ ν‚€ μ„€μ • 변경을 μš”μ²­ν•  것. ## 성곡 응닡 λ΄‰νˆ¬ `/v2` 의 λͺ¨λ“  2xx 본문은 `{ \"data\": … }` μž…λ‹ˆλ‹€. 단일 λ¦¬μ†ŒμŠ€λ“  λͺ©λ‘μ΄λ“  κ°™μŠ΅λ‹ˆλ‹€. λͺ©λ‘μ²˜λŸΌ λΆ€κ°€ 정보가 μžˆλŠ” 응닡은 `meta` κ°€ ν•¨κ»˜ μ‹€λ¦½λ‹ˆλ‹€ β€” 예: `{ \"data\": [...], \"meta\": { \"nextCursor\": \"…\" } }`. λΆ€κ°€ 정보가 μ—†μœΌλ©΄ `meta` ν‚€λŠ” μ•„μ˜ˆ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€(빈 객체λ₯Ό μ‹£μ§€ μ•ŠμŠ΅λ‹ˆλ‹€). λ΄‰νˆ¬λ₯Ό μ“°μ§€ μ•ŠλŠ” ν‘œλ©΄μ€ μ…‹μž…λ‹ˆλ‹€. `/oauth/_*` 와 `/.well-known/_*` λŠ” 각각 RFC 6749Β·RFC 8414Β·RFC 9728 이 μ΅œμƒμœ„ ν•„λ“œλ₯Ό κ·œμ •ν•˜κ³ , `/v1/_*` 은 λ™κ²°λœ λ ˆκ±°μ‹œ ν‘œλ©΄μ΄λ©°, 파일 λ‚΄μš© 응닡은 본문이 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 λ³„λ‘œ λͺ…μ‹œλΌ μžˆλ‹€. μƒˆ slug 은 좔가될 수 μžˆμœΌλ―€λ‘œ, λͺ¨λ₯΄λŠ” slug 을 λ§Œλ‚˜λ©΄ `type` 이 μ•„λ‹ˆλΌ **HTTP 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` κ°€ μ‹€λ¦°λ‹€. ## 버전 수λͺ…(deprecation/sunset) - **_/v1** 은 λ ˆκ±°μ‹œ V5 cutover μ™„λ£Œ μ‹œμ κΉŒμ§€ μœ μ§€λ˜λŠ” μΆ©μ‹€ ν”„λ‘μ‹œμž…λ‹ˆλ‹€. 폐지 일정이 μ •ν•΄μ§€λ©΄ /v1 응닡에 헀더 μ„Έ κ°œκ°€ μ‹€λ¦½λ‹ˆλ‹€ β€” `Deprecation`(RFC 9745, `@<epoch초>`) Β· `Sunset`(RFC 8594, HTTP-date) Β· `Link`(RFC 8288, `rel=\"deprecation\"`/`rel=\"sunset\"` β€” 이전 μ•ˆλ‚΄ λ¬Έμ„œλ₯Ό κ°€λ¦¬ν‚΅λ‹ˆλ‹€). 일정이 μ •ν•΄μ§€κΈ° μ „μ—λŠ” μ…‹ λ‹€ λ‚˜κ°€μ§€ μ•ŠμŠ΅λ‹ˆλ‹€. μ’…λ£ŒμΌμ΄ μ§€λ‚œ λ’€μ˜ ν˜ΈμΆœμ€ `404` κ°€ μ•„λ‹ˆλΌ **`410 Gone`** κ³Ό `type: …/endpoint-sunset` 으둜 κ±°μ ˆλ©λ‹ˆλ‹€. λ‘˜μ˜ 뜻이 λ‹€λ¦…λ‹ˆλ‹€ β€” `404` λŠ” \"그런 것이 μžˆμ—ˆλŠ”μ§€ λͺ¨λ₯΄κ² λ‹€\", `410` 은 \"μžˆμ—ˆκ³  μ˜λ„μ μœΌλ‘œ μ—†μ•΄λ‹€\" μž…λ‹ˆλ‹€. `410` 을 λ°›μœΌλ©΄ 경둜 μ˜€νƒ€λ₯Ό μ˜μ‹¬ν•˜μ§€ 말고 /v2 둜 μ΄μ „ν•˜μ„Έμš”. - **_/v2** breaking 변경은 CHANGELOG SemVer(major bump)와 `Deprecation`/`Sunset` ν—€λ”λ‘œ ν†΅μ§€ν•œλ‹€. μ†ŒλΉ„μžλŠ” 이 헀더λ₯Ό λͺ¨λ‹ˆν„°λ§ν•  것.
4
4
  *
5
- * The version of the OpenAPI document: 31.1.1
5
+ * The version of the OpenAPI document: 31.3.0
6
6
  * Contact: semo.io.kr@gmail.com
7
7
  *
8
8
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -14,4 +14,8 @@ export interface BidRegisteredResponseDto {
14
14
  * μƒμ„±λœ 곡고 μ‹λ³„μž.
15
15
  */
16
16
  'bidId': string;
17
+ /**
18
+ * ν™•μ •λœ 발주처 μ‘°λ‹¬λ²ˆν˜Έ. 등둝 μš”μ²­μ˜ `purchaseNo` **에코가 μ•„λ‹ˆλΌ μ„œλ²„κ°€ ν™•μ •ν•œ κ°’**이닀 β€” 동일 μ‘°λ‹¬λ²ˆν˜Έμ˜ μ„ ν–‰ 곡고가 μ „λΆ€ μ·¨μ†Œ/유찰이면 μž¬μž…μ°°λ‘œ μƒˆ λ²ˆν˜Έκ°€ μ±„λ²ˆλœλ‹€(`PO-1` β†’ `PO-1(2)`). ERP 원μž₯에 μ €μž₯ν•  ν‚€λŠ” 이 값이닀. 등둝 μš”μ²­μ— μ‘°λ‹¬λ²ˆν˜Έκ°€ μ—†μ—ˆμœΌλ©΄ null.
19
+ */
20
+ 'purchaseNo': string | null;
17
21
  }