Skip to main content

​
Quickstart

This guide will help you make your first API calls to the AICO Connectors.

​
Base URLs

Each connector has its own base URL:
ConnectorProduction URLLocal Development
Brunkhorsthttps://brunkhorst.connectors.aicoflow.comhttp://localhost:8101
PlanSohttps://reit.connectors.aicoflow.comhttp://localhost:8102

​
Authentication

Currently, the connector APIs do not require client-side authentication. Server-side credentials for external systems (Zeitmechanik, PlanSo) are configured via environment variables.
Rate limiting may apply to prevent abuse. Contact support if you need higher limits.

​
Example: Book an Appointment (Brunkhorst)

1

List Available Services

curl https://brunkhorst.connectors.aicoflow.com/api/services
Response:
{
  "success": true,
  "services": [
    {"id": "inspektion", "name": "Inspektion", "category": "maintenance"},
    {"id": "oelwechsel", "name": "Ölwechsel", "category": "maintenance"}
  ],
  "count": 2
}
2

Check Available Days

curl -X POST https://brunkhorst.connectors.aicoflow.com/api/availability/days \
  -H "Content-Type: application/json" \
  -d '{"service_ids": ["inspektion"]}'
3

Get Time Slots

curl -X POST https://brunkhorst.connectors.aicoflow.com/api/availability/times \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-03-15", "service_ids": ["inspektion"]}'
4

Reserve a Slot

curl -X POST https://brunkhorst.connectors.aicoflow.com/api/booking/reserve \
  -H "Content-Type: application/json" \
  -d '{"time": "2026-03-15T09:00:00", "service_ids": ["inspektion"]}'
5

Confirm the Booking

curl -X POST https://brunkhorst.connectors.aicoflow.com/api/booking/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "car": {
      "license_plate": "HH-AB 1234",
      "type": "VW Golf",
      "mileage": "50000"
    },
    "customer": {
      "surname": "Max Mustermann",
      "email": "max@example.com",
      "phone": "+49 170 1234567"
    }
  }'

​
Example: Query Orders (PlanSo)

# Search by license plate
curl "https://reit.connectors.aicoflow.com/api/orders?plate=HH-AB"

# Search with multiple filters
curl "https://reit.connectors.aicoflow.com/api/orders?status=in_progress&missing_parts=true&limit=10"

​
Health Checks

All connectors expose health endpoints: 
# Liveness check
curl https://brunkhorst.connectors.aicoflow.com/health

# Readiness check (includes dependency checks)
curl https://brunkhorst.connectors.aicoflow.com/ready

​
Error Handling

All APIs return consistent error responses: 
{
  "success": false,
  "error": "Resource not found",
  "error_code": "NOT_FOUND",
  "details": {
    "resource": "Service",
    "id": "unknown-service"
  }
}
Common HTTP status codes:
  • 200 - Success
  • 400 - Bad request (validation error)
  • 404 - Resource not found
  • 500 - Internal server error
  • 503 - Service unavailable (external dependency down)

​
Next Steps

Brunkhorst API

Full API reference for the Brunkhorst booking connector

PlanSo API

Full API reference for the PlanSo order connector