Suche

Übersicht

POST /v3/search durchsucht ausschließlich die PostgreSQL-Suchprojektion crm_suche des authentifizierten Mandanten. Treffer werden anschließend über die regulären v3-Handler geladen; Berechtigungen, Löschmarkierungen und die üblichen Response-Felder gelten daher genauso wie an den Ressourcen-Endpunkten.

Die Freitextsuche zerlegt query an Leerzeichen. Jeder Token muss als Teilstring im Suchtext vorkommen. Eine Rechtschreibkorrektur oder Edit-Distance-Suche wird nicht angewendet.

Scopes

Neben v3:search:read braucht jeder angefragte Index seinen Ressourcen-Scope:

Fehlt ein Scope, antwortet die API mit 403 forbidden_indices, bevor eine Suche ausgeführt wird.

Request

Freitext

{
  "query": "Anna Müller",
  "indices": ["customers", "contracts"],
  "limit": 25
}

indices ist bei Freitext erforderlich. limit gilt pro Index, ist standardmäßig 50 und darf höchstens 5000 betragen.

Strukturierte Form

{
  "query": [
    { "index": "customers", "include": { "name": "Müller", "ort": "Berlin" } },
    { "name": "contracts", "fields": { "nummer": "V-2026-00471" } }
  ],
  "limit": 25
}

Die Schlüsselpaare index/include und name/fields sind gleichwertig. Die Indices werden aus dem Array abgeleitet. Primitive Werte innerhalb von include beziehungsweise fields werden als Such-Tokens verwendet; Feldnamen sind keine exakten SQL-Filter.

Unterstützte Indices sind customers, products, users, contracts, damages, contactPersons, portals, activities, documents, finances und goals. portals besitzt derzeit keine eigene crm_suche-Projektion und liefert deshalb keine Treffer. tariffs und commissions sind nicht unterstützt und werden als ungültige Indices abgewiesen.

Response

{
  "ok": true,
  "total": 2,
  "data": {
    "customers": {
      "total": 2,
      "items": [
        { "kid": 12345, "vorname": "Anna", "name": "Müller" }
      ]
    },
    "contracts": {
      "total": 0,
      "items": []
    }
  }
}

total summiert die Kandidaten der angefragten Indices. Die Reihenfolge der hydratisierten items folgt der Reihenfolge der Treffer in crm_suche. Teilfehler können zusätzlich in errors erscheinen; schlägt die Suche vollständig fehl, antwortet der Endpoint mit 502 search_backend_failed.

Beispiel

curl -X POST https://www.api.i-planner.app/v3/search \
  -H "Authorization: Bearer $IPLANNER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Anna Müller",
    "indices": ["customers"],
    "limit": 25
  }'

Interne Tools-Kompatibilität

Der interne Endpoint /tools/search nutzt dieselbe Toolkit-Suche und erhält die Modi apiv3, multi und batch. Eine mitgesendete unterstützte fuzziness-Option wird aus Kompatibilitätsgründen akzeptiert, aber nicht angewendet; die Antwort enthält fuzziness_not_supported_by_crm_suche. exactOnly wird mit 400 exact_only_not_supported abgewiesen.

Der entfernte Modus output: "elastic" antwortet mit 410 search_backend_removed. /tools/search/upsert antwortet deterministisch mit 410 search_index_managed_by_crm, weil crm_suche ausschließlich aus CRM-Schreibvorgängen und Rebuild-Werkzeugen gepflegt wird.