{ "openapi": "3.1.0", "info": { "title": "Zestt API", "version": "2.0.0-draft.1", "summary": "Zestt (Zester) API v2 — suppliers, buyers, accounting and BI integrations.", "description": "Source of truth for the Zestt API v2. Draft generated from the product spec (docs/spec/api-v2-spec.md, 11/09/2026). Every path carries `x-phase` (1/2/3), `x-scopes` (required scopes) and, where relevant, `x-plan` (minimum plan). Conventions: JSON only, snake_case, string enums, money as decimal strings with 2 fraction digits, dates as RFC 3339 with offset, cursor pagination, RFC 9457 problem+json errors, `Idempotency-Key` on POST.", "termsOfService": "https://developers.zester.co.il/terms", "contact": { "name": "Zestt Developers", "url": "https://developers.zester.co.il" }, "x-status": "draft", "x-spec-source": "docs/spec/api-v2-spec.md" }, "servers": [ { "url": "https://api.zester.co.il/v2", "description": "Production (keys prefixed zk_live_)" }, { "url": "https://sandbox-api.zester.co.il/v2", "description": "Sandbox (keys prefixed zk_test_; demo buyer + demo supplier, resettable)" } ], "security": [ { "apiKey": [] }, { "oauth2": [] } ], "tags": [ { "name": "Auth", "description": "Token exchange (optional; direct API keys are also accepted)." }, { "name": "Account", "description": "Who am I, what can I do." }, { "name": "Supplier – Buyers", "description": "The buyers linked to the authenticated supplier." }, { "name": "Supplier – Orders", "description": "Orders placed by buyers to the authenticated supplier." }, { "name": "Supplier – Documents", "description": "Delivery notes, invoices and credit notes issued by the supplier." }, { "name": "Supplier – Catalog", "description": "Products, availability and price lists." }, { "name": "Buyer – Reference", "description": "Branches, purchase types, suppliers, catalog, expense categories and accounts." }, { "name": "Buyer – Purchases", "description": "Orders and purchase documents across all suppliers." }, { "name": "Buyer – Expenses", "description": "Expense documents (no products) and card transactions." }, { "name": "Buyer – Accounting", "description": "ZesttBox journal lines and export marking." }, { "name": "Buyer – Sales", "description": "POS Z-reports and item sales." }, { "name": "Buyer – Inventory", "description": "Inventory counts." }, { "name": "Reports", "description": "Computed reports (food cost, purchases, expenses, P&L). For BI use the fact endpoints instead." }, { "name": "Events", "description": "Pull-based change feed. Same catalog as webhooks." }, { "name": "Webhooks", "description": "Signed push notifications." }, { "name": "Files", "description": "Upload attachments; referenced by file_id." }, { "name": "Exports", "description": "Asynchronous bulk export (Enterprise)." }, { "name": "Audit", "description": "Request log access (Enterprise)." } ], "x-tagGroups": [ { "name": "Getting started", "tags": [ "Auth", "Account" ] }, { "name": "Supplier API", "tags": [ "Supplier – Buyers", "Supplier – Orders", "Supplier – Documents", "Supplier – Catalog" ] }, { "name": "Buyer API", "tags": [ "Buyer – Reference", "Buyer – Purchases", "Buyer – Expenses", "Buyer – Accounting", "Buyer – Sales", "Buyer – Inventory", "Reports" ] }, { "name": "Platform", "tags": [ "Events", "Webhooks", "Files", "Exports", "Audit" ] } ], "paths": { "/oauth/token": { "post": { "tags": [ "Auth" ], "operationId": "createAccessToken", "summary": "Exchange an API key for a short-lived access token", "description": "OAuth 2.0 client_credentials grant. `client_id` is the ApiClient id, `client_secret` is the API key (zk_live_… / zk_test_…). Returns a JWT valid for 60 minutes carrying the client's scopes. Optional — the API key itself is accepted directly as a Bearer token. Accepts both `application/x-www-form-urlencoded` (RFC 6749) and `application/json`.", "security": [], "x-phase": 1, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Access token issued.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Describe the authenticated client", "description": "Account, account type, plan, effective scopes, branch restriction, rate limits and enabled features. The first call every integration should make; support asks for its output.", "x-phase": 1, "x-scopes": [], "responses": { "200": { "description": "Client context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier/buyers": { "get": { "tags": [ "Supplier – Buyers" ], "operationId": "listSupplierBuyers", "summary": "List buyers linked to this supplier", "x-phase": 1, "x-scopes": [ "supplier.buyers:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.buyers:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" } ], "responses": { "200": { "description": "Page of buyers.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierBuyer" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier/buyers/{buyer_id}": { "parameters": [ { "$ref": "#/components/parameters/buyer_id" } ], "get": { "tags": [ "Supplier – Buyers" ], "operationId": "getSupplierBuyer", "summary": "Get one linked buyer", "x-phase": 1, "x-scopes": [ "supplier.buyers:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.buyers:read" ] } ], "responses": { "200": { "description": "Buyer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierBuyer" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Supplier – Buyers" ], "operationId": "updateSupplierBuyer", "summary": "Update supplier-side fields of a buyer (customer number, ERP reference)", "x-phase": 1, "x-scopes": [ "supplier.buyers:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.buyers:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/If-Match" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_number": { "type": "string", "description": "Customer number in the supplier's ERP." }, "erp_ref": { "type": "string", "description": "Free reference (e.g. ERP account key)." } } } } } }, "responses": { "200": { "description": "Updated buyer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierBuyer" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/supplier/buyer-invitations": { "post": { "tags": [ "Supplier – Buyers" ], "operationId": "createBuyerInvitation", "summary": "Invite a new buyer to Zestt", "description": "Replaces v1 \"Create New customer\". Does not create a user; returns an onboarding link.", "x-phase": 1, "x-scopes": [ "supplier.buyers:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.buyers:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerInvitationCreate" } } } }, "responses": { "201": { "description": "Invitation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerInvitation" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/supplier/orders": { "get": { "tags": [ "Supplier – Orders" ], "operationId": "listSupplierOrders", "summary": "List orders sent to this supplier", "description": "Default returns all statuses. Use `status` to fetch only `pending_approval`, or `updated_since` for incremental polling.", "x-phase": 1, "x-scopes": [ "supplier.orders:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/order_status" }, { "name": "buyer_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Page of orders.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/supplier/orders/{order_id}": { "parameters": [ { "$ref": "#/components/parameters/order_id" } ], "get": { "tags": [ "Supplier – Orders" ], "operationId": "getSupplierOrder", "summary": "Get an order", "x-phase": 1, "x-scopes": [ "supplier.orders:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.orders:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Order.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/orders/{order_id}/confirm": { "post": { "tags": [ "Supplier – Orders" ], "operationId": "confirmSupplierOrder", "summary": "Confirm an order (fully or with line changes)", "description": "Empty body = full confirmation. Send `lines[]` to confirm partially, substitute items or adjust prices (if the buyer allows).", "x-phase": 1, "x-scopes": [ "supplier.orders:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/order_id" }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderConfirmRequest" } } } }, "responses": { "200": { "description": "Order after confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/supplier/orders/{order_id}/reject": { "post": { "tags": [ "Supplier – Orders" ], "operationId": "rejectSupplierOrder", "summary": "Reject an order", "x-phase": 1, "x-scopes": [ "supplier.orders:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/order_id" }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Order after rejection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/supplier/orders/{order_id}/schedule": { "post": { "tags": [ "Supplier – Orders" ], "operationId": "scheduleSupplierOrder", "summary": "Set or change the delivery date / window", "x-phase": 1, "x-scopes": [ "supplier.orders:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/order_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "delivery_date" ], "properties": { "delivery_date": { "type": "string", "format": "date" }, "delivery_window": { "$ref": "#/components/schemas/TimeWindow" } } } } } }, "responses": { "200": { "description": "Order after scheduling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/supplier/orders/{order_id}/acknowledge": { "post": { "tags": [ "Supplier – Orders" ], "operationId": "acknowledgeSupplierOrder", "summary": "Mark the order as received in the supplier's ERP", "description": "Replaces v1 \"Export Status\". `external_ref` (ERP sales-order number) is shown to the buyer.", "x-phase": 1, "x-scopes": [ "supplier.orders:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/order_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "external_ref": { "type": "string", "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Order after acknowledgement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/documents": { "get": { "tags": [ "Supplier – Documents" ], "operationId": "listSupplierDocuments", "summary": "List documents issued by this supplier, with the buyer's receiving status", "x-phase": 1, "x-scopes": [ "supplier.documents:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.documents:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/document_type" }, { "name": "buyer_status", "in": "query", "schema": { "$ref": "#/components/schemas/DocumentBuyerStatus" } }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Page of documents.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } ] } } } } } }, "post": { "tags": [ "Supplier – Documents" ], "operationId": "createSupplierDocument", "summary": "Create a delivery note, invoice, credit note or consolidated invoice", "description": "Attachments are uploaded first via `POST /files` and referenced by `file_ids[]`. `Idempotency-Key` is required — use the document number.", "x-phase": 1, "x-scopes": [ "supplier.documents:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.documents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key-Required" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreate" } } } }, "responses": { "201": { "description": "Document created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/supplier/documents/batch": { "post": { "tags": [ "Supplier – Documents" ], "operationId": "createSupplierDocumentsBatch", "summary": "Create up to 500 documents in one call", "description": "Per-item result. Returns 422 only when every item failed.", "x-phase": 1, "x-scopes": [ "supplier.documents:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.documents:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key-Required" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/DocumentCreate" } } } } } } }, "responses": { "200": { "description": "Per-item results (at least one succeeded).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "422": { "description": "Every item failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } } } } }, "/supplier/documents/{document_id}": { "parameters": [ { "$ref": "#/components/parameters/document_id" } ], "get": { "tags": [ "Supplier – Documents" ], "operationId": "getSupplierDocument", "summary": "Get a document, including what the buyer actually received", "x-phase": 1, "x-scopes": [ "supplier.documents:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.documents:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/products/{sku}": { "parameters": [ { "$ref": "#/components/parameters/sku" } ], "put": { "tags": [ "Supplier – Catalog" ], "operationId": "upsertSupplierProduct", "summary": "Create or update a product (upsert by SKU)", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierProductUpsert" } } } }, "responses": { "200": { "description": "Product updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierProduct" } } } }, "201": { "description": "Product created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierProduct" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Supplier – Catalog" ], "operationId": "deleteSupplierProduct", "summary": "Remove a product from the catalog (soft delete)", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "responses": { "204": { "description": "Removed." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/products/batch": { "post": { "tags": [ "Supplier – Catalog" ], "operationId": "upsertSupplierProductsBatch", "summary": "Upsert up to 500 products", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "allOf": [ { "$ref": "#/components/schemas/SupplierProductUpsert" }, { "type": "object", "required": [ "sku" ], "properties": { "sku": { "type": "string" } } } ] } } } } } } }, "responses": { "200": { "description": "Per-item results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "422": { "description": "Every item failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } } } } }, "/supplier/products/{sku}/availability": { "post": { "tags": [ "Supplier – Catalog" ], "operationId": "setSupplierProductAvailability", "summary": "Set product availability", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/sku" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "until": { "type": "string", "format": "date", "description": "When `available=false`, optional date the product is expected back." }, "reason": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Availability updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupplierProduct" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/price-lists": { "get": { "tags": [ "Supplier – Catalog" ], "operationId": "listSupplierPriceLists", "summary": "List price lists and the buyers assigned to each", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Page of price lists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceList" } } } } ] } } } } } } }, "/supplier/price-lists/{price_list_id}/prices": { "put": { "tags": [ "Supplier – Catalog" ], "operationId": "upsertSupplierPrices", "summary": "Upsert prices in a price list (up to 500 per call)", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/price_list_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/PriceEntry" } } } } } } }, "responses": { "200": { "description": "Per-item results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/price-lists/{price_list_id}/buyers": { "post": { "tags": [ "Supplier – Catalog" ], "operationId": "assignPriceListToBuyer", "summary": "Assign a price list to a buyer", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/price_list_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "buyer_id" ], "properties": { "buyer_id": { "type": "string" }, "valid_from": { "type": "string", "format": "date" } } } } } }, "responses": { "204": { "description": "Assigned." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/supplier/price-lists/{price_list_id}/buyers/{buyer_id}": { "delete": { "tags": [ "Supplier – Catalog" ], "operationId": "unassignPriceListFromBuyer", "summary": "Unlink a price list from a buyer", "x-phase": 1, "x-scopes": [ "supplier.catalog:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.catalog:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/price_list_id" }, { "$ref": "#/components/parameters/buyer_id" } ], "responses": { "204": { "description": "Unlinked." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/branches": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listBranches", "summary": "List branches (physical sites) of the account", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.purchases:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.purchases:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Page of branches.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } } } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/purchase-types": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listPurchaseTypes", "summary": "List purchase types (business lines, e.g. FC / MK / EV / OC)", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.purchases:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.purchases:read" ] } ], "responses": { "200": { "description": "Purchase types.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseType" } } } } } } } } } }, "/suppliers": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listSuppliers", "summary": "List suppliers (vendors) of the account", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.suppliers:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.suppliers:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "vendor_type", "in": "query", "schema": { "$ref": "#/components/schemas/VendorType" } } ], "responses": { "200": { "description": "Page of suppliers.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Supplier" } } } } ] } } } } } } }, "/suppliers/{supplier_id}": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "getSupplier", "summary": "Get a supplier", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.suppliers:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.suppliers:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/supplier_id_path" } ], "responses": { "200": { "description": "Supplier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/products": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listBuyerProducts", "summary": "List the buyer's catalog", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.catalog:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.catalog:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/supplier_id" }, { "name": "product_group", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of products.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerProduct" } } } } ] } } } } } } }, "/expense-categories": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listExpenseCategories", "summary": "List the expense category tree (2 levels)", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.expenses:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:read" ] } ], "responses": { "200": { "description": "Categories (flat list with parent_id).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseCategory" } } } } } } } } } }, "/expense-accounts": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listExpenseAccounts", "summary": "List the ZesttBox expense account catalog", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.accounting:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.accounting:read" ] } ], "responses": { "200": { "description": "Accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseAccount" } } } } } } } } } }, "/account-mappings": { "get": { "tags": [ "Buyer – Reference" ], "operationId": "listAccountMappings", "summary": "List the category × purchase-type → expense-account matrix", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.accounting:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.accounting:read" ] } ], "responses": { "200": { "description": "Mappings. `purchase_type = null` is the fallback row.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountMapping" } } } } } } } } } }, "/orders": { "get": { "tags": [ "Buyer – Purchases" ], "operationId": "listOrders", "summary": "List orders across all suppliers", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.purchases:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.purchases:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/branch_id" }, { "$ref": "#/components/parameters/supplier_id" }, { "$ref": "#/components/parameters/order_status" }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Page of orders.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Buyer – Purchases" ], "operationId": "createOrder", "summary": "Create an order from an external system (phase 3)", "x-phase": 3, "x-plan": "pro", "x-scopes": [ "buyer.orders:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.orders:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key-Required" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "201": { "description": "Order created (status per buyer approval rules).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/orders/{order_id}": { "get": { "tags": [ "Buyer – Purchases" ], "operationId": "getOrder", "summary": "Get an order", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.purchases:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.purchases:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/order_id" }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents": { "get": { "tags": [ "Buyer – Purchases" ], "operationId": "listDocuments", "summary": "List purchase documents (delivery notes, invoices, credits) with lines and export status", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.purchases:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.purchases:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/branch_id" }, { "$ref": "#/components/parameters/supplier_id" }, { "$ref": "#/components/parameters/document_type" }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/DocumentSource" } }, { "name": "export_status", "in": "query", "schema": { "$ref": "#/components/schemas/ExportStatus" } }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Page of documents.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } ] } } } } } } }, "/documents/{document_id}": { "get": { "tags": [ "Buyer – Purchases" ], "operationId": "getDocument", "summary": "Get a purchase document", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.purchases:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.purchases:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/document_id" }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/expenses": { "get": { "tags": [ "Buyer – Expenses" ], "operationId": "listExpenses", "summary": "List expense documents", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.expenses:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/branch_id" }, { "name": "category_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ExpenseStatus" } }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Page of expenses.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Expense" } } } } ] } } } } } }, "post": { "tags": [ "Buyer – Expenses" ], "operationId": "createExpense", "summary": "Create an expense document from an external system", "description": "Applies the buyer's blocking rules (mandatory attachment, allocation number above 5,000 ILS, missing account mapping).", "x-phase": 3, "x-plan": "pro", "x-scopes": [ "buyer.expenses:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key-Required" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpenseCreate" } } } }, "responses": { "201": { "description": "Expense created (status `draft` or `pending_approval`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Expense" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/expenses/{expense_id}": { "parameters": [ { "name": "expense_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Buyer – Expenses" ], "operationId": "getExpense", "summary": "Get an expense document", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.expenses:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:read" ] } ], "responses": { "200": { "description": "Expense.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Expense" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Buyer – Expenses" ], "operationId": "updateExpense", "summary": "Update a draft expense", "description": "Only `draft` expenses can be edited. After export, create a counter document instead.", "x-phase": 3, "x-plan": "pro", "x-scopes": [ "buyer.expenses:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/If-Match" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpenseCreate" } } } }, "responses": { "200": { "description": "Expense updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Expense" } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/card-transactions": { "get": { "tags": [ "Buyer – Expenses" ], "operationId": "listCardTransactions", "summary": "List imported card transactions and their linked expense", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.expenses:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "name": "matched", "in": "query", "description": "Filter transactions with (`true`) or without (`false`) a linked expense.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Page of transactions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CardTransaction" } } } } ] } } } } } } }, "/card-transactions/batch": { "post": { "tags": [ "Buyer – Expenses" ], "operationId": "importCardTransactions", "summary": "Import card transactions (creates draft expenses)", "x-phase": 3, "x-plan": "pro", "x-scopes": [ "buyer.expenses:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.expenses:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key-Required" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/CardTransactionCreate" } } } } } } }, "responses": { "200": { "description": "Per-item results. Duplicates by `external_id` are reported as `skipped`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } } } } }, "/inventory-counts": { "get": { "tags": [ "Buyer – Inventory" ], "operationId": "listInventoryCounts", "summary": "List inventory counts", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.inventory:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.inventory:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/branch_id" }, { "$ref": "#/components/parameters/expand" } ], "responses": { "200": { "description": "Page of counts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryCount" } } } } ] } } } } } } }, "/inventory-counts/{count_id}": { "get": { "tags": [ "Buyer – Inventory" ], "operationId": "getInventoryCount", "summary": "Get an inventory count with lines", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.inventory:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.inventory:read" ] } ], "parameters": [ { "name": "count_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryCount" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sales/z-reports": { "get": { "tags": [ "Buyer – Sales" ], "operationId": "listZReports", "summary": "List POS Z-reports", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.sales:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.sales:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/branch_id" } ], "responses": { "200": { "description": "Page of Z-reports.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ZReport" } } } } ] } } } } } }, "post": { "tags": [ "Buyer – Sales" ], "operationId": "createZReports", "summary": "Push Z-reports from the POS (replaces v1 POSIncome/ZTotals)", "description": "Idempotent per `branch_id` + `z_number`. Re-sending the same Z updates it.", "x-phase": 2, "x-scopes": [ "buyer.sales:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.sales:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/ZReportCreate" } } } } } } }, "responses": { "200": { "description": "Per-item results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } } } } }, "/sales/item-sales": { "get": { "tags": [ "Buyer – Sales" ], "operationId": "listItemSales", "summary": "List item-level sales", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.sales:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.sales:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "$ref": "#/components/parameters/branch_id" }, { "name": "z_number", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of item sales.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemSale" } } } } ] } } } } } }, "post": { "tags": [ "Buyer – Sales" ], "operationId": "createItemSales", "summary": "Push item-level sales (replaces v1 POSIncome/SalesDetails)", "x-phase": 2, "x-scopes": [ "buyer.sales:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.sales:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "$ref": "#/components/schemas/ItemSaleCreate" } } } } } } }, "responses": { "200": { "description": "Per-item results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } } } } }, "/accounting/journal-lines": { "get": { "tags": [ "Buyer – Accounting" ], "operationId": "listJournalLines", "summary": "List ZesttBox journal lines (debit / credit / VAT) ready for the ERP", "description": "One row per journal line. Filter `status=approved_for_export` to pull what is ready; mark with `POST /accounting/exports`. Generic replacement for per-ERP export files.", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.accounting:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.accounting:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "period", "in": "query", "description": "Accounting period `YYYY-MM`.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ExportStatus" } }, { "$ref": "#/components/parameters/branch_id" }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/DocumentSource" } } ], "responses": { "200": { "description": "Page of journal lines.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JournalLine" } } } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/accounting/exports": { "post": { "tags": [ "Buyer – Accounting" ], "operationId": "createAccountingExport", "summary": "Mark journal lines as exported", "description": "Marks the given lines `exported`, records `exported_by` = this client and returns an `export_batch_id`.", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.accounting:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.accounting:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key-Required" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingExportCreate" } } } }, "responses": { "201": { "description": "Export batch recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingExport" } } } }, "409": { "description": "One or more lines were already exported.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/accounting/exports/{export_batch_id}": { "get": { "tags": [ "Buyer – Accounting" ], "operationId": "getAccountingExport", "summary": "Get an export batch", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.accounting:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.accounting:read" ] } ], "parameters": [ { "name": "export_batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountingExport" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/reports/food-cost": { "get": { "tags": [ "Reports" ], "operationId": "getFoodCostReport", "summary": "Food cost by branch and purchase type", "description": "Same numbers as the in-app report. Excludes `source != purchase` and `vendor_type != goods`.", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.reports:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.reports:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/from_required" }, { "$ref": "#/components/parameters/to_required" }, { "$ref": "#/components/parameters/branch_id" }, { "name": "purchase_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResult" } } } } } } }, "/reports/purchases": { "get": { "tags": [ "Reports" ], "operationId": "getPurchasesReport", "summary": "Purchases grouped by supplier, branch or product group", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.reports:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.reports:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/from_required" }, { "$ref": "#/components/parameters/to_required" }, { "name": "group_by", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "supplier", "branch", "product_group", "purchase_type", "month" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Report rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResult" } } } } } } }, "/reports/expenses": { "get": { "tags": [ "Reports" ], "operationId": "getExpensesReport", "summary": "Expenses pivot (category × purchase type × branch × month)", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.reports:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.reports:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/from_required" }, { "$ref": "#/components/parameters/to_required" }, { "name": "group_by", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "category", "purchase_type", "branch", "month", "merchant" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Report rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResult" } } } } } } }, "/reports/pnl": { "get": { "tags": [ "Reports" ], "operationId": "getPnlReport", "summary": "Profit and loss for a period", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "buyer.reports:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "buyer.reports:read" ] } ], "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" } }, { "$ref": "#/components/parameters/branch_id" } ], "responses": { "200": { "description": "Report rows (one per P&L group).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResult" } } } } } } }, "/events": { "get": { "tags": [ "Events" ], "operationId": "listEvents", "summary": "Pull the change feed", "description": "Ordered by `occurred_at`. Store `next_cursor` and resume from it. Retention 30 days (Pro) / 90 days (Enterprise). Same event catalog as webhooks.", "x-phase": 2, "x-plan": "pro", "x-scopes": [ "events:read" ], "security": [ { "apiKey": [] }, { "oauth2": [ "events:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "name": "type", "in": "query", "description": "Comma-separated event types.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "since", "in": "query", "description": "Start of feed when no cursor is given.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Page of events.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } ] } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhook endpoints", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Endpoints.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create a webhook endpoint", "description": "Returns the signing `secret` once. Endpoint limit depends on plan.", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Endpoint created; `secret` shown only in this response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/webhooks/{webhook_id}": { "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "Get a webhook endpoint", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "Endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Update URL, events or status", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "Endpoint updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "responses": { "204": { "description": "Deleted." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/{webhook_id}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Send a signed `ping` event to the endpoint", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/webhook_id" } ], "responses": { "200": { "description": "Delivery attempt result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List delivery attempts for an endpoint", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/webhook_id" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] } } ], "responses": { "200": { "description": "Page of deliveries.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] } } } } } } }, "/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver": { "post": { "tags": [ "Webhooks" ], "operationId": "redeliverWebhookDelivery", "summary": "Re-send a delivery", "x-phase": 1, "x-scopes": [ "webhooks:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/webhook_id" }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Queued." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/files": { "post": { "tags": [ "Files" ], "operationId": "uploadFile", "summary": "Upload a file (multipart, up to 25 MB)", "description": "Returns a `file_id` to reference from documents and expenses. Files not referenced within 24 hours are deleted.", "x-phase": 1, "x-scopes": [ "supplier.documents:write", "buyer.expenses:write" ], "security": [ { "apiKey": [] }, { "oauth2": [ "supplier.documents:write" ] }, { "oauth2": [ "buyer.expenses:write" ] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": [ "document_attachment", "expense_attachment", "product_image" ] } } } } } }, "responses": { "201": { "description": "File stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" } } } }, "413": { "description": "File too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/files/{file_id}": { "get": { "tags": [ "Files" ], "operationId": "getFile", "summary": "Get file metadata and a signed download URL (valid 1 hour)", "x-phase": 1, "x-scopes": [], "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/exports": { "post": { "tags": [ "Exports" ], "operationId": "createExport", "summary": "Start an asynchronous bulk export", "x-phase": 3, "x-plan": "enterprise", "x-scopes": [ "exports:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "exports:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJobCreate" } } } }, "responses": { "202": { "description": "Export queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJob" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{export_id}": { "get": { "tags": [ "Exports" ], "operationId": "getExport", "summary": "Poll an export job; download links appear when `status=completed`", "x-phase": 3, "x-plan": "enterprise", "x-scopes": [ "exports:manage" ], "security": [ { "apiKey": [] }, { "oauth2": [ "exports:manage" ] } ], "parameters": [ { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJob" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/audit/requests": { "get": { "tags": [ "Audit" ], "operationId": "listAuditRequests", "summary": "Read the API request log of this account", "x-phase": 2, "x-plan": "enterprise", "x-scopes": [], "parameters": [ { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/from" }, { "$ref": "#/components/parameters/to" }, { "name": "client_id", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "HTTP status code.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Page of request log rows.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditRequest" } } } } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "webhooks": { "order.created": { "post": { "summary": "A buyer issued a new order to the supplier (status pending_approval)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Acknowledged. Any other status is retried with exponential backoff (8 attempts, ~24h)." } } } }, "order.updated": { "post": { "summary": "Order changed (lines, dates, status) — including cancelled_after_approval", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "document.received": { "post": { "summary": "The buyer received a supplier document; `data.differences[]` lists gaps", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "journal_lines.approved_for_export": { "post": { "summary": "Journal lines were approved for export (buyer side)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "zk_live_… / zk_test_…", "description": "API key of an ApiClient, sent directly as a Bearer token. Issued in the app under Settings → Developers, shown once, stored hashed. Subject to the client's scopes, IP allowlist and the account's plan." }, "oauth2": { "type": "oauth2", "description": "Optional exchange of the API key for a 60-minute JWT (client_credentials).", "flows": { "clientCredentials": { "tokenUrl": "https://api.zester.co.il/v2/oauth/token", "scopes": { "supplier.orders:read": "Read orders sent to the supplier", "supplier.orders:write": "Confirm, reject, schedule, acknowledge orders", "supplier.documents:read": "Read supplier documents and buyer receiving status", "supplier.documents:write": "Create delivery notes, invoices, credit notes", "supplier.catalog:write": "Manage products, availability, price lists", "supplier.buyers:read": "Read linked buyers", "supplier.buyers:write": "Update customer numbers, invite buyers", "buyer.purchases:read": "Read orders and purchase documents", "buyer.suppliers:read": "Read supplier (vendor) records", "buyer.catalog:read": "Read the buyer catalog", "buyer.inventory:read": "Read inventory counts", "buyer.expenses:read": "Read expense documents and card transactions", "buyer.expenses:write": "Create expenses, import card transactions", "buyer.accounting:read": "Read journal lines, accounts, mappings", "buyer.accounting:write": "Mark journal lines as exported", "buyer.sales:read": "Read POS sales", "buyer.sales:write": "Push POS sales", "buyer.reports:read": "Read computed reports", "buyer.orders:write": "Create orders from external systems", "events:read": "Read the change feed", "webhooks:manage": "Manage webhook endpoints", "exports:manage": "Create and read bulk exports" } } } } }, "parameters": { "cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response (`next_cursor`).", "schema": { "type": "string" } }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "updated_since": { "name": "updated_since", "in": "query", "description": "Return items whose `updated_at` is strictly after this instant. Use for incremental sync.", "schema": { "type": "string", "format": "date-time" } }, "from": { "name": "from", "in": "query", "description": "Inclusive start date (document / order date).", "schema": { "type": "string", "format": "date" } }, "to": { "name": "to", "in": "query", "description": "Inclusive end date.", "schema": { "type": "string", "format": "date" } }, "from_required": { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, "to_required": { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, "order_status": { "name": "status", "in": "query", "description": "Comma-separated list of order statuses.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderStatus" } }, "style": "form", "explode": false }, "document_type": { "name": "type", "in": "query", "description": "Comma-separated list of document types.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentType" } }, "style": "form", "explode": false }, "expand": { "name": "expand", "in": "query", "description": "Comma-separated related objects to embed, e.g. `lines,supplier,files,history`. Default responses are lean.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, "branch_id": { "name": "branch_id", "in": "query", "schema": { "type": "string" } }, "supplier_id": { "name": "supplier_id", "in": "query", "schema": { "type": "string" } }, "supplier_id_path": { "name": "supplier_id", "in": "path", "required": true, "schema": { "type": "string" } }, "buyer_id": { "name": "buyer_id", "in": "path", "required": true, "schema": { "type": "string" } }, "order_id": { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } }, "document_id": { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string" } }, "sku": { "name": "sku", "in": "path", "required": true, "description": "Supplier SKU (catalog number). URL-encode if needed.", "schema": { "type": "string", "maxLength": 64 } }, "price_list_id": { "name": "price_list_id", "in": "path", "required": true, "schema": { "type": "string" } }, "webhook_id": { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } }, "Idempotency-Key": { "name": "Idempotency-Key", "in": "header", "description": "Optional. Same key + same body within 24h returns the original response; same key + different body → 409.", "schema": { "type": "string", "maxLength": 128 } }, "Idempotency-Key-Required": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required. Use a stable business key (e.g. document number). Same key + same body within 24h returns the original response; same key + different body → 409.", "schema": { "type": "string", "maxLength": 128 } }, "If-Match": { "name": "If-Match", "in": "header", "description": "ETag from a previous GET. Mismatch → 412.", "schema": { "type": "string" } } }, "headers": { "X-Request-Id": { "description": "Correlation id. Quote it in support requests.", "schema": { "type": "string" } }, "ETag": { "description": "Entity tag for optimistic concurrency (`If-Match`).", "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Malformed request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Missing, invalid, expired or revoked credential (`code`: unauthorized, key_expired, key_revoked).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "revoked": { "value": { "type": "https://developers.zester.co.il/errors/key_revoked", "title": "API key revoked", "status": 401, "code": "key_revoked", "detail": "This key was revoked on 2026-09-01. Create a new key in Settings → Developers.", "request_id": "req_01J9KQ7X4M" } } } } } }, "Forbidden": { "description": "Authenticated but not allowed (`code`: scope_missing, plan_required, ip_not_allowed, client_suspended).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "plan_required": { "value": { "type": "https://developers.zester.co.il/errors/plan_required", "title": "Plan upgrade required", "status": 403, "code": "plan_required", "detail": "The buyer API requires the Pro plan or above.", "request_id": "req_01J9KQ7X4M", "upgrade_url": "https://app.zester.co.il/billing" } } } } } }, "NotFound": { "description": "Resource does not exist or belongs to another account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "State conflict (`code`: conflict, idempotency_conflict).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionFailed": { "description": "ETag mismatch.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ValidationError": { "description": "Body or query failed validation; see `errors[]`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation": { "value": { "type": "https://developers.zester.co.il/errors/validation_error", "title": "Validation failed", "status": 422, "code": "validation_error", "detail": "2 fields are invalid", "request_id": "req_01J9KQ7X4M", "errors": [ { "field": "lines[1].quantity", "code": "must_be_positive", "message": "Quantity must be greater than 0" }, { "field": "delivery_date", "code": "in_the_past" } ] } } } } } }, "RateLimited": { "description": "Too many requests.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Money": { "type": "string", "description": "Decimal amount with exactly 2 fraction digits, as a string. Currency is on the parent object.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "138.00", "-15.25" ] }, "Quantity": { "type": "string", "description": "Decimal quantity with up to 3 fraction digits, as a string.", "pattern": "^-?\\d+(\\.\\d{1,3})?$", "examples": [ "2", "2.500" ] }, "Currency": { "type": "string", "description": "ISO 4217. Phase 1 supports ILS only.", "enum": [ "ILS" ] }, "TimeWindow": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "examples": [ "06:00" ] }, "to": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "examples": [ "09:00" ] } } }, "Page": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": {} }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details with a stable `code`.", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "description": "Stable machine-readable code.", "enum": [ "unauthorized", "key_expired", "key_revoked", "client_suspended", "ip_not_allowed", "scope_missing", "plan_required", "not_found", "validation_error", "idempotency_conflict", "precondition_failed", "conflict", "rate_limited", "file_too_large", "internal_error" ] }, "detail": { "type": "string" }, "instance": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } }, "upgrade_url": { "type": "string", "format": "uri" } } }, "ValidationErrorItem": { "type": "object", "required": [ "field", "code" ], "properties": { "field": { "type": "string", "description": "JSON path of the offending field." }, "code": { "type": "string" }, "message": { "type": "string" } } }, "BatchResult": { "type": "object", "required": [ "summary", "items" ], "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemResult" } } } }, "BatchItemResult": { "type": "object", "required": [ "index", "status" ], "properties": { "index": { "type": "integer", "description": "Position in the request `items[]`." }, "key": { "type": "string", "description": "Business key of the item (document number, SKU, external_id…)." }, "status": { "type": "string", "enum": [ "created", "updated", "skipped", "failed" ] }, "id": { "type": "string", "description": "Id of the created / updated resource." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } } } }, "TokenRequest": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "The API key (zk_live_… / zk_test_…)." }, "scope": { "type": "string", "description": "Optional space-separated subset of the client's scopes." } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds (3600)." }, "scope": { "type": "string" } } }, "Me": { "type": "object", "required": [ "account", "client", "scopes", "plan", "features", "rate_limit" ], "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "buyer", "supplier", "partner" ] }, "parent_id": { "type": [ "string", "null" ] } } }, "client": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "key_prefix": { "type": "string" }, "ip_allowlist": { "type": "array", "items": { "type": "string" } }, "branch_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Null = all branches of the account." } } }, "scopes": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "string", "enum": [ "basic", "pro", "enterprise", "supplier" ] }, "features": { "type": "array", "items": { "type": "string", "enum": [ "buyer_api", "webhooks", "events", "bulk_export", "ip_allowlist", "mtls", "audit_api" ] } }, "rate_limit": { "type": "object", "properties": { "per_minute": { "type": "integer" }, "per_day": { "type": [ "integer", "null" ] } } }, "api_version": { "type": "string", "examples": [ "2" ] } } }, "OrderStatus": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "partially_approved", "rejected", "cancelled", "cancelled_after_approval", "waiting_to_send" ] }, "DocumentType": { "type": "string", "enum": [ "delivery_note", "invoice", "credit_note", "consolidated_invoice" ] }, "DocumentBuyerStatus": { "type": "string", "description": "What happened to the document on the buyer side.", "enum": [ "pending", "received", "received_with_differences", "disputed", "approved_for_export", "exported" ] }, "DocumentSource": { "type": "string", "enum": [ "purchase", "expense", "card", "migration" ] }, "ExportStatus": { "type": "string", "enum": [ "not_ready", "approved_for_export", "exported" ] }, "VendorType": { "type": "string", "description": "goods = counts in food cost; service / card / internal never do.", "enum": [ "goods", "service", "card", "internal" ] }, "PartyRef": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "BranchRef": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tax_id": { "type": [ "string", "null" ] } } }, "FileRef": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "download_url": { "type": "string", "format": "uri", "description": "Signed URL, valid ~1 hour. Present when `expand=files`." } } }, "Totals": { "type": "object", "required": [ "before_vat", "vat", "with_vat" ], "properties": { "before_vat": { "$ref": "#/components/schemas/Money" }, "vat": { "$ref": "#/components/schemas/Money" }, "with_vat": { "$ref": "#/components/schemas/Money" }, "discount": { "$ref": "#/components/schemas/Money" } } }, "HistoryEntry": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "action": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_client", "system" ] }, "id": { "type": "string" }, "name": { "type": "string" } } }, "changes": { "type": "object", "additionalProperties": true } } }, "OrderLine": { "type": "object", "required": [ "id", "sku", "name", "quantity", "unit_price", "total" ], "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "unit": { "type": "string", "description": "Unit of `quantity` (unit, kg, l, carton…)." }, "package_quantity": { "$ref": "#/components/schemas/Quantity" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "discount_pct": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d{1,2})?$" }, "vat_exempt": { "type": "boolean" }, "total": { "$ref": "#/components/schemas/Money" }, "quantity_confirmed": { "oneOf": [ { "$ref": "#/components/schemas/Quantity" }, { "type": "null" } ] }, "substitute_sku": { "type": [ "string", "null" ] }, "product_group": { "type": [ "string", "null" ], "description": "Buyer catalog group (buyer view only)." }, "expense_account": { "type": [ "string", "null" ], "description": "Resolved expense account (buyer view only)." } } }, "Order": { "type": "object", "required": [ "id", "number", "status", "buyer", "supplier", "delivery_date", "currency", "totals", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "number": { "type": "string", "description": "Human-readable order number." }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "buyer": { "allOf": [ { "$ref": "#/components/schemas/PartyRef" }, { "type": "object", "properties": { "customer_number": { "type": [ "string", "null" ], "description": "The buyer's customer number at this supplier." } } } ] }, "supplier": { "$ref": "#/components/schemas/PartyRef" }, "branch": { "$ref": "#/components/schemas/BranchRef" }, "purchase_type": { "type": [ "string", "null" ], "description": "Business line (FC / MK / EV / OC…) when the buyer uses purchase types." }, "sent_at": { "type": "string", "format": "date-time" }, "delivery_date": { "type": "string", "format": "date" }, "delivery_window": { "$ref": "#/components/schemas/TimeWindow" }, "currency": { "$ref": "#/components/schemas/Currency" }, "totals": { "$ref": "#/components/schemas/Totals" }, "lines": { "type": "array", "description": "Present by default; omit with `expand=-lines`.", "items": { "$ref": "#/components/schemas/OrderLine" } }, "notes": { "type": [ "string", "null" ] }, "external_ref": { "type": [ "string", "null" ], "description": "Set by the supplier via `acknowledge` (ERP sales-order number)." }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "related_document_ids": { "type": "array", "items": { "type": "string" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileRef" } }, "history": { "type": "array", "description": "Present with `expand=history`.", "items": { "$ref": "#/components/schemas/HistoryEntry" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "OrderConfirmRequest": { "type": "object", "description": "Empty object = full confirmation.", "properties": { "delivery_date": { "type": "string", "format": "date" }, "delivery_window": { "$ref": "#/components/schemas/TimeWindow" }, "note": { "type": "string", "maxLength": 500 }, "lines": { "type": "array", "description": "Only lines that differ from the order need to be sent.", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "quantity_confirmed": { "$ref": "#/components/schemas/Quantity" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "substitute_sku": { "type": "string" }, "reason": { "type": "string", "maxLength": 200 } } } } } }, "OrderCreate": { "type": "object", "required": [ "supplier_id", "branch_id", "delivery_date", "lines" ], "properties": { "supplier_id": { "type": "string" }, "branch_id": { "type": "string" }, "purchase_type": { "type": "string" }, "delivery_date": { "type": "string", "format": "date" }, "notes": { "type": "string" }, "external_ref": { "type": "string" }, "lines": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "unit_price": { "$ref": "#/components/schemas/Money" } } } } } }, "DocumentLine": { "type": "object", "required": [ "id", "sku", "name", "quantity", "unit_price", "total" ], "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "unit": { "type": "string" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "discount_pct": { "type": [ "string", "null" ] }, "vat_exempt": { "type": "boolean" }, "total": { "$ref": "#/components/schemas/Money" }, "order_id": { "type": [ "string", "null" ] }, "order_line_id": { "type": [ "string", "null" ] }, "quantity_received": { "oneOf": [ { "$ref": "#/components/schemas/Quantity" }, { "type": "null" } ], "description": "Buyer-side received quantity." }, "purchase_type": { "type": [ "string", "null" ] }, "expense_account": { "type": [ "string", "null" ] } } }, "DocumentLineCreate": { "type": "object", "required": [ "sku", "quantity", "unit_price" ], "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "unit": { "type": "string" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "discount_pct": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$" }, "vat_exempt": { "type": "boolean", "default": false }, "order_id": { "type": "string" }, "order_line_id": { "type": "string" } } }, "Difference": { "type": "object", "description": "Gap between what the supplier issued and what the buyer received.", "properties": { "line_id": { "type": "string" }, "sku": { "type": "string" }, "field": { "type": "string", "enum": [ "quantity", "unit_price", "missing_line", "extra_line" ] }, "issued": { "type": "string" }, "received": { "type": "string" }, "note": { "type": "string" } } }, "Document": { "type": "object", "required": [ "id", "type", "number", "date", "supplier", "buyer", "currency", "totals", "buyer_status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/DocumentType" }, "number": { "type": "string", "description": "Document number as printed by the issuer." }, "date": { "type": "string", "format": "date" }, "accounting_period": { "type": "string", "description": "YYYY-MM. Defaults to the month of `date`." }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "supplier": { "$ref": "#/components/schemas/PartyRef" }, "buyer": { "$ref": "#/components/schemas/PartyRef" }, "branch": { "$ref": "#/components/schemas/BranchRef" }, "purchase_type": { "type": [ "string", "null" ] }, "source": { "$ref": "#/components/schemas/DocumentSource" }, "order_ids": { "type": "array", "items": { "type": "string" } }, "currency": { "$ref": "#/components/schemas/Currency" }, "totals": { "$ref": "#/components/schemas/Totals" }, "allocation_number": { "type": [ "string", "null" ], "description": "Israeli invoice allocation number (mandatory above 5,000 ILS)." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLine" } }, "buyer_status": { "$ref": "#/components/schemas/DocumentBuyerStatus" }, "differences": { "type": "array", "items": { "$ref": "#/components/schemas/Difference" } }, "payment_status": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "export_status": { "$ref": "#/components/schemas/ExportStatus" }, "exported_at": { "type": [ "string", "null" ], "format": "date-time" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileRef" } }, "external_ref": { "type": [ "string", "null" ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryEntry" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DocumentCreate": { "type": "object", "required": [ "type", "number", "date", "buyer_id", "lines", "totals" ], "properties": { "type": { "$ref": "#/components/schemas/DocumentType" }, "number": { "type": "string", "maxLength": 64 }, "date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "buyer_id": { "type": "string" }, "branch_id": { "type": "string", "description": "Required when the buyer has more than one branch and `order_ids` is empty." }, "order_ids": { "type": "array", "items": { "type": "string" } }, "currency": { "$ref": "#/components/schemas/Currency" }, "totals": { "$ref": "#/components/schemas/Totals" }, "allocation_number": { "type": "string", "maxLength": 32 }, "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DocumentLineCreate" } }, "file_ids": { "type": "array", "items": { "type": "string" } }, "external_ref": { "type": "string", "maxLength": 64 }, "notes": { "type": "string", "maxLength": 1000 } } }, "SupplierBuyer": { "type": "object", "required": [ "id", "name", "status", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tax_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "customer_number": { "type": [ "string", "null" ] }, "erp_ref": { "type": [ "string", "null" ] }, "branches": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/BranchRef" }, { "type": "object", "properties": { "address": { "type": "string" }, "delivery_days": { "type": "array", "items": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat" ] } } } } ] } }, "min_order": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "payment_terms": { "type": [ "string", "null" ] }, "price_list_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BuyerInvitationCreate": { "type": "object", "required": [ "business_name", "contact_email" ], "properties": { "business_name": { "type": "string" }, "tax_id": { "type": "string" }, "contact_name": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "contact_phone": { "type": "string" }, "customer_number": { "type": "string" }, "price_list_id": { "type": "string" } } }, "BuyerInvitation": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "accepted", "expired" ] }, "onboarding_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, "SupplierProductUpsert": { "type": "object", "required": [ "name", "unit" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "unit": { "type": "string", "description": "Selling unit (unit, kg, l, carton…)." }, "package_quantity": { "$ref": "#/components/schemas/Quantity" }, "category": { "type": "string" }, "barcode": { "type": "string" }, "vat_exempt": { "type": "boolean", "default": false }, "available": { "type": "boolean", "default": true }, "image_file_id": { "type": "string" }, "external_ref": { "type": "string" } } }, "SupplierProduct": { "allOf": [ { "$ref": "#/components/schemas/SupplierProductUpsert" }, { "type": "object", "required": [ "sku", "updated_at" ], "properties": { "sku": { "type": "string" }, "available_until": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] }, "PriceList": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "$ref": "#/components/schemas/Currency" }, "buyer_ids": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time" } } }, "PriceEntry": { "type": "object", "required": [ "sku", "price" ], "properties": { "sku": { "type": "string" }, "price": { "$ref": "#/components/schemas/Money" }, "min_quantity": { "$ref": "#/components/schemas/Quantity" }, "valid_from": { "type": "string", "format": "date" } } }, "Branch": { "allOf": [ { "$ref": "#/components/schemas/BranchRef" }, { "type": "object", "properties": { "code": { "type": "string" }, "region": { "type": "string" }, "address": { "type": "string" }, "active": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "PurchaseType": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "examples": [ "FC" ] }, "name": { "type": "string" }, "is_default": { "type": "boolean" } } }, "Supplier": { "type": "object", "required": [ "id", "name", "vendor_type", "counts_in_food_cost", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tax_id": { "type": [ "string", "null" ] }, "vendor_type": { "$ref": "#/components/schemas/VendorType" }, "counts_in_food_cost": { "type": "boolean" }, "vat_status": { "type": "string", "enum": [ "standard", "exempt", "zero" ] }, "payment_terms": { "type": [ "string", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "default_category_id": { "type": [ "string", "null" ] }, "default_purchase_type": { "type": [ "string", "null" ] }, "credit_account": { "type": [ "string", "null" ] }, "merged_into_vendor_id": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BuyerProduct": { "type": "object", "required": [ "id", "sku", "name", "supplier_id", "updated_at" ], "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "supplier_id": { "type": "string" }, "product_group": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ], "description": "Expense category mapped from `product_group`." }, "unit": { "type": "string" }, "package_quantity": { "$ref": "#/components/schemas/Quantity" }, "current_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "vat_exempt": { "type": "boolean" }, "inventory_item": { "type": "boolean" }, "active": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ExpenseCategory": { "type": "object", "required": [ "id", "name", "pl_group", "is_active" ], "properties": { "id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "pl_group": { "type": "string", "enum": [ "sales_marketing", "salaries", "general_admin", "fixed", "delivery_fees", "other", "finance", "taxes" ] }, "default_vat_treatment": { "type": "string", "enum": [ "full", "two_thirds", "quarter", "none" ] }, "is_recurring_fixed": { "type": "boolean" }, "is_active": { "type": "boolean" } } }, "ExpenseAccount": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "examples": [ "511110200" ] }, "name": { "type": "string" }, "active": { "type": "boolean" } } }, "AccountMapping": { "type": "object", "required": [ "category_id", "expense_account" ], "properties": { "category_id": { "type": "string" }, "purchase_type": { "type": [ "string", "null" ], "description": "Null = fallback for any purchase type." }, "expense_account": { "type": "string" } } }, "ExpenseStatus": { "type": "string", "enum": [ "draft", "pending_approval", "approved", "exported", "cancelled" ] }, "ExpenseLine": { "type": "object", "required": [ "id", "category_id", "amount_before_vat", "vat_amount" ], "properties": { "id": { "type": "string" }, "category_id": { "type": "string" }, "purchase_type": { "type": [ "string", "null" ] }, "branch_id": { "type": [ "string", "null" ] }, "amount_before_vat": { "$ref": "#/components/schemas/Money" }, "vat_amount": { "$ref": "#/components/schemas/Money" }, "description": { "type": [ "string", "null" ] }, "expense_account": { "type": [ "string", "null" ], "description": "Resolved from the account matrix; null = missing mapping (blocks approval)." } } }, "ExpenseLineCreate": { "type": "object", "required": [ "category_id", "amount_before_vat" ], "properties": { "category_id": { "type": "string" }, "purchase_type": { "type": "string" }, "branch_id": { "type": "string" }, "amount_before_vat": { "$ref": "#/components/schemas/Money" }, "vat_amount": { "$ref": "#/components/schemas/Money" }, "description": { "type": "string", "maxLength": 200 } } }, "Expense": { "type": "object", "required": [ "id", "vendor_id", "doc_type", "doc_date", "branch_id", "vat_mode", "currency", "totals", "status", "source", "lines", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/PartyRef" }, "merchant_name": { "type": [ "string", "null" ], "description": "Free text; required when the vendor is a card." }, "doc_type": { "type": "string", "enum": [ "tax_invoice", "invoice_receipt", "receipt", "payment_request", "charge_notice", "card_txn", "credit_note", "none" ] }, "doc_number": { "type": [ "string", "null" ] }, "allocation_number": { "type": [ "string", "null" ] }, "doc_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "accounting_period": { "type": "string", "description": "YYYY-MM." }, "branch_id": { "type": "string" }, "purchase_type": { "type": [ "string", "null" ] }, "vat_mode": { "type": "string", "enum": [ "with_vat", "exempt", "no_tax_doc" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "totals": { "allOf": [ { "$ref": "#/components/schemas/Totals" }, { "type": "object", "properties": { "deductible_vat": { "$ref": "#/components/schemas/Money" } } } ] }, "payment_method": { "type": [ "string", "null" ] }, "payment_status": { "type": "string", "enum": [ "unpaid", "partially_paid", "paid" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/ExpenseStatus" }, "source": { "type": "string", "enum": [ "manual", "recurring", "ocr", "email", "card_import", "migration", "api" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ExpenseLine" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileRef" } }, "notes": { "type": [ "string", "null" ] }, "approved_by": { "type": [ "string", "null" ] }, "approved_at": { "type": [ "string", "null" ], "format": "date-time" }, "exported_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_ref": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ExpenseCreate": { "type": "object", "required": [ "vendor_id", "doc_type", "doc_date", "branch_id", "vat_mode", "totals", "lines" ], "properties": { "vendor_id": { "type": "string" }, "merchant_name": { "type": "string", "maxLength": 120 }, "doc_type": { "type": "string", "enum": [ "tax_invoice", "invoice_receipt", "receipt", "payment_request", "charge_notice", "card_txn", "credit_note", "none" ] }, "doc_number": { "type": "string", "maxLength": 64 }, "allocation_number": { "type": "string", "maxLength": 32 }, "doc_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "accounting_period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "branch_id": { "type": "string" }, "purchase_type": { "type": "string" }, "vat_mode": { "type": "string", "enum": [ "with_vat", "exempt", "no_tax_doc" ] }, "totals": { "allOf": [ { "$ref": "#/components/schemas/Totals" }, { "type": "object", "properties": { "deductible_vat": { "$ref": "#/components/schemas/Money" } } } ] }, "payment_method": { "type": "string" }, "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ExpenseLineCreate" } }, "file_ids": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "maxLength": 1000 }, "external_ref": { "type": "string", "maxLength": 64 }, "submit": { "type": "boolean", "default": false, "description": "When true, moves the expense out of `draft` (to `pending_approval` or `approved` per the buyer's rules)." } } }, "CardTransaction": { "type": "object", "required": [ "id", "external_id", "txn_date", "merchant", "amount", "currency" ], "properties": { "id": { "type": "string" }, "external_id": { "type": "string", "description": "Id from the card provider feed. Unique per account." }, "card_last4": { "type": "string" }, "txn_date": { "type": "string", "format": "date" }, "merchant": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string" }, "expense_id": { "type": [ "string", "null" ] }, "suggested_category_id": { "type": [ "string", "null" ] }, "imported_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CardTransactionCreate": { "type": "object", "required": [ "external_id", "txn_date", "merchant", "amount", "currency" ], "properties": { "external_id": { "type": "string" }, "card_last4": { "type": "string" }, "txn_date": { "type": "string", "format": "date" }, "merchant": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "currency": { "type": "string", "default": "ILS" }, "vendor_id": { "type": "string", "description": "Card vendor (type=card). Defaults to the account's default card vendor." } } }, "InventoryCount": { "type": "object", "required": [ "id", "branch_id", "counted_at", "status", "updated_at" ], "properties": { "id": { "type": "string" }, "branch_id": { "type": "string" }, "counted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "open", "completed" ] }, "total_value": { "$ref": "#/components/schemas/Money" }, "lines": { "type": "array", "description": "Present with `expand=lines` or on GET by id.", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "unit": { "type": "string" }, "unit_cost": { "$ref": "#/components/schemas/Money" }, "value": { "$ref": "#/components/schemas/Money" } } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "ZReportCreate": { "type": "object", "required": [ "branch_id", "z_number", "closed_at", "total_before_vat" ], "properties": { "branch_id": { "type": "string" }, "z_number": { "type": "string" }, "closed_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "total_before_vat": { "$ref": "#/components/schemas/Money" }, "orders_count": { "type": "integer" }, "dine_in_total": { "$ref": "#/components/schemas/Money" }, "dine_in_count": { "type": "integer" }, "take_away_total": { "$ref": "#/components/schemas/Money" }, "take_away_count": { "type": "integer" }, "tips": { "$ref": "#/components/schemas/Money" }, "cash_total": { "$ref": "#/components/schemas/Money" }, "card_total": { "$ref": "#/components/schemas/Money" }, "cheque_total": { "$ref": "#/components/schemas/Money" }, "discounts_total": { "$ref": "#/components/schemas/Money" } } }, "ZReport": { "allOf": [ { "$ref": "#/components/schemas/ZReportCreate" }, { "type": "object", "required": [ "id", "updated_at" ], "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "ItemSaleCreate": { "type": "object", "required": [ "branch_id", "z_number", "value_date", "item_code", "item_name", "quantity", "unit_price", "total" ], "properties": { "branch_id": { "type": "string" }, "z_number": { "type": "string" }, "value_date": { "type": "string", "format": "date-time" }, "item_code": { "type": "string" }, "item_name": { "type": "string" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "line_number": { "type": "integer" }, "main_category": { "type": "string" }, "sub_category": { "type": "string" } } }, "ItemSale": { "allOf": [ { "$ref": "#/components/schemas/ItemSaleCreate" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "JournalLine": { "type": "object", "required": [ "id", "document_id", "source", "side", "account", "amount", "accounting_period", "status", "updated_at" ], "properties": { "id": { "type": "string" }, "document_id": { "type": "string" }, "document_type": { "type": "string", "description": "DocumentType or expense doc_type." }, "document_number": { "type": "string" }, "source": { "$ref": "#/components/schemas/DocumentSource" }, "side": { "type": "string", "enum": [ "debit", "credit", "vat" ] }, "account": { "type": "string", "description": "Expense account (debit), vendor credit account (credit) or input-VAT account (vat)." }, "counter_account": { "type": [ "string", "null" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "currency": { "$ref": "#/components/schemas/Currency" }, "description": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor_tax_id": { "type": [ "string", "null" ] }, "branch_id": { "type": "string" }, "branch_tax_id": { "type": [ "string", "null" ] }, "purchase_type": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ] }, "reference": { "type": "string", "description": "Document number." }, "allocation_number": { "type": [ "string", "null" ] }, "doc_date": { "type": "string", "format": "date" }, "accounting_period": { "type": "string", "description": "YYYY-MM (value date)." }, "movement_type_code": { "type": [ "string", "null" ] }, "batch_number": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ExportStatus" }, "export_batch_id": { "type": [ "string", "null" ] }, "exported_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AccountingExportCreate": { "type": "object", "required": [ "journal_line_ids" ], "properties": { "journal_line_ids": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "type": "string" } }, "target": { "type": "string", "description": "Free label of the destination system (e.g. \"meshek\", \"hashavshevet\")." }, "external_ref": { "type": "string" } } }, "AccountingExport": { "type": "object", "required": [ "id", "line_count", "exported_at", "exported_by" ], "properties": { "id": { "type": "string", "description": "export_batch_id." }, "line_count": { "type": "integer" }, "target": { "type": [ "string", "null" ] }, "external_ref": { "type": [ "string", "null" ] }, "exported_at": { "type": "string", "format": "date-time" }, "exported_by": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" } } } } }, "ReportResult": { "type": "object", "required": [ "from", "to", "generated_at", "rows" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "generated_at": { "type": "string", "format": "date-time" }, "currency": { "$ref": "#/components/schemas/Currency" }, "dimensions": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "description": "Keys are the requested dimensions plus metric names (e.g. `purchases`, `sales`, `food_cost_pct`).", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true } } }, "Event": { "type": "object", "required": [ "id", "type", "api_version", "occurred_at", "account_id", "data" ], "properties": { "id": { "type": "string", "examples": [ "evt_01J9KQ7X4M9C" ] }, "type": { "type": "string", "enum": [ "ping", "order.created", "order.updated", "order.cancelled", "order.status_changed", "document.created", "document.updated", "document.received", "document.disputed", "document.approved_for_export", "expense.created", "expense.approved", "journal_lines.approved_for_export", "inventory_count.completed", "supplier.updated", "card_transaction.imported", "buyer.linked", "price_list.assigned", "api_client.suspended", "webhook.disabled" ] }, "api_version": { "type": "string", "enum": [ "2" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "account_id": { "type": "string" }, "data": { "type": "object", "description": "The resource as it was at the time of the event. Always includes `object` and `id`.", "required": [ "object", "id" ], "properties": { "object": { "type": "string", "enum": [ "order", "document", "expense", "journal_lines", "inventory_count", "supplier", "card_transaction", "buyer", "price_list", "api_client", "webhook", "ping" ] }, "id": { "type": "string" } }, "additionalProperties": true } } }, "WebhookCreate": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "description": { "type": "string", "maxLength": 200 } } }, "WebhookUpdate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "description": { "type": "string" } } }, "Webhook": { "type": "object", "required": [ "id", "url", "events", "status", "created_at" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled", "failing" ] }, "description": { "type": [ "string", "null" ] }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "HMAC-SHA256 signing secret. Shown once." } } } ] }, "WebhookDelivery": { "type": "object", "required": [ "id", "event_id", "event_type", "attempt", "status" ], "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "response_status": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": [ "integer", "null" ] }, "response_snippet": { "type": [ "string", "null" ], "maxLength": 500 }, "error": { "type": [ "string", "null" ] }, "attempted_at": { "type": "string", "format": "date-time" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "FileObject": { "allOf": [ { "$ref": "#/components/schemas/FileRef" }, { "type": "object", "properties": { "purpose": { "type": "string" }, "sha256": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When unreferenced files are purged." } } } ] }, "ExportJobCreate": { "type": "object", "required": [ "resources" ], "properties": { "resources": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "orders", "documents", "expenses", "journal_lines", "suppliers", "products", "inventory_counts", "z_reports", "item_sales", "card_transactions" ] } }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "format": { "type": "string", "enum": [ "ndjson", "csv", "parquet" ], "default": "ndjson" }, "branch_ids": { "type": "array", "items": { "type": "string" } } } }, "ExportJob": { "type": "object", "required": [ "id", "status", "created_at" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "expired" ] }, "request": { "$ref": "#/components/schemas/ExportJobCreate" }, "files": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "size_bytes": { "type": "integer" }, "row_count": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AuditRequest": { "type": "object", "required": [ "request_id", "timestamp", "client_id", "method", "path", "status" ], "properties": { "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ] }, "client_id": { "type": "string" }, "client_name": { "type": "string" }, "key_id": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "query": { "type": [ "string", "null" ], "description": "Sensitive parameters redacted." }, "status": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "latency_ms": { "type": "integer" }, "ip": { "type": "string" }, "user_agent": { "type": [ "string", "null" ] }, "request_bytes": { "type": "integer" }, "response_bytes": { "type": "integer" }, "scope_used": { "type": [ "string", "null" ] } } } } } }