API-Referenz

Verbinde dein ERP oder andere Systeme mit dem maintainkit-Bestand — Bestand lesen und schreiben und Webhooks bei Änderungen empfangen.

Basis-URL

https://maintainkit.app/api/v1

Authentifizierung

Jede Anfrage benötigt einen API-Schlüssel, gesendet als Bearer-Token (oder Header X-API-Key).

Schlüssel erstellen und verwalten in API & Webhooks. Schlüssel haben den Geltungsbereich Nur-Lesen oder Lesen & Schreiben und sehen nur die Daten der eigenen Organisation.

curl https://maintainkit.app/api/v1/parts \
  -H "Authorization: Bearer mk_live_xxxxxxxx"

# or:  -H "X-API-Key: mk_live_xxxxxxxx"

Konventionen

Anfragen und Antworten sind JSON. Erfolgreiche Antworten verpacken das Ergebnis in einem "data"-Feld.
Referenziere Teile per numerischer id oder sku, und Standorte per id oder Name.
Geldfelder (unitCost) sind ganzzahlige Cent — 18500 bedeutet 185,00 $.
Schreiboperationen brauchen einen Lesen-&-Schreiben-Schlüssel; Nur-Lese-Schlüssel erhalten 403.

Fehler geben den passenden HTTP-Status und einen JSON-Umschlag zurück:

{ "error": { "code": "unprocessable", "message": "`sku` and `name` are required." } }

Endpoints

Parts

GET /parts Listet alle Teile mit Bestandssummen

POST /parts Erstellt ein Teil

GET /parts/:id Holt ein Teil mit Bestand je Standort

PATCH /parts/:id Aktualisiert ein Teil (Name, Min, Kosten, Notizen)

Locations

GET /locations Listet Standorte

POST /locations Erstellt einen Standort

Stock

GET /stock Bestände, filterbar nach Teil oder Standort

Movements

GET /movements Listet den Bewegungsverlauf

POST /movements Erfasst eine Bestandsbewegung

Bestandsbewegungen erfassen

Sende POST /movements mit einem kind. Die Summen werden aus diesem Verlauf abgeleitet.

receive Fügt Bestand an einem Standort hinzu (optional mit unitCost).

consume Entfernt Bestand von einem Standort.

adjust Wendet eine vorzeichenbehaftete Korrektur an (qtyDelta, + oder −).

count Setzt den absoluten Bestand an einem Standort (target).

transfer Verschiebt Bestand von einem Standort zu einem anderen.

Beispiel — 20 L an einem Standort buchen:

curl -X POST https://maintainkit.app/api/v1/movements \
  -H "Authorization: Bearer mk_live_xxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "kind": "receive",
    "sku": "OIL-15W40",
    "location": "Almacén Central",
    "qty": 20,
    "unitCost": 18500
  }'

# → { "data": { "partId": 3, "sku": "OIL-15W40", "onHand": 20, "unit": "L" } }

Zwischen Standorten umlagern:

{ "kind": "transfer", "sku": "OIL-15W40",
  "from": "Almacén Central", "to": "Camioneta de Alice", "qty": 5 }

Webhooks

Registriere Endpoints in den Einstellungen. Wir senden (POST) ein signiertes JSON-Event im Moment des Ereignisses (und wiederholen Fehler mit Backoff).

stock.movement.created Jede Bestandsänderung (Eingang, Verbrauch, Anpassung, Zählung, Umlagerung).

stock.low Der Bestand ist auf oder unter den Meldebestand gefallen.

part.created Ein Teil wurde erstellt.

part.updated Die Details eines Teils haben sich geändert.

Jede Zustellung sieht so aus:

POST  (your endpoint)
X-MK-Event: stock.movement.created
X-MK-Signature: sha256=<hmac>

{
  "event": "stock.movement.created",
  "orgId": 1,
  "createdAt": 1780517417000,
  "data": { "partId": 3, "sku": "OIL-15W40", "locationId": 2,
            "qtyDelta": -2, "kind": "consume", "onHand": 18, "unit": "L" }
}

Verifiziere die Signatur mit deinem Webhook-Secret:

import { createHmac } from 'node:crypto';

const expected = 'sha256=' + createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)            // the exact bytes received
  .digest('hex');
const ok = request.headers['x-mk-signature'] === expected;

Gesunde Endpoints werden sofort aufgerufen. Fehlgeschlagene Zustellungen werden mehrere Stunden lang mit exponentiellem Backoff wiederholt.