# Interface Control Document: [System A] to [System B] [Interface name]

> Interface control document (ICD) that defines and controls one
> interface between two systems or subsystems: the parties, the
> requirements allocated to the interface, its physical and logical
> characteristics, data elements, protocol and sequencing, error handling,
> security, performance, versioning and verification. Both parties sign it
> and change it only through the change control process in section 12.
> Replace every `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- One ICD per interface. If two systems exchange data over several
  unrelated channels, write one ICD per channel or split section 6 clearly.
- The data element table (section 7) is the contract. Every field needs a
  type, units, range or allowed values, precision and frequency; "string"
  alone is not a definition.
- Write requirements as "shall" statements with IDs so the verification
  matrix (section 13) can trace them.
- Do not change the interface without updating this document and getting
  both signatures. An undocumented change is the most common cause of
  integration failure.
-->

## Document control

<!-- Guidance: Identify the ICD, the interface and the controlling authority. Both interface parties own the document jointly. -->

| Field | Value |
|---|---|
| Document ID | [ICD-A-B-001] |
| Interface ID | [IF-ORD-WMS-01] |
| Interface name | [Order fulfilment interface] |
| Version | [0.1] |
| Status | [Draft / In review / Baselined / Superseded] |
| Controlling authority | [Interface control working group / configuration control board] |
| Party A owner | [@owner-a] |
| Party B owner | [@owner-b] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |

### Approvals

| Role | Organisation | Name | Signature / decision | Date |
|---|---|---|---|---|
| Party A system owner | [Organisation A] | [@name] | [Approved] | YYYY-MM-DD |
| Party B system owner | [Organisation B] | [@name] | [Approved] | YYYY-MM-DD |
| Integration lead | [Organisation] | [@name] | [Approved] | YYYY-MM-DD |
| Security officer | [Organisation] | [@name] | [Approved] | YYYY-MM-DD |

## Revision history

<!-- Guidance: Each change references the approved interface change request (ICR) from section 12. -->

| Version | Date | Author | Change request | Change summary |
|---|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | n/a | Initial draft |
| 1.0 | YYYY-MM-DD | [@name] | n/a | *Example:* Baselined after joint review |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* ICR-004 | *Example:* Added optional field `deliveryWindow` |

## Contents

1. [Scope](#1-scope)
2. [Referenced documents](#2-referenced-documents)
3. [Interface identification and parties](#3-interface-identification-and-parties)
4. [Interface overview](#4-interface-overview)
5. [Requirements allocation](#5-requirements-allocation)
6. [Interface characteristics](#6-interface-characteristics)
7. [Message and data element definitions](#7-message-and-data-element-definitions)
8. [Protocol and sequencing](#8-protocol-and-sequencing)
9. [Error handling and recovery](#9-error-handling-and-recovery)
10. [Security](#10-security)
11. [Performance and timing](#11-performance-and-timing)
12. [Versioning and change control](#12-versioning-and-change-control)
13. [Verification and test](#13-verification-and-test)
14. [Signatories](#14-signatories)
15. [Glossary](#15-glossary)

## 1. Scope

<!-- Guidance: Say what this ICD controls and what it does not, in two or three sentences. -->

This ICD defines the interface through which [System A, for example the
Order Management System] sends fulfilment orders to [System B, for example
the Warehouse Management System] and receives shipment status updates. It
controls message content, transport, sequencing, error handling, security
and performance. It does not cover [internal processing in either system,
the user interfaces, or batch reconciliation reports].

## 2. Referenced documents

<!-- Guidance: List every document whose content is relied on: specifications of both systems, standards, security policies. Note the exact version. -->

| ID | Document | Version | Relevance |
|---|---|---|---|
| REF-01 | [System A requirements specification] | [x.y] | Source of interface requirements |
| REF-02 | [System B interface specification] | [x.y] | Endpoint behaviour |
| REF-03 | [Enterprise integration standard] | [x.y] | Transport and naming rules |
| REF-04 | RFC 8259 (JSON) and ISO 8601 (dates and times) | n/a | Data formats |

## 3. Interface identification and parties

<!-- Guidance: Identify each party, its role in the interface, and the contacts responsible for operations and changes. -->

| Item | Party A | Party B |
|---|---|---|
| System name | [Order Management System (OMS)] | [Warehouse Management System (WMS)] |
| Organisation / team | [Commerce platform team] | [Logistics IT] |
| Role | Producer of orders, consumer of status | Consumer of orders, producer of status |
| Technical contact | [@name, email] | [@name, email] |
| Operations contact (24/7) | [On-call rotation] | [On-call rotation] |
| Environments | [Test, staging, production] | [Test, staging, production] |

Interface type: [system to system, real-time messaging]. Criticality:
[High: orders not fulfilled if the interface fails].

## 4. Interface overview

<!-- Guidance: One diagram and a short description of what flows in which direction. -->

The diagram shows the two parties, the channels and the direction of each
message flow.

```mermaid
flowchart LR
  subgraph A [Party A: OMS]
    pub[Order publisher]
    sub[Status consumer]
  end
  subgraph B [Party B: WMS]
    rcv[Order receiver]
    stat[Status publisher]
  end
  pub -->|M-01 FulfilmentOrder| q1[[Queue orders.fulfilment]]
  q1 --> rcv
  rcv -->|M-02 OrderAck| q2[[Queue orders.ack]]
  stat -->|M-03 ShipmentStatus| q3[[Queue orders.status]]
  q2 --> sub
  q3 --> sub
```

| Message ID | Name | Direction | Trigger |
|---|---|---|---|
| M-01 | FulfilmentOrder | A to B | Order paid in OMS |
| M-02 | OrderAck | B to A | Order received and validated by WMS |
| M-03 | ShipmentStatus | B to A | Status change in WMS (picked, packed, shipped, cancelled) |

## 5. Requirements allocation

<!-- Guidance: List the requirements the interface must satisfy, each allocated to Party A, Party B or both, with a verification method. -->

| ID | Requirement | Allocated to | Source | Verification |
|---|---|---|---|---|
| ICD-REQ-001 | Party A shall publish M-01 within 5 s of an order reaching status Paid | A | REF-01 SRS-FR-031 | Test |
| ICD-REQ-002 | Party B shall acknowledge each M-01 with M-02 within 30 s | B | REF-02 | Test |
| ICD-REQ-003 | Both parties shall reject messages that fail schema validation and log the rejection | A, B | REF-03 | Test, inspection |
| ICD-REQ-004 | Party B shall process M-01 idempotently using `orderId` and `messageId` | B | This ICD | Test |
| ICD-REQ-005 | Messages shall not contain payment card data | A, B | Security policy | Inspection |
| [ICD-REQ-nnn] | [Requirement] | [A / B / A, B] | [Source] | [Test / Inspection / Analysis / Demonstration] |

## 6. Interface characteristics

<!-- Guidance: Physical characteristics describe connectivity and transport; logical characteristics describe message format, encoding and semantics. -->

### 6.1 Physical characteristics

| Characteristic | Value |
|---|---|
| Transport | [AMQP 1.0 over TLS 1.3 to managed message broker] |
| Network path | [Private link between VPC A and broker; WMS connects via site-to-site VPN] |
| Endpoints | [Broker host per environment, port 5671] |
| Availability window | [24/7; WMS maintenance Sundays 02:00 to 03:00 UTC] |
| Message size limit | [256 KB] |

### 6.2 Logical characteristics

| Characteristic | Value |
|---|---|
| Message format | [JSON, UTF-8, validated against JSON Schema draft 2020-12] |
| Schema location | [Repository path or registry URL] |
| Character set | [UTF-8; no byte order mark] |
| Date and time | [ISO 8601 in UTC with `Z` suffix] |
| Delivery semantics | [At least once; ordering per `orderId` guaranteed by partition key] |
| Headers | [`messageId` (UUID v4), `messageType`, `schemaVersion`, `correlationId`, `sentAt`] |

## 7. Message and data element definitions

<!-- Guidance: Define every data element of every message. Units, range and precision are where integrations fail; leave none blank. Use "n/a" only when truly not applicable. -->

### 7.1 M-01 FulfilmentOrder

| Element | Type | Units | Range / allowed values | Precision | Mandatory | Frequency | Description |
|---|---|---|---|---|---|---|---|
| `orderId` | String | n/a | Pattern `ORD-[0-9]{10}` | n/a | Yes | Once per message | Unique order identifier, assigned by OMS |
| `orderDate` | Date-time | UTC | Not in the future | 1 s | Yes | Once | Time the order was paid |
| `warehouseCode` | String | n/a | `DE01`, `DE02`, `NL01` | n/a | Yes | Once | Fulfilling warehouse |
| `lines[].sku` | String | n/a | 8 to 14 alphanumeric characters | n/a | Yes | 1 to 200 per order | Stock keeping unit |
| `lines[].quantity` | Integer | Pieces | 1 to 999 | 1 | Yes | Per line | Quantity to ship |
| `lines[].weight` | Decimal | kg | 0.001 to 1000.000 | 0.001 kg | No | Per line | Unit gross weight |
| `shipTo.countryCode` | String | n/a | ISO 3166-1 alpha-2 | n/a | Yes | Once | Destination country |
| `deliveryWindow.start` | Date-time | UTC | After `orderDate` | 1 min | No | Once | Earliest delivery time |
| [element] | [Type] | [Units] | [Range] | [Precision] | [Yes / No] | [Frequency] | [Description] |

Example message:

```json
{
  "orderId": "ORD-0000123456",
  "orderDate": "2026-03-14T09:26:53Z",
  "warehouseCode": "DE01",
  "lines": [{"sku": "SKU12345678", "quantity": 2, "weight": 0.450}],
  "shipTo": {"countryCode": "DE"}
}
```

### 7.2 M-02 OrderAck

| Element | Type | Units | Range / allowed values | Precision | Mandatory | Frequency | Description |
|---|---|---|---|---|---|---|---|
| `orderId` | String | n/a | As M-01 | n/a | Yes | Once | Order acknowledged |
| `result` | Enum | n/a | `ACCEPTED`, `REJECTED` | n/a | Yes | Once | Validation outcome |
| `reasonCode` | String | n/a | Codes in section 9.2 | n/a | If REJECTED | Once | Reason for rejection |
| [element] | [Type] | [Units] | [Range] | [Precision] | [Yes / No] | [Frequency] | [Description] |

### 7.3 M-03 ShipmentStatus

| Element | Type | Units | Range / allowed values | Precision | Mandatory | Frequency | Description |
|---|---|---|---|---|---|---|---|
| `orderId` | String | n/a | As M-01 | n/a | Yes | Once | Order concerned |
| `status` | Enum | n/a | `PICKED`, `PACKED`, `SHIPPED`, `CANCELLED` | n/a | Yes | Once | New status |
| `statusTime` | Date-time | UTC | Not before `orderDate` | 1 s | Yes | Once | Time of status change |
| `trackingNumber` | String | n/a | Up to 35 characters | n/a | If SHIPPED | Once | Carrier tracking number |
| [element] | [Type] | [Units] | [Range] | [Precision] | [Yes / No] | [Frequency] | [Description] |

## 8. Protocol and sequencing

<!-- Guidance: Show the normal message sequence and the rules for ordering, timeouts and retries. Include at least one failure sequence. -->

The normal sequence for one order is shown below.

```mermaid
sequenceDiagram
  participant OMS as Party A (OMS)
  participant Broker
  participant WMS as Party B (WMS)
  OMS->>Broker: M-01 FulfilmentOrder
  Broker->>WMS: Deliver M-01
  WMS->>WMS: Validate and reserve stock
  WMS->>Broker: M-02 OrderAck (ACCEPTED)
  Broker->>OMS: Deliver M-02
  WMS->>Broker: M-03 ShipmentStatus (PICKED)
  WMS->>Broker: M-03 ShipmentStatus (SHIPPED)
  Broker->>OMS: Deliver M-03 messages in order
```

| Rule | Description |
|---|---|
| Ordering | Messages for the same `orderId` are processed in send order |
| Acknowledgement timeout | If no M-02 arrives within 30 s, Party A resends M-01 with the same `messageId` |
| Retry limit | Up to 5 resends with exponential backoff (30 s, 60 s, 120 s, 240 s, 480 s), then alert |
| Status transitions | `PICKED` then `PACKED` then `SHIPPED`; `CANCELLED` allowed before `SHIPPED` only |

## 9. Error handling and recovery

<!-- Guidance: Define how each party detects, reports and recovers from errors, and what the other party should expect. -->

### 9.1 Error handling responsibilities

| Error condition | Detected by | Action | Notification |
|---|---|---|---|
| *Example:* Schema validation failure | Receiver | Reject, move to dead-letter queue, do not retry | Alert to sender on-call |
| *Example:* Duplicate `messageId` | Party B | Discard silently, re-send previous M-02 | None |
| *Example:* Broker unavailable | Sender | Buffer locally up to 24 h, retry | Alert after 5 minutes |
| *Example:* Unknown SKU | Party B | Send M-02 `REJECTED` with `SKU_UNKNOWN` | Party A creates exception case |
| [Condition] | [Party] | [Action] | [Notification] |

### 9.2 Reason codes

| Code | Meaning | Retryable |
|---|---|---|
| `SCHEMA_INVALID` | Message failed schema validation | No |
| `SKU_UNKNOWN` | SKU not known in the warehouse | No, after master data fix |
| `CAPACITY` | Warehouse temporarily cannot accept orders | Yes, after 15 minutes |
| [Code] | [Meaning] | [Yes / No] |

### 9.3 Recovery

[Describe recovery after prolonged outage: replay from the broker
(retention 7 days), reconciliation report comparing open orders daily at
06:00 UTC, and manual resubmission procedure with runbook link.]

## 10. Security

<!-- Guidance: Authentication, authorisation, confidentiality, integrity, data classification and logging for the interface. -->

| Aspect | Control |
|---|---|
| Authentication | [Mutual TLS with certificates issued by the corporate CA; rotated yearly] |
| Authorisation | [Party A may publish to `orders.fulfilment` only; Party B may publish to `orders.ack` and `orders.status` only] |
| Confidentiality | [TLS 1.3 in transit; broker encryption at rest] |
| Integrity | [Broker checksums; `messageId` uniqueness] |
| Data classification | [Confidential: contains delivery addresses (personal data)] |
| Logging | [Message headers logged for 90 days; bodies not logged] |

## 11. Performance and timing

<!-- Guidance: Volumes, rates, latency and availability targets, with the peak calculation. -->

Peak message rate is derived from the peak order forecast:

$$
r_{peak} = \frac{N_{orders/peak\ hour} \times (1 + \bar{m}_{status})}{3600} = \frac{18\,000 \times (1 + 3)}{3600} = 20\ \text{messages/s}
$$

| Parameter | Value |
|---|---|
| Average volume | [40,000 orders per day] |
| Peak volume | [18,000 orders per hour] |
| End-to-end latency M-01 | [95% within 10 s, 99.9% within 60 s] |
| Availability | [99.9% per calendar month excluding agreed maintenance] |
| Throughput headroom | [2x peak tested] |

## 12. Versioning and change control

<!-- Guidance: How the interface evolves without breaking either party. Define what counts as a breaking change and the notice period. -->

| Rule | Description |
|---|---|
| Version scheme | `schemaVersion` major.minor; major in queue name for breaking changes |
| Non-breaking changes | Adding optional fields or enum values announced 30 days ahead; receivers ignore unknown fields |
| Breaking changes | New major version on new queues; old version supported for at least 6 months |
| Change request | Interface change request (ICR) raised by either party, assessed by both, approved by the controlling authority |

| ICR ID | Description | Raised by | Impact | Decision | Date |
|---|---|---|---|---|---|
| *Example:* ICR-004 | Add optional `deliveryWindow` to M-01 | Party A | Non-breaking | Approved | YYYY-MM-DD |
| [ICR-nnn] | [Description] | [Party] | [Breaking / Non-breaking] | [Approved / Rejected] | YYYY-MM-DD |

## 13. Verification and test

<!-- Guidance: Map each interface requirement to a verification activity and record results. Joint integration tests are signed by both parties. -->

| Requirement | Method | Test case | Environment | Result | Date |
|---|---|---|---|---|---|
| ICD-REQ-001 | Test | IT-ICD-01 publish latency | Staging | [Pass / Fail] | YYYY-MM-DD |
| ICD-REQ-002 | Test | IT-ICD-02 acknowledgement timing | Staging | [Pass / Fail] | YYYY-MM-DD |
| ICD-REQ-003 | Test | IT-ICD-03 invalid schema rejected | Staging | [Pass / Fail] | YYYY-MM-DD |
| ICD-REQ-004 | Test | IT-ICD-04 duplicate message | Staging | [Pass / Fail] | YYYY-MM-DD |
| ICD-REQ-005 | Inspection | Schema review | n/a | [Pass / Fail] | YYYY-MM-DD |
| [ICD-REQ-nnn] | [Method] | [Test case] | [Environment] | [Result] | YYYY-MM-DD |

Entry criteria for joint testing: [both parties deployed to staging with
schema version x.y]. Exit criteria: [all requirements passed, no open
severity 1 or 2 defects].

## 14. Signatories

<!-- Guidance: Signatures baseline the ICD. Both parties sign each new baselined version. -->

By signing, each party agrees to implement and maintain its side of the
interface as defined in this document and to change it only through the
process in section 12.

| Party | Name | Title | Signature | Date |
|---|---|---|---|---|
| Party A | [@name] | [System owner, OMS] | [Signature] | YYYY-MM-DD |
| Party B | [@name] | [System owner, WMS] | [Signature] | YYYY-MM-DD |
| Controlling authority | [@name] | [Chair, interface control working group] | [Signature] | YYYY-MM-DD |

## 15. Glossary

<!-- Guidance: Define abbreviations and terms used in this ICD. -->

| Term | Meaning |
|---|---|
| ICD | Interface control document |
| ICR | Interface change request |
| Party | One of the two systems (and their owners) on either side of the interface |
| Dead-letter queue | Queue holding messages that could not be processed, for investigation |
| [Term] | [Meaning] |

## Standard and licence note

Based on common systems engineering practice for interface control
documents (interface identification, requirements allocation, data
element definitions, protocol, error handling, verification and joint
change control). Template licence: MIT.