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

ParameterTypeDescription
as2_idstringUnique AS2 identifier (3-128 characters)
namestringPartner organization name
urlstringPartner's AS2 endpoint URL (HTTPS required)
emailstringAdministrative contact email

Optional Parameters

ParameterTypeDefaultDescription
compressionbooleanfalseEnable message compression
encryption_cert_idstringnullCertificate for message encryption
signing_cert_idstringnullCertificate for message signing
mdn_modeenumsyncMDN delivery mode (sync/async/none)
mdn_urlstringnullAsynchronous MDN delivery URL
retry_attemptsinteger3Failed transmission retry count
retry_intervalinteger300Retry interval in seconds
timeoutinteger30Request 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.

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

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"
  }'
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.

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