Receiving AS2 Messages

AS2aaS handles incoming AS2 messages automatically through dedicated receiving endpoints. This guide explains how message receiving works and how to configure your trading partners to send messages to your AS2aaS endpoint.

AS2 Receiving Endpoint

AS2 Receiving Endpoint

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

How Message Receiving Works

1. AS2 Message Flow

The AS2aaS platform automatically processes incoming messages through a secure, enterprise-grade processing pipeline.

2. Message Processing Steps

1. Message Reception: AS2 message received at as2.as2aas.com/as2/receive
2. Protocol Handling: AS2aaS processing engine handles AS2 protocol (encryption, signatures, compression)
3. Partner Validation: Verify sending partner is configured and authorized
4. Payload Extraction: Extract and store business document payload
5. MDN Generation: Generate and return Message Disposition Notification
6. Secure Storage: Store message metadata and delivery status
7. Event Notification: Notify your application via configured webhooks

Partner Configuration

Setting Up Partners to Send to You

Provide your trading partners with these details:

AS2 Configuration:

AS2 URL: https://as2.as2aas.com/as2/receive
AS2-From: [Partner's AS2 ID]
AS2-To: [Your AS2 ID from dashboard]
Content-Type: application/pkcs7-mime (for encrypted)
           or application/pkcs7-signature (for signed)
           or application/edi-x12 (for plain EDI)

Security Requirements:

• Encryption: Supported algorithms: AES128_CBC, AES192_CBC, AES256_CBC, 3DES
• Signing: Supported algorithms: SHA1withRSA, SHA256withRSA, SHA384withRSA, SHA512withRSA
• Certificates: X.509 certificates required for encryption/signing
• MDN: Supports both sync and async MDN modes

Example Partner AS2 Configuration

<!-- Partner's AS2 configuration -->
<AS2Configuration>
  <PartnerID>YOUR-AS2-ID</PartnerID>
  <URL>https://as2.as2aas.com/as2/receive</URL>
  <Encryption>
    <Algorithm>AES128_CBC</Algorithm>
    <Certificate>your-public-cert.pem</Certificate>
  </Encryption>
  <Signing>
    <Algorithm>SHA256withRSA</Algorithm>
    <Certificate>partner-private-cert.pem</Certificate>
  </Signing>
  <MDN>
    <Mode>async</Mode>
    <URL>https://as2.as2aas.com/as2/mdn</URL>
  </MDN>
</AS2Configuration>

Receiving Message Types

Supported Content Types

Message Size Limits

Monitoring Incoming Messages

Via Dashboard

1. Navigate to Messages in your dashboard
2. Filter by Direction: Inbound
3. View message status, payload, and MDN details
4. Download original payloads

Via API

GET /v1/messages?direction=inbound

Via Webhooks

Configure webhook endpoints to receive real-time notifications:

{
  "event": "message.received",
  "data": {
    "id": "msg_000001",
    "message_id": "MSG_20240115_103000_ABC123",
    "partner": {
      "id": "prt_000001", 
      "name": "Acme Corp",
      "as2_id": "ACME-CORP-AS2"
    },
    "status": "received",
    "direction": "inbound",
    "subject": "Purchase Order #67890",
    "content_type": "application/edi-x12",
    "bytes": 2048,
    "received_at": "2024-01-15T10:30:00Z"
  }
}

Error Handling

Common Receiving Errors

Error Webhook Events

{
  "event": "message.failed",
  "data": {
    "id": "msg_000001",
    "status": "failed",
    "error_code": "DECRYPTION_FAILED",
    "error_message": "Unable to decrypt message with provided certificate",
    "partner": {
      "id": "prt_000001",
      "as2_id": "ACME-CORP-AS2"
    }
  }
}

Testing Message Receiving

Using Sandbox

Simulate incoming messages for testing:

POST /v1/sandbox/incoming-message

{
  "from_as2_id": "TEST-PARTNER",
  "to_as2_id": "YOUR-AS2-ID",
  "subject": "Test Purchase Order", 
  "payload": "ISA*00*...*IEA*1*000000001~",
  "content_type": "application/edi-x12",
  "encrypt": false,
  "sign": true,
  "request_mdn": true
}

Testing Tools Dashboard

Use the Testing Tools in your dashboard:

1. Go to Testing Tools → Incoming Messages
2. Configure test message parameters
3. Load sample EDI or XML payloads
4. Simulate message reception
5. View results and generated MDNs

Security Considerations

Certificate Requirements

• Your Certificate: Upload your identity certificate for decryption
• Partner Certificates: Upload partner public certificates for signature verification
• Certificate Validation: All certificates are validated for expiry and chain of trust

Network Security

• HTTPS Only: All AS2 communication uses TLS 1.2+
• IP Allowlisting: Configure allowed IP ranges for partners (Enterprise)
• Rate Limiting: Automatic protection against message flooding
• Audit Logging: All receiving activity is logged for compliance

Troubleshooting

Message Not Received

1. Check Partner Configuration: Verify AS2-To ID matches your configuration
2. Verify Endpoint: Ensure partner is sending to https://as2.as2aas.com/as2/receive
3. Certificate Issues: Check certificate expiry and validity
4. Network Issues: Verify partner can reach the endpoint

MDN Issues

1. MDN Not Sent: Check if partner requested MDN in original message
2. MDN Signature Failed: Verify your signing certificate is valid
3. Async MDN Delivery: Check partner's MDN receiving endpoint

Getting Help

• Dashboard Logs: View detailed error logs in your dashboard
• Support: Contact support with message ID for investigation
• Testing Tools: Use sandbox to reproduce issues safely

Integration Examples

Processing Received Messages

// Webhook handler for received messages
app.post('/webhooks/as2', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'message.received') {
    // Download and process the payload
    const payloadResponse = await fetch(
      `https://api.as2aas.com/v1/messages/${data.id}/payload`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    const payload = await payloadResponse.text();
    
    // Process your EDI/XML document
    await processBusinessDocument(payload, data);
  }
  
  res.status(200).send('OK');
});

Automatic Partner Setup

// Automatically add new partners when they send messages
app.post('/webhooks/as2', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'partner.unknown') {
    // Create partner automatically
    await fetch('https://api.as2aas.com/v1/partners', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: `Auto-created: ${data.as2_id}`,
        as2_id: data.as2_id,
        url: data.return_url,
        active: true
      })
    });
  }
});