API-Dokumentation

API-Dokumentation

Greifen Sie programmatisch auf Ihre Inventory-App-Daten uber unsere externe API zu.

Ubersicht

Was ist die API?

Die externe API bietet eine Schnittstelle fur den Zugriff auf Inventory-App-Daten von externen Programmen.

Anwendungsfalle

  • Automatisierung: Stapelverarbeitung von Dokumenten durch Skripte
  • Drittanbieter-Integration: Datensynchronisierung mit anderen Diensten
  • Massenoperationen: Massenhafte Vorlagenerstellung und -freigabe

Erste Schritte

API-Schlussel erhalten

Um die API zu nutzen, benotigen Sie zunachst einen API-Schlussel.

  1. Offnen Sie den Profil-Bildschirm in der Inventory-App
  2. Suchen Sie den API-Schlussel-Bereich
  3. Tippen Sie auf die Schaltflache Schlussel generieren
  4. Ihr API-Schlussel wird auf dem Bildschirm angezeigt

Wichtig: Der API-Schlussel wird bei der Generierung nur einmal angezeigt. Stellen Sie sicher, dass Sie ihn kopieren und an einem sicheren Ort aufbewahren. Bei Verlust muss er neu generiert werden.

API-Schlussel-Format

API-Schlussel folgen diesem Format:

inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Beginnt mit dem Prafix inv_
  • Etwa 50 Zeichen lange Base64URL-kodierte Zeichenkette

API-Schlussel verwalten

  • Neu generieren: Widerruft den vorhandenen Schlussel und stellt einen neuen aus
  • Loschen: Entfernt den API-Schlussel vollstandig (API-Zugriff deaktiviert)

Authentifizierung

Alle API-Anfragen erfordern einen Authorization-Header.

Bearer-Token

Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Anfrage-Beispiel

curl -H "Authorization: Bearer inv_your_api_key" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items"

Ratenbegrenzung

Die API-Nutzung unterliegt Beschrankungen.

Limittyp Schwellenwert Beschreibung
Pro Minute 60 Anfragen Verhindert ubermassige Anfragen
Monatlich Je nach Konto Durch Vertrag bestimmt

Bei Uberschreitung des Limits

  • HTTP-Statuscode 429 Too Many Requests wird zuruckgegeben
  • Bitte warten und spater erneut versuchen

API-Endpunkte

Basis-URL

https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1

Lese-APIs (GET)

Endpunkt Beschreibung
GET /items Ihre Artikel auflisten
GET /items/{token} Artikeldetails abrufen
GET /templates Ihre Vorlagen auflisten
GET /templates/{token} Vorlagendetails abrufen
GET /templates/shared Geteilte Vorlagen auflisten
GET /user/stats Benutzerstatistiken abrufen

Schreib-APIs (POST)

Endpunkt Beschreibung
POST /templates Neue Vorlage erstellen
POST /templates/{token}/share Vorlage teilen
POST /templates/revoke Freigabe widerrufen
POST /templates/{token}/send Vorlage senden

Detaillierte API-Referenz

GET /items - Artikel auflisten

Ruft eine Liste der Artikel (Dokumente) ab, die Sie besitzen.

Anfrage

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items?page=1&pageSize=20"

Abfrageparameter

Parameter Typ Standard Beschreibung
page number 1 Seitennummer
pageSize number 20 Artikel pro Seite (max 100)
status string “active” Statusfilter (active, pending)
type string - Typfilter (paper, stamp)

Antwort

{
  "success": true,
  "data": {
    "items": [
      {
        "token": "verschlusselte_artikel_id",
        "title": "Artikel-Titel",
        "content": "Artikel-Inhalt",
        "type": "paper",
        "status": "active",
        "imageUrl": "https://...",
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 50,
      "totalPages": 3
    }
  }
}

GET /items/{token} - Artikeldetails

Ruft detaillierte Informationen uber einen bestimmten Artikel ab.

Anfrage

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items/{token}"

Antwort

{
  "success": true,
  "data": {
    "token": "verschlusselte_artikel_id",
    "title": "Artikel-Titel",
    "content": "Artikel-Inhalt",
    "type": "paper",
    "status": "active",
    "imageUrl": "https://...",
    "keywords": ["schlussel:wert", "tag:beispiel"],
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

POST /templates - Vorlage erstellen

Erstellt eine neue Vorlage (Stempel).

Anfrage

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "imageUrl": "https://example.com/image.png",
       "title": "Vorlagen-Titel",
       "content": "Vorlagen-Inhalt",
       "commentMode": "independent",
       "keywords": ["produkt:laptop", "preis:$1500EUR$"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates"

Anfrage-Body

Feld Typ Erforderlich Beschreibung
imageUrl string Ja Bild-URL (HTTPS empfohlen)
title string Ja Titel (max 32 Zeichen)
content string Ja Inhalt (max 1024 Zeichen)
commentMode string Nein Kommentarmodus: “independent” oder “shared”
keywords string[] Nein Schlusselwort-Array (max 128)

Schlusselwort-Format

Schlusselworter mussen dem Format schlussel:wert folgen.

Typ Format Beispiel
Allgemein schlussel:wert produkt:stift
Datum schlussel:@YYYY-MM-DD@ start:@2025-01-15@
Telefon schlussel:#telefon# kontakt:#+49 170-1234567#
Ort schlussel:%adresse% ort:%Berlin, Mitte%
Betrag schlussel:$betragWahrung$ preis:$50000EUR$

Antwort

{
  "success": true,
  "data": {
    "token": "verschlusselte_vorlagen_id",
    "title": "Vorlagen-Titel",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

POST /templates/{token}/share - Vorlage teilen

Teilt eine Vorlage, damit andere Benutzer sie finden konnen.

Anfrage

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "durationMinutes": 1440,
       "tags": ["TAG1", "TAG2"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/share"

Anfrage-Body

Feld Typ Erforderlich Beschreibung
durationMinutes number Ja Freigabedauer (Minuten). 60-43200 oder 0 (unbegrenzt)
tags string[] Ja Such-Tags (1-16, automatische Grossschreibung)

Antwort

{
  "success": true,
  "data": {
    "shareToken": "verschlusselter_freigabe_id",
    "expiresAt": "2025-01-02T00:00:00Z",
    "tags": ["TAG1", "TAG2"]
  }
}

Fehlercodes

Bei fehlgeschlagenen API-Anfragen werden Fehler in diesem Format zuruckgegeben:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Fehlerbeschreibung"
  }
}

Fehlercode-Liste

Code HTTP-Status Beschreibung
INVALID_API_KEY 401 Ungultiger API-Schlussel
API_KEY_EXPIRED 401 Abgelaufener API-Schlussel
API_DISABLED 403 API deaktiviert
RATE_LIMIT_EXCEEDED 429 Anfragelimit uberschritten
VALIDATION_ERROR 400 Ungultige Eingabe
INVALID_TOKEN 400 Ungultiges Token
NOT_FOUND 404 Ressource nicht gefunden
FORBIDDEN 403 Zugriff verweigert
RECIPIENT_NOT_FOUND 404 Empfanger nicht gefunden

Sicherheitsempfehlungen

  1. API-Schlussel schutzen: API-Schlussel niemals in offentlichen Repositories oder Client-Code offenlegen
  2. HTTPS verwenden: Alle Anfragen werden uber HTTPS ubertragen
  3. Schlusselrotation: API-Schlussel regelmaszig neu generieren
  4. Minimale Berechtigungen: Nur notwendige Operationen durchfuhren

Kontakt

Bei Problemen mit der API-Nutzung kontaktieren Sie uns bitte uber die Vorschlage-Seite.