> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# AceDataCloud 플랫폼 주문 상태 새로고침

> Platform API guide - Ace Data Cloud

주문에 해당하는 결제 수단의 최신 상태를 능동적으로 조회하고 플랫폼에 동기화합니다. 이 요청은 결제 서비스에 접근하고 주문 상태를 변경할 수 있으므로, 콜백이 지연되었거나 즉시 확인이 필요한 경우에만 사용하세요.

## 준비 작업

* [Account Token](https://platform.acedata.cloud/documents/platform-token)을 사용하세요.
* [주문 목록](https://platform.acedata.cloud/documents/platform-order-list)에서 본인 주문 ID를 가져오세요.

```shell theme={null}
export PLATFORM_TOKEN='귀하의 계정 토큰'
export ORDER_ID='귀하의 주문 ID'
```

## 인터페이스 개요

| 항목 | 내용 |
| - | - |
| 메서드 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/orders/{order_id}/refresh/` |
| 인증 | 주문 소유자 또는 슈퍼 관리자 |
| Body | 일반적으로 비어 있음; PayPal 콜백 시나리오에서는 `payer_id` / `PayerID`가 필요할 수 있음 |

```shell theme={null}
curl -X POST \
  "https://platform.acedata.cloud/api/v1/orders/${ORDER_ID}/refresh/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

성공 시 새로고침된 전체 Order 객체를 반환합니다. `state`를 사용하여 결과를 판단하고, `finished_at`을 완료 시간으로 사용하세요. 현재 모델에는 `paid_at` 필드가 없습니다. 상태 값에는 `Pending`, `Paid`, `Finished`, `Expired`, `Failed`, `Refunded`가 포함됩니다.

결제 마감 시간은 여전히 `Pending` 상태인 주문만 `Expired`로 변경합니다. 환불된 `Refunded` 주문은 새로고침하거나 지연된 결제 콜백을 받은 후에도 환불 상태를 유지합니다.

## 재시도 권장 사항

* 정상 결제는 우선 플랫폼 콜백에 의존하세요. 상태가 오랫동안 업데이트되지 않을 때만 능동적으로 refresh하세요.
* 고정된 고빈도 폴링을 하지 마세요. 지수 백오프를 권장하며, 명확한 최종 상태에 도달하면 중지하세요.
* `401`은 토큰이 유효하지 않음을 의미하고, `403`은 주문 소유자가 아님을 의미하며, `404`는 주문이 존재하지 않음을 의미합니다.
* 결제 서비스 조회에 실패한 경우 주문 ID와 trace ID를 보존하고 나중에 재시도하세요. 상태 확인을 대신하기 위해 중복 주문을 생성하지 마세요.

## 관련 인터페이스

* [주문 상세 정보 가져오기](https://platform.acedata.cloud/documents/platform-order-detail)
* [주문 결제](https://platform.acedata.cloud/documents/platform-order-pay)
* [주문 목록 가져오기](https://platform.acedata.cloud/documents/platform-order-list)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.