API로 주문 확인 시 '처리 중' 상태 처리

API 응답에서 processing이 의미하는 것

processing, in_progress 또는 이와 동등한 상태는 공급자가 주문을 접수해 작업 중이지만 결과를 확정하지 않았음을 의미합니다. 프로모션 서비스의 경우 링크 검증, 대기열 대기, 작업 시작 또는 주문한 물량의 점진적 제공일 수 있습니다.

Processing은 성공적인 수행을 확인하는 것도 아니고 오류를 의미하는 것도 아닙니다. 이후 주문은 completed, partial, canceled 또는 failed로 전환될 수 있습니다. 공급자가 중간 상태를 반환하는 동안에는 동일한 링크와 동일한 물량에 대해 재요청을 생성하지 마세요.

processing 상태의 HTTP 200은 API 응답이 성공했다는 의미이지 주문이 성공적으로 완료되었다는 의미가 아닙니다. 이 두 이벤트는 별도로 저장하고 처리해야 합니다.

주문 확인에 필요한 데이터

폴링에는 생성 시 공급자가 반환한 외부 주문 ID가 필요합니다. 이를 내부 ID, 원래 물량, 서비스 파라미터, 링크, 생성 시간, 원본 API 응답과 함께 저장하세요. 채널명, 링크 또는 물량으로 주문을 조회하는 것은 신뢰할 수 없습니다. 이러한 값은 여러 요청에서 일치할 수 있습니다.

생성 후 타임아웃이 발생한 경우 요청을 자동으로 다시 보내지 마세요. 공급자가 요청을 접수했을 수 있지만 응답이 전송 중에 유실되었을 수 있습니다. 먼저 문서에 주문 조회 메서드가 있으면 사용하고, 없으면 해당 건을 확인 대상으로 전달하세요.

현재 상태만 저장할 때의 단점은 분쟁 시 주문이 언제 processing으로 전환되었는지, 진행 상황이 있었는지, 이전에 어떤 응답이 왔는지 복원할 수 없다는 것입니다.

curl로 상태를 요청하는 예시

정확한 주소, 인증 방법, 필드 이름은 공급자 문서에서 가져오세요. 아래는 템플릿이며, 꺾쇠괄호 안의 값은 특정 API의 데이터로 교체해야 합니다.

단일 주문에 대한 GET 요청

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

응답 예시:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

completed_quantity와 remains 필드는 구조 예시로만 제시되었습니다. 공급자는 progress, start_count, balance 또는 다른 이름을 사용할 수 있습니다. GET 방식의 단점은 일부 API가 상태 확인을 POST로만 허용한다는 것입니다.

POST 요청 예시 및 일괄 확인

단일 주문 상태에 대한 POST 요청

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

API 키를 URL 문자열에 전달하지 마세요. 요청 주소는 프록시 로그, 분석 시스템, 브라우저 기록, 기술 로그에 남습니다. POST의 단점은 주소 표시줄로 수동 확인하기 어렵다는 것이지만, 그렇다고 해서 시크릿을 URL로 옮겨야 하는 것은 아닙니다.

활성 주문 일괄 요청

API가 일괄 확인을 지원하면 여러 ID를 하나의 요청으로 보내세요:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

응답은 배열 내 항목의 위치가 아니라 외부 ID로 내부 주문과 매칭하세요. 일괄 확인의 단점: 공급자가 모든 주문을 반환하지 않거나, 목록 크기를 제한하거나, 하나의 ID에 대해서만 오류를 보고할 수 있습니다.

processing에 대한 폴링을 설정하는 방법

첫 processing 응답 후 다음 확인을 대기열에 넣으세요. 간격은 API 문서, 빈도 제한, 서비스 특성에 따라 선택하세요. 상태가 빠르게 변하는 작업은 초기에 더 자주 확인하는 것이 허용됩니다. 점진적 프로모션의 경우 지속적인 짧은 요청은 일반적으로 새로운 정보를 제공하지 않습니다.

실용적인 방식은 동일한 processing 응답 후 대기 시간을 늘리는 것입니다. 첫 확인은 초기 지연 후 실행되고, 이후 간격은 설정된 최대값까지 증가합니다. API가 진행 상황이나 새로운 업데이트 시간을 반환하면 그 변경 시점부터 다시 계산할 수 있습니다.

• 주문 생성 후 즉시 여러 번 연속으로 상태를 확인하지 마세요. 서비스가 대기열에 넣는 데 시간이 필요할 수 있습니다.
• processing이 반복되면 고정 빈도를 유지하지 말고 요청 간 간격을 늘리세요.
• 주문이 동시에 API를 폴링하지 않도록 작업 시작 시간에 약간의 무작위 편차를 추가하세요.
• 공급자가 Retry-After 또는 유사한 권장 사항을 전달하면 이를 우선적으로 사용하세요.
• 웹훅이 있는 주문에도 제어용 폴링을 유지하세요. 알림이 도달하지 않을 수 있습니다.

드문 폴링의 단점은 실제 완료 후 인터페이스가 오래된 상태를 표시할 수 있다는 것입니다. 너무 잦은 폴링의 단점은 API 한도에 부딪혀 429를 받고 불필요한 부하를 생성할 위험이 있다는 것입니다.

processing 제어를 위해 저장해야 할 시간

일반적인 수행과 멈춤을 구분하려면 현재 상태 하나로는 충분하지 않습니다. 각 활성 주문에 대해 생성 시간, processing 최초 수신 시각, 마지막 성공 API 응답, 외부 상태의 마지막 변경, 진행 상황의 마지막 변경을 저장하세요.

원래 물량, 확인된 수행 물량, 잔여분, 공급자의 원본 상태도 저장하는 것이 유용합니다. API가 진행 상황을 제공하지 않는다고 해서 주문이 멈췄다고 판단해서는 안 됩니다. 마지막 응답 시간과 서비스 조건에 명시된 예상 처리 기간을 기준으로 하세요.

최대 대기 시간을 모든 서비스에 하나의 숫자로 설정할 수는 없습니다. 공급자가 특정 서비스에 대해 명시한 기한에 대기열 및 데이터 업데이트를 위한 내부 여유를 더해 사용하세요. 기한이 명시되지 않은 경우 서비스 카테고리별로 별도 규칙을 설정하고 실제 처리 이력을 바탕으로 재검토하세요.

processing이 변하지 않을 때 해야 할 일

장기간의 processing이 오류를 증명하지는 않습니다. 먼저 성공적인 API 응답이 있었는지, completed_quantity나 remains가 변경되었는지, 웹훅이 있었는지, 서비스 규칙이 변경되었는지 확인하세요. 눈에 보이는 증가가 없는 것은 플랫폼 통계 지연이나 공급자가 최종 단계에서만 진행 상황을 업데이트하기 때문일 수 있습니다.

내부 대기 기한을 초과한 경우 주문을 자동으로 취소하지 마세요. 우선순위 상태 확인을 수행하고, 별도 메서드가 마련되어 있으면 해당 데이터를 요청하고, 알림 이력을 확인하세요. 공급자가 여전히 processing을 확인하면 주문을 내부 상태 '확인 필요'로 전환하되 외부 상태는 대체하지 않고 유지하세요.

• 마지막으로 확인된 응답 시간과 전체 API 응답을 기록하세요.
• 이전 폴링 이후 진행 상황이 변경되었는지 확인하세요.
• 내부 임계값에 도달한 후 자동 요청 빈도를 낮추세요.
• 지원팀에 외부 ID, 링크, 서비스 파라미터, 상태 이력, 기술 오류를 전달하세요.
• 공급자의 응답이나 명확한 최종 상태 전까지 잔여분을 재실행하지 마세요.

수동 확인의 단점은 주문에 지원팀의 주의가 필요하다는 것입니다. 그러나 자동 취소나 중복은 더 위험합니다. 공급자 측에서 수행이 계속될 수 있기 때문입니다.

요청 실패와 주문 상태를 구분하는 방법

네트워크 오류, 타임아웃, HTTP 429, 5xx 응답은 주문 자체의 상태를 알려주지 않습니다. 이는 새로운 신뢰할 수 있는 상태를 얻지 못했을 뿐임을 의미합니다. 이러한 상황에서는 마지막으로 확인된 상태를 유지하고 기술 오류를 기록하며 새로운 확인을 예약하세요.

429의 경우 헤더가 전달되면 Retry-After를 고려하세요. 일시적인 네트워크 오류와 5xx의 경우 시도 간 대기 시간을 늘리세요. 인증, 서명 또는 접근 권한 오류의 경우 잦은 재시도를 하지 마세요. 키, 토큰 만료, IP 제한, 접근 설정을 확인해야 합니다.

API가 HTTP 200을 반환했지만 JSON이 파싱되지 않거나 응답에 order_id와 status가 없는 경우 응답 본문 전체를 저장하고 확인을 잘못된 것으로 표시하세요. 상태 부재를 completed, canceled 또는 processing으로 대체하지 마세요.

자동 재요청을 중단해야 할 때

폴링은 무한해서는 안 됩니다. 일시적 오류에 대한 기술적 재시도 횟수를 제한하고, 주문이 processing에 머무는 전체 기간을 별도로 관리하세요. 재시도 한도를 소진한 후에는 매분 결과 없이 새로운 요청을 생성하지 말고 확인 작업을 검토 대기열로 전환하세요.

상태 요청의 반복은 메서드가 데이터만 읽는 경우 일반적으로 안전합니다. 생성, 취소, 충전, 재시작, 환불 메서드는 타임아웃 후 기계적으로 반복할 수 없습니다. 멱등성 키나 공급자의 명확한 확인 없이는 이러한 반복이 주문을 두 번 변경할 수 있습니다.

재시도 제한의 단점은 일부 업데이트가 수동 작업이 된다는 것입니다. 무한 재시도는 더 나쁩니다. 오류를 숨기고 한도를 소모하며 로그 분석을 복잡하게 만듭니다.

processing 이후 최종 상태를 수용하는 방법

늦은 폴링 응답이나 오래된 웹훅으로 인해 completed에서 processing으로 역전환되는 것을 허용하지 마세요. 각 업데이트 시 공급자의 이벤트 시간, 버전 번호(있는 경우), 현재 내부 상태를 비교하세요.

• new와 pending은 processing, canceled 또는 failed로 전환될 수 있습니다.
• processing은 completed, partial, canceled 또는 failed로 전환될 수 있습니다.
• partial을 자동으로 completed로 간주해서는 안 됩니다.
• completed, canceled, failed는 일반적으로 최종 상태로 간주되어 자동 역전환을 차단합니다.
• 알 수 없는 상태나 허용되지 않는 전환은 별도 확인이 필요합니다.

엄격한 전환 테이블에도 단점이 있습니다. 공급자가 올바른 새 상태를 추가할 수 있습니다. 따라서 원본 상태를 저장하고 내부 분류로 덮어쓰지 마세요.

partial 및 주문 잔여분을 처리하는 방법

Partial은 원래 물량의 일부만 확인되었음을 의미합니다. API 응답에는 실제 수행 수량, 잔여분, 사유, 보상 데이터가 있을 수 있습니다. 이러한 값을 별도로 저장하세요. 원래 주문 물량을 수행 수량으로 대체해서는 안 됩니다.

최종 응답 예시는 다음과 같을 수 있습니다:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

먼저 API가 정확히 무엇을 확인하는지 파악하세요. 환불이 이미 처리되었는지, 환불이 예정만 되었는지, 잔여분이 취소되었는지, 지원팀 문의가 필요한지 확인하세요. 환불 필드가 없으면 잔여분이 자동으로 보상되었다고 간주하지 마세요.

별도 결정 없이 미수행 부분을 재시작하지 마세요. 공급자가 아직 정산을 완료 중일 수 있고, 플랫폼 통계가 지연 업데이트될 수 있으며, 재요청이 중복 프로모션을 생성할 수 있습니다. 확인을 기다릴 때의 단점은 잔여분이 즉시 마감되지 않는다는 것이지만, 불필요한 주문이 생기지는 않습니다.

웹훅은 제어 확인을 대체하지 않습니다

웹훅을 사용하면 다음 폴링을 기다리지 않고 이벤트 직후 주문 카드를 업데이트할 수 있습니다. 핸들러에서 외부 ID로 주문을 찾고, 서명이나 시크릿을 검증하고, 이벤트 ID를 저장하고, 허용 여부를 확인한 후에만 전환을 적용하세요.

웹훅의 재전송은 안전해야 합니다. 동일한 이벤트를 새로운 변경으로 간주해서는 안 됩니다. 이벤트가 순서대로 도착하지 않을 수도 있으므로 늦은 processing만을 근거로 최종 주문을 역전환하지 마세요.

안정적인 웹훅이 있더라도 제어용 폴링이 필요합니다. 웹훅의 단점은 설정이 더 복잡하다는 것입니다. 접근 가능한 핸들러, 위조 요청 방지, 중복 제거, 이벤트 로그가 필요합니다.

processing 및 멈춤 시 고객에게 표시할 내용

인터페이스에 전체 기술 JSON을 출력할 필요는 없습니다. processing의 경우 '주문 처리 중' 상태로 충분합니다. API가 신뢰할 수 있는 진행 상황을 전달한 경우 확인된 물량을 원래 물량과 별도로 표시하고 최종 결과로 제시하지 마세요.

내부 제어 기한을 초과한 주문의 경우 '수행 여부 확인 중'과 같이 이해하기 쉬운 상태를 사용하세요. 공급자의 응답으로 확인되기 전까지 취소, 환불 또는 완전 완료를 알리지 마세요.

알림은 주문 접수, 최종 수행, partial, 취소, 오류, 확인 필요 시 유용합니다. 매 폴링 후 메시지는 소음을 만들고 고객이 요청의 실제 상태를 이해하는 데 도움이 되지 않습니다.

처리 로그에 필요한 기록

응답 이력은 멈춘 processing, 유실된 웹훅, 부분 수행 분쟁, 인터페이스와 API 간의 불일치를 분석하는 데 도움이 됩니다. 각 호출에 대해 외부 ID, 업데이트 출처, 요청 및 응답 시간, HTTP 코드, 원본 상태, 정규화된 상태, 진행 상황, 잔여분, 기술 오류 텍스트를 저장하세요.

일반 로그에 API 키, 토큰, 서명 및 기타 시크릿을 기록하지 마세요. 원본 응답에 대한 접근을 제한하세요. 지원 인터페이스에 있어서는 안 되는 데이터가 포함될 수 있습니다.

출시 전에 반복되는 processing, 진행 상황 부재, 타임아웃, 429, 5xx 오류, 잘못된 JSON, 늦은 웹훅, 중복 웹훅, partial, canceled, 알 수 없는 상태 시나리오를 테스트하세요. 테스트 모드는 통합 구조에 유용하지만 실제 대기열과 운영 API의 지연을 재현하지 못할 수 있다는 단점이 있습니다.