{"openapi":"3.1.0","info":{"title":"e-furnizori Public API","description":"\nAPI public pentru platforma B2B marketplace e-furnizori.\n\n## Autentificare\n\nAPI-ul suporta doua metode de autentificare:\n\n1. **API Key in Header**: `X-API-Key: efz_your_key_here`\n2. **Bearer Token**: `Authorization: Bearer efz_your_key_here`\n\nFara API key, cererile sunt limitate la 30-60 pe minut per IP.\nCu API key, poti face pana la 1000 cereri pe ora (sau mai multe, in functie de plan).\n\n## Rate Limiting\n\n| Tip | Limita | Fereastra |\n|-----|--------|-----------|\n| Fara API Key | 30-60 req | per minut |\n| API Key Basic | 1000 req | per ora |\n| API Key Pro | 5000 req | per ora |\n\nHeadere de rate limit:\n- `X-RateLimit-Limit`: Limita totala\n- `X-RateLimit-Remaining`: Cereri ramase\n- `X-RateLimit-Reset`: Timestamp reset (Unix ms)\n\n## Paginare\n\nEndpoint-urile care returneaza liste suporta paginare:\n\n```\nGET /api/products?page=1&limit=20\n```\n\nRaspunsul include metadata:\n```json\n{\n  \"success\": true,\n  \"data\": [...],\n  \"meta\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"total\": 150,\n    \"totalPages\": 8\n  }\n}\n```\n\n## Coduri de Eroare\n\n| Cod | Descriere |\n|-----|-----------|\n| 400 | Bad Request - Parametri invalizi |\n| 401 | Unauthorized - API key lipsa sau invalid |\n| 403 | Forbidden - Permisiuni insuficiente |\n| 404 | Not Found - Resursa nu exista |\n| 429 | Too Many Requests - Rate limit depasit |\n| 500 | Server Error - Eroare interna |\n    ","version":"1.0.0","contact":{"name":"e-furnizori Developer Support","email":"developers@e-furnizori.ro","url":"https://e-furnizori.ro/developers"},"license":{"name":"Proprietar","url":"https://e-furnizori.ro/terms"}},"servers":[{"url":"https://e-furnizori.ro","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"tags":[{"name":"Products","description":"Operatiuni cu produse"},{"name":"Categories","description":"Categorii de produse"},{"name":"Suppliers","description":"Furnizori verificati"},{"name":"Orders","description":"Gestiunea comenzilor (necesita autentificare)"},{"name":"Reviews","description":"Recenzii produse si furnizori"},{"name":"Stock","description":"Proiectie read-only a stocurilor (necesita read:stock)"},{"name":"Prices","description":"Proiectie read-only a preturilor (necesita read:prices)"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API Key in header X-API-Key. Scopes: read:products, read:categories, read:suppliers, read:orders, read:reviews, read:stock, read:prices, write:orders, write:products, admin:all."},"BearerAuth":{"type":"http","scheme":"bearer","description":"API Key as Bearer token"}},"schemas":{"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":150},"totalPages":{"type":"integer","example":8}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Produsul nu a fost gasit"},"details":{"type":"object"}}}}},"Product":{"type":"object","properties":{"id":{"type":"string","example":"clx123abc"},"name":{"type":"string","example":"Laptop Business Pro 15"},"nameEn":{"type":"string","example":"Business Laptop Pro 15"},"slug":{"type":"string","example":"laptop-business-pro-15"},"description":{"type":"string"},"price":{"type":"number","format":"decimal","example":3499.99},"compareAtPrice":{"type":"number","format":"decimal","example":3999.99},"minOrder":{"type":"integer","example":1},"stock":{"type":"integer","example":50},"sku":{"type":"string","example":"LBP15-001"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"specifications":{"type":"object"},"isActive":{"type":"boolean","example":true},"isFeatured":{"type":"boolean","example":false},"viewCount":{"type":"integer","example":1234},"vatRate":{"type":"number","example":0.21},"vatCategory":{"type":"string","enum":["STANDARD","REDUCED","EXEMPT"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"supplier":{"$ref":"#/components/schemas/SupplierSummary"},"category":{"$ref":"#/components/schemas/CategorySummary"},"_count":{"type":"object","properties":{"reviews":{"type":"integer"},"favorites":{"type":"integer"}}}}},"ProductSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"price":{"type":"number"},"images":{"type":"array","items":{"type":"string"}}}},"Category":{"type":"object","properties":{"id":{"type":"string","example":"clx456def"},"name":{"type":"string","example":"Electronice"},"nameEn":{"type":"string","example":"Electronics"},"slug":{"type":"string","example":"electronice"},"description":{"type":"string"},"image":{"type":"string","format":"uri"},"parentId":{"type":"string","nullable":true},"order":{"type":"integer","example":1},"isActive":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time"},"children":{"type":"array","items":{"$ref":"#/components/schemas/CategorySummary"}},"_count":{"type":"object","properties":{"products":{"type":"integer"}}}}},"CategorySummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}},"Supplier":{"type":"object","properties":{"id":{"type":"string","example":"clx789ghi"},"companyName":{"type":"string","example":"Tech Distribution SRL"},"cui":{"type":"string","example":"RO12345678"},"address":{"type":"string"},"city":{"type":"string","example":"Bucuresti"},"county":{"type":"string","example":"Bucuresti"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"description":{"type":"string"},"logo":{"type":"string","format":"uri"},"website":{"type":"string","format":"uri"},"verified":{"type":"boolean","example":true},"rating":{"type":"number","example":4.5},"reviewCount":{"type":"integer","example":127},"createdAt":{"type":"string","format":"date-time"},"_count":{"type":"object","properties":{"products":{"type":"integer"},"reviews":{"type":"integer"}}}}},"SupplierSummary":{"type":"object","properties":{"id":{"type":"string"},"companyName":{"type":"string"},"verified":{"type":"boolean"},"rating":{"type":"number"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"orderNumber":{"type":"string","example":"ORD-1704067200000-ABC123"},"status":{"type":"string","enum":["PENDING","CONFIRMED","PROCESSING","SHIPPED","DELIVERED","CANCELLED","REFUNDED"]},"subtotal":{"type":"number"},"discount":{"type":"number"},"shippingCost":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"notes":{"type":"string"},"shippingAddress":{"type":"object"},"trackingNumber":{"type":"string"},"trackingCarrier":{"type":"string"},"trackingUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"buyer":{"type":"object"},"supplier":{"$ref":"#/components/schemas/SupplierSummary"}}},"OrderItem":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"quantity":{"type":"integer"},"price":{"type":"number"},"total":{"type":"number"},"product":{"$ref":"#/components/schemas/ProductSummary"}}},"CreateOrder":{"type":"object","required":["supplierId","items"],"properties":{"supplierId":{"type":"string"},"addressId":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["productId","quantity"],"properties":{"productId":{"type":"string"},"variantId":{"type":"string"},"quantity":{"type":"integer","minimum":1}}}},"shippingAddress":{"type":"object","properties":{"fullName":{"type":"string"},"companyName":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"county":{"type":"string"},"postalCode":{"type":"string"}}},"notes":{"type":"string"},"couponCode":{"type":"string"}}},"Review":{"type":"object","properties":{"id":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string"},"comment":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"isVerified":{"type":"boolean"},"verifiedPurchase":{"type":"boolean"},"supplierResponse":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"StockRecord":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","nullable":true},"stock":{"type":"integer","example":50},"lowStockThreshold":{"type":"integer","example":10},"trackInventory":{"type":"boolean","example":true},"minOrder":{"type":"integer","example":1},"isActive":{"type":"boolean","example":true},"updatedAt":{"type":"string","format":"date-time"}}},"PriceRecord":{"type":"object","properties":{"id":{"type":"string"},"sku":{"type":"string","nullable":true},"price":{"type":"number","format":"decimal","example":3499.99},"compareAtPrice":{"type":"number","format":"decimal","example":3999.99,"nullable":true},"vatRate":{"type":"number","example":0.21},"updatedAt":{"type":"string","format":"date-time"}}}},"parameters":{"PageParam":{"name":"page","in":"query","description":"Numarul paginii (default: 1)","schema":{"type":"integer","default":1,"minimum":1}},"LimitParam":{"name":"limit","in":"query","description":"Numar de rezultate pe pagina (default: 12, max: 100)","schema":{"type":"integer","default":12,"minimum":1,"maximum":100}},"SearchParam":{"name":"search","in":"query","description":"Termen de cautare","schema":{"type":"string"}}},"responses":{"UnauthorizedError":{"description":"API key invalid sau lipsa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"UNAUTHORIZED","message":"API key invalid"}}}}},"RateLimitError":{"description":"Limita de cereri depasita","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Ai depasit limita de cereri","retryAfter":60}}}},"headers":{"Retry-After":{"description":"Secunde pana la reset","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Limita totala","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Cereri ramase","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Timestamp reset","schema":{"type":"integer"}}}},"NotFoundError":{"description":"Resursa nu a fost gasita","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NOT_FOUND","message":"Produsul nu a fost gasit"}}}}}}},"paths":{"/api/products":{"get":{"tags":["Products"],"summary":"Lista produse","description":"Returneaza o lista paginata de produse active","operationId":"listProducts","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SearchParam"},{"name":"categoryId","in":"query","description":"Filtreaza dupa categoria","schema":{"type":"string"}},{"name":"supplierId","in":"query","description":"Filtreaza dupa furnizor","schema":{"type":"string"}},{"name":"minPrice","in":"query","description":"Pret minim","schema":{"type":"number"}},{"name":"maxPrice","in":"query","description":"Pret maxim","schema":{"type":"number"}},{"name":"featured","in":"query","description":"Doar produse promovate","schema":{"type":"boolean"}},{"name":"sortBy","in":"query","description":"Ordinea rezultatelor","schema":{"type":"string","enum":["newest","price_asc","price_desc","popular"],"default":"newest"}}],"responses":{"200":{"description":"Lista de produse","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}]}}}},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{}]}},"/api/products/{slug}":{"get":{"tags":["Products"],"summary":"Detalii produs","description":"Returneaza detaliile complete ale unui produs","operationId":"getProduct","parameters":[{"name":"slug","in":"path","required":true,"description":"Slug-ul produsului","schema":{"type":"string"}}],"responses":{"200":{"description":"Detalii produs","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{}]}},"/api/categories":{"get":{"tags":["Categories"],"summary":"Lista categorii","description":"Returneaza toate categoriile active","operationId":"listCategories","parameters":[{"name":"parentOnly","in":"query","description":"Doar categoriile parinte (nivel 1)","schema":{"type":"boolean"}},{"name":"includeProducts","in":"query","description":"Include cateva produse din fiecare categorie","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Lista de categorii","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}]}}}},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{}]}},"/api/categories/{slug}":{"get":{"tags":["Categories"],"summary":"Detalii categorie","description":"Returneaza detaliile unei categorii si subcategoriile","operationId":"getCategory","parameters":[{"name":"slug","in":"path","required":true,"description":"Slug-ul categoriei","schema":{"type":"string"}}],"responses":{"200":{"description":"Detalii categorie","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Category"}}}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{}]}},"/api/suppliers":{"get":{"tags":["Suppliers"],"summary":"Lista furnizori","description":"Returneaza o lista paginata de furnizori","operationId":"listSuppliers","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/SearchParam"},{"name":"verified","in":"query","description":"Doar furnizori verificati","schema":{"type":"boolean"}},{"name":"city","in":"query","description":"Filtreaza dupa oras","schema":{"type":"string"}},{"name":"county","in":"query","description":"Filtreaza dupa judet","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Ordinea rezultatelor","schema":{"type":"string","enum":["rating","name","newest","products"],"default":"rating"}}],"responses":{"200":{"description":"Lista de furnizori","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}}}}]}}}},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{}]}},"/api/suppliers/{id}":{"get":{"tags":["Suppliers"],"summary":"Detalii furnizor","description":"Returneaza detaliile complete ale unui furnizor","operationId":"getSupplier","parameters":[{"name":"id","in":"path","required":true,"description":"ID-ul furnizorului","schema":{"type":"string"}}],"responses":{"200":{"description":"Detalii furnizor","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Supplier"}}}]}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]},{}]}},"/api/orders":{"get":{"tags":["Orders"],"summary":"Lista comenzi","description":"Returneaza comenzile utilizatorului autentificat","operationId":"listOrders","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"status","in":"query","description":"Filtreaza dupa status","schema":{"type":"string","enum":["PENDING","CONFIRMED","PROCESSING","SHIPPED","DELIVERED","CANCELLED","REFUNDED"]}}],"responses":{"200":{"description":"Lista de comenzi","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]},"post":{"tags":["Orders"],"summary":"Creeaza comanda","description":"Plaseaza o noua comanda","operationId":"createOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"201":{"description":"Comanda creata","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"description":"Date invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/api/orders/{id}":{"get":{"tags":["Orders"],"summary":"Detalii comanda","description":"Returneaza detaliile complete ale unei comenzi","operationId":"getOrder","parameters":[{"name":"id","in":"path","required":true,"description":"ID-ul comenzii","schema":{"type":"string"}}],"responses":{"200":{"description":"Detalii comanda","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/api/v1/stock":{"get":{"tags":["Stock"],"summary":"Stoc curent","description":"Returneaza nivelul de stoc pentru un produs (dupa productId sau sku) sau o lista paginata de stocuri cand niciun filtru nu e oferit.","operationId":"getStock","parameters":[{"name":"productId","in":"query","description":"ID-ul produsului pentru lookup individual","schema":{"type":"string"}},{"name":"sku","in":"query","description":"SKU-ul produsului pentru lookup individual","schema":{"type":"string"}},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Stoc curent","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/StockRecord"},{"type":"array","items":{"$ref":"#/components/schemas/StockRecord"}}]}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Permisiuni insuficiente (necesita read:stock)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}},"/api/v1/prices":{"get":{"tags":["Prices"],"summary":"Pret curent","description":"Returneaza pretul si compareAtPrice pentru un produs (dupa productId sau sku) sau o lista paginata de preturi cand niciun filtru nu e oferit.","operationId":"getPrice","parameters":[{"name":"productId","in":"query","description":"ID-ul produsului pentru lookup individual","schema":{"type":"string"}},{"name":"sku","in":"query","description":"SKU-ul produsului pentru lookup individual","schema":{"type":"string"}},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Pret curent","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/PriceRecord"},{"type":"array","items":{"$ref":"#/components/schemas/PriceRecord"}}]}}}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Permisiuni insuficiente (necesita read:prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"429":{"$ref":"#/components/responses/RateLimitError"}},"security":[{"ApiKeyHeader":[]},{"BearerAuth":[]}]}}}}