maintainkit maintainkit
Se connecter
maintain-kit

Référence de l'API

Connectez votre ERP ou d'autres systèmes au stock de maintainkit — lisez et écrivez le stock, et recevez des webhooks quand il change.

URL de base

https://maintainkit.app/api/v1

Authentification

Chaque requête nécessite une clé API, envoyée en jeton bearer (ou l'en-tête X-API-Key).

Créez et gérez les clés dans API et webhooks. Les clés ont une portée lecture seule ou lecture et écriture, et ne voient que les données de leur propre organisation.

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

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

Conventions

  • Les requêtes et réponses sont en JSON. Les réponses réussies encapsulent le résultat dans un champ "data".
  • Référencez les pièces par id numérique ou par sku, et les emplacements par id ou par nom.
  • Les champs monétaires (unitCost) sont des centimes entiers — 18500 signifie 185,00 $.
  • Les opérations d'écriture nécessitent une clé lecture et écriture ; les clés en lecture seule reçoivent 403.

Les erreurs renvoient le statut HTTP correspondant et une enveloppe JSON :

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

Endpoints

Parts

GET /parts
POST /parts
GET /parts/:id
PATCH /parts/:id

Locations

GET /locations
POST /locations

Stock

GET /stock

Movements

GET /movements
POST /movements

Enregistrer des mouvements de stock

Envoyez POST /movements avec un kind. Les totaux sont dérivés de cet historique.

receive Ajoute du stock à un emplacement (avec unitCost en option).
consume Retire du stock d'un emplacement.
adjust Applique une correction signée (qtyDelta, + ou −).
count Définit le stock absolu à un emplacement (target).
transfer Déplace du stock d'un emplacement à un autre.

Exemple — réceptionner 20 L à un emplacement :

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" } }

Transférer entre emplacements :

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

Webhooks

Enregistrez des endpoints dans les Paramètres. Nous envoyons (POST) un événement JSON signé dès qu'il se produit (et réessayons les échecs avec backoff).

stock.movement.created Tout changement de stock (réception, consommation, ajustement, comptage, transfert).
stock.low Le stock est descendu au niveau du seuil de réapprovisionnement ou en dessous.
part.created Une pièce a été créée.
part.updated Les détails d'une pièce ont changé.

Chaque livraison ressemble à ceci :

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" }
}

Vérifiez la signature avec le secret de votre webhook :

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;

Les endpoints sains sont appelés instantanément. Les livraisons échouées sont réessayées avec un backoff exponentiel pendant plusieurs heures.