---
# API: Planned Order (A2X)
# File: API_PLANNED_ORDERS.md
# Version: 1.0.0
# Status: ACTIVE
# Protocol: OData V2
# Source URL: https://api.sap.com/api/API_PLANNED_ORDERS/overview
# Generated: 2026-07-23 14:17:02
---

# Planned Order / 计划订单 API

> **API 版本:** 1.0.0 | **状态:** ACTIVE | **协议:** OData V2  
> **技术名称:** `API_PLANNED_ORDERS`  
> **服务根路径:** `/sap/opu/odata/sap/API_PLANNED_ORDERS`  
> **SAP 通信场景:** `SAP_COM_0010`

## 概述 / Overview

该服务支持对计划订单主数据进行创建、读取、更新和删除（CRUD）操作，包括计划订单及其组件。

This synchronous inbound OData V2 service enables CRUD operations on planned order master data, including planned orders and their components.

**API 业务加速器中心:** [https://api.sap.com/api/API_PLANNED_ORDERS/overview](https://api.sap.com/api/API_PLANNED_ORDERS/overview)

---

## 实体列表 / Entity List

| # | 实体名称 | 描述 (EN) | 描述 (CN) | 主键 |
|---|----------|-----------|-----------|------|
| 1 | `A_PlannedOrder` | Planned Order | 计划订单 | `PlannedOrder` |
| 2 | `A_PlannedOrderComponent` | Planned Order Component | 计划订单组件 | `PlannedOrder`, `Component` |

---

## 1. A_PlannedOrder — 计划订单

**实体集合路径:** `A_PlannedOrder`  
**主键 (Key):** `PlannedOrder` (String 12)  
**ETag:** 支持 (`LastChangeDate` 字段)

### 字段列表 / Field List

| 字段名 | 类型 | 长度 | 描述 (EN) | 描述 (CN) |
|--------|------|------|-----------|-----------|
| `PlannedOrder` | String | 12 | Planned Order Number | 计划订单编号 (主键) |
| `Material` | String | 40 | Material Number | 物料编号 |
| `Plant` | String | 4 | Plant | 工厂 |
| `PlanningPlant` | String | 4 | Planning Plant | 计划工厂 |
| `MRPArea` | String | 10 | MRP Area | MRP 区域 |
| `TotalQuantity` | Decimal | 15 | Total Order Quantity | 订单总数量 |
| `QuantityUnit` | String | 3 | Base Unit of Measure | 基本计量单位 |
| `PlanOrderType` | String | 4 | Order Type | 计划订单类型 |
| `ProductionVersion` | String | 4 | Production Version | 生产版本 |
| `ProductionPlant` | String | 4 | Production Plant | 生产工厂 |
| `ProcurementType` | String | 2 | Procurement Type (E=In-house, F=External, X=Both) | 采购类型 |
| `LotSize` | Decimal | 15 | Lot Size Quantity | 批量数量 |
| `FixedLotSize` | Decimal | 15 | Fixed Lot Size | 固定批量 |
| `BasicFinishDate` | DateTime | - | Basic Finish Date | 基本完成日期 |
| `BasicFinishTime` | Time | - | Basic Finish Time | 基本完成时间 |
| `OrderStartDate` | DateTime | - | Order Start Date | 订单开始日期 |
| `OrderStartTime` | Time | - | Order Start Time | 订单开始时间 |
| `AvailabilityCheck` | String | 2 | Availability Check Rule | 可用性检查规则 |
| `StorageLocation` | String | 4 | Storage Location | 存储地点 |
| `ProfitCenter` | String | 10 | Profit Center | 利润中心 |
| `Reservation` | String | 10 | Reservation Number | 预留编号 |
| `MRPController` | String | 3 | MRP Controller | MRP 控制者 |
| `MaterialProcurementGroup` | String | 4 | Material Procurement Group | 物料采购组 |
| `CreationDate` | DateTime | - | Created On | 创建日期 |
| `LastChangeDate` | DateTime | - | Last Changed On | 最后更改日期 |
| `CreatedByUser` | String | 12 | Created By | 创建人 |
| `LastChangedByUser` | String | 12 | Last Changed By | 最后更改人 |
| `GoodsReceiptDate` | DateTime | - | Goods Receipt Date | 收货日期 |
| `GoodsReceiptTime` | Time | - | Goods Receipt Time | 收货时间 |
| `ProductionStartDate` | DateTime | - | Production Start Date | 生产开始日期 |
| `ProductionStartTime` | Time | - | Production Start Time | 生产开始时间 |
| `ProductionEndDate` | DateTime | - | Production End Date | 生产结束日期 |
| `ProductionEndTime` | Time | - | Production End Time | 生产结束时间 |
| `ConversionDate` | DateTime | - | Conversion Date | 转换日期 |
| `ConversionTime` | Time | - | Conversion Time | 转换时间 |
| `ConversionStatus` | String | 1 | Conversion Status (1=Not Conv., 2=Partially, 3=Fully) | 转换状态 |
| `FirmIndicator` | String | 1 | Firm Indicator | 固化标识 |
| `FirmDate` | DateTime | - | Firm Date | 固化日期 |
| `FirmTime` | Time | - | Firm Time | 固化时间 |
| `DeletionFlag` | Boolean | - | Deletion Flag | 删除标识 |
| `MRPRelevance` | String | 1 | MRP Relevance | MRP 相关性 |
| `SchedulingStartDate` | DateTime | - | Scheduling Start Date | 排程开始日期 |
| `SchedulingStartTime` | Time | - | Scheduling Start Time | 排程开始时间 |
| `SchedulingEndDate` | DateTime | - | Scheduling End Date | 排程结束日期 |
| `SchedulingEndTime` | Time | - | Scheduling End Time | 排程结束时间 |
| `FirmedQuantity` | Decimal | 15 | Firmed Quantity | 固化数量 |
| `FirmedQuantityUnit` | String | 3 | Unit for Firmed Qty | 固化数量单位 |
| `ComponentAvailabilityDate` | DateTime | - | Comp. Avail. Date | 组件可用日期 |
| `ComponentAvailabilityTime` | Time | - | Comp. Avail. Time | 组件可用时间 |
| `ExplosionDate` | DateTime | - | BOM Explosion Date | BOM 展开日期 |
| `CostEstimationDate` | DateTime | - | Costing Date | 成本核算日期 |
| `CostEstimationTime` | Time | - | Costing Time | 成本核算时间 |
| `PlannedOrderText` | String | 40 | Order Text | 订单文本 |

### 导航属性 / Navigation Properties

| 属性名 | 目标实体 | 基数 | 描述 |
|--------|----------|------|------|
| `to_PlannedOrderComponent` | A_PlannedOrderComponent | 0..* | 计划订单组件 |
| `to_PlannedOrderCapacity` | A_PlannedOrderCapacity | 0..* | 计划订单产能 |

---

## 2. A_PlannedOrderComponent — 计划订单组件

**实体集合路径:** `A_PlannedOrderComponent`  
**主键 (Key):** `PlannedOrder` (String 12), `Component` (String 4)

### 字段列表 / Field List

| 字段名 | 类型 | 长度 | 描述 (EN) | 描述 (CN) |
|--------|------|------|-----------|-----------|
| `PlannedOrder` | String | 12 | Planned Order Number | 计划订单编号 (主键) |
| `Component` | String | 4 | Component Item Number | 组件项目号 (主键) |
| `ComponentDescription` | String | 40 | Component Description | 组件描述 |
| `ComponentQuantity` | Decimal | 15 | Component Quantity | 组件数量 |
| `WithdrawalQuantity` | Decimal | 15 | Withdrawal Quantity | 已提库数量 |
| `BaseUnit` | String | 3 | Base Unit of Measure | 基本计量单位 |
| `RequirementDate` | DateTime | - | Requirement Date | 需求日期 |
| `ComponentPlant` | String | 4 | Component Plant | 组件工厂 |
| `StorageLocation` | String | 4 | Storage Location | 存储地点 |
| `Batch` | String | 10 | Batch Number | 批次号 |
| `Material` | String | 40 | Material Number | 物料编号 |
| `MaterialDescription` | String | 40 | Material Description | 物料描述 |
| `ComponentScrap` | Decimal | 5 | Component Scrap (%) | 组件废品率 |
| `SortOrder` | String | 10 | Sort String | 排序字符串 |
| `ReservationNumber` | String | 10 | Reservation Number | 预留编号 |
| `ReservationItem` | String | 4 | Reservation Item | 预留项目号 |
| `IsAlternativeComponent` | Boolean | - | Alternative Component | 替代组件标识 |
| `AlternativeComponentGroup` | String | 4 | Alt. Component Group | 替代组件组 |
| `ComponentPriority` | String | 1 | Component Priority | 组件优先级 |
| `ComponentUsage` | String | 1 | Component Usage | 组件用途 |
| `MRPRelevance` | String | 1 | MRP Relevance | MRP 相关性 |
| `FixedQuantity` | Boolean | - | Fixed Quantity | 固定数量标识 |
| `CostRelevance` | String | 1 | Cost Relevance | 成本相关性 |
| `GoodsMovementAllowed` | Boolean | - | Goods Movement Allowed | 允许货物移动 |
| `Backflush` | Boolean | - | Backflush | 反冲标识 |
| `ChangedBy` | String | 12 | Changed By | 更改人 |
| `LastChangeDate` | DateTime | - | Last Changed On | 最后更改日期 |
| `CreationDate` | DateTime | - | Created On | 创建日期 |

### 导航属性 / Navigation Properties

| 属性名 | 目标实体 | 基数 | 描述 |
|--------|----------|------|------|
| `to_PlannedOrder` | A_PlannedOrder | 0..1 | 计划订单抬头 |

---

## CRUD 端点 / CRUD Endpoints

所有实体的 CRUD 端点遵循 OData V2 约定。以下以 `A_PlannedOrder` 为例：

### 创建 (Create) — POST

```
POST /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder
Content-Type: application/json
```

### 读取 (Read) — GET

```
GET /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder(PlannedOrder='12345')
GET /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder?$filter=...&$expand=...
```

### 更新 (Update) — PATCH

```
PATCH /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder(PlannedOrder='12345')
Content-Type: application/json
```

### 替换 (Replace) — PUT

```
PUT /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder(PlannedOrder='12345')
Content-Type: application/json
```

### 删除 (Delete) — DELETE

```
DELETE /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder(PlannedOrder='12345')
```

### 各实体端点路径速查表

| 实体 | 端点路径 |
|------|---------|
| A_PlannedOrder | `A_PlannedOrder` |
| A_PlannedOrderComponent | `A_PlannedOrderComponent` |

---

## 深插入 (Deep Insert)

API_PLANNED_ORDERS 支持通过单次 POST 携带导航属性创建计划订单及其组件。

### 深插入示例: 创建计划订单 + 组件

```json
POST /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder
Content-Type: application/json

{
  "Material": "MAT-001",
  "Plant": "PLNT",
  "TotalQuantity": 100,
  "QuantityUnit": "PC",
  "BasicFinishDate": "2026-08-01",
  "OrderStartDate": "2026-07-15",
  "ProcurementType": "E",
  "to_PlannedOrderComponent": [
    {
      "Component": "0001",
      "Material": "COMP-A",
      "ComponentQuantity": 200,
      "BaseUnit": "PC",
      "RequirementDate": "2026-07-10"
    },
    {
      "Component": "0002",
      "Material": "COMP-B",
      "ComponentQuantity": 150,
      "BaseUnit": "PC",
      "RequirementDate": "2026-07-12"
    }
  ]
}
```

### 深插入支持的关系

| 导航属性 | 目标实体 | 说明 |
|----------|----------|------|
| `to_PlannedOrderComponent` | A_PlannedOrderComponent | 计划订单组件 |

---

## 导航属性关系总表 / Navigation Property Matrix

| 源实体 | 导航属性 | 目标实体 | 基数 |
|--------|----------|----------|------|
| A_PlannedOrder | `to_PlannedOrderComponent` | A_PlannedOrderComponent | 0..* |
| A_PlannedOrder | `to_PlannedOrderCapacity` | A_PlannedOrderCapacity | 0..* |
| A_PlannedOrderComponent | `to_PlannedOrder` | A_PlannedOrder | 0..1 |

---

## OData 查询选项 / Query Options

| 参数 | 示例 | 说明 |
|------|------|------|
| `$filter` | `$filter=Material eq 'MAT-001'` | 过滤 |
| `$select` | `$select=PlannedOrder,Material,TotalQuantity` | 选择字段 |
| `$expand` | `$expand=to_PlannedOrderComponent` | 展开导航属性 |
| `$top` | `$top=100` | 返回前 N 条 |
| `$skip` | `$skip=50` | 跳过前 N 条 |
| `$orderby` | `$orderby=PlannedOrder desc` | 排序 |
| `$count` | `$count=true` | 返回计数 |
| `$inlinecount` | `$inlinecount=allpages` | 内联计数 (OData V2) |

### $expand 示例

```http
GET /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder('12345')?$expand=to_PlannedOrderComponent
```

---

## ETag 处理 / ETag Handling

API_PLANNED_ORDERS 通过 ETag 支持乐观锁并发控制。

### 读取时获取 ETag

```
GET /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder('12345')
```

响应头将包含 `ETag: W/"datetime'2026-07-23T14%3A17%3A02'"`。

### 更新时携带 ETag (If-Match)

```
PATCH /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder('12345')
If-Match: W/"datetime'2026-07-23T14%3A17%3A02'"
Content-Type: application/json

{ "TotalQuantity": 150 }
```

### 强制更新 (忽略 ETag)

```
PATCH /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder('12345')
If-Match: *
Content-Type: application/json

{ "TotalQuantity": 150 }
```

---

## 批处理 / Batch Processing

批处理通过在单个 HTTP 请求中组合多个 CRUD 操作，减少网络开销。

### 批处理端点

```
POST /sap/opu/odata/sap/API_PLANNED_ORDERS/$batch
Content-Type: multipart/mixed; boundary=batch_123
```

### 批处理示例 (创建 + 读取 + 更新)

```http
--batch_123
Content-Type: application/http
Content-Transfer-Encoding: binary

POST A_PlannedOrder HTTP/1.1
Content-Type: application/json

{ "Material": "MAT-001", "Plant": "PLNT", "TotalQuantity": 100 }

--batch_123
Content-Type: application/http
Content-Transfer-Encoding: binary

GET A_PlannedOrder('12345')?$select=PlannedOrder,Material,TotalQuantity HTTP/1.1

--batch_123
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH A_PlannedOrder('12345') HTTP/1.1
If-Match: *
Content-Type: application/json

{ "TotalQuantity": 150 }

--batch_123--
```

---

## 认证 / Authentication

### OAuth 2.0 (推荐)

```
Authorization: Bearer <access_token>
Content-Type: application/json
```

SAP S/4HANA Cloud 通常使用 OAuth 2.0 客户端凭证流。

### 基本认证 (Basic Auth)

```
Authorization: Basic <base64(username:password)>
```

用于 Service User / Communication User 场景。

### CSRF Token 处理

SAP 要求写操作必须携带有效的 CSRF Token：

```http
# 步骤 1: 获取 CSRF Token
GET /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder
X-CSRF-Token: Fetch

# 响应: X-CSRF-Token: <token_value>

# 步骤 2: 使用 Token 执行写操作
POST /sap/opu/odata/sap/API_PLANNED_ORDERS/A_PlannedOrder
X-CSRF-Token: <token_value>
Content-Type: application/json
Cookie: SAP-SESSIONID=<session_id>
```

---

## 错误码 / Error Codes

| HTTP 状态码 | 描述 (EN) | 描述 (CN) |
|-------------|-----------|-----------|
| 200 | OK | 请求成功 |
| 201 | Created | 创建成功 |
| 204 | No Content | 无返回内容 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未授权 |
| 403 | Forbidden | 禁止访问 |
| 404 | Not Found | 资源不存在 |
| 405 | Method Not Allowed | 方法不允许 |
| 412 | Precondition Failed | ETag 不匹配 |
| 500 | Internal Server Error | 服务器内部错误 |

---

## 可扩展性 / Extensibility

通过 SAP Fiori "Custom Fields and Logic" 应用添加自定义字段：

| 实体 | 业务上下文 |
|------|-----------|
| A_PlannedOrder | Planned Order Core View |
| A_PlannedOrderComponent | Planned Order Component Core View |

自定义字段以 `YY1_<FieldName>_<Context>` 格式返回。

---

## 服务限制 / Constraints

通过此 API **无法** 执行以下操作：

1. 修改已转换的订单
2. 删除已部分收货的计划订单
3. 更改已固化计划订单的某些关键字段

---

## 相关资源 / References

| 资源 | 链接 |
|------|------|
| SAP API Business Hub | [https://api.sap.com/api/API_PLANNED_ORDERS/overview](https://api.sap.com/api/API_PLANNED_ORDERS/overview) |
| SAP Help Portal | [https://help.sap.com/docs/SAP_S4HANA_CLOUD](https://help.sap.com/docs/SAP_S4HANA_CLOUD) |