Integration Setup or Change — Required Information
This page describes what information is required when raising a 03-EDI ticket to set up a new integration or to change an existing one based on new requirements. Providing complete information upfront avoids delays during the process.
Note
This page applies when you are building a new integration or extending an existing one — for example adding a new message type, adjusting a field mapping, connecting a new trading partner, or onboarding a new external system such as SAP, Shopify, or Exact. If the integration exists and has stopped working, see Troubleshooting an Existing Integration instead.
Why This Information Matters
Setting up or changing an integration requires alignment between 3PL Dynamics and the external system on protocols, credentials, message formats, and field mappings. The more complete the information at the start, the fewer rounds of back-and-forth are needed before the integration can go live.
Required Information Checklist
1 — External System
| Field | What to provide |
|---|---|
| System name | E.g. SAP S/4HANA, Shopify, Exact Globe, WooCommerce, Microsoft Dynamics 365 |
| System version / release | The version or release number of the external system |
| New or existing integration? | Is this a completely new setup, or a change to an existing integration? |
| What is changing? | For existing integrations: describe what is being added or adjusted (e.g. new message type, changed field mapping, new trading partner) |
| Environment | Production, test, or sandbox |
2 — Protocol and Connection
| Field | What to provide |
|---|---|
| Protocol | REST API, SOAP, SFTP, FTP, EDIFACT, X12, Webhook, Azure Service Bus, etc. |
| Endpoint / host | The full URL, hostname, or IP address used for the connection |
| Port | The port number (e.g. 443, 22, 21) |
| Authentication method | API key, OAuth 2.0, Basic auth, certificate, IP whitelist |
3 — Credentials
Important
Do not include credentials in the ticket body. Share API keys, passwords, and certificates via a secure channel such as a password manager or encrypted email. State in the ticket that credentials are available and how they will be provided.
Depending on the authentication method, prepare the following:
| Authentication type | What is needed |
|---|---|
| API key | Key name and value |
| OAuth 2.0 | Client ID, client secret, token endpoint URL, required scopes |
| Basic authentication | Username and password |
| SFTP / FTP | Host, port, username, and password or private key file (.ppk / .pem) |
| Certificate | Certificate file (.pfx or .pem) and passphrase |
| IP whitelist | The IP address(es) that must be whitelisted on the partner's side |
4 — Message Details
| Field | What to provide |
|---|---|
| Message format | JSON, XML, CSV, EDIFACT, X12, flat file, etc. |
| Direction | Inbound (external system → 3PL Dynamics) or Outbound (3PL Dynamics → external system) |
| Message / transaction type | E.g. sales order, shipment confirmation, invoice, ASN, stock mutation, label request |
| Example file | Attach a real or anonymized sample message (see tip below) |
Tip
Always attach an example file. For EDIFACT or X12, include the raw EDI message. For REST or SOAP, include a sample request and the expected response. Anonymize personal or commercially sensitive data where needed.
5 — Partner Technical Contact
Provide the contact details of the technical person at the external party. This allows the Boltrics integration team to coordinate directly if needed.
| Field | What to provide |
|---|---|
| Name | Full name of the technical contact |
| Direct email address | |
| Phone | Phone number (optional) |
6 — Documentation and Specifications
Attach or link any of the following if available:
- API documentation or integration guide provided by the partner
- Field mapping specification or interface agreement
- Data flow diagram or process description
- Previous test results or go-live report
- Known limitations or exceptions documented by the partner
Submitting the Ticket
Once you have gathered all the above, go to Creating a Support or Change Ticket and select category 03-EDI. Attach all relevant files in Step 4 — Add Attachments.