[Partner Name] - Integration Guide

Version: 1.0 Last Updated: YYYY-MM-DD Contact: [Team/Person verantwortlich] Status: Draft | Active | Deprecated

Overview

Kurze Beschreibung: Was macht diese Integration?

• Zweck: [Warum gibt es diese Integration]
• Datenfluss: [Was wird ausgetauscht]
• Trigger: [Wann/wie wird Integration ausgelöst]

Prerequisites

Technische Voraussetzungen:

• Zugang zu [Partner-Portal/API]
• API-Credentials (siehe Credentials Management)
• Netzwerk: Firewall-Regeln für IP-Ranges
• Zertifikate: [Falls TLS Client Certs notwendig]

Fachliche Voraussetzungen:

• Vertrag mit Partner unterzeichnet
• Test-Account vorhanden
• Datenschutz-Vereinbarung geklärt

Authentication & Authorization

Production

POST https://api.partner.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}

Response:
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Token Handling:

• Refresh vor Ablauf (empfohlen: 5 Min vor expires_in)
• Secrets über Azure Key Vault (siehe Secrets Guide)

Test Environment

• Base URL: https://test-api.partner.com
• Test Credentials: [In Azure DevOps Variable Group: partner-test-creds]

API Endpoints

1. Submit Data

POST /api/v1/data
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "customerId": "12345",
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

Response 200 OK:
{
  "transactionId": "abc-123",
  "status": "accepted",
  "timestamp": "2025-01-01T10:00:00Z"
}

Validierung:

• customerId: Pflichtfeld, max 10 Zeichen
• field1: Enum [value1, value2, value3]

Error Responses:

Code	Bedeutung	Retry?
400	Validation Error	No
401	Auth failure	No (get new token)
429	Rate limit	Yes (backoff)
500	Server error	Yes (max 3x)

2. Check Status

GET /api/v1/data/{transactionId}
Authorization: Bearer {access_token}

Response 200 OK:
{
  "transactionId": "abc-123",
  "status": "completed",
  "result": { ... }
}

Status Values:

• pending: Wird noch verarbeitet
• completed: Erfolgreich abgeschlossen
• failed: Fehler (siehe errorCode)

Integration Flows

Happy Path: Data Submission

# Sequence: Successful data submission
# Import colors: ...@../../../assets/colors/_colors.d2

User -> System: Trigger Export
System -> Partner API: POST /data (with auth)
Partner API -> System: 200 OK + transactionId
System -> Queue: Schedule Status Check
Worker -> Partner API: GET /data/{id}
Partner API -> Worker: 200 OK + status=completed
Worker -> Database: Update Status

Error Handling: Auth Failure

# Sequence: Token expired
# Import colors: ...@../../../assets/colors/_colors.d2

System -> Partner API: POST /data (with expired token)
Partner API -> System: 401 Unauthorized
System -> Partner API: POST /oauth/token (refresh)
Partner API -> System: New Token
System -> Partner API: POST /data (retry with new token)
Partner API -> System: 200 OK

Rate Limits

• Requests: 100 requests / minute
• Retry Strategy: Exponential Backoff (1s, 2s, 4s, 8s)
• Header: X-RateLimit-Remaining in Response

Data Mapping

Our Field	Partner Field	Type	Required	Notes
customerId	customer_id	string	Yes	Max 10 chars
orderDate	order_date	ISO 8601	Yes	UTC timezone
amount	total_amount	decimal(10,2)	Yes	Euro, no currency code

Error Codes

Code	Message	Bedeutung	Action
E001	Invalid customer	Kunde nicht gefunden	Daten prüfen
E002	Duplicate transaction	Transaction ID bereits verwendet	Neue ID generieren
E003	Service unavailable	Partner-System down	Retry nach 5 Min

Monitoring & Alerts

Health Check:

# Azure Monitor: Application Insights
# Alert Rule: "Partner API Errors > 10 in 5 minutes"

Key Metrics:

• Success Rate (Target: > 99%)
• Response Time (Target: < 2s)
• Failed Auth Attempts (Alert: > 5 / hour)

Testing

Test Credentials

# Azure DevOps Variable Group: partner-test
CLIENT_ID=test-client-12345
CLIENT_SECRET=***
BASE_URL=https://test-api.partner.com

Test Scenarios

1. Smoke Test: Single successful submission

   curl -X POST ... # Example curl command

2. Error Test: Invalid customer ID

   # Expected: 400 Bad Request + E001

3. Load Test: 50 concurrent requests (Rate Limit Test)

Troubleshooting

Problem: 401 Unauthorized trotz gültigem Token

Lösung:

1. Token abgelaufen? Check expires_in
2. Client ID/Secret korrekt? Verify in Key Vault
3. IP-Adresse whitelisted? Contact Partner Support

Problem: Timeouts beim POST

Lösung:

1. Check Partner Status Page: https://status.partner.com
2. Increase Timeout (aktuell: 30s)
3. Retry mit Backoff

Rollout Checklist

Production-Rollout für neue Partner-Integration:

• Test-Credentials validiert
• Prod-Credentials in Key Vault
• IP Whitelisting bei Partner beantragt
• Monitoring & Alerts konfiguriert
• Runbook dokumentiert
• Go-Live mit Partner koordiniert
• Smoke Test in Prod erfolgreich

Contact & Support

• Internal: [Team Name] - [Email/Slack]
• Partner Support: support@partner.com
• SLA: Response Time 4h (Business Hours)
• Escalation: [Partner Account Manager]

Change Log

Date	Version	Change	Author
YYYY-MM-DD	1.0	Initial version	[Name]

---

Related Documents:

• Technical Design
• API Spec (OpenAPI)
• Security Assessment