Referencia de la API

Conecta tu ERP u otros sistemas al inventario de maintainkit — lee y escribe existencias, y recibe webhooks cuando cambian.

URL base

https://maintainkit.app/api/v1

Autenticación

Cada solicitud necesita una llave de API, enviada como token bearer (o el header X-API-Key).

Crea y administra llaves en API y webhooks. Las llaves tienen alcance de solo lectura o lectura y escritura, y solo ven los datos de su propia organización.

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

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

Convenciones

Las solicitudes y respuestas son JSON. Las respuestas exitosas envuelven el resultado en un campo "data".
Referencia las refacciones por id numérico o por sku, y las ubicaciones por id o por nombre.
Los campos de dinero (unitCost) son centavos enteros — 18500 significa $185.00.
Las operaciones de escritura requieren una llave de lectura y escritura; las de solo lectura reciben 403.

Los errores devuelven el estado HTTP correspondiente y un sobre JSON:

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

Endpoints

Parts

GET /parts Lista todas las refacciones con existencias totales

POST /parts Crea una refacción

GET /parts/:id Obtiene una refacción con existencias por ubicación

PATCH /parts/:id Actualiza una refacción (nombre, mín, costo, notas)

Locations

GET /locations Lista ubicaciones

POST /locations Crea una ubicación

Stock

GET /stock Existencias disponibles, filtra por refacción o ubicación

Movements

GET /movements Lista el historial de movimientos

POST /movements Registra un movimiento de existencias

Registrar movimientos de existencias

Envía POST /movements con un kind. Los totales se derivan de este historial.

receive Agrega existencias a una ubicación (opcionalmente con unitCost).

consume Quita existencias de una ubicación.

adjust Aplica una corrección con signo (qtyDelta, + o −).

count Fija las existencias absolutas en una ubicación (target).

transfer Mueve existencias de una ubicación a otra.

Ejemplo — recibir 20 L en una ubicación:

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

Transferir entre ubicaciones:

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

Webhooks

Registra endpoints en Configuración. Enviamos (POST) un evento JSON firmado en el momento en que ocurre (y reintentamos las fallas con backoff).

stock.movement.created Cualquier cambio de existencias (recibir, consumir, ajustar, contar, transferir).

stock.low Las existencias bajaron a o por debajo del punto de reorden.

part.created Se creó una refacción.

part.updated Cambiaron los datos de una refacción.

Cada entrega se ve así:

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

Verifica la firma con tu secreto de 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;

Los endpoints sanos se llaman al instante. Las entregas fallidas se reintentan con backoff exponencial durante varias horas.