API Reference

Complete reference documentation for all AS2aaS API endpoints. The API follows REST principles and returns JSON responses for all operations.

Base URL

https://api.as2aas.com/v1

Authentication

All API requests require authentication using Bearer tokens in the Authorization header:

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

Partners

List Partners

GET /v1/partners

Parameters:

• active (boolean, optional) - Filter by active status
• as2_id (string, optional) - Filter by AS2 identifier
• limit (integer, optional) - Results per page (max 100, default 20)

Response:

{
  "data": [
    {
      "id": "prt_1234567890",
      "as2_id": "PARTNER_CORP",
      "name": "Partner Corporation",
      "url": "https://partner.com/as2",
      "email": "[email protected]",
      "status": "active",
      "compression": true,
      "mdn_mode": "sync",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 95,
    "has_more": true
  }
}

Create Partner

POST /v1/partners

Request Body:

{
  "as2_id": "PARTNER_CORP",
  "name": "Partner Corporation", 
  "url": "https://partner.com/as2",
  "email": "[email protected]",
  "compression": true,
  "mdn_mode": "sync"
}

Response:

{
  "id": "prt_1234567890",
  "as2_id": "PARTNER_CORP",
  "name": "Partner Corporation",
  "url": "https://partner.com/as2",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Partner

GET /v1/partners/{partner_id}

Update Partner

PATCH /v1/partners/{partner_id}

Delete Partner

DELETE /v1/partners/{partner_id}

Messages

List Messages

GET /v1/messages

Parameters:

• status (string, optional) - Filter by message status
• partner_id (string, optional) - Filter by partner
• direction (string, optional) - Filter by direction (inbound/outbound)
• created_after (datetime, optional) - Filter by creation date
• created_before (datetime, optional) - Filter by creation date
• limit (integer, optional) - Results per page

Send Message

POST /v1/messages

Request Body:

{
  "partner_id": "prt_000001",
  "subject": "Business Document",
  "payload": {
    "content": "Message content here",
    "filename": "document.edi"
  },
  "content_type": "application/edi-x12",
  "headers": {
    "Document-Type": "Invoice"
  }
}

Get Message

GET /v1/messages/{message_id}

Get Message Payload

GET /v1/messages/{message_id}/payload

Response: Binary content with appropriate Content-Type header

Certificates

List Certificates

GET /v1/certificates

Parameters:

• type (string, optional) - Filter by certificate type
• active (boolean, optional) - Filter by active status
• expires_soon (boolean, optional) - Filter by expiration status
• expires_soon_days (integer, optional) - Days until expiration threshold

Upload Certificate

POST /v1/certificates

Request Body:

{
  "name": "Certificate Name",
  "type": "signing",
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "password": "optional_password"
}

Get Certificate

GET /v1/certificates/{certificate_id}

Update Certificate

PATCH /v1/certificates/{certificate_id}

Delete Certificate

DELETE /v1/certificates/{certificate_id}

Generate CSR

POST /v1/certificates/generate-csr

Webhooks

List Webhook Endpoints

GET /v1/webhook-endpoints

Create Webhook Endpoint

POST /v1/webhook-endpoints

Request Body:

{
  "url": "https://your-app.com/webhooks/as2",
  "events": [
    "message.sent",
    "message.delivered",
    "message.failed"
  ],
  "description": "Production webhook endpoint"
}

Get Webhook Endpoint

GET /v1/webhook-endpoints/{webhook_id}

Update Webhook Endpoint

PATCH /v1/webhook-endpoints/{webhook_id}

Delete Webhook Endpoint

DELETE /v1/webhook-endpoints/{webhook_id}

Test Webhook

POST /v1/webhook-endpoints/{webhook_id}/test

Billing

Get Billing Information

GET /v1/billing

Response:

{
  "customer_id": "cus_customer123",
  "subscription": {
    "id": "sub_subscription123",
    "status": "active",
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-02-01T00:00:00Z"
  },
  "billing_plan": {
    "name": "Enterprise Plan",
    "model": "base_plus_usage"
  },
  "has_payment_method": true
}

Get Usage Information

GET /v1/billing/usage

Parameters:

• start_date (date, optional) - Usage period start
• end_date (date, optional) - Usage period end

Subscribe to Plan

POST /v1/billing/subscribe

Error Responses

All error responses follow a consistent format:

{
  "error": {
    "type": "error_category",
    "code": "specific_error_code", 
    "message": "Human-readable error description",
    "details": {
      "additional": "context information"
    }
  }
}

HTTP Status Codes

Error Types

Rate Limiting

API requests are subject to rate limiting based on your subscription plan:

Headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1640995200

Rate Limit Response:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded",
    "retry_after": 60
  }
}

Idempotency

POST and PATCH operations support idempotency using the Idempotency-Key header:

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: unique_operation_identifier" \
  -d '{...}'

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 20,
    "total": 200,
    "has_more": true
  }
}

Pagination Parameters:

• limit - Number of items per page (max 100)
• page - Page number (1-based)

Interactive Documentation

For interactive API exploration, visit the OpenAPI documentation:

https://api.as2aas.com/api/documentation