Trading Partners
Trading partners represent the business entities with whom you exchange AS2 messages. Each partner configuration includes AS2 identifiers, endpoint URLs, security certificates, and communication preferences.
Partner Configuration
Required Parameters
Parameter | Type | Description |
---|---|---|
as2_id | string | Unique AS2 identifier (3-128 characters) |
name | string | Partner organization name |
url | string | Partner's AS2 endpoint URL (HTTPS required) |
email | string | Administrative contact email |
Optional Parameters
Parameter | Type | Default | Description |
---|---|---|---|
compression | boolean | false | Enable message compression |
encryption_cert_id | string | null | Certificate for message encryption |
signing_cert_id | string | null | Certificate for message signing |
mdn_mode | enum | sync | MDN delivery mode (sync/async/none) |
mdn_url | string | null | Asynchronous MDN delivery URL |
retry_attempts | integer | 3 | Failed transmission retry count |
retry_interval | integer | 300 | Retry interval in seconds |
timeout | integer | 30 | Request timeout in seconds |
Creating Partners
Basic Partner Creation
curl -X POST https://api.as2aas.com/v1/partners \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: partner_creation_001" \
-d '{
"as2_id": "ENTERPRISE_PARTNER",
"name": "Enterprise Trading Partner",
"url": "https://partner.enterprise.com/as2/receive",
"email": "[email protected]"
}'
Advanced Configuration
curl -X POST https://api.as2aas.com/v1/partners \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: advanced_partner_001" \
-d '{
"as2_id": "SECURE_PARTNER",
"name": "Secure Trading Partner",
"url": "https://secure.partner.com/as2",
"email": "[email protected]",
"compression": true,
"encryption_cert_id": "cert_encryption_001",
"signing_cert_id": "cert_signing_001",
"mdn_mode": "async",
"mdn_url": "https://secure.partner.com/mdn",
"retry_attempts": 5,
"retry_interval": 600,
"timeout": 45
}'
AS2 Identifier Requirements
AS2 ID Specifications
AS2 identifiers must be unique within your tenant and coordinated with your trading partner. Use meaningful identifiers that clearly identify your organization.
AS2 identifiers must be unique within your tenant and coordinated with your trading partner. Use meaningful identifiers that clearly identify your organization.
Identifier Guidelines
- Length: 3 to 128 characters
- Characters: Alphanumeric, hyphens, underscores, periods
- Case sensitivity: AS2 IDs are case-sensitive
- Uniqueness: Must be unique within tenant scope
Common Patterns
- Company name:
ACME_CORP
- GLN-based:
GLN_0123456789012
- Department-specific:
ACME_PURCHASING
- System-based:
ACME_ERP_PROD
Message Disposition Notifications
Synchronous MDN
{
"mdn_mode": "sync"
}
Receipt confirmations are returned immediately in the HTTP response. Recommended for partners with reliable, fast endpoints.
Asynchronous MDN
{
"mdn_mode": "async",
"mdn_url": "https://partner.example.com/mdn/receive"
}
Receipt confirmations are sent to a separate endpoint. Required for partners with processing delays or complex workflows.
No MDN
{
"mdn_mode": "none"
}
No receipt confirmations are requested. Not recommended for production environments requiring delivery confirmation.
Partner Management
Retrieve Partner List
curl -X GET https://api.as2aas.com/v1/partners \
-H "Authorization: Bearer pk_test_your_api_key"
Filter Partners
# Filter by status
curl -X GET "https://api.as2aas.com/v1/partners?active=true" \
-H "Authorization: Bearer pk_test_your_api_key"
# Filter by AS2 ID
curl -X GET "https://api.as2aas.com/v1/partners?as2_id=ENTERPRISE_PARTNER" \
-H "Authorization: Bearer pk_test_your_api_key"
# Pagination
curl -X GET "https://api.as2aas.com/v1/partners?limit=50&page=2" \
-H "Authorization: Bearer pk_test_your_api_key"
Update Partner Configuration
curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Partner Name",
"email": "[email protected]",
"compression": false,
"timeout": 60
}'
Certificate Association
Link Encryption Certificate
curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"encryption_cert_id": "cert_encryption_new"
}'
Link Signing Certificate
curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"signing_cert_id": "cert_signing_new"
}'
Partner Status Management
Activate Partner
curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"status": "active"
}'
Deactivate Partner
curl -X PATCH https://api.as2aas.com/v1/partners/prt_123 \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"status": "inactive"
}'
Partner Status Effects
Messages cannot be sent to inactive partners. Existing messages in the processing queue will continue normal processing.
Messages cannot be sent to inactive partners. Existing messages in the processing queue will continue normal processing.
Connection Testing
Validate Partner Connectivity
curl -X POST https://api.as2aas.com/v1/partners/prt_123/test \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"test_type": "connection"
}'
Certificate Validation
curl -X POST https://api.as2aas.com/v1/partners/prt_123/test \
-H "Authorization: Bearer pk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"test_type": "certificates"
}'
Enterprise Integration Examples
Healthcare Partner Configuration
{
"as2_id": "HEALTHCARE_SYSTEM",
"name": "Regional Healthcare System",
"url": "https://edi.healthsystem.com/as2",
"email": "[email protected]",
"compression": true,
"mdn_mode": "async",
"encryption_cert_id": "cert_healthcare_enc",
"signing_cert_id": "cert_healthcare_sign"
}
Retail Partner Configuration
{
"as2_id": "RETAIL_CHAIN",
"name": "National Retail Chain",
"url": "https://b2b.retailchain.com/as2/receive",
"email": "[email protected]",
"compression": true,
"mdn_mode": "sync",
"retry_attempts": 5,
"timeout": 30
}
Manufacturing Partner Configuration
{
"as2_id": "MANUFACTURING_CORP",
"name": "Manufacturing Corporation",
"url": "https://supply.manufacturing.com/as2",
"email": "[email protected]",
"compression": false,
"mdn_mode": "async",
"mdn_url": "https://supply.manufacturing.com/mdn",
"encryption_cert_id": "cert_mfg_public"
}
Error Handling
Validation Errors
Duplicate AS2 ID:
{
"error": {
"type": "validation_error",
"code": "duplicate_as2_id",
"message": "AS2 ID already exists for this tenant",
"details": {
"as2_id": "EXISTING_PARTNER",
"existing_partner_id": "prt_existing_123"
}
}
}
Invalid Endpoint URL:
{
"error": {
"type": "validation_error",
"code": "invalid_endpoint_url",
"message": "Partner endpoint must use HTTPS protocol",
"details": {
"provided_url": "http://insecure.partner.com",
"requirement": "HTTPS protocol required for AS2 endpoints"
}
}
}
Best Practices
Security
- Always use HTTPS endpoints for partner URLs
- Associate encryption and signing certificates when available
- Validate certificate chains before production deployment
- Monitor certificate expiration dates
Configuration
- Use descriptive AS2 IDs that partners can easily recognize
- Configure appropriate timeout values based on partner response times
- Set retry parameters based on partner reliability characteristics
- Use asynchronous MDN for partners with processing delays
Monitoring
- Track message success rates by partner
- Monitor partner endpoint response times
- Set up alerts for partner connectivity issues
- Review partner configurations during scheduled maintenance windows