maintainkit maintainkit
Entrar
maintain-kit

Referência da API

Conecte seu ERP ou outros sistemas ao estoque do maintainkit — leia e grave estoque e receba webhooks quando ele mudar.

URL base

https://maintainkit.app/api/v1

Autenticação

Cada requisição precisa de uma chave de API, enviada como token bearer (ou o header X-API-Key).

Crie e gerencie chaves em API e webhooks. As chaves têm escopo somente leitura ou leitura e escrita, e só veem os dados da própria organização.

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

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

Convenções

  • Requisições e respostas são JSON. Respostas bem-sucedidas envolvem o resultado em um campo "data".
  • Referencie peças por id numérico ou por sku, e locais por id ou por nome.
  • Campos de dinheiro (unitCost) são centavos inteiros — 18500 significa $185,00.
  • Operações de escrita exigem uma chave de leitura e escrita; chaves somente leitura recebem 403.

Erros retornam o status HTTP correspondente e um envelope 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

Registrar movimentações de estoque

Envie POST /movements com um kind. Os totais são derivados deste histórico.

receive Adiciona estoque a um local (opcionalmente com unitCost).
consume Remove estoque de um local.
adjust Aplica uma correção com sinal (qtyDelta, + ou −).
count Define o estoque absoluto em um local (target).
transfer Move estoque de um local para outro.

Exemplo — receber 20 L em um local:

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 locais:

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

Webhooks

Registre endpoints em Configurações. Enviamos (POST) um evento JSON assinado no momento em que acontece (e reenviamos falhas com backoff).

stock.movement.created Qualquer mudança de estoque (receber, consumir, ajustar, contar, transferir).
stock.low O estoque caiu até ou abaixo do ponto de reposição.
part.created Uma peça foi criada.
part.updated Os dados de uma peça mudaram.

Cada entrega tem este formato:

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

Verifique a assinatura com o segredo do seu 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;

Endpoints saudáveis são chamados instantaneamente. Entregas com falha são reenviadas com backoff exponencial por várias horas.