Documentație API Extern

Ghid de integrare pentru vânzători externi

URL de bază: https://api.kstock.roVersiune 1.0

Autentificare

Fiecare cerere trebuie să includă cheia API în header-ul X-API-Key:

http

X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Pentru endpoint-ul de creare comandă, cheia poate fi trimisă alternativ în corpul JSON ca "key". Header-ul are prioritate dacă sunt prezente ambele.

Cheia API este generată de operatorul KStock la înregistrarea companiei dumneavoastră. Păstrați-o în siguranță — oferă acces complet la produse, stoc și gestionarea comenzilor.

Endpoint-uri

GET/api/external/v1/productsListare produse (paginat)

GET/api/external/v1/products/by-sku/:skuProdus după SKU

GET/api/external/v1/products/by-ean/:eanCodeProdus după EAN

GET/api/external/v1/products/stock-statusSumar stoc depozite

POST/api/external/v1/seller-ordersCreare comandă

PATCH/api/external/v1/seller-orders/:orderIdExternalModificare comandă

DELETE/api/external/v1/seller-orders/:orderIdExternalAnulare comandă

1. Listare Produse

Returnează o listă paginată cu toate produsele și stocul disponibil din toate depozitele.

GET/api/external/v1/products

Parametri Query

Parametru	Tip	Implicit	Descriere
page	integer	1	Numărul paginii
pageSize	integer	50	Produse per pagină (max 200)
q	string	—	Căutare după nume sau SKU
location	integer	—	Filtrare pe un singur depozit

Exemplu

bash

curl -X GET "https://api.kstock.ro/api/external/v1/products?page=1&pageSize=20&q=covor" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Răspuns

json

{
  "status": true,
  "data": [
    {
      "sku": "CTG2374",
      "name": "Covor tip granit #2",
      "eanCode": "5942724651876",
      "price": 25.15,
      "image": "https://storage.kstock.ro/products/67628c11e59e4ba2bfff86ac/1774360183744.png",
      "totalStock": 150,
      "availableStock": 145,
      "blocked": 5,
      "locations": [
        { "locationId": 3, "locationName": "Depozitul de sare", "stock": 100 },
        { "locationId": 5, "locationName": "Depozit Central", "stock": 50 }
      ]
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "totalItems": 1245, "totalPages": 63 }
}

2. Căutare Produs după SKU

GET/api/external/v1/products/by-sku/:sku

Returnează informațiile unui produs identificat prin codul SKU, cu stoc agregat din toate depozitele.

bash

curl -X GET "https://api.kstock.ro/api/external/v1/products/by-sku/CTG2374" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Parametru opțional: ?location=3 pentru filtrare pe un depozit specific.

3. Căutare Produs după EAN

GET/api/external/v1/products/by-ean/:eanCode

Returnează produsul identificat prin codul de bare EAN (exact 13 cifre).

bash

curl -X GET "https://api.kstock.ro/api/external/v1/products/by-ean/5942724651876" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

4. Sumar Stoc

GET/api/external/v1/products/stock-status

Imagine de ansamblu a stocului din toate depozitele, inclusiv detaliu per depozit.

bash

curl -X GET "https://api.kstock.ro/api/external/v1/products/stock-status" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Răspuns

json

{
  "status": true,
  "data": {
    "filter": "all_warehouses",
    "summary": {
      "totalProducts": 1245,
      "totalStock": 54320,
      "totalBlocked": 120,
      "totalAvailable": 54200,
      "lowStockItems": 38,
      "outOfStockItems": 12
    },
    "locations": [
      { "locationId": 3, "locationName": "Depozitul de sare", "totalProducts": 1100, "totalStock": 40000 },
      { "locationId": 5, "locationName": "Depozit Central", "totalProducts": 820, "totalStock": 14320 }
    ]
  }
}

5. Creare Comandă

POST/api/external/v1/seller-orders

Înregistrează o comandă deja finalizată (ambalată și expediată). Stocul este redus imediat din toate depozitele disponibile.

Corp Cerere

Câmp	Tip	Obligatoriu	Descriere
key	string	da	Cheia API (alternativă la header)
orderIdExternal	string	da	ID unic al comenzii (deduplicare)
products	array	da	Lista de produse (1–200)
orderName	string	nu	Numele clientului final
orderPhone	string	nu	Telefonul clientului final
awb	string	nu	Număr AWB / tracking
paymentType	string	nu	Tipul plății
orderNote	string	nu	Observații suplimentare

Lista de Produse

Câmp	Tip	Obligatoriu	Descriere
sku	string	da	Codul SKU (trebuie să existe în KStock)
qty	integer	da	Cantitatea (≥ 1)

Prețurile și facturarea sunt gestionate integral de KStock pe baza catalogului intern. Nu trebuie să trimiteți prețuri.

Exemplu

bash

curl -X POST "https://api.kstock.ro/api/external/v1/seller-orders" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "orderIdExternal": "WEB-20260401-0042",
    "products": [
      { "sku": "CTG2374", "qty": 3 },
      { "sku": "CMP5189", "qty": 1 }
    ]
  }'

Răspuns Succes (201)

json

{
  "status": true,
  "data": {
    "orderId": "665f1a2b3c4d5e6f7a8b9c0d",
    "receivedAt": "2026-04-01T14:23:45.123Z"
  }
}

Important: orderId din răspuns este ID-ul intern KStock (MongoDB). Pentru cererile PATCH și DELETE folosiți întotdeauna orderIdExternal — valoarea pe care ați trimis-o la creare (ex: WEB-20260401-0042). Salvați orderId doar pentru referință și suport tehnic.

6. Modificare Comandă

PATCH/api/external/v1/seller-orders/:orderIdExternal

Înlocuiește lista de produse a unei comenzi existente. KStock ajustează stocul automat (restituie produse eliminate, deduce produse noi, aplică diferențe de cantitate). Doar comenzile nefacturate pot fi modificate.

URL corect: asigurați-vă că folosiți endpoint-ul extern /api/external/v1/seller-orders/.... Apelurile la /api/orders/... (ruta internă) returnează „Unauthorized: Valid JWT token or API key required" deoarece cheia ks-online- nu este validă acolo.

Identificatorul din URL trebuie să fie orderIdExternal — valoarea pe care ați trimis-o la creare (ex: WEB-20260401-0042), nu orderId din răspunsul POST (care este ID-ul intern MongoDB).

Notă: Cheia API trebuie trimisă în header-ul X-API-Key pentru PATCH. Câmpul key din body funcționează doar la POST (creare comandă), nu și la PATCH.

Corp Cerere

Câmp	Tip	Obligatoriu	Descriere
products	array	da	Noua listă completă de produse
products[].sku	string	da	Codul SKU
products[].qty	integer	da	Cantitatea (≥ 1)

Exemplu

bash

curl -X PATCH "https://api.kstock.ro/api/external/v1/seller-orders/WEB-20260401-0042" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      { "sku": "CTG2374", "qty": 5 },
      { "sku": "CMP6200", "qty": 2 }
    ]
  }'

Răspuns Succes (200)

json

{
  "status": true,
  "data": {
    "orderId": "665f1a2b3c4d5e6f7a8b9c0d",
    "updatedAt": "2026-04-01T15:00:00.000Z"
  }
}

7. Anulare Comandă

DELETE/api/external/v1/seller-orders/:orderIdExternal

Anulează o comandă și restituie tot stocul în depozite. Doar comenzile nefacturate pot fi anulate.

Identificatorul din URL trebuie să fie orderIdExternal — valoarea pe care ați trimis-o la creare (ex: WEB-20260401-0042), nu orderId din răspunsul POST. Utilizarea orderId (ID-ul intern MongoDB) returnează eroarea E1201 — Order not found.

bash

curl -X DELETE "https://api.kstock.ro/api/external/v1/seller-orders/WEB-20260401-0042" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Răspuns Succes (200)

json

{
  "status": true,
  "data": {
    "orderId": "665f1a2b3c4d5e6f7a8b9c0d",
    "cancelledAt": "2026-04-01T15:30:00.000Z"
  }
}

După anulare, orderIdExternal poate fi reutilizat pentru o comandă nouă.

Coduri de Eroare

Cod	HTTP	Semnificație
E1103	409	Comandă duplicat
E1107	400	SKU necunoscut sau eroare de stoc
E1201	404	Produs sau comandă negăsită
E1203	400	Format EAN invalid (trebuie 13 cifre)
E1301	400	Validare eșuată
E1501	401	Cheie API lipsă sau invalidă
E1503	403	Cheie neasociată sau companie inactivă
E1504	403	Comandă facturată / permisiuni insuficiente
E1601	500	Eroare internă de server

Flux Tipic de Integrare

Sincronizare catalog

Periodic (la câteva ore), apelați GET /products pentru a menține catalogul și stocul actualizat.

GET/products

Verificare stoc

Înainte de ambalare, verificați disponibilitatea produsului în timp real.

GET/products/by-sku/:sku

Înregistrare comandă

După ambalare și generare AWB, trimiteți comanda. Stocul se reduce imediat.

POST/seller-orders

Corecție (dacă e necesar)

Modificați produsele sau anulați comanda. Folosiți orderIdExternal (valoarea trimisă la creare) în URL — nu orderId. Stocul se ajustează automat.

PATCH/seller-orders/:orderIdExternal

Verificare

Salvați orderId din răspuns pentru referință și suport. Dacă primiți 409, comanda a fost deja înregistrată (retry sigur).

Bune Practici

1Sincronizați produsele periodic — apelați GET /products la câteva ore pentru catalog actualizat.

2Verificați stocul înainte de comandă — GET /products/by-sku/:sku confirmă disponibilitatea.

3Folosiți orderIdExternal unic — permite retrimiteri sigure (409 în loc de duplicat).

4Salvați orderId din răspuns — este ID-ul intern KStock, util doar pentru suport tehnic. Nu îl folosiți ca identificator în cererile PATCH/DELETE.

5Folosiți orderIdExternal în URL pentru PATCH și DELETE — valoarea trimisă la creare (ex: WEB-20260401-0042), nu orderId.

6Cheia API merge în X-API-Key header pentru PATCH și DELETE. Câmpul key din body funcționează doar la POST.

7SKU-urile sunt case-insensitive — API-ul normalizează la majuscule intern.

8Comenzile facturate nu pot fi modificate — corectați înainte de facturare.

9Stocul se deduce din toate depozitele — nu trebuie să specificați depozitul.

Test Rapid

Verificați că cheia API funcționează:

bash

curl -s "https://api.kstock.ro/api/external/v1/products/stock-status" \
  -H "X-API-Key: ks-online-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | python3 -m json.tool

Dacă vedeți "status": true cu date de stoc, conexiunea este funcțională.

KStock API v1.0 — Pentru asistență contactați echipa de operare KStock.