Quickstart

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

Base URLs

Each connector has its own base URL:

Connector	Production URL	Local Development
Brunkhorst	`https://brunkhorst.connectors.aicoflow.com`	`http://localhost:8101`
PlanSo	`https://reit.connectors.aicoflow.com`	`http://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)

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
}

Check Available Days

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

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"]}'

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"]}'

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)

Getting Started

Platform

Connectors

Quickstart

Quickstart

Base URLs

Authentication

Example: Book an Appointment (Brunkhorst)

Example: Query Orders (PlanSo)

Health Checks

Error Handling

Next Steps

Brunkhorst API

PlanSo API

​Quickstart

​Base URLs

​Authentication

​Example: Book an Appointment (Brunkhorst)

​Example: Query Orders (PlanSo)

​Health Checks

​Error Handling

​Next Steps

Brunkhorst API

PlanSo API

Quickstart

Base URLs

Authentication

Example: Book an Appointment (Brunkhorst)

Example: Query Orders (PlanSo)

Health Checks

Error Handling

Next Steps