Developer Guide

For EDI integrators and technical consultants. Developer accounts include the Visual Mapping GUI, EDI Validator, endpoint configuration, and API access on top of everything available to clients.

Getting started

Create a developer account

Sign up at /signup?type=developer. Developer accounts have access to all client features plus the full developer toolset. After email verification, your developer workspace is available immediately at /dashboard.

Developer Workspace

The developer dashboard gives you a unified overview of your mapping projects, endpoints, connected clients, and API key status. Key sections:

Mapping Projects — all saved mapping rules, sortable by last modified
Endpoints — AS2, SFTP, and API communication configurations
Dev Clients — client accounts linked to your developer account
AI Credits — balance for AI-assisted mapping and validation features
API Keys — generate and manage keys for programmatic access

Visual Mapping GUI

The Mapping GUI at /mapping lets you build X12 field-mapping rules visually. See the Visual Mapping GUI full guide → for a step-by-step walkthrough covering all features. Supported formats on both source and target sides:

Format	Notes
X12	Native ANSI X12 EDI (ISA/GS/ST envelope)
JSON	Flat or nested JSON objects
CSV	Comma-separated with header row
XML	Structured XML documents

Building a mapping project

Click + New Project in the mapping toolbar
Select your source format (e.g., JSON) and target format (e.g., X12)
Select the transaction set (e.g., 850 for a Purchase Order)
Paste a sample source document — x12port will parse it and show discovered fields
Add mapping rules: drag source fields to target fields, or add rules manually
Apply transforms per rule: none, uppercase, lowercase, trim, date_iso
Click Save to persist the project

AI Mapping Suggestions

Paste a source document and click AI Suggest. The AI analyzes the document and generates 5–15 mapping rule suggestions. You can accept, modify, or discard each one. Costs 1 credit.

Testing a mapping

After building rules, paste a full source document and click Convert. The output appears in the right panel. You can save the output to your Document Vault directly from the converter.

EDI Validator

The validator at /dev/validate checks X12 documents for structural and segment-level errors.

Paste your X12 document into the input area
Click Validate
Errors are listed with segment positions and error codes
Click Explain with AI on any error to get a plain-English explanation and suggested fix. Costs 1 credit.

✅ Always validate outbound X12 documents before sending to trading partners. A rejected 850 or 856 can trigger chargebacks and compliance penalties from large retailers.

Endpoint Management

Endpoints at /endpoints define the communication channels between you and your trading partners. x12port supports:

Type	Common use	Key config fields
AS2	Large retailers (Walmart, Target, Amazon, Home Depot)	AS2 ID, partner AS2 ID, URL, certificates
SFTP	Mid-market partners, 3PLs	Host, port, username, key or password, inbox/outbox paths
API	Modern ERP/WMS integrations	Endpoint URL, auth type, API key or Bearer token
VAN	Value-Added Networks (GS1, SPS Commerce, TrueCommerce)	VAN provider, mailbox ID, credentials

Each endpoint is linked to a trading partner. One partner can have multiple endpoints (e.g., AS2 for production, SFTP for testing).

Developer Clients

Developer clients at /dev/clients are the business accounts you manage on behalf of your customers. You can:

Create offline clients — set up a client profile with their EDI identity (ISA qualifier and ID) without them needing an x12port account
Link existing clients — clients sign up with your developer invite link and appear in your Dev Clients view
Manage EDI identity — store each client's ISA qualifier/ID for use in your mapping projects
View client details — inspect transaction sets and connection info per client

Developer invite link

Your developer dashboard shows a unique shareable link. When a business signs up via that link, they're linked to your account automatically and appear in your Dev Clients view.

API Keys

Generate API keys from your developer dashboard under API Access. x12port uses two environments:

Environment	Key prefix	Use for
Sandbox	`xp_test_...`	Development and testing — no real documents processed
Live	`xp_live_...`	Production — real EDI documents and partner connections

⚠️ API keys are shown only once at generation time. Store them securely in your environment variables — never hard-code them in your application source code.

See the API Reference for how to authenticate and use the available endpoints.

Transaction Sets (Developer)

When configuring trading partner connections for your clients, select the transaction sets that apply. The most common sets across industries:

850 — Purchase Order
855 — Purchase Order Acknowledgment
856 — Ship Notice / ASN
810 — Invoice
820 — Payment Order / Remittance
997 — Functional Acknowledgment (required with all exchanges)
204 — Motor Carrier Load Tender
214 — Shipment Status Message
830 — Planning Schedule / Forecast

For a full list of supported transaction sets, see EDI Basics.