Interface Control Document (ICD) Template

ICD between two systems – parties, requirements allocation, data element table, protocol sequence, errors, security, timing, change control

Arquitectura y diseño de sistemasCompletainterface control document mathActualizada 20 oct 2026

Abrir en el editorDescargar .md

Cómo usar: Integrations between teams, vendors or organisations that need a signed contract. Fill the data element table completely (type, units, range, precision, frequency) before coding. The main pitfall is changing the interface without an approved change request.

Vista previa

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.

Document control

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

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`

Scope
Referenced documents
Interface identification and parties
Interface overview
Requirements allocation
Interface characteristics
Message and data element definitions
Protocol and sequencing
Error handling and recovery
Security
Performance and timing
Versioning and change control
Verification and test
Signatories
Glossary

1. Scope

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

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

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

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

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

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

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

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:

{
  "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

The normal sequence for one order is shown below.

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

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

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

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

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

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

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

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.

Plantillas relacionadas

Arquitectura y diseño de sistemas