AS2 Messages

AS2 messages are the core communication mechanism for secure B2B document exchange. The platform handles all aspects of AS2 message processing including encryption, digital signing, compression, and delivery confirmation.

Message Overview

AS2aaS provides comprehensive message processing capabilities:

Content Agnostic - Support for EDI, XML, JSON, and binary content
Security - Automatic encryption and digital signing
Compression - Optional payload compression for efficiency
Delivery Confirmation - MDN (Message Disposition Notification) handling
Status Tracking - Real-time visibility into message lifecycle

Sending Messages

Basic Message Transmission

curl -X POST https://api.as2aas.com/v1/messages \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg_unique_001" \
  -d '{
    "partner_id": "prt_000001",
    "subject": "Business Document",
    "payload": {
      "content": "ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *240115*1030*U*00401*000000001*0*T*>~",
      "filename": "document.edi"
    },
    "content_type": "application/edi-x12"
  }'

Advanced Message Configuration

curl -X POST https://api.as2aas.com/v1/messages \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg_advanced_001" \
  -d '{
    "partner_id": "prt_enterprise",
    "subject": "Purchase Order Document",
    "payload": {
      "content": "<?xml version=\"1.0\"?><PurchaseOrder><OrderID>PO-2024-001</OrderID></PurchaseOrder>",
      "filename": "purchase_order.xml"
    },
    "content_type": "application/xml",
    "headers": {
      "Document-Type": "PurchaseOrder",
      "Document-ID": "PO-2024-001",
      "Business-Unit": "Procurement"
    },
    "priority": "high",
    "compress": true,
    "encrypt": true,
    "sign": true
  }'

Message Parameters

Required Fields

Field	Type	Description
`partner_id`	string	Trading partner identifier
`payload.content`	string	Message content (base64 for binary)
`content_type`	string	MIME type of the content

Optional Fields

Field	Type	Default	Description
`subject`	string	`null`	Message subject line
`payload.filename`	string	`null`	Original filename
`headers`	object	`{}`	Custom AS2 headers
`priority`	enum	`normal`	Processing priority (low/normal/high)
`compress`	boolean	Partner setting	Override compression preference
`encrypt`	boolean	Partner setting	Override encryption preference
`sign`	boolean	Partner setting	Override signing preference
`mdn_request`	boolean	Partner setting	Request delivery confirmation

Content Types

EDI Documents

{
  "content_type": "application/edi-x12",
  "payload": {
    "content": "ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *240115*1030*U*00401*000000001*0*T*>~",
    "filename": "transaction.edi"
  }
}

XML Documents

{
  "content_type": "application/xml",
  "payload": {
    "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Document><Header>...</Header></Document>",
    "filename": "business_document.xml"
  }
}

JSON Data

{
  "content_type": "application/json",
  "payload": {
    "content": "{\"transaction_id\": \"TXN-001\", \"items\": [...]}",
    "filename": "transaction.json"
  }
}

Binary Files

{
  "content_type": "application/pdf",
  "payload": {
    "content": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo...",
    "filename": "contract.pdf",
    "encoding": "base64"
  }
}

Message Lifecycle

Status Progression

Messages progress through these states during processing:

queued - Message accepted and queued for processing
processing - Message preparation and transmission in progress
sent - Message successfully transmitted to partner endpoint
delivered - MDN confirmation received from partner
failed - Transmission failed with error details

Status Monitoring

curl -X GET https://api.as2aas.com/v1/messages/msg_123 \
  -H "Authorization: Bearer pk_test_your_api_key"

Response:

{
  "id": "msg_9876543210",
  "partner_id": "prt_000001",
  "direction": "outbound",
  "status": "delivered",
  "subject": "Business Document",
  "content_type": "application/edi-x12",
  "message_id": "[email protected]",
  "payload_size": 2048,
  "compressed": true,
  "encrypted": true,
  "signed": true,
  "mdn_status": "received",
  "attempts": 1,
  "created_at": "2024-01-15T10:35:00Z",
  "sent_at": "2024-01-15T10:35:05Z",
  "delivered_at": "2024-01-15T10:35:15Z"
}

Message Retrieval

List Messages

curl -X GET "https://api.as2aas.com/v1/messages?status=delivered&limit=50" \
  -H "Authorization: Bearer pk_test_your_api_key"

Filter by Partner

curl -X GET "https://api.as2aas.com/v1/messages?partner_id=prt_000001" \
  -H "Authorization: Bearer pk_test_your_api_key"

Filter by Date Range

curl -X GET "https://api.as2aas.com/v1/messages?created_after=2024-01-01&created_before=2024-01-31" \
  -H "Authorization: Bearer pk_test_your_api_key"

Payload Management

Download Message Payload

curl -X GET https://api.as2aas.com/v1/messages/msg_123/payload \
  -H "Authorization: Bearer pk_test_your_api_key" \
  -o message_content.edi

Payload Information

curl -X GET https://api.as2aas.com/v1/messages/msg_123/payload/info \
  -H "Authorization: Bearer pk_test_your_api_key"

Response:

{
  "filename": "business_document.edi",
  "content_type": "application/edi-x12",
  "size": 2048,
  "checksum": "sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "compressed": true,
  "encrypted": true
}

Message Security

Encryption

When encryption certificates are configured, messages are automatically encrypted:

{
  "encrypted": true,
  "encryption_algorithm": "AES-256-CBC",
  "encryption_cert_fingerprint": "SHA256:ab:cd:ef:12:34:56..."
}

Digital Signing

When signing certificates are configured, messages are digitally signed:

{
  "signed": true,
  "signature_algorithm": "SHA256withRSA", 
  "signing_cert_fingerprint": "SHA256:12:34:56:78:90..."
}

Message Disposition Notifications

MDN Configuration

{
  "mdn_request": true,
  "mdn_options": {
    "signed_receipt_protocol": "pkcs7-signature",
    "signed_receipt_micalg": "sha256"
  }
}

MDN Processing

AS2aaS automatically handles MDN responses:

{
  "mdn_status": "received",
  "mdn_disposition": "automatic-action/MDN-sent-automatically; processed",
  "mdn_received_at": "2024-01-15T10:35:15Z",
  "mdn_message_id": "[email protected]"
}

Receiving Messages

Inbound Message Endpoint

Configure trading partners to send messages to:

https://api.as2aas.com/v1/as2/receive

Automatic Processing

Inbound messages are automatically:

Received and validated
Decrypted (if encrypted)
Signature verified (if signed)
Decompressed (if compressed)
Stored securely
MDN sent to partner
Webhook notification triggered

Retry Handling

Automatic Retries

Failed message transmissions are automatically retried based on partner configuration:

{
  "retry_attempts": 3,
  "retry_interval": 300,
  "retry_backoff": "exponential"
}

Manual Retry

curl -X POST https://api.as2aas.com/v1/messages/msg_123/retry \
  -H "Authorization: Bearer pk_test_your_api_key"

Error Handling

Common Message Errors

Invalid Partner:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_partner",
    "message": "Specified partner not found or inactive"
  }
}

Payload Size Limit:

{
  "error": {
    "type": "validation_error",
    "code": "payload_too_large", 
    "message": "Message payload exceeds maximum size limit of 100MB"
  }
}

Transmission Failure:

{
  "error": {
    "type": "transmission_error",
    "code": "connection_timeout",
    "message": "Partner endpoint did not respond within configured timeout period"
  }
}

Enterprise Integration Patterns

High-Volume Processing

For enterprise environments with high message volumes:

# Batch message creation with proper idempotency
for i in {1..100}; do
  curl -X POST https://api.as2aas.com/v1/messages \
    -H "Authorization: Bearer pk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: batch_msg_${i}" \
    -d "{\"partner_id\": \"prt_high_volume\", \"payload\": {...}}"
done

Error Recovery

import time
import requests

def send_message_with_retry(api_key, message_data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://api.as2aas.com/v1/messages',
                headers={
                    'Authorization': f'Bearer {api_key}',
                    'Content-Type': 'application/json',
                    'Idempotency-Key': f'msg_{message_data["id"]}'
                },
                json=message_data,
                timeout=30
            )
            
            if response.status_code == 201:
                return response.json()
            elif response.status_code == 429:
                # Rate limited - exponential backoff
                time.sleep(2 ** attempt)
                continue
            else:
                response.raise_for_status()
                
        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Performance Optimization

Message Compression

Enable compression for large payloads:

{
  "compress": true,
  "payload": {
    "content": "Large EDI document content...",
    "filename": "large_document.edi"
  }
}

Batch Operations

Process multiple messages efficiently:

# Retrieve multiple message statuses
curl -X GET "https://api.as2aas.com/v1/messages?id=msg_001,msg_002,msg_003" \
  -H "Authorization: Bearer pk_test_your_api_key"

Monitoring and Analytics

Message Metrics

curl -X GET "https://api.as2aas.com/v1/messages/analytics?period=last_30_days" \
  -H "Authorization: Bearer pk_test_your_api_key"

Response:

{
  "total_messages": 15420,
  "successful_deliveries": 15398,
  "failed_transmissions": 22,
  "success_rate": 99.86,
  "average_processing_time": 2.3,
  "partner_breakdown": {
    "prt_partner_001": {"sent": 8500, "success_rate": 99.9},
    "prt_partner_002": {"sent": 6920, "success_rate": 99.8}
  }
}