> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.go-lizard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Referenz

> Vollständige Dokumentation der LizardPro API Endpunkte.

# Entwickler-API & Schnittstellen

Die LizardPro API ermöglicht den programmatischen Zugriff auf deine Daten. Sie folgt REST-Prinzipien und verwendet Standard-HTTP-Methoden sowie JSON für den Datenaustausch.

<Note>
  Diese Dokumentation richtet sich an Entwickler und IT-Administratoren, die LizardPro in ihre eigene Softwarelandschaft integrieren möchten.
</Note>

## Authentifizierung

Alle Anfragen an die API müssen authentifiziert werden. Wir verwenden **Bearer Tokens**.

Füge deinen API-Token in den `Authorization` Header jeder Anfrage ein:

```bash theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

<Warning>
  Dein API-Token gewährt vollen Zugriff auf dein Benutzerkonto. Teile ihn niemals und veröffentliche ihn nicht in client-seitigem Code (z.B. JavaScript im Browser).
</Warning>

### Token erstellen

1. Gehe zu deinem **Benutzer-Profil**.
2. Navigiere zu **API-Tokens**.
3. Klicke auf **Token erstellen**.
4. Gib dem Token einen Namen (z.B. "Webshop Integration").
5. Kopiere den Token. Er wird **nie wieder** vollständig angezeigt.

***

## Items

Verwalte deine Inventargegenstände (Items).

### Items auflisten

Rufe eine paginierte Liste aller Items ab.

<ParamField query="sort" type="string">
  Sortierung der Ergebnisse. Beispiele: `name`, `-created_at`, `updated_at`.
</ParamField>

<ParamField query="filter[status]" type="string">
  Filtert nach Status (z.B. `active`, `archived`).
</ParamField>

<ParamField query="filter[company_id]" type="string">
  Filtert nach Unternehmens-ID.
</ParamField>

<ParamField query="filter[number]" type="string">
  Filtert nach Item-Nummer.
</ParamField>

<ParamField query="include" type="string">
  Komma-separierte Liste von Relationen, die in der Antwort enthalten sein sollen. Siehe [Relationen einbinden](#relationen-einbinden).
</ParamField>

```http theme={null}
GET /api/items
```

### Einzelnes Item abrufen

<ParamField path="item" type="string" required>
  Die UUID des Items.
</ParamField>

<ParamField query="include" type="string">
  Komma-separierte Liste von Relationen. Siehe [Relationen einbinden](#relationen-einbinden).
</ParamField>

```http theme={null}
GET /api/items/{item}
```

### Relationen einbinden

Über den `include`-Query-Parameter kannst du gezielt Relationen eines Items laden. So reduzierst du die Antwortgröße auf das, was du tatsächlich benötigst.

**Verfügbare Relationen:**

| Relation               | Beschreibung                             |
| :--------------------- | :--------------------------------------- |
| `compliances`          | Zugeordnete Compliance-Regelwerke.       |
| `category`             | Kategorie des Items.                     |
| `inspectionCategory`   | Prüfkategorie des Items.                 |
| `location`             | Standort des Items.                      |
| `user`                 | Zuständiger Benutzer.                    |
| `dyntags`              | Verknüpfte DynTags.                      |
| `dataAttributes`       | Alle Eigenschaften mit Felddefinitionen. |
| `searchableAttributes` | Nur durchsuchbare Eigenschaften.         |

<Tip>
  Mehrere Relationen werden komma-separiert übergeben, z. B. `?include=category,location,dyntags`.
</Tip>

```http theme={null}
GET /api/items?include=category,location,dataAttributes
GET /api/items/{item}?include=compliances,inspectionCategory,dyntags
```

### Item erstellen

Erstellt ein neues Item.

<ParamField body="name" type="string" required>
  Der Name des Items. Max. 255 Zeichen.
</ParamField>

<ParamField body="number" type="string">
  Eine eindeutige Nummer für das Item.
</ParamField>

<ParamField body="category_id" type="string" required>
  Die UUID der Kategorie.
</ParamField>

<ParamField body="location_id" type="string">
  Die UUID des Standorts.
</ParamField>

```http theme={null}
POST /api/items
```

<Note>
  Wenn du `dataAttributes` übergibst, müssen die Schlüssel gültige Attribut-UUIDs sein. Ungültige IDs führen zu einem `422`-Fehler mit Hinweis auf die betroffene ID.
</Note>

### DynTag mit Item verknüpfen

Verknüpft einen physischen DynTag (oder externen Code/NFC) mit einem bestehenden Item.

<ParamField body="item_id" type="string" required>
  Die UUID des Items.
</ParamField>

<ParamField body="dyntag_short_id" type="string" required>
  Die Short-ID des DynTags (z.B. `kP1IMzcH5z` oder die ganze URL).
</ParamField>

```http theme={null}
POST /api/items/link-dyntag
```

<Info>
  Diese API-Route übernimmt automatisch die externe Validierung und Verknüpfung mit dem DynTag-Dienst. Archivierte Items können nicht verknüpft werden (`422 Unprocessable Entity`).
</Info>

### Item aktualisieren

<ParamField path="item" type="string" required>
  Die UUID des Items.
</ParamField>

<ParamField body="name" type="string">
  Der neue Name des Items.
</ParamField>

<ParamField body="status" type="string">
  Der neue Status.
</ParamField>

```http theme={null}
PUT /api/items/{item}
```

<Note>
  Wenn du `dataAttributes` übergibst, müssen die Schlüssel gültige Attribut-UUIDs sein. Ungültige IDs führen zu einem `422`-Fehler mit Hinweis auf die betroffene ID.
</Note>

***

## Item Eigenschaften (Attribute)

Verwalte die dynamischen Attribute eines Items.

### Attribute auflisten

Gibt alle Attribute eines Items zurück.

<ParamField path="item" type="string" required>
  Die UUID des Items.
</ParamField>

```http theme={null}
GET /api/items/{item}/attributes
```

### Attribut aktualisieren

Setzt den Wert eines spezifischen Attributs.

<ParamField path="item" type="string" required>
  Die UUID des Items.
</ParamField>

<ParamField path="attribute" type="string" required>
  Die UUID des Attributs (nicht des Feldes).
</ParamField>

<ParamField body="value" type="string" required>
  Der neue Wert. Bei Datei-Uploads muss dies ein Multipart-Request sein.
</ParamField>

```http theme={null}
PUT /api/items/{item}/attributes/{attribute}
```

<Info>
  Änderungen an Eigenschaften, die über die API vorgenommen werden (z. B. Seriennummern oder Baujahre), werden im Verlauf des Betriebsmittels erfasst. So kannst du jederzeit nachvollziehen, wann welche Werte angepasst wurden – auch wenn die Änderungen aus angebundenen Systemen stammen.
</Info>

***

## Prüfungen & Ergebnisse

Dokumentiere Prüfergebnisse für Items.

### Ergebnisse auflisten

<ParamField path="item" type="string" required>
  Die UUID des Items.
</ParamField>

<ParamField query="filter[status]" type="string">
  Filter z.B. nach `passed`, `failed`.
</ParamField>

```http theme={null}
GET /api/items/{item}/inspection-results
```

### Ergebnisse erstellen

Fügt einem Item ein neues Prüfergebnis hinzu.

<ParamField path="item" type="string" required>
  Die UUID des Items.
</ParamField>

<ParamField body="title" type="string" required>
  Titel der Prüfung (z.B. "Jahresprüfung 2024").
</ParamField>

<ParamField body="status" type="string" required>
  Status des Ergebnisses: `passed`, `failed`, `visual_defect`, oder andere definierte Status.
</ParamField>

<ParamField body="last_inspection_at" type="string" format="date-time" required>
  Datum und Uhrzeit der Prüfung (ISO 8601).
</ParamField>

<ParamField body="inspection_interval" type="integer" required>
  Das Intervall bis zur nächsten Prüfung in Monaten.
</ParamField>

<ParamField body="inspector_name" type="string">
  Name des Prüfers.
</ParamField>

<ParamField body="file" type="binary">
  Optional: Prüfbericht als Datei (Multipart-Upload).
</ParamField>

```http theme={null}
POST /api/items/{item}/inspection-results
```

***

## Stammdaten

Hilfreiche Endpunkte für Dropdowns und Validierungen.

### Kategorien (Categories)

<ParamField query="filter[name]" type="string">
  Suche nach Kategorienamen.
</ParamField>

```http theme={null}
GET /api/categories
```

### Standorte (Locations)

<ParamField query="filter[name]" type="string">
  Suche nach Standortnamen.
</ParamField>

```http theme={null}
GET /api/locations
```

**Standort erstellen**

<ParamField body="name" type="string" required>
  Name des Standorts.
</ParamField>

```http theme={null}
POST /api/locations
```

### Collaborations (Zusammenarbeiten)

Verwalte Firmen-Zusammenarbeiten und Freigaben.

**Collaborations auflisten**

Gibt eine Liste aller bestehenden Zusammenarbeiten inklusive der Partner zurück.

<ParamField query="filter[company_id]" type="string">
  Suche nach spezifischer Company ID.
</ParamField>

<ParamField query="filter[name]" type="string">
  Suche im Namen der Collaboration.
</ParamField>

```http theme={null}
GET /api/collaborations
```

### Partner

Verwalte Kunden oder Partnerfirmen.

```http theme={null}
GET /api/partners
```

**Partner erstellen**

<ParamField body="company" type="string" required>
  Name der Firma.
</ParamField>

<ParamField body="customer_number" type="string">
  Kundennummer.
</ParamField>

```http theme={null}
POST /api/partners
```

### Qualifikationen

Liste aller verfügbaren Qualifikationen.

```http theme={null}
GET /api/qualifications
```

### Produkte & Services

Liste von Produkten und Dienstleistungen.

```http theme={null}
GET /api/product-services
```

***

## Felder & Metadaten

### Attribut-Felder

Definitionen der dynamischen Felder.

```http theme={null}
GET /api/attribute-fields
```

### Inspektions-Kategorien

Kategorien für Prüfungen.

```http theme={null}
GET /api/inspection-categories
```

### Compliance

Verfügbare Compliance-Regelwerke.

```http theme={null}
GET /api/compliances
```

***

## Öffentliche Item-Daten

Dieser Endpunkt gibt öffentlich freigegebene Informationen eines Items zurück – **ohne Authentifizierung**. Er eignet sich für QR-Code-Landingpages, öffentliche Statusseiten oder die Integration in externe Systeme.

```http theme={null}
GET /i/{item}/json
```

<Note>
  Die `{item}` ID entspricht der UUID oder Short-ID des Items, wie sie z. B. auf einem DynTag hinterlegt ist.
</Note>

**Antwortstruktur:**

<ResponseField name="id" type="string">
  Die UUID des Items.
</ResponseField>

<ResponseField name="status" type="string">
  Aktueller Status (z. B. `active`).
</ResponseField>

<ResponseField name="name" type="string">
  Bezeichnung des Items.
</ResponseField>

<ResponseField name="number" type="string">
  Betriebsmittel-Nummer.
</ResponseField>

<ResponseField name="user" type="string">
  Name des zuständigen Benutzers. Wird **nur** ausgegeben, wenn der anfragende Nutzer angemeldet und dem Betriebsmittel zugehörig ist (gleiches Unternehmen oder über eine Kollaboration verbunden). Für Gäste und fremde Nutzer ist das Feld `null`.
</ResponseField>

<ResponseField name="inspections" type="array">
  Nicht-archivierte Prüfergebnisse, sortiert nach Prüfdatum (neueste zuerst). Jeder Eintrag enthält `title`, `inspector_name`, `last_inspection_at`, `next_inspection_at`, `status` und `status_label`.
</ResponseField>

<ResponseField name="public_properties" type="object">
  Öffentlich sichtbare Eigenschaften des Items als Schlüssel-Wert-Paare (z. B. `"Gewicht": "150 kg"`).
</ResponseField>

<ResponseField name="public_documents" type="array">
  Öffentlich freigegebene Dokumente und Dokumente aus öffentlichen Dokumentenordnern. Jeder Eintrag enthält `name` und `url`.
</ResponseField>

<Accordion title="Beispielantwort">
  ```json theme={null}
  {
    "id": "a1b2c3d4-...",
    "status": "active",
    "name": "Kran A-12",
    "number": "BM-00123",
    "user": "Max Mustermann",
    "inspections": [
      {
        "title": "Jahresprüfung 2026",
        "inspector_name": "Anna Schmidt",
        "last_inspection_at": "2026-03-15",
        "next_inspection_at": "2027-03-15",
        "status": "passed",
        "status_label": "Bestanden"
      }
    ],
    "public_properties": {
      "Tragfähigkeit": "5000 kg",
      "Baujahr": "2019"
    },
    "public_documents": [
      {
        "name": "Sicherheitsdatenblatt",
        "url": "https://..."
      }
    ]
  }
  ```
</Accordion>

<Warning>
  Dieser Endpunkt ist öffentlich zugänglich. Es werden ausschließlich Daten zurückgegeben, die als „öffentlich" markiert sind (öffentliche Eigenschaften, öffentliche Dokumente und Dokumentenordner).
</Warning>

***

## Benutzer

### Eigenes Profil

Gibt Informationen über den aktuell authentifizierten Benutzer zurück, einschließlich seiner `company_id`.

```http theme={null}
GET /api/user
```