Trading Partners API

The Partners API manages trading partner configurations including AS2 identifiers, endpoint URLs, security preferences, and certificate associations. Partners can exist at two levels: tenant-specific partners and account-level master partners that are inherited by tenants.

Table of Contents

• Partner Types
• List Partners
• Create Partner
• Get Partner Details
• Update Partner
• Delete Partner
• Test Partner Connection
• Master Partner Inheritance
• Partner Certificate Management
• Partner Configuration Schema

Partner Types

Tenant Partners

Standard partners created and managed at the tenant level:

• Scope: Limited to specific tenant
• Management: Created via /v1/partners endpoints
• Use Case: Tenant-specific trading relationships
• Isolation: Not shared with other tenants

Master Partners (Inherited)

Account-level partners that are automatically inherited by tenants:

• Scope: Shared across all account tenants
• Management: Created via /v1/accounts/{account}/partners endpoints (see Master Partners API)
• Use Case: Common trading partners used by multiple tenants
• Inheritance: Automatically available to all tenants with optional overrides

Partner Resolution Priority

When a tenant accesses partners, the system returns both types with clear identification:

1. Tenant-specific partners (created directly for the tenant)
2. Inherited master partners (shared from account level)
3. Override capability (tenant settings can override master partner configurations)

List Partners

Retrieve paginated list of trading partners with optional filtering.

GET /v1/partners

Query Parameters

Note: This endpoint returns both tenant-specific partners and inherited master partners. Use the type parameter to filter results.

Response Schema

Partner Object Fields

Success Response (200 OK)

{
  "data": [
    {
      "id": "prt_000001",
      "name": "McKesson Corporation",
      "as2_id": "MCKESSON",
      "url": "https://as2.mckesson.com/receive",
      "active": true,
      "type": "inherited",
      "master_partner_id": "prt_master_001",
      "has_overrides": false,
      "sign": true,
      "encrypt": true,
      "compress": false,
      "mdn_mode": "async",
      "sign_algorithm": "SHA256withRSA",
      "encrypt_algorithm": "AES256_CBC",
      "created_at": "2024-01-01T10:00:00.000000Z",
      "updated_at": "2024-01-15T14:30:00.000000Z"
    },
    {
      "id": "prt_000002",
      "name": "Regional Supplier",
      "as2_id": "REGIONAL-SUPPLIER",
      "url": "https://regional.supplier.com/as2",
      "active": true,
      "type": "tenant",
      "master_partner_id": null,
      "has_overrides": false,
      "sign": true,
      "encrypt": false,
      "compress": true,
      "mdn_mode": "sync",
      "sign_algorithm": "SHA256withRSA",
      "encrypt_algorithm": null,
      "created_at": "2024-01-10T15:20:00.000000Z",
      "updated_at": "2024-01-12T09:45:00.000000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 20,
    "total": 25,
    "from": 1,
    "to": 20
  }
}

Create Partner

Create a new tenant-specific trading partner configuration.

POST /v1/partners

Note: This creates a tenant-specific partner. To create master partners shared across tenants, use the Master Partners API endpoints at /v1/accounts/{account}/partners.

Request Parameters

Required Parameters

Optional Parameters

Algorithm Options

Signing Algorithms

Encryption Algorithms

Request Example

{
  "name": "Acme Corporation",
  "as2_id": "ACME-CORP-AS2",
  "url": "https://acme.example.com/as2",
  "sign": true,
  "encrypt": true,
  "compress": false,
  "mdn_mode": "async",
  "sign_algorithm": "SHA256withRSA",
  "encrypt_algorithm": "AES256_CBC"
}

Response

Success Response (201 Created)

{
  "message": "Partner created successfully",
  "data": {
    "id": "prt_000002",
    "name": "Acme Corporation",
    "as2_id": "ACME-CORP-AS2",
    "url": "https://acme.example.com/as2",
    "active": true,
    "sign": true,
    "encrypt": true,
    "compress": false,
    "mdn_mode": "async",
    "sign_algorithm": "SHA256withRSA",
    "encrypt_algorithm": "AES256_CBC",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

Get Partner Details

Retrieve detailed information about a specific partner including certificates and statistics.

GET /v1/partners/{partner_id}

Path Parameters

Response

Extended Partner Object

Includes additional fields not present in list responses:

{
  "data": {
    "id": "prt_000001",
    "name": "Acme Corporation",
    "as2_id": "ACME-CORP-AS2",
    "url": "https://acme.example.com/as2",
    "active": true,
    "sign": true,
    "encrypt": true,
    "compress": false,
    "mdn_mode": "async",
    "sign_algorithm": "SHA256withRSA",
    "encrypt_algorithm": "AES256_CBC",
    "certificates": [
      {
        "id": "cert_000001",
        "name": "Acme Corp Encryption Certificate",
        "type": "partner",
        "usage": "encryption",
        "subject": "CN=Acme Corp AS2, O=Acme Corporation, C=US",
        "active": true,
        "expires_at": "2025-01-01T00:00:00.000000Z",
        "created_at": "2024-01-01T10:00:00.000000Z"
      }
    ],
    "message_stats": {
      "total_sent": 1250,
      "total_received": 890,
      "success_rate": 99.2,
      "last_message_at": "2024-01-15T10:00:00.000000Z"
    },
    "connection_status": {
      "last_test": "2024-01-15T09:00:00.000000Z",
      "last_test_result": "success",
      "response_time_ms": 245
    },
    "created_at": "2024-01-01T10:00:00.000000Z",
    "updated_at": "2024-01-15T14:30:00.000000Z"
  }
}

Update Partner

Modify existing partner configuration.

PATCH /v1/partners/{partner_id}

Path Parameters

Request Parameters

All parameters are optional. Only provided fields will be updated.

Response

Returns updated partner object with same schema as create response.

Delete Partner

Permanently remove a trading partner and all associated data.

DELETE /v1/partners/{partner_id}

Path Parameters

Response

Success Response (200 OK)

{
  "message": "Partner deleted successfully",
  "data": {
    "id": "prt_000001",
    "deleted_at": "2024-01-15T10:30:00.000000Z"
  }
}

Deletion Impact

Test Partner Connection

Validate partner configuration and test connectivity.

POST /v1/partners/{partner_id}/test

Request Parameters

Test Types

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Partner connection test successful",
  "data": {
    "test_type": "full",
    "partner": {
      "id": "prt_000001",
      "name": "Acme Corporation",
      "as2_id": "ACME-CORP-AS2",
      "url": "https://acme.example.com/as2"
    },
    "results": {
      "connectivity": "success",
      "ssl_validation": "success",
      "certificate_validation": "success",
      "as2_protocol": "success",
      "response_time_ms": 245
    },
    "timeline": [
      {
        "step": "DNS resolution",
        "status": "success",
        "duration_ms": 12,
        "details": "Resolved acme.example.com to 203.0.113.10"
      },
      {
        "step": "TCP connection",
        "status": "success",
        "duration_ms": 89,
        "details": "Connected to 203.0.113.10:443"
      },
      {
        "step": "SSL handshake",
        "status": "success",
        "duration_ms": 144,
        "details": "TLS 1.3 connection established"
      }
    ],
    "tested_at": "2024-01-15T10:30:00.000000Z"
  }
}

Master Partner Inheritance

Understanding Partner Inheritance

When tenants access partners via /v1/partners, they receive:

1. Tenant-specific partners - Partners created directly for the tenant
2. Inherited master partners - Account-level partners automatically shared

Inherited Partner Behavior

Automatic Inheritance

• All master partners are automatically visible to tenants
• No explicit inheritance step required
• Master partner changes propagate to all tenants immediately

Configuration Override

Tenants can override master partner settings for their specific needs:

PATCH /v1/partners/{inherited_partner_id}

Request Example:

{
  "url": "https://tenant-specific.endpoint.com/as2",
  "mdn_mode": "sync"
}

Response:

{
  "message": "Partner configuration overridden successfully",
  "data": {
    "id": "prt_000001",
    "name": "McKesson Corporation",
    "type": "inherited",
    "master_partner_id": "prt_master_001",
    "has_overrides": true,
    "url": "https://tenant-specific.endpoint.com/as2",
    "mdn_mode": "sync",
    "override_settings": {
      "url": "https://tenant-specific.endpoint.com/as2",
      "mdn_mode": "sync"
    }
  }
}

Override Management

View Override Settings:

GET /v1/partners/{inherited_partner_id}/overrides

Reset to Master Configuration:

DELETE /v1/partners/{inherited_partner_id}/overrides

Master vs Tenant Partner Comparison

Best Practices

1. Use Master Partners for Common Relationships
   • Partners used by multiple tenants
   • Standard industry partners (McKesson, Cardinal Health, etc.)
   • Corporate trading partners
2. Use Tenant Partners for Specialized Relationships
   • Tenant-specific suppliers
   • Regional partners
   • Testing/development partners
3. Override Strategically
   • Only override when necessary
   • Document override reasons
   • Review overrides periodically

Partner Certificate Management

List Partner Certificates

GET /v1/partners/{partner_id}/certificates

Upload Partner Certificate

POST /v1/partners/{partner_id}/certificates

Request Parameters (multipart/form-data)

Certificate Usage Types

Partner Configuration Schema

Complete Configuration Object

{
  "id": "prt_000001",
  "name": "Acme Corporation",
  "as2_id": "ACME-CORP-AS2",
  "url": "https://acme.example.com/as2",
  "active": true,
  "security": {
    "sign": true,
    "encrypt": true,
    "compress": false,
    "sign_algorithm": "SHA256withRSA",
    "encrypt_algorithm": "AES256_CBC"
  },
  "mdn": {
    "mode": "async",
    "url": "https://acme.example.com/as2/mdn",
    "signed": true,
    "algorithm": "SHA256withRSA"
  },
  "connection": {
    "timeout_seconds": 60,
    "retry_attempts": 3,
    "retry_interval_seconds": 300
  },
  "certificates": [
    {
      "id": "cert_000001",
      "usage": "encryption",
      "active": true,
      "expires_at": "2025-01-01T00:00:00.000000Z"
    }
  ],
  "statistics": {
    "messages_sent": 1250,
    "messages_received": 890,
    "success_rate": 99.2,
    "last_activity": "2024-01-15T10:00:00.000000Z"
  },
  "created_at": "2024-01-01T10:00:00.000000Z",
  "updated_at": "2024-01-15T14:30:00.000000Z"
}

Validation Rules

AS2 ID Requirements

Valid AS2 ID Examples

• ACME-CORP-AS2
• SUPPLIER_001
• PARTNER-PROD-01

Invalid AS2 ID Examples

• ACME CORP (contains space)
• PARTNER@PROD (contains special character)
• partner-001 (if case-sensitive partner expects uppercase)

URL Requirements

Error Codes

Partner-Specific Errors

Partner Validation Error Example

{
  "message": "Validation failed",
  "errors": {
    "as2_id": [
      "The AS2 ID field is required",
      "The AS2 ID must not contain spaces"
    ],
    "url": [
      "The URL must be a valid HTTPS endpoint"
    ],
    "encrypt_algorithm": [
      "The selected encryption algorithm is invalid"
    ]
  }
}

Partner Testing

Connection Test Results

Test Result Schema

Timeline Step Schema

Test Failure Response

{
  "success": false,
  "message": "Partner connection test failed",
  "data": {
    "test_type": "ping",
    "partner": {
      "id": "prt_000001",
      "as2_id": "ACME-CORP-AS2"
    },
    "results": {
      "connectivity": "failed",
      "error": "Connection timeout"
    },
    "timeline": [
      {
        "step": "DNS resolution",
        "status": "success",
        "duration_ms": 15,
        "details": "Resolved to 203.0.113.10"
      },
      {
        "step": "TCP connection",
        "status": "failure",
        "duration_ms": 60000,
        "details": "Connection timeout after 60 seconds"
      }
    ],
    "duration_ms": 60015,
    "tested_at": "2024-01-15T10:30:00.000000Z"
  }
}

Usage Limits

Partner Limits by Plan

Partner Limit Error

{
  "message": "Partner limit exceeded for current plan",
  "error": {
    "type": "billing_error",
    "code": "PARTNER_LIMIT_EXCEEDED",
    "details": {
      "current_partners": 6,
      "plan_limit": 5,
      "plan": "free",
      "upgrade_url": "https://as2aas.com/dashboard/billing"
    }
  }
}

Integration Examples

Partner Management with Inheritance

// Get all partners (tenant + inherited)
async function getAllPartners(tenantId) {
  const partners = await as2.partners.list();
  
  const result = {
    tenant_partners: partners.data.filter(p => p.type === 'tenant'),
    inherited_partners: partners.data.filter(p => p.type === 'inherited'),
    total: partners.data.length
  };
  
  return result;
}

// Create tenant-specific partner
async function createTenantPartner(partnerData) {
  const partner = await as2.partners.create({
    name: partnerData.name,
    as2_id: partnerData.as2_id,
    url: partnerData.endpoint,
    sign: true,
    encrypt: true,
    sign_algorithm: 'SHA256withRSA',
    encrypt_algorithm: 'AES256_CBC'
  });
  
  // Upload tenant-specific certificates
  if (partnerData.encryptionCertificate) {
    await as2.partners.uploadCertificate(partner.id, {
      name: `${partner.name} Encryption`,
      usage: 'encryption',
      certificate: partnerData.encryptionCertificate
    });
  }
  
  return partner;
}

// Override master partner configuration
async function overrideMasterPartner(partnerId, overrides) {
  const updatedPartner = await as2.partners.update(partnerId, overrides);
  
  console.log(`Master partner ${partnerId} overridden for tenant`);
  console.log('Overrides:', updatedPartner.data.override_settings);
  
  return updatedPartner;
}

Bulk Partner Operations

// Bulk partner management
async function bulkUpdatePartners(updates) {
  const results = [];
  
  for (const update of updates) {
    try {
      const result = await updatePartner(update.partner_id, update.changes);
      results.push({ success: true, partner_id: update.partner_id, data: result });
    } catch (error) {
      results.push({ 
        success: false, 
        partner_id: update.partner_id, 
        error: error.message 
      });
    }
  }
  
  return results;
}