Produktpartner

Übersicht

Ein Produktpartner ist die Gesellschaft/Bank/Fondsgesellschaft, die Produkte und Tarife anbietet — Allianz, AXA, DWS, Sparkasse Bayern und vergleichbare Anbieter. Im API-Pfad heißt die Ressource /v3/products, in der Doku und im UI nennen wir sie Produktpartner, weil sie nicht einzelne Tarife/Policen abbildet, sondern den vermittelnden Anbieter dahinter.

Produktpartner haben dieselben Stammdaten-Felder und Sub-Resources wie Customers↗ (Adressen, Bankverbindungen, Kontaktdaten, …) plus zwei produktpartner-spezifische — Contact-Persons (Ansprechpartner beim Partner) und Portals (Maklerportal-Logins). Sie laufen unter eigenem API-Pfad und eigener Scope-Familie v3:products:*.

Seit Mai 2026 stehen am Produktpartner zusätzlich Aktivitäten↗ und Links↗ parent-scoped zur Verfügung — GET/POST /v3/products/{kid}/activities und GET/POST/DELETE /v3/products/{kid}/links[/{id}]. Update/Delete einzelner Aktivitäten laufen über die Top-Level-Route /v3/activities/{id} (v3:activities:*); Links nutzen die eigene Familie v3:products:*.

Scopes

Produktpartner-Stammdaten und direkte Sub-Resources verwenden v3:products:read|write. Dokumente und Aktivitäten behalten ihre eigenen Scopes:

Auth-Mechanik und Fehler siehe Authentifizierung↗. Vollständige Scope-Referenz mit Token-Beispielen: Scopes↗.

Pagination & Limits

Identisch zu Customers > Pagination & Limits↗ — page, limit, Default 50, Max 5000, Envelope { page, page_size, total, items }.

Schema

{
  "id": 67890,
  "name": "Allianz Versicherungs-AG",
  "kurzname": "Allianz",
  "kategorie": "versicherer",         // siehe select_fields.products.kategorien
  "vermittlernummer": "MAKLER-12345",
  "website": "https://www.allianz.de",
  "notiz": "Hauptansprechpartner Region Süd: …",
  "insert_datum": "2020-03-15",
  "edit_datum": "2024-06-15",

  // Sub-Resources — opt-in via `?with_*=true` (Default `false` seit Phase C)
  "addresses":       [ /* siehe /rest/v3/customers#addresses */ ],
  "contacts":        [ /* siehe /rest/v3/customers#contacts */ ],
  "banking":         [ /* siehe /rest/v3/customers#banking */ ],
  "contact_persons": [ /* siehe /rest/v3/contact-persons */ ],
  "portals":         [ /* siehe /rest/v3/portals */ ]
}

// Bei `?with_schema=true` (opt-in, Default `false`) zusätzlich zum `items[]`-Array.
{
  "fields": {
    "products": {
    "name":             { "label": "Name",            "data_type": "string", "select_fields_name": null },
    "kurzname":         { "label": "Kurzname",        "data_type": "string", "select_fields_name": null },
    "kategorie":        { "label": "Kategorie",       "data_type": "string", "select_fields_name": "kategorien" },
    "vermittlernummer": { "label": "Vermittler-Nr.",  "data_type": "string", "select_fields_name": null },
    "website":          { "label": "Website",         "data_type": "string", "select_fields_name": null }
    }
  },
  "select_fields": {
    "products": {
    "kategorien": [
      { "value": "versicherer",      "display": "Versicherer" },
      { "value": "bank",             "display": "Bank" },
      { "value": "fondsgesellschaft","display": "Fondsgesellschaft" },
      { "value": "bausparkasse",     "display": "Bausparkasse" },
      { "value": "sonstige",         "display": "Sonstige" }
    ]
    }
  }
}

Endpoints

Verhalten und Response-Shapes sind wie bei Customers: Bei with_schema=true stehen Produktfelder unter fields.products, ihre Auswahllisten unter select_fields.products. Mit with_* eingebettete Daten erhalten eigene Gruppen, z. B. fields.addresses und select_fields.addresses. Für Detail-Beispiele zu Query-Parametern, Batch-POST und Soft-Delete siehe die entsprechenden Customer-Sektionen.

Produkte abfragen

Liefert paginierte Liste aller Produktpartner. Query-Parameter und Response-Envelope identisch zu Customers abfragen↗.

Einzelnen Produktpartner abrufen

Verhalten wie Customer abrufen↗.

Produktpartner anlegen

Body folgt dem Customer-POST-Pattern↗ — Single-Item oder Array (max. 100), per-item Transaktion, gescheiterte Items in failed[]. Pflicht-Feld: name. Sub-Resources im Body (Ansprechpartner, Portale) werden ignoriert — separate Endpoints nutzen.

curl -X POST https://www.api.i-planner.app/v3/products \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Allianz Versicherungs-AG",
    "kurzname": "Allianz",
    "kategorie": "versicherer",
    "vermittlernummer": "MAKLER-12345"
  }'

Response: 201 mit { success, id }. Mögliche Fehler: 400 missing_name (Pflicht-Feld fehlt), 400 invalid_kategorie (Kategorie nicht im Tenant-Schema, siehe Schema↓).

Produktpartner aktualisieren

Verhalten wie Customer aktualisieren↗. Response: { success, updated }.

Produktpartner löschen

Soft-Delete. Verhalten wie Customer löschen↗. Response: { success, soft_deleted, kid }.

Unterressourcen

Die folgenden Sub-Ressourcen folgen dem Customer-Pattern. Direkte Stammdaten und Annotationen verwenden v3:products:read|write; Dokumente verwenden v3:documents:read|write, Aktivitäten v3:activities:read|write. Schreiben erteilt nicht automatisch die Leseberechtigung.

Nicht verfügbar an Produktpartnern: Identity, Jobs, Contracts, Damages, Finances, Goals — semantisch keine Anwendung am Produktpartner-Modell.