Portale

Übersicht

Ein Portal ist ein Anbieter-Portal-Zugang, der an einem Produktpartner hängt — z. B. das Maklerportal eines Versicherers oder das Vermittler-Login einer Bank. Portale tragen URL, Login-Daten, Notizen und optionale Branding-Felder.

Das Portal hat eine global eindeutige id — alle CRUD-Operationen laufen daher top-level über /v3/portals/{id}, ohne Detour über den Produktpartner:

1. Top-Level Full-CRUD — /v3/portals (List, Create) und /v3/portals/{id} (Read, Update, Delete).
2. Parent-scoped Listing + Create — GET /v3/products/{kid}/portals und POST /v3/products/{kid}/portals. Path-kid ist Source-of-Truth; Body darf kein kid-Feld tragen (sonst 400 body_kid_forbidden).

Beide Patterns teilen sich die Scope-Familie mit Produktpartnern: v3:products:*.

Scopes

Wer Customers (Typ 0) verwalten will und Portale lesen will, braucht beide Scopes — v3:customers:* und v3:products:read — getrennt und unabhängig. Auth-Mechanik und Fehler siehe Authentifizierung↗. Vollständige Scope-Referenz mit Token-Beispielen: Scopes↗.

Pagination & Limits

Standard-Pagination (page, limit). Default-Limit 50, Hard-Cap 5000, Envelope { page, page_size, total, items }. Details und Beispiel-Loop in der Customers-Pagination↗.

Schema

{
  "id": 41001,
  "kid": 67890,                       // Customer-ID des Produktpartners
  "art": "Intern",
  "name": "Maklerportal",
  "url": "https://makler.example-versicherer.de/login",
  "user": "MAKLER-12345",             // Login-Name
  "pass": "****",                    // nicht-leerer Wert im Response maskiert
  "zusatz": "Login funktioniert nur über VPN.",
  "insert_datum": "2024-03-08",
  "edit_datum": "2024-06-15"
}

// Bei `?with_schema=true` (opt-in, Default `false`) zusätzlich zum `items[]`-Array.
{
  "fields": {
    "art":    { "label": "Art",  "data_type": "string", "select_fields_name": "portale_sichtbarkeit" },
    "name":   { "label": "Name", "data_type": "string", "select_fields_name": null },
    "url":    { "label": "URL",  "data_type": "string", "select_fields_name": null },
    "user":   { "label": "User", "data_type": "string", "select_fields_name": null },
    "zusatz": { "label": "Zusatz", "data_type": "string", "select_fields_name": null },
    "pass":   { "label": "Passwort", "data_type": "string", "select_fields_name": null }
  }
}

Endpoints

Portale abfragen

Liefert eine paginierte Liste aller Portale deiner Organisation. Optional auf einen einzelnen Produktpartner einschränkbar.

Query-Parameter:

curl "https://www.api.i-planner.app/v3/portals?kid=67890&limit=50" \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

// Alle Portale eines Produktpartners laden
const result = await $fetch('https://www.api.i-planner.app/v3/portals', {
  query: { kid: 67890, limit: 100 },
  headers: { Authorization: `Bearer ${process.env.IPLANNER_API_TOKEN}` },
})
console.log(`${result.total} Portale für Partner 67890`)

Response: Standard-Envelope { page, page_size, total, items, fields?, select_fields? }.

Einzelnes Portal abrufen

Liefert ein einzelnes Portal über seine numerische id.

Path-Parameter: id (integer, positiv).

Response: 200 mit dem vollen Portal-Objekt. 404 endpoint_not_found bei nicht-numerischer ID, 404 not_found bei syntaktisch gültiger aber nicht existierender ID, 400 invalid_id bei 0 oder negativen Werten. Volle Error-Tabelle in Fehler↗.

curl https://www.api.i-planner.app/v3/portals/41001 \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN"

Portal top-level anlegen

Produktpartner-kid ist Pflicht-Feld im Body — ein Portal ohne Produktpartner ergibt fachlich keinen Sinn.

curl -X POST 'https://www.api.i-planner.app/v3/portals' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": 67890,
    "art": "Intern",
    "name": "Maklerportal",
    "url": "https://makler.example-versicherer.de/login",
    "user": "MAKLER-12345",
    "zusatz": "Login nur über VPN."
  }'

Portal am Produktpartner anlegen

kid aus dem Pfad ist Source-of-Truth; Body darf kein kid tragen (400 body_kid_forbidden).

curl -X POST 'https://www.api.i-planner.app/v3/products/67890/portals' \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "art": "Intern",
    "name": "Maklerportal",
    "url": "https://makler.example-versicherer.de/login",
    "user": "MAKLER-12345"
  }'

Portal aktualisieren

PATCH-Semantik. Für Zugangsdaten heißt das Feld pass. Ein gesetzter Wert wird in späteren v3-Leseantworten maskiert; die v3-API fügt beim Schreiben keine eigene Verschlüsselung hinzu.

Portal löschen

Soft-Delete, idempotent. Volle Error-Tabelle in Fehler↗.

Annotations

Portale haben keine direkten Documents. Anhänge werden über Links↗ verbunden.

/v3/portals/<id>/comments[/<rid>]   # 5-op: list, get, create, patch, delete
/v3/portals/<id>/followers[/<rid>]  # 3-op: list, create, delete
/v3/portals/<id>/tags[/<rid>]       # 3-op: list, create, delete
/v3/portals/<id>/links[/<rid>]      # 3-op: list, create, delete

/v3/portals/<id>/documents ist nicht verfügbar — der Endpoint antwortet 404 unsupported_sub_resource.