B2B, EDI and File Transfer Design: [Programme or B2B platform name]
Design for business-to-business integration with external trading
partners and for managed file transfer: the trading partner landscape,
message standards and versions (ASC X12, UN/EDIFACT, industry XML and
APIs), transport protocols (AS2, AS4, SFTP, HTTPS APIs, value-added
networks), the B2B platform, mapping and canonical formats,
acknowledgements (X12 TA1, 997 and 999, EDIFACT CONTRL, AS2 MDN, AS4
receipts), file transfer scheduling, keys and certificates, partner
onboarding and testing, error handling and service levels, archiving and
non-repudiation, and the operating model. AS2 follows RFC 4130; AS4
follows the OASIS AS4 Profile of ebMS 3.0 Version 1.0. X12 and EDIFACT
are described by structure only. Replace every [bracketed] value and
every row marked Example.
Document control
| Field | Value |
|---|
| Document ID | [B2B-001] |
| Platform or programme | [Name] |
| B2B platform and provider | [Product or managed service] |
| Partner communities | [Suppliers, carriers, customers, banks, marketplaces] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@b2b-lead] |
| Approvers/reviewers | [@integration-architect], [@security-architect], [@supply-chain-lead], [@finance-systems-lead] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related documents | [Integration strategy], [Partner agreements], [Implementation guides] |
Approvals
| Role | Name | Decision | Date |
|---|
| Integration architecture | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| Supply chain business owner | [@name] | [Decision] | YYYY-MM-DD |
| Finance systems | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | Example: Approved; AS2 primary, SFTP secondary, in-house translator |
| 1.1 | YYYY-MM-DD | [@name] | Example: Added AS4 for European e-invoicing partners |
Contents
1. Scope, drivers and context
1.1 Drivers
| ID | Driver | Implication |
|---|
| B2D-001 (Example) | Onboard 200 more suppliers in two years | Self-service onboarding, reusable maps, automated testing |
| B2D-002 (Example) | Current EDI provider contract ends in YYYY | Migration of partner connections without disruption |
| B2D-003 (Example) | European customers mandate structured e-invoicing | AS4 or network access point capability |
| B2D-004 (Example) | Late detection of missing ship notices causes receiving delays | Acknowledgement tracking and alerts per document |
| [B2D-NNN] | [Driver] | [Implication] |
1.2 Scope
| In scope | Out of scope |
|---|
| Example: EDI with suppliers, carriers and marketplaces | Consumer-facing APIs (see API Management Platform Design, architecture/api-management-platform-design) |
| Example: Managed file transfer for bank, payroll and logistics files | Internal batch jobs between internal systems only |
| Example: Partner APIs used as an alternative to EDI | Partner portal web screens for manual entry |
| [Item] | [Item] |
1.3 Context
The context view shows partner communities, the B2B edge, the platform components and the internal systems they feed.
2. Trading partner landscape
| Community | Partners | Standard used | Transport | Monthly documents | Who sets the guide |
|---|
| North American suppliers (Example) | 80 | X12 | AS2 | 45,000 | Us |
| European suppliers (Example) | 40 | EDIFACT | AS2, SFTP | 18,000 | Us |
| Carriers (Example) | 6 | X12 and carrier APIs | SFTP, HTTPS | 60,000 | Carrier |
| Marketplaces (Example) | 3 | Marketplace JSON APIs | HTTPS | 120,000 | Marketplace |
| Banks (Example) | 2 | ISO 20022 XML files | SFTP | 1,500 | Bank |
| [Community] | [Count] | [Standard] | [Transport] | [Volume] | [Owner] |
2.1 Partner tiers
| Tier | Criteria | Service level | Onboarding path |
|---|
| Strategic (Example) | Top 20 by spend or revenue | Monitored 24x7, named contact | Full EDI with testing support |
| Standard (Example) | Regular EDI partners | Business hours support | Self-service onboarding with test kit |
| Small (Example) | Fewer than 50 documents a month | Best effort | Web form or spreadsheet upload through the portal |
3. Message standards and versions
3.1 Standards in use
| Standard | Versions in use | Envelope structure | Notes |
|---|
| ASC X12 (Example) | 004010, 005010 | Interchange (ISA to IEA), functional group (GS to GE), transaction set (ST to SE) | X12 publishes one release a year; 008070 became available in March 2026 and 008080 is in balloting; check x12.org for the current release |
| UN/EDIFACT (Example) | D.96A, D.01B | Optional service string advice (UNA), interchange (UNB to UNZ), optional functional group (UNG to UNE), message (UNH to UNT) | Directories published by UNECE; check unece.org for the latest directory |
| ISO 20022 (Example) | pain.001, camt.053 versions per bank | XML message with business application header where used | Bank-specific implementation guides |
| Industry XML or JSON APIs (Example) | Partner versions | Partner-defined | Marketplace and carrier APIs |
| [Standard] | [Versions] | [Envelope] | [Notes] |
3.2 Documents exchanged
| Business process | X12 transaction set | EDIFACT message | Direction | Business owner |
|---|
| Purchase order (Example) | 850 | ORDERS | Outbound to supplier | Procurement |
| Order response (Example) | 855 | ORDRSP | Inbound from supplier | Procurement |
| Order change (Example) | 860 | ORDCHG | Outbound | Procurement |
| Advance ship notice (Example) | 856 | DESADV | Inbound | Warehouse |
| Invoice (Example) | 810 | INVOIC | Inbound | Accounts payable |
| Remittance advice (Example) | 820 | REMADV | Outbound | Accounts payable |
| Carrier status (Example) | 214 | IFTSTA | Inbound from carrier | Logistics |
| Inventory advice (Example) | 846 | INVRPT | Outbound to marketplace or customer | Sales |
| [Process] | [Set] | [Message] | [Direction] | [Owner] |
3.3 Internal implementation guides
Publish one implementation guide per document and standard (for
example "Purchase order, X12 005010, v1.2") that states which segments
and elements the organisation sends or expects, code lists, mandatory
business rules and examples. Partners conform to the guide; exceptions
are recorded in the partner profile. Keep the guides under version
control next to the maps.
4. Transport protocols
| Protocol | Basis | Strengths | Weaknesses | Use for |
|---|
| AS2 | RFC 4130 (July 2005): MIME over HTTP or HTTPS with S/MIME signing and encryption and signed Message Disposition Notifications (MDN) | Mature, widely supported by retail and supply chain, signed receipts give non-repudiation | Both sides host endpoints; certificate exchange per partner; push only | Default for EDI partners in tier 1 and 2 |
| AS4 | OASIS AS4 Profile of ebMS 3.0 Version 1.0 (OASIS Standard, January 2013): web services messaging with WS-Security, receipts and optional pull | Signed receipts, pull mode lets a partner without an inbound endpoint collect messages, used by e-invoicing and energy networks | More complex to configure than AS2 | Network access points, partners that require it |
| SFTP | SSH File Transfer Protocol over SSH (the SFTP draft never became an RFC; SSH itself is RFC 4251 to RFC 4254) | Simple, universal, key-based authentication | No business-level receipt; file naming and completeness rules needed | Banks, carriers, small partners, bulk files |
| FTPS | FTP over TLS | Supported by legacy partners | Firewall complexity with data channels | Legacy only, no new connections |
| HTTPS API | OpenAPI-described REST or partner APIs | Real time, rich error responses | Partner-specific; no standard receipt | Marketplaces, carriers, modern partners |
| Value-added network (VAN) | Provider mailbox and interconnects | One connection reaches many partners | Per-document fees; provider dependency | Partners reachable only through a VAN |
4.1 Transport rules
| ID | Rule |
|---|
| TRP-001 (Example) | AS2 messages are signed and encrypted; signed MDN requested; synchronous MDN by default, asynchronous for partners that require it |
| TRP-002 (Example) | SFTP uses key-based authentication only; passwords disabled; one account per partner, chrooted to its own folders |
| TRP-003 (Example) | Files are written under a temporary name and renamed when complete, or accompanied by a checksum or trigger file |
| TRP-004 (Example) | No plain FTP or unencrypted HTTP |
| TRP-005 (Example) | Inbound endpoints are reachable only through the B2B edge; outbound connections leave through the egress allow list |
| [TRP-NNN] | [Rule] |
5. Platform architecture
| Component | Responsibility | Choice (Example) |
|---|
| Partner management | Partner profiles, identifiers (ISA and GS IDs, UNB IDs, AS2 IDs), certificates, agreements | B2B platform module |
| Communication adapters | AS2, AS4, SFTP, HTTPS endpoints and clients | B2B gateway in the perimeter network |
| Translator and mapper | Parse, validate, map EDI to and from internal formats | B2B platform with maps in version control |
| Managed file transfer | Scheduling, routing, checksums, retries, file audit | MFT product shared with internal file flows |
| Tracking and archive | Document-level status, search by business reference, retention | B2B platform plus archive storage |
| Integration to internal systems | Canonical messages and APIs to ERP, WMS, TMS | Integration platform per the Integration Strategy |
| Partner portal | Onboarding forms, test results, web entry for small partners | Portal module or developer portal |
| Option | Fit | Notes |
|---|
| Managed EDI service (outsourced) | Small teams, many partners on VANs | Check contract rights to maps, data and exit assistance |
| Licensed B2B platform run in-house | Large volumes, strict control | Needs EDI skills and 24x7 operations |
| iPaaS with B2B features | Organisations already on the iPaaS | Check protocol and standard coverage and per-document pricing |
Record the choice in an ADR and score options in Build vs Buy Analysis
(architecture/build-vs-buy-analysis).
6. Mapping and canonical formats
| Rule | Detail |
|---|
| Canonical formats | One per document type (order, order response, ship notice, invoice), owned by the domain team, versioned |
| Map reuse | One map per standard and version using the internal implementation guide; partner deviations handled by profile parameters, not copies of the map |
| Code lists | Units, currencies, countries and party identifiers (GLN, DUNS) translated in reference tables |
| Validation layers | Syntax (standard), implementation guide rules, business rules (prices, items, duplicates) in that order |
| Duplicate detection | Interchange control number per partner, plus business key (purchase order number and version) |
| Map testing | Golden test files per map run in CI; regression run before every map release |
| Change control | Map changes follow the platform change process and are announced to affected partners |
7. Acknowledgements and reconciliation
| Level | Mechanism | Question answered | Timing target (Example) |
|---|
| Transport | AS2 signed MDN; AS4 receipt signal; SFTP successful close and checksum | Did the message arrive intact at the partner's endpoint? | Seconds (synchronous MDN) |
| Interchange | X12 TA1 interchange acknowledgment; EDIFACT CONTRL at interchange level | Was the envelope readable? | Within 1 hour |
| Syntax and implementation | X12 997 functional acknowledgment (syntax); X12 999 implementation acknowledgment (syntax and implementation guide rules, common in health care); EDIFACT CONTRL at group or message level | Were the transaction sets or messages accepted, accepted with errors, or rejected? | Within 4 hours |
| Business | X12 855 or EDIFACT ORDRSP order response; application advice where agreed | Did the partner accept the order, and on what terms? | Per partner agreement, for example 24 hours |
Reconciliation: a daily report per partner lists documents sent, receipts
received, acknowledgements outstanding and rejected documents; the
business owner reviews exceptions. Overdue acknowledgements create a
ticket for the partner manager.
8. Managed file transfer and scheduling
| Item | Rule (Example) |
|---|
| Naming | [partner]_[doctype]_[yyyymmddhhmmss]_[sequence].[ext] |
| Completeness | Write to a temporary name, then rename; or check a SHA-256 checksum file before pickup |
| Pickup | Event-driven pickup where the platform supports it; polling every [5 minutes] otherwise |
| Duplicates | File hash and name stored for [30 days]; repeated files quarantined and reported |
| Scheduling | Calendar-aware schedules with time zone per partner; cut-off times for bank files |
| Retries | Outbound transfer retried [5] times with increasing delay, then alert |
| Large files | Compression and resumable transfer above [1 GB] |
| Encryption at rest | Partner folders encrypted; OpenPGP encryption of payload where the partner requires it |
| Cleanup | Files removed from transfer folders after successful processing and archiving |
| Flow ID | Partner | Direction | Schedule | Cut-off | Size | Downstream |
|---|
| MFT-001 (Example) | Bank A | Outbound payment file | Weekdays 14:00 local | 15:00 | 2 MB | Payments |
| MFT-002 (Example) | Bank A | Inbound statement | Daily 06:00 | Not applicable | 5 MB | Treasury |
| MFT-003 (Example) | Carrier B | Inbound status files | Every 15 minutes | Not applicable | 50 KB | TMS |
| [MFT-NNN] | [Partner] | [Direction] | [Schedule] | [Cut-off] | [Size] | [System] |
9. Security, keys and certificates
| Control | Rule |
|---|
| AS2 and AS4 certificates | Separate signing and encryption certificates; from a public or agreed CA, or self-signed only where the partner agreement allows; key length and algorithms per the current security policy |
| Certificate renewal | Inventory of every partner certificate with expiry; renewal starts [60 days] before expiry; overlap period with both certificates accepted |
| SFTP keys | Partner public keys registered per account; host key fingerprint shared out of band; keys rotated at least every [2 years] |
| Transport encryption | TLS 1.2 or later on HTTPS endpoints; modern SSH algorithms only |
| Payload encryption | S/MIME for AS2, WS-Security for AS4, OpenPGP for files where required |
| Network | B2B edge in the perimeter network; inbound allow lists per partner where practical |
| Data protection | Invoices and remittances contain bank details and sometimes personal data; access to tracking screens is role-based and logged |
| Supplier assurance | Strategic partners complete a security questionnaire (compliance/supplier-security-assessment) |
10. Partner onboarding and testing
10.1 Partner profile
| Field | Example |
|---|
| Partner ID | PTN-0042 (Example) |
| Legal name and business contact | [Name], [@contact] |
| Technical contact and escalation | [Name], [Phone], [Email] |
| Identifiers | ISA qualifier and ID, GS application code, AS2 ID, GLN |
| Standard and version per document | X12 005010 for 850, 855, 856, 810 |
| Transport and endpoints | AS2, URL, certificates, MDN mode |
| Acknowledgement expectations | 997 within 4 hours, 855 within 24 hours |
| Special rules | Deviations from the internal guide |
| Go-live date and status | YYYY-MM-DD, Live |
10.2 Onboarding steps
| Step | Activity | Owner | Exit criterion |
|---|
| 1 | Business request and agreement, including trading partner agreement terms for EDI | Partner manager | Signed agreement |
| 2 | Profile and identifiers exchanged | B2B analyst | Profile complete |
| 3 | Connectivity test (AS2 or SFTP), certificate exchange | B2B engineer | Test message and MDN or file exchange succeed |
| 4 | Document tests with the partner using test indicators in the envelope | B2B analyst and partner | All test cases pass |
| 5 | Business validation in the test ERP | Business owner | Documents post correctly |
| 6 | Go-live with monitoring for the first [10] documents | B2B analyst | No unresolved errors after [2 weeks] |
10.3 Test cases per document
| Test ID | Case | Expected result |
|---|
| B2T-001 (Example) | Valid invoice (810) with three lines | 997 accepted, invoice posted |
| B2T-002 (Example) | Invoice (810) quoting an unknown purchase order number | 997 accepted, invoice held with a business rejection reason sent to the supplier |
| B2T-003 (Example) | Invoice (810) with a syntax error in a mandatory segment | 997 rejected with error detail |
| B2T-004 (Example) | Duplicate interchange control number | Quarantined, alert |
| B2T-005 (Example) | Expired partner certificate | Message refused, alert to partner manager |
| [B2T-NNN] | [Case] | [Expected] |
11. Error handling, monitoring and service levels
| Error class | Example | Detection | Owner | Target to resolve (Example) |
|---|
| Transport | Partner endpoint down, MDN not received | Platform alert | B2B operations | Retry automatically; escalate after 1 hour |
| Envelope and syntax | Invalid ISA, segment errors | Translator validation | B2B operations with partner | 4 business hours |
| Mapping | Map exception after a partner change | Translator error | B2B analyst | 1 business day |
| Business rule | Unknown item, price mismatch | Validation or ERP rejection | Business owner | Per process, for example 1 business day |
| Missing document | Expected ship notice not received | Reconciliation in section 7 | Partner manager | Contact partner the same day |
| Measure | Target (Example) |
|---|
| Platform availability for inbound endpoints | 99.9 % per month |
| Inbound document processed to ERP | 95 % within 15 minutes of receipt |
| Outbound document delivered | 99 % within 15 minutes of creation |
| First-time-right rate per partner | Above 98 % |
| Onboarding lead time, standard tier | Below 10 working days |
Monitoring views: document status by business reference (order number,
invoice number), partner health, certificate expiry and acknowledgement
backlog. Link signals to Observability Specification (ops/observability-spec).
12. Archiving, audit and non-repudiation
| Item | Rule (Example) |
|---|
| What is archived | Raw inbound and outbound payload as exchanged, signed MDNs and receipts, acknowledgements, mapped canonical message, processing log |
| Retention | Per tax and contract rules for each country, for example invoices [10 years]; confirm with finance and legal |
| Integrity | Write-once storage or hash chain; signatures and certificates kept with the message so that they can be verified later |
| Search | By partner, document type, business reference, control number, date |
| Access | Read-only, role-based, logged |
| Disposal | Deletion at end of retention with approval and log |
| Non-repudiation | Signed message plus signed receipt with message integrity check, stored together, prove origin and receipt |
13. Operating model
| Activity | Partner manager | B2B analyst | B2B platform team | Business owner | Security |
|---|
| Partner agreement and relationship | A, R | C | I | C | I |
| Partner profile and onboarding | C | A, R | C | C | C |
| Implementation guides and maps | I | A, R | C | C | I |
| Platform operation and upgrades | I | C | A, R | I | C |
| Certificate and key lifecycle | I | R | A, R | I | C |
| Business rejections | C | C | I | A, R | I |
| Incident with partner impact | R | R | A, R | C | C |
14. Risks and decisions
| ID | Type | Description | Response | Owner |
|---|
| RSK-001 (Example) | Risk | Migration from the current provider breaks partner connections | Partner-by-partner cutover in waves, parallel run, rollback per partner (project/cutover-plan) | @b2b-lead |
| RSK-002 (Example) | Risk | Certificate expiry stops a strategic partner | Inventory, alerts at 60, 30 and 7 days, overlap periods | @b2b-platform |
| RSK-003 (Example) | Risk | Few staff with EDI mapping skills | Training, documented maps, provider support contract | @b2b-lead |
| RSK-004 (Example) | Risk | Partner changes its guide without notice | Agreement clause requiring [30 days] notice; regression tests | @partner-manager |
| DEC-001 (Example) | Decision | AS2 as default transport for EDI partners | ADR-B2B-001 | @integration-architect |
| DEC-002 (Example) | Decision | Canonical document formats between platform and ERP | ADR-B2B-002 | @integration-architect |
| [ID] | [Type] | [Description] | [Response] | [@owner] |
15. Glossary and references
15.1 Glossary
| Term | Meaning |
|---|
| Interchange | Outer envelope of an EDI transmission between two partners |
| Functional group | Group of documents of one type inside an interchange |
| Transaction set (X12) or message (EDIFACT) | One business document, such as an order |
| Implementation guide | Document stating how a standard is used between partners |
| MDN | Message Disposition Notification, the AS2 receipt |
| VAN | Value-added network, a provider that relays EDI between partners |
| MFT | Managed file transfer |
| GLN | Global Location Number, a GS1 identifier for parties and locations |
| Non-repudiation | Evidence that prevents a party from denying it sent or received a message |
15.2 References
| Reference | Version or date checked | Use |
|---|
| RFC 4130, MIME-Based Secure Peer-to-Peer Business Data Interchange Using HTTP, Applicability Statement 2 (AS2), IETF | July 2005 | AS2 transport and MDN |
| AS4 Profile of ebMS 3.0 Version 1.0, OASIS | OASIS Standard, January 2013 | AS4 transport and receipts |
| SSH File Transfer Protocol, IETF draft-ietf-secsh-filexfer (expired draft); RFC 4251 to RFC 4254 for SSH | Checked YYYY-MM-DD | SFTP |
| ASC X12 standards and acknowledgements (TA1, 997, 999), x12.org | Release per section 3.1 | Envelope and transaction set names only |
| UN/EDIFACT directories and CONTRL message, UNECE | Directory per section 3.1 | Envelope and message names only |
| ISO 20022, iso20022.org | Message versions per bank guide | Bank files |
| [Partner implementation guides] | [Version] | [Use] |
Standard and licence note
Based on public specifications: RFC 4130 (AS2) and the SSH RFCs from
the IETF, and the AS4 Profile of ebMS 3.0 Version 1.0 from OASIS.
Structure aligned with ASC X12 and UN/EDIFACT: ASC X12 standards are
copyrighted by ASC X12, and this template names envelopes, transaction
set numbers and acknowledgement types only, with no segment, element or
code list content reproduced; UN/EDIFACT message names come from the
directories published by UNECE. Product and network names are trademarks
of their owners; this template is not affiliated with or endorsed by
them. This template is original text written for this collection. Check
the current official version of every standard, directory and release
before use. Template licence: MIT.