来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 [important] Implement PENDING as a new order status in Open API
Dear Developers,
In order to optimize the user experience and solve the pain point of some orders, although with the order status "READY_TO_SHIP" but cannot be shipped by calling ship_order API, we have introduced a new order status--"PENDING".
The specific updates are as follows:
1.The order_status flow:
1.1 Old flow:
UNPAID -> (Original)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
1.2 New flow:
UNPAID -> (New)PENDING-> (Updated)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
2.Scenarios that trigger PENDING status:
| No | Order Pending Scenarios | Description | Action can take while pending |
|---|---|---|---|
| 1 | 3PL allocating | It’s a 3PL masking order and at this point, the order has not matched with a suitable fulfillment channel | Wait until the order got shipping_carrier from v2.order.get_order_detail |
| 2 | Fraud check | The order is being detected for fraud by Shopee | Wait until the system finished the fraud check, will take up to 4 hours |
| 3 | TW CB KYC Pre-authorisation | The order needs buyer to do the TW Pre-authorisation only apply for Taiwan cross -border orders | Remind buyers to complete Pre-authorisation |
3.The specific updates for Open APIs:
3.1.1 For v2.order.get_order_detail and v2.order.get_order_list add a new compatible field"request_order_status_pending" for request parameter.
| No | Scenarios | order_status enum value |
|---|---|---|
| 1 | request_order_status_pending send as truee | UNPAID (New)PEDNING READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
| 2 | request_order_status_pending send as false or not send | UNPAID READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
3.1.2.The deprecation plan of the field "request_order_status_pending"
| Phase | Time | Performance |
|---|---|---|
| 1 | June 15 - Sep 15 | Decide whether to return an order in pending status by passing in the value of the compatible field request_order_status_pending |
| 2 | Sep 16 and after | the compatible field request_order_status_pending will be deprecated and removed, directly follow the new order_status logic |
3.2.for v2.order.get_order_detail add a new response field "pending_terms" to indicate which type the current pending belongs to.
| No | "pending_term" enum value | Order Pending Scenarios |
|---|---|---|
| 1 | SYSTEM_PENDING | 1.3PL allocating 2.Fraud check |
| 2 | KYC_PENDING | TW CB KYC Pre-authorisation |
Sample1: pending_terms= SYSTEM_PENDING，the response from
v2.order.get_order_detail：
{
"error":"",
"message":"",
"request_id":"dbb07ea9fea183f413ebacb9bf13de20",
"response":{
"order_list":[
{
…………
"order_sn":"230605JQD3HUHJ",
"order_status":"PENDING",
"pending_terms":[
"SYSTEM_PENDING"
],
"region":"ID",
"reverse_shipping_fee":0,
"ship_by_date":0,
"update_time":1685944418
}
]
}
Sample2: pending_terms=KYC_PENDING，the response from v2.order.get_order_detail:
{
"error": "",
"message": "",
"request_id": "6d80e40c11f8f854b6687b3996b27c20",
"response": {
"order_list": [
{
…………
"order_sn": "230606MU6CG0QU",
"order_status": "PENDING",
"pending_terms":[
"KYC_PENDING"
],
"region":"TW",
"shipping_carrier": "蝦皮海外 - OK MART（海運）",
"update_time": 1686017238
}
]
}
Related APIs:
v2.order.get_order_detail
v2.order.get_order_list
4.FAQs
Q1. How does order_status_push behave now?
A: There will be no push message when the order status is updated to pending, regardless of whether the API request has switched to the new logic.
We're planning to support pushing the push message when the order status is updated to pending, and the specific online time will be subject to the subsequent platform announcement time.
Q2. Can both SYSTEM_PENDING and KYC_PENDING be returned in the "pending_terms" field?
A: No, only one of the two pending types will appear in one order at the same time.
Effective Date on Live: Lived
尊敬的开发者，
您好，为优化用户体验，解决部分状态为"READY_TO_SHIP"的订单，调用发货接口无法发货的问题，引入了新的订单状态---"PENDING"。
具体更新如下：
1.订单状态流转
1.1 Old flow:
UNPAID -> (Original)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
1.2 New flow:
UNPAID -> (New)PENDING-> (Updated)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
2.触发订单状态为PENDING的场景：
| No | 场景 | 描述 | 可采取的行动 |
|---|---|---|---|
| 3PL allocating | 属于3PL masking 订单，该订单未匹配到履约渠道 | 等待 直到调用v2.order.get_order_detail,shipping_carrier字段有值 | |
| Fraud check | 订单正在进行欺诈检测 | 等待 最长4小时 | |
| TW CB KYC Pre-authorisation | 订单需要买家进行预先委任 仅适用于台湾的跨境订单 | 提醒买家尽快完成预先委任 |
3.Open API接口更新：
3.1.对 v2.order.get_order_detail 和 v2.order.get_order_list 请求参数新增兼容性字段"request_order_status_pending".
| No | 场景 | order_status枚举值 |
|---|---|---|
| 1 | request_order_status_pending 传为true | UNPAID (新增)PEDNING READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
| 2 | request_order_status_pending 传为false或不传该字段 | UNPAID READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
3.1.2.兼容性字段request_order_status_pending下线计划
| 阶段 | 时间 | 表现 |
|---|---|---|
| 1 | 6月 15日 - 9月 15日 | 通过传入兼容字段request_order_status_pending的值来决定是否返回处于pending状态的订单 |
| 2 | 9月16日及以后 | 兼容字段request_order_status_pending将被废弃并删除，无论是否传入该字段，都遵循新的order_status flow |
3.2.对 v2.order.get_order_detail 新增响应字段 "pending_terms" 用于说明当前pending所属的类型，具体如下：
| No | pending_terms 枚举值 | 订单Pending 场景 |
|---|---|---|
| 1 | SYSTEM_PENDING | 1.3PL allocating 2.Fraud check |
| 2 | KYC_PENDING | TW CB KYC Pre-authorisation |
Sample1: pending_terms为SYSTEM_PENDING，v2.order.get_order_detail接口响应：
{
"error":"",
"message":"",
"request_id":"dbb07ea9fea183f413ebacb9bf13de20",
"response":{
"order_list":[
{
…………
"order_sn":"230605JQD3HUHJ",
"order_status":"PENDING",
"pending_terms":[
"SYSTEM_PENDING"
],
"region":"ID",
"reverse_shipping_fee":0,
"ship_by_date":0,
"update_time":1685944418
}
]
}
Sample2: pending_terms为KYC_PENDING，v2.order.get_order_detail接口响应：
{
"error": "",
"message": "",
"request_id": "6d80e40c11f8f854b6687b3996b27c20",
"response": {
"order_list": [
{
…………
"order_sn": "230606MU6CG0QU",
"order_status": "PENDING",
"pending_terms":[
"KYC_PENDING"
],
"region":"TW",
"shipping_carrier": "蝦皮海外 - OK MART（海運）",
"update_time": 1686017238
}
]
}
影响接口:
v2.order.get_order_detail
v2.order.get_order_list
4.FAQs
Q1.order_status_push的表现是？
A: 当订单状态更新为PENDING时不会有push消息的推送。
平台有计划支持当订单状态更新为pending时推送push消息，具体上线时间以后续平台公告时间为准。
Q2.SYSTEM_PENDING和KYC_PENDING 可同时在"pending_terms" 字段返回吗？
A: 不可以,目前一个订单如果处于pending状态，则一定是两种pending 类型的其中之一。
上线时间：已上线
Olá desenvolvedores,
Com o propósito de melhorar a experiência e resolver alguns problemas relacionados ao status da order “READY_TO_SHIP” e mesmo assim não sendo possível que a order fosse organizada ao chamar a API ship_order, criamos um novo status de order “PENDING”.
Seguem fluxos afetados:
1.Fluxo de status das orders:
1.1 Fluxo antigo:
UNPAID -> (Antigo)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
1.2 Novo Fluxos:
UNPAID -> (Novo)PENDING -> (Atualizado)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
- Cenários que passariam pelo novo status PENDING:
| No | Possíveis Cenários | Descrição | Ações que podem ser tomadas enquanto no status PENDING |
|---|---|---|---|
| Alocação do Parceiro Logístico(não se aplica ao BR) | Pedido ainda sem um fulfillment channel correto | Esperar até o retorno do shipping_carrier pela API v2.order.get_order_detail | |
| Fraud check | A order está sendo verificada por possível FRAUD. | Esperar até o sistema de validação terminar, que pode demorar no máximo 4 horas. | |
| TW CB KYC Pre-authorisation(não se aplica ao BR) | O pedido precisa do vendedor para realizar o TW Pre-authorisation Só se aplica para Taiwan CrossBorder | Avisar o Buyer para completar a Pre-authorisation |
- Atualizações nas APIs:
3.1.1 Para API v2.order.get_order_detail e v2.order.get_order_list foi adicionado um novo parâmetro "request_order_status_pending" para ser usado durante o processo de migração apenas nas chamadas de request,
| No | Cenários | order_status enum value |
|---|---|---|
| 1 | request_order_status_pending enviado como “true” | UNPAID (New)PEDNING READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
| 2 | request_order_status_pending enviado como “false” ou não enviado | UNPAID READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
3.1.2. Plano de depreciação do parâmetro "request_order_status_pending"
| Phase | Data | Performance |
|---|---|---|
| 1 | 15 de Junho - 15 de Setembro | Será possível escolher se quer filtrar por esse novo status usando o parâmetro request_order_status_pending |
| 2 | 16 de Setembro em diante | O parâmetro request_order_status_pending será removido e o novo status seguirá estará disponível como os outros |
3.2. Para API v2.order.get_order_detail será adicionada um novo response “pending_terms” para indicar a que tipo de pendência se refere.
| No | pending_terms enum value | Order Pending Scenarios |
|---|---|---|
| 1 | SYSTEM_PENDING | 1.3PL allocating 2.Fraud check |
| 2 | KYC_PENDING | TW CB KYC Pre-authorisation |
Exemplo 1: pending_terms= SYSTEM_PENDING，response da API
v2.order.get_order_detail：
{
"error":"",
"message":"",
"request_id":"dbb07ea9fea183f413ebacb9bf13de20",
"response":{
"order_list":[
{
…………
"order_sn":"230605JQD3HUHJ",
"order_status":"PENDING",
"pending_terms":[
"SYSTEM_PENDING"
],
"region":"ID",
"reverse_shipping_fee":0,
"ship_by_date":0,
"update_time":1685944418
}
]
}
Examplo 2: pending_terms=KYC_PENDING，response da API v2.order.get_order_detail:
{
"error": "",
"message": "",
"request_id": "6d80e40c11f8f854b6687b3996b27c20",
"response": {
"order_list": [
{
…………
"order_sn": "230606MU6CG0QU",
"order_status": "PENDING",
"pending_terms":[
"KYC_PENDING"
],
"region":"TW",
"shipping_carrier": "蝦皮海外 - OK MART（海運）",
"update_time": 1686017238 }
]
}
APIs afetadas:
v2.order.get_order_detail
v2.order.get_order_list
4.FAQs
Q1. Como o order_status_push vai se comportar?
A: Não haverá nenhuma Push Message quando a order mudar para o status de PENDING. Mas planejamos realizar esse ajuste no futuro, assim que tivermos detalhes vocês serão informados.
Q2. Tanto o SYSTEM_PENDING quanto o KYC_PENDING poderão ser retornados no parâmetro "pending_terms" ?
A: Não, apenas um dos dois tupos irá aparecer para cada order.Quando estará em
LIVE: Já disponíveis no ambiente LIVE.
사용자 경험을 최적화하고 일부 오더 관련 문제를 해결하기 위해, "READY_TO_SHIP" 상태이지만 ship_order API를 호출하여 발송할 수 없는 주문건에 대해 "PENDING"이라는 새로운 주문 상태값이 추가되었습니다.
구체적인 업데이트는 다음과 같습니다:
- order_status 흐름
1.1 Old flow:
UNPAID -> (Original)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
1.2 New flow:
UNPAID -> (New)PENDING-> (Updated)READY_TO_SHIP -> PROCESSED -> SHIPPED->TO CONFIRM RECEIVE -> COMPLETED
- PENDING 상태를 유발하는 시나리오
| No | 주문 PENDING 시나리오 | 설명 | PENDING 상태에서 취할 수 있는 액션 |
|---|---|---|---|
| 1 | 3PL 할당 | 3PL 마스킹 주문건이며 아직 적합한 풀필먼트 채널에 매칭이 되지 않은 상태 | v2.order.get_order_detail에서 shipping_carrier를 받을 때까지 대기합니다. |
| 2 | 사기 확인 | Shopee에 의해 주문이 사기 케이스로 감지된 경우 | 시스템이 사기 확인을 완료할 때까지 대기합니다. 최대 4시간 소요될 수 있습니다. |
| 3 | TW CB KYC 사전 승인 | 주문에 대해 구매자가 대만 사전 승인 (TW Pre-authorisation)을 진행해야 합니다.이는 대만 마켓 크로스보더 (CB) 주문건에만 적용됩니다. | 구매자에게 사전 승인을 완료하도록 알립니다. |
- Open API에 대한 구체적인 업데이트:
3.1.1. v2.order.get_order_detail 와 v2.order.get_order_list에 대해, request parameter (요청 매개변수)의 마이그레이션 기간 동안 "request_order_status_pending"이라는 새로운 호환 필드가 추가됩니다.
| No | Scenarios | order_status enum value |
|---|---|---|
| 1 | request_order_status_pending send as true | UNPAID (New)PEDNING READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
| 2 | request_order_status_pending send as false or not send | UNPAID READY_TO_SHIP PROCESSED SHIPPED TO CONFIRM RECEIVE COMPLETED IN_CANCEL CANCELLED TO_RETURN |
3.1.2. "request_order_status_pending" 필드의 사용 중지 계획:
| Phase | Time | Performance |
|---|---|---|
| 1 | 6월 15일 - 9월 15일 | 호환 필드 "request_order_status_pending"의 값을 전달하여 대기 중인 상태의 주문 반환 여부를 결정합니다. |
| 2 | 9월 16일 이후 | 호환 필드 "request_order_status_pending"가 폐기되고 제거되며, 새로운 order_status 로직을 직접 따릅니다. |
3.2. v2.order.get_order_detail에 "pending_terms"라는 새로운 응답 필드를 추가하여 현재 대기 중인 상태가 어떤 유형에 속하는지 나타냅니다.
| No | pending_terms enum value | Order Pending Scenarios |
|---|---|---|
| 1 | SYSTEM_PENDING | 1. 3PL 할당 2. 사기 확인 |
| 2 | KYC_PENDING | TW CB KYC 사전 승인 |
샘플1: pending_terms= SYSTEM_PENDING, v2.order.get_order_detail에서의 응답:{
{
"error":"",
"message":"",
"request_id":"dbb07ea9fea183f413ebacb9bf13de20",
"response":{
"order_list":[
{
…………
"order_sn":"230605JQD3HUHJ",
"order_status":"PENDING",
"pending_terms":[
"SYSTEM_PENDING"
],
"region":"ID",
"reverse_shipping_fee":0,
"ship_by_date":0,
"update_time":1685944418
}
]
}
샘플2: pending_terms=KYC_PENDING, v2.order.get_order_detail에서의 응답:
{
"error": "",
"message": "",
"request_id": "6d80e40c11f8f854b6687b3996b27c20",
"response": {
"order_list": [
{
…………
"order_sn": "230606MU6CG0QU",
"order_status": "PENDING",
"pending_terms":[
"KYC_PENDING"
],
"region":"TW",
"shipping_carrier": "蝦皮海外 - OK MART（海運）",
"update_time": 1686017238
}
]
}
관련 API:
v2.order.get_order_detail
v2.order.get_order_list
4.FAQs
Q1. order_status_push는 현재 어떻게 동작하나요?
A: 현재는 주문 상태가 “pending”으로 업데이트되면 API 요청이 새로운 로직으로 전환되었는지 여부와는 관계없이 더 이상 푸시 메시지가 전송되지 않습니다.하지만 앞으로는 주문 상태가 “pending”으로 업데이트될 때 푸시 메시지를 지원할 계획이며, 구체적인 일정은 이후 오픈 플랫폼 공지로 업데이트 드릴 예정입니다.
Q2. "pending_terms" 필드에 SYSTEM_PENDING과 KYC_PENDING 둘 다 반환될 수 있나요?
A: 아니요, 동일한 주문건 내에서는 한번에 둘 중 하나만 반환됩니다.유효 날짜: Live (현재 시행 중)