{"openapi":"3.1.0","info":{"title":"Keep","version":"1.0.0","description":"APIs for Keep, PayMe's accounting product: partners create and manage sellers, income documents, expenses, and tax and VAT balances, authenticating with OAuth 2.0 client credentials."},"servers":[{"url":"https://<partner_domain>.keep.co.il","description":"Sandbox: your partner domain on the Keep sandbox"},{"url":"https://<partner_domain>.keep.co.il","description":"Production: your partner domain"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Partners API"}],"paths":{"/oauth2/token":{"post":{"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"grant_type":{"type":"string","description":"The grant type\n\nAllowed values: `client_credentials`, `refresh_token`."},"scope":{"type":"string","description":"Space-separated scopes. Send `partner-api` with `grant_type=client_credentials`.\n\nThe field is optional in the request, but a token issued without a scope is refused with `403` by every Keep endpoint. With `grant_type=refresh_token` it is not needed: the new token keeps the scopes of the original one."},"client_id":{"type":"string","description":"Your client ID"},"client_secret":{"type":"string","description":"Your client secret"},"refresh_token":{"type":"string","description":"Required when `grant_type` is `refresh_token`. A refresh token works once: the response carries a new one, and the old access token stops working."}},"required":["grant_type","client_id","client_secret"]},"example":{"grant_type":"client_credentials","scope":"partner-api","client_id":"your-client-id","client_secret":"your-client-secret"}}}},"responses":{"200":{"description":"Successful authentication","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"token_type":{"type":"string"},"access_token":{"type":"string","description":"JWT access token"},"refresh_token":{"type":"string","description":"Refresh token"},"expires_in":{"type":"integer","description":"Access token lifetime in seconds"},"refresh_expires_in":{"type":"integer","description":"Refresh token lifetime in seconds"},"scope":{"type":"string","description":"Granted scopes"}}}}}},"400":{"description":"Invalid request. `error` is `invalid_request`, for an unknown refresh token.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"401":{"description":"Unauthorized. When `client_id` or `client_secret` is missing, the body is the plain text `Unauthorized`, not JSON.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"`unauthorized_client` (wrong client ID or secret) or `unauthorized_scope` (scope not granted to this client)"},"error_description":{"type":"string"}}}}}}},"operationId":"gettoken","summary":"Obtain access token","tags":["Partners API"],"description":"Use this endpoint to obtain an access token using Client Credentials or to refresh an existing token."}},"/api/public/sellers/create":{"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"Seller's first name, 2 to 250 characters: letters, spaces and the marks `-` `_` `.` `,` `'` `\"` `״` `(` `)` `:` `;`."},"lastName":{"type":"string","description":"Seller's last name, 2 to 250 characters: letters, spaces and the marks `-` `_` `.` `,` `'` `\"` `״` `(` `)` `:` `;`."},"email":{"type":"string","description":"Seller's primary email address (used for login)"},"contactEmail":{"type":"string","description":"Business contact email address"},"password":{"type":"string","description":"Account password, at least 6 characters."},"phone":{"type":"string","description":"Phone number, 1 to 250 characters."},"businessName":{"type":"string","description":"Legal business name, at most 250 characters."},"businessType":{"type":"integer","description":"Israeli business type.\n\n- `0` Not sure (לא ידוע)\n- `1` Osek Murshe, sole proprietorship (עוסק מורשה)\n- `2` Osek Patur, exempt small business (עוסק פטור)\n- `3` Incorporated company (חברה בע\"מ)\n- `4` Partnership (שותפות)\n- `6` Non-profit (עמותה)\n- `7` Limited partnership (שותפות מוגבלת)\n- `8` Publicly traded company (חברה ציבורית)\n- `9` Shared cooperative (אגודה שיתופית)\n- `10` Public benefit company (חברה לתועלת הציבור)"},"businessNumber":{"type":"string","description":"Israeli business registration number (ח.פ. / עוסק מורשה). Digits only, at most 9, with a valid check digit."},"socialId":{"type":"string","description":"Israeli ID number (תעודת זהות). Digits only, at most 9, with a valid check digit."},"industryClassification":{"type":"number","description":"Industry classification code (optional)"},"bankId":{"type":"string","description":"Israeli bank code (optional) Digits only."},"accountNumber":{"type":"string","description":"Bank account number (optional) Digits only."},"branchNumber":{"type":"string","description":"Bank branch number (optional) Digits only."},"logo":{"type":"string","description":"Business logo as base64 encoded data URI (optional)"}},"required":["firstName","lastName","email","contactEmail","password","phone","businessName","businessType","businessNumber","socialId"]},"example":{"firstName":"David","lastName":"Cohen","email":"david.cohen@example.com","contactEmail":"seller@example.com","password":"securePassword123","phone":"0500000009","businessName":"Cohen Electronics Ltd","businessType":1,"businessNumber":"330988015","socialId":"123456782","industryClassification":12,"bankId":"12","accountNumber":"123456789012345","branchNumber":"123","logo":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."}}}},"responses":{"201":{"description":"Seller created successfully","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"sellerId":{"type":"string","description":"Newly created seller's UUID"}}}}},"example":{"payload":{"sellerId":"9a5e7898-067e-4c0c-a50f-5f8d83e7c686"}}}}},"400":{"description":"Bad Request. Returned for validation errors, and for these onboarding refusals:\n\n- `Social ID is invalid` — a Keep seller already uses this ID number.\n- `The email is invalid. Please try again` — a Keep account already uses this email.\n\nOther onboarding errors are returned as `400` with their own message.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}}},"operationId":"createseller","summary":"Create seller","tags":["Partners API"],"description":"Register a new seller account with Israeli business compliance validation. Includes validation for Israeli ID numbers, business registration, and bank account details."}},"/api/public/sellers/{sellerId}":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"description":"Seller UUID or MPL ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Seller retrieved successfully. When no seller matches, `payload` is null.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"string","description":"Seller UUID"},"firstName":{"type":"string","description":"Seller's first name"},"lastName":{"type":"string","description":"Seller's last name"},"email":{"type":"string","description":"Primary email address"},"contactEmail":{"type":"string","description":"Business contact email"},"phone":{"type":"string","description":"Phone number"},"businessName":{"type":"string","description":"Legal business name"},"businessType":{"type":"integer","description":"Israeli business type.\n\n- `0` Not sure (לא ידוע)\n- `1` Osek Murshe, sole proprietorship (עוסק מורשה)\n- `2` Osek Patur, exempt small business (עוסק פטור)\n- `3` Incorporated company (חברה בע\"מ)\n- `4` Partnership (שותפות)\n- `6` Non-profit (עמותה)\n- `7` Limited partnership (שותפות מוגבלת)\n- `8` Publicly traded company (חברה ציבורית)\n- `9` Shared cooperative (אגודה שיתופית)\n- `10` Public benefit company (חברה לתועלת הציבור)"},"businessNumber":{"type":"string","description":"Israeli business registration number"},"socialId":{"type":"string","description":"Israeli ID number"},"createdAt":{"type":"string","description":"Account creation timestamp"},"updatedAt":{"type":"string","description":"Last update timestamp"},"sellerStatus":{"type":"integer","description":"`-1` new, `0` closed, `1` active"},"industryClassification":{"type":"integer"}}}}},"example":{"payload":{"id":"97bdce55-b2a2-450d-8d29-1dcf6bbcc419","firstName":"David","lastName":"Cohen","email":"david.cohen@example.com","contactEmail":"seller@example.com","phone":"0500000009","businessName":"Cohen Electronics Ltd","businessType":1,"businessNumber":"330988015","socialId":"123456782","createdAt":"2026-01-22T09:19:54.264Z","updatedAt":"2026-01-22T09:19:54.403Z"}}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}}},"operationId":"getsellerbyid","summary":"Get seller","tags":["Partners API"],"description":"Retrieve seller information by Keep seller UUID or by MPL. Returns seller details including business information and timestamps."}},"/api/public/plans":{"get":{"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Plans retrieved successfully","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the plan"},"name":{"type":"string","description":"Display name of the plan"},"price":{"type":"number","description":"Plan price in the partner's currency"}}}}}}}},"example":{"payload":{"items":[{"id":"90abd0eb-c374-4a2b-829e-681fba0cdbee","name":"PaturBasic","price":39.9},{"id":"29b1f228-c779-4de3-bb99-aa8e34f29ddc","name":"PaturPremium","price":105},{"id":"3d653770-6376-40a5-b98e-17c598f1d7d8","name":"MursheBasic","price":39.9},{"id":"c2249657-fe98-49ae-950a-3bdf28cdbfee","name":"MurshePremium","price":228}]}}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}}},"operationId":"getpartnerplans","summary":"Get available plans","tags":["Partners API"],"description":"Retrieve the plans available to the authenticated partner. Only plans that are currently offered for selection are returned; retired plans are not."}},"/api/public/expenses":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"sellerId","in":"query","required":false,"description":"Seller UUID (use this OR socialId + email)","schema":{"type":"string"}},{"name":"socialId","in":"query","required":false,"description":"Seller ID number, digits only, sent as a number (must be paired with email).","schema":{"type":"integer"}},{"name":"email","in":"query","required":false,"description":"Seller email address (must be paired with socialId)","schema":{"type":"string"}},{"name":"valueDateStart","in":"query","required":false,"description":"Filter expenses from this value date (inclusive, YYYY-MM-DD)","schema":{"type":"string"}},{"name":"valueDateEnd","in":"query","required":false,"description":"Filter expenses up to this value date (inclusive, YYYY-MM-DD)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number (zero-based). Minimum 0, default 0.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Items per page. Positive number, at most 500; use a whole-number item count. Default 10.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Expenses retrieved successfully","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of matching expenses"},"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Items per page"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Expense record UUID"},"capturedDate":{"type":"string","description":"Timestamp when the expense was captured"},"valueDate":{"type":"string","description":"Expense value date"},"sellerId":{"type":"string","description":"Seller UUID"},"totalAmount":{"type":"number","description":"Total expense amount"},"vatAmount":{"type":"number","description":"VAT amount"},"currency":{"type":"string","description":"Currency code"},"bookkeeperRevisionStatus":{"type":"string","description":"Bookkeeper revision status"},"docRegulationId":{"type":"string","description":"Document regulation ID"},"docType":{"type":"string","description":"Document type"}}}}}}}},"example":{"payload":{"total":1,"page":0,"limit":10,"items":[{"id":"50c6b740-874a-4f54-9669-9a60024be4ed","capturedDate":"2024-06-20T09:35:36.326Z","valueDate":"2024-06-20T00:00:00.000Z","sellerId":"a6a9700f-8571-4f9b-bfae-ba943fb96982","totalAmount":15200,"vatAmount":2209,"currency":"ILS","bookkeeperRevisionStatus":"approved-and-classified","docRegulationId":"1262","docType":"invrec"}]}}}}},"400":{"description":"Bad Request","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"403":{"description":"The seller does not belong to your partner account.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}}}}},"422":{"description":"Unprocessable Entity. Message: `Could not resolve seller` — the identifiers match no seller.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":422,"message":"Bad seller configuration. Please contact support!","error":"Unprocessable Entity"}}}}},"operationId":"listpublicexpenses","summary":"List expenses","tags":["Partners API"],"description":"Retrieve expense records for a seller with optional date filtering and pagination.\n\n**Seller identification:** Same rules as the upload endpoint — provide `sellerId` alone, or `socialId` + `email`.\n\n**Date filtering:** `valueDateStart` and `valueDateEnd` filter on the expense value date (not creation date). Dates must be ISO format (`YYYY-MM-DD`) and `valueDateStart` must be ≤ `valueDateEnd`.\n\n**Pagination:** Defaults to `page=0`, `limit=10`. Maximum `limit=500`.\n\nOrder of returned items is not guaranteed."},"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sellerId":{"type":"string","description":"Seller UUID (use this OR socialId + email, not both)"},"socialId":{"type":"number","description":"Seller social/business ID number (must be paired with email)"},"email":{"type":"string","description":"Seller email address (must be paired with socialId)"},"file":{"type":"string","description":"Publicly accessible URL of the expense document (PDF, JPG, or PNG)"}},"required":["file"]},"example":{"sellerId":"a6a9700f-8571-4f9b-bfae-ba943fb96982","file":"https://i0.wp.com/avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/AK-3.png?ssl=1"}}}},"responses":{"201":{"description":"Expense document uploaded successfully","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the created expense record"},"capturedDate":{"type":"string","description":"Timestamp when the expense was captured"},"sellerId":{"type":"string","description":"Resolved seller UUID"}}}}},"example":{"payload":{"id":"a3504d9d-c187-48a0-8274-bea3b48e5663","capturedDate":"2026-02-02T13:05:54.170Z","sellerId":"a6a9700f-8571-4f9b-bfae-ba943fb96982"}}}}},"400":{"description":"Validation error","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["socialId must be a number conforming to the specified constraints","socialId should not be empty","email must be an email","email should not be empty","sellerId must be a UUID","sellerId should not be empty"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"422":{"description":"Unprocessable entity — seller not resolved or file URL unreachable","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":422,"message":"Could not resolve seller","error":"Unprocessable Entity"}}}}},"operationId":"uploadpublicexpense","summary":"Upload expense document","tags":["Partners API"],"description":"Upload an expense document for a seller via a publicly accessible file URL.\n\n**Seller identification:** Exactly one method must be used per request:\n- **Option A:** `sellerId` (UUID)\n- **Option B:** `socialId` + `email`\n\nProviding neither returns HTTP 400.\n\n**Supported file formats:** PDF, JPG, PNG."}},"/api/public/expenses/{expenseId}":{"patch":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"expenseId","in":"path","required":true,"description":"Expense UUID to update","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sellerId":{"type":"string","description":"Seller UUID the expense belongs to"},"valueDate":{"type":"string","description":"Expense value date (ISO 8601 UTC)"},"totalAmount":{"type":"number","description":"Total expense amount, minimum 0."},"vatAmount":{"type":"number","description":"VAT amount (must be ≤ totalAmount), minimum 0. Required when `totalAmount` is sent."},"currency":{"type":"string","description":"Currency code. Allowed values: `ILS`, `USD`, `EUR`, `GBP`, `TRY`, `CHF`, `SEK`, `NOK`, `CAD`, `ZAR`, `JPY`, `AUD`, `AED`, `ARS`, `BHD`, `BRL`, `CNY`, `INR`, `KRW`, `KWD`, `KZT`, `MXN`, `NGN`, `PLN`, `RSD`, `RUB`, `SAR`, `UAH`, `PHP`, `VND`."},"docType":{"type":"string","description":"Document type. Allowed values: `invoice`, `invrec`, `receipt`, `deal`, `unknown`."},"docRegulationId":{"type":"string","description":"Document regulation ID"},"classification":{"type":"integer","description":"Classification ID from the Keep expense classification table. An unknown ID is refused with `422` `Invalid classification`."},"deductibleIncomeTaxPercent":{"type":"number","description":"Deductible income tax percentage (0–100). Decimals are accepted."},"deductibleVatPercent":{"type":"number","description":"Deductible VAT percentage (0–100). Decimals are accepted."},"assetVatRefundPercent":{"type":"number","description":"Asset VAT refund percentage (0–100). Decimals are accepted."},"comment":{"type":"string","description":"Optional partner note, at most 1024 characters."},"supplierName":{"type":"string","description":"Supplier name, at most 256 characters. Applied only together with `supplierVatId`."},"supplierVatId":{"type":"string","description":"Supplier VAT ID, digits. An invalid ID is refused with `422` `Provided supplier ID is invalid`."}},"required":["sellerId"]},"example":{"sellerId":"a6a9700f-8571-4f9b-bfae-ba943fb96982","valueDate":"2025-10-28T00:00:00.000Z","totalAmount":15000,"vatAmount":2288,"currency":"ILS","docType":"invrec","docRegulationId":"5132277","classification":6,"deductibleIncomeTaxPercent":100,"deductibleVatPercent":100,"assetVatRefundPercent":0,"comment":"Optional partner note","supplierName":"Supplier Ltd","supplierVatId":"123456789"}}}},"responses":{"200":{"description":"Expense updated successfully","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"string","description":"Expense UUID"},"sellerId":{"type":"string","description":"Seller UUID"},"valueDate":{"type":"string","description":"Expense value date"},"totalAmount":{"type":"number","description":"Total expense amount"},"vatAmount":{"type":"number","description":"VAT amount"},"currency":{"type":"string","description":"Currency code"},"docType":{"type":"string","description":"Document type"},"docRegulationId":{"type":"string","description":"Document regulation ID"},"classification":{"type":"integer","description":"Classification ID"},"capturedDate":{"type":"string","description":"Timestamp when expense was captured"}}}}},"example":{"payload":{"id":"edc855f7-cb7c-4d82-8c26-baf5c296d391","sellerId":"a6a9700f-8571-4f9b-bfae-ba943fb96982","valueDate":"2025-10-28T00:00:00.000Z","totalAmount":15000,"vatAmount":2288,"currency":"ILS","docType":"invrec","docRegulationId":"5132277","classification":6,"capturedDate":"2025-10-28T09:13:37.423Z"}}}}},"400":{"description":"Validation error, and the message `Bad identifier` when the expense does not exist.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"403":{"description":"Partner is not authorized to update this expense","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"}}}}}},"422":{"description":"Unprocessable Entity. Messages: `Only expenses with pending status can be updated`, `Could not resolve seller`, `Provided supplier ID is invalid`, `Invalid classification`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}}}}},"429":{"description":"Rate limit exceeded","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"updatepublicexpense","summary":"Update expense","tags":["Partners API"],"description":"Partially update an existing expense document. Only expenses with `pending` status can be updated.\n\nThe partner can only update expenses within their own scope, and the expense must belong to the provided `sellerId`.\n\n**Immutable fields** (ignored if provided): `id`, `uid`, `partnerId`, `createdAt`, `updatedAt`, `updatedBy`, `seller`, `supplierSnapshot`, `vatReportSnapshot`, `isAbleToAutoApprove`, `status`."}},"/api/public/sellers/{sellerId}/update":{"put":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"sellerId","in":"path","required":true,"description":"Seller UUID (v4), as returned by Create seller or Get seller. An MPL is not accepted here.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","description":"Seller's first name, 2 to 250 characters: letters, spaces and the marks `-` `_` `.` `,` `'` `\"` `״` `(` `)` `:` `;`."},"lastName":{"type":"string","description":"Seller's last name, 2 to 250 characters: letters, spaces and the marks `-` `_` `.` `,` `'` `\"` `״` `(` `)` `:` `;`."},"email":{"type":"string","description":"Primary email address"},"contactEmail":{"type":"string","description":"Business contact email"},"phone":{"type":"string","description":"Phone number, 1 to 250 characters."},"businessName":{"type":"string","description":"Legal business name, at most 250 characters."},"businessType":{"type":"integer","description":"Israeli business type.\n\n- `0` Not sure (לא ידוע)\n- `1` Osek Murshe, sole proprietorship (עוסק מורשה)\n- `2` Osek Patur, exempt small business (עוסק פטור)\n- `3` Incorporated company (חברה בע\"מ)\n- `4` Partnership (שותפות)\n- `6` Non-profit (עמותה)\n- `7` Limited partnership (שותפות מוגבלת)\n- `8` Publicly traded company (חברה ציבורית)\n- `9` Shared cooperative (אגודה שיתופית)\n- `10` Public benefit company (חברה לתועלת הציבור)"},"businessNumber":{"type":"string","description":"Israeli business registration number (ח.פ. / עוסק מורשה). Digits only, at most 9, with a valid check digit."},"socialId":{"type":"string","description":"Israeli ID number (תעודת זהות). Digits only, at most 9, with a valid check digit."},"industryClassification":{"type":"number","description":"Industry classification code"},"bankId":{"type":"string","description":"Israeli bank code Digits only."},"accountNumber":{"type":"string","description":"Bank account number Digits only."},"branchNumber":{"type":"string","description":"Bank branch number Digits only."},"logo":{"type":"string","description":"Business logo as base64 encoded data URI"}},"required":["firstName","lastName","email","contactEmail","phone","businessName","businessType","businessNumber","socialId"]},"example":{"firstName":"David","lastName":"Cohen","email":"david.cohen1115@example.com","contactEmail":"seller@example.com","phone":"0500000008","businessName":"Cohen Electronics","businessType":2,"businessNumber":"330988015","socialId":"123456782","bankId":"12","accountNumber":"123456789012345","branchNumber":"123","logo":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."}}}},"responses":{"200":{"description":"Seller updated successfully","x-response-kind":"success","content":{"application/json":{"example":{}}}},"400":{"description":"Bad Request. Returned for validation errors, when `sellerId` is not a UUID v4, and with the message `Bad identifier` when the seller does not exist.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"403":{"description":"The seller does not belong to your partner account","x-response-kind":"error"}},"operationId":"updatesellerbyid","summary":"Update seller","tags":["Partners API"],"description":"Replace a seller's details. Send all required fields on every request."}},"/api/public/plans/activate":{"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sellerId":{"type":"string","description":"Seller UUID"},"planId":{"type":"string","description":"Plan UUID, from Get available plans"},"payer":{"type":"string","description":"Who pays for the plan. 'partner' = immediate activation, 'seller' = may require credit card. Allowed values: `partner`, `seller`."}},"required":["sellerId","planId","payer"]},"example":{"sellerId":"a6a9700f-8571-4f9b-bfae-ba943fb96982","planId":"3d653770-6376-40a5-b98e-17c598f1d7d8","payer":"partner"}}}},"responses":{"201":{"description":"Plan set successfully","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"status":{"type":"string","description":"'activated' when plan is active immediately, 'pending' when seller must complete payment first."},"message":{"type":"string","description":"Human-readable message (present when status is 'pending')"},"creditCardUrl":{"type":"string","description":"URL for seller to submit credit card details (present when status is 'pending')"}}}}},"example":{"payload":{"status":"activated"}}}}},"400":{"description":"Bad Request. Returned for validation errors, and with the message `Bad seller identifier` when the seller is unknown.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"403":{"description":"The seller does not belong to your partner account","x-response-kind":"error"},"422":{"description":"Unprocessable Entity","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":422,"message":"Bad seller configuration. Please contact support!","error":"Unprocessable Entity"}}}}},"operationId":"setsellerplan","summary":"Set seller billing plan","tags":["Partners API"],"description":"Assign a billing plan to a seller with payer-based activation flow.\n\n**Payer modes:**\n- `partner` — No credit card is required. The plan is normally activated at once. It is scheduled instead of activated when the seller is on a free plan within the trial or the sign-up month, and when a no-cost plan is chosen on days 20–31 of a month; the response is still `activated`, and the plan takes effect at the scheduled date.\n- `seller` — If the seller already has a credit card on file, the plan is activated immediately. If not, a credit card URL is returned and the plan activates once the seller completes payment.\n\n**Pending response** (`payer` is `seller` and no card is on file):\n\n```json\n{\n  \"payload\": {\n    \"status\": \"pending\",\n    \"message\": \"Please complete payment to activate plan\",\n    \"creditCardUrl\": \"<payment_url>\"\n  }\n}\n```"}},"/partner/api/documents/income":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"sellerPaymeId","in":"query","required":false,"description":"Seller PayMe ID. One of `sellerPaymeId` or `sellerId` is required.","schema":{"type":"string"}},{"name":"sellerId","in":"query","required":false,"description":"Keep seller UUID (v4). One of `sellerPaymeId` or `sellerId` is required.","schema":{"type":"string"}},{"name":"docNum","in":"query","required":false,"description":"Document number, digits only. Matches the regulation number of the document (`docRegulationId`).","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number. Minimum 0, default 0.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Items per page. Positive number, at most 500; use a whole-number item count. Default 10.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}},"description":"Each item also contains the fields sent when the document was created."}}}}}}}},"400":{"description":"Bad Request. Messages include `At least one of sellerPaymeId or sellerId should exists` and `Bad seller identifier`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}}},"operationId":"listincomedocuments","summary":"List income documents","tags":["Partners API"],"description":"Retrieve a list of income documents for a seller"}},"/partner/api/documents/income/manual":{"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seller_email":{"type":"string","description":"Seller's email address"},"seller_social_id_number":{"type":"string","description":"Seller's ID or business number, 9 digits"},"osek_type":{"type":"integer","description":"`1` Osek Murshe or `2` Osek Patur. Must match the seller's record."},"doc_type":{"type":"integer","description":"Send a supported numeric document code: `300` deal invoice, `305` invoice, `320` invoice with receipt, `330` refund, `400` receipt, `600` offer"},"value_date":{"type":"string","description":"Document date: `YYYY-MM-DD`, `DD.M.YYYY` or `DD.MM.YYYY`"},"currency":{"type":"string","description":"Allowed values: `ILS`."},"doc_language":{"type":"string","description":"Allowed values: `he`."},"client_type":{"type":"string","description":"Allowed values: `ConsumerPrivate`, `Business`."},"client_name":{"type":"string","description":"Client name"},"client_id":{"type":"string","description":"Client's ID or business number, 9 digits"},"document_number":{"type":"string","description":"Document number. Must be unique for the seller and must not start with `514` or `515`."},"document_id":{"type":"string","description":"Your identifier for the document"},"total_sum_including_vat":{"type":"number","description":"Total including VAT, in shekels"},"total_vat_number":{"type":"number","description":"VAT amount, in shekels"},"item_description":{"type":"string","description":"Item description"},"item_type":{"type":"string","description":"Allowed values: `Service`, `PhysicalGoods`, `VirtualGoods`."},"sale_currency":{"type":"string","description":"Allowed values: `ILS`."},"sale_vat_rule_vat_exempt":{"type":"boolean","description":"`true` when the item is VAT exempt"},"unit_price":{"type":"number","description":"Unit price before VAT, in shekels"},"quantity":{"type":"number","description":"Quantity"},"sum_amount_paid_with_this_payment_method":{"type":"number","description":"Amount paid, in shekels"},"payment_methods":{"type":"string","description":"Allowed values: `bank_transfer`, `credit_card`, `pay_pal`."},"origin_tax_deduction":{"type":"number","description":"Tax deducted at source, in shekels. Send `0` when there is none."},"file_id":{"type":"string","description":"ID of an already uploaded file. Required when `file_name` and `file_path` are not sent."},"file_name":{"type":"string","description":"Document file name. Required with `file_path` when `file_id` is not sent."},"file_path":{"type":"string","description":"Object key of the file in Keep storage — not a URL. Required with `file_name` when `file_id` is not sent."}},"required":["seller_email","seller_social_id_number","osek_type","doc_type","value_date","currency","doc_language","client_type","client_name","document_number","total_sum_including_vat","total_vat_number","item_description","item_type","sale_currency","sale_vat_rule_vat_exempt","unit_price","quantity","sum_amount_paid_with_this_payment_method","payment_methods","origin_tax_deduction"]},"example":{"seller_email":"seller@example.com","seller_social_id_number":"123456782","osek_type":1,"doc_type":320,"value_date":"2024-01-15","currency":"ILS","doc_language":"he","client_type":"Business","client_name":"Israel Israeli","client_id":"123456782","document_number":"10001","total_sum_including_vat":1170,"total_vat_number":170,"item_description":"Consulting Service","item_type":"Service","sale_currency":"ILS","sale_vat_rule_vat_exempt":false,"unit_price":1000,"quantity":1,"sum_amount_paid_with_this_payment_method":1170,"payment_methods":"bank_transfer","origin_tax_deduction":0,"file_name":"invoice.pdf","file_path":"uploads/invoices/invoice.pdf"}}}},"responses":{"201":{"description":"Document created","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"string","description":"Document ID"}}}}}}}},"400":{"description":"Bad Request. Returned for validation errors and these refusals: `Bad document number`, `Bad seller identifier`, `There is already document with the same number`, `Could not get file!`, and an error when `osek_type` does not match the seller's record.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}}},"operationId":"createmanualincomedocument","summary":"Create manual income document","tags":["Partners API"],"description":"Create a new income document manually"}},"/partner/api/statistic/checkpoints":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"socialId","in":"query","required":true,"description":"Seller's Israeli ID number: digits only, with a valid check digit.","schema":{"type":"string"}},{"name":"reportingYear","in":"query","required":true,"description":"Reporting year, 4 digits","schema":{"type":"string"}},{"name":"reportingMonths[]","in":"query","required":true,"description":"A month as a two-digit string, `01` to `12`. Repeat the parameter once per month, at most 12: `reportingMonths[]=06&reportingMonths[]=08`. Without the brackets (`reportingMonths=06`) the request is rejected with `400`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","description":"One object for the requested months. The totals are summed over those months.","properties":{"reportingYear":{"type":"string"},"reportingMonths":{"type":"array"},"seller":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"sellerStatus":{"type":"integer","description":"Seller status: `-1` new, `0` closed, `1` active."},"accountEmail":{"type":"string"},"phone":{"type":"string"},"businessNumber":{"type":"integer"},"businessType":{"type":"integer","description":"Business type, the same numeric codes as `businessType` in Create seller (`-1` other)."},"industryClassificationId":{"type":"integer"},"idNumber":{"type":"integer"},"socialSecurityAdvAmount":{"type":"number"}}},"directDebit":{"type":"object","description":"Direct debit authorisation per authority, keys `tax-authority`, `vat-authority`, `social-security`. Values: `0` none, `1` started, `2` filled in, `3` authorised."},"paychecks":{"type":"object","description":"Salary figures from the last checkpoint in the period.","properties":{"totalIncome":{"type":"number"},"totalTax":{"type":"number"},"creditPoints":{"type":"number"},"marginalTaxRate":{"type":"number"}}},"totalIncomesWithoutVat":{"type":"number"},"totalIncomesVat":{"type":"number"},"totalIncomesWithVat":{"type":"number"},"totalIncomesDebts":{"type":"number"},"totalIncomesDeposit":{"type":"number"},"totalIncomesOriginTaxDeduction":{"type":"number"},"totalExpensesWithoutVat":{"type":"number"},"totalExpensesWithVat":{"type":"number"},"totalDeductibleExpenses":{"type":"number"},"totalDeductibleExpensesVat":{"type":"number"},"refundPoints":{"type":"number"},"profit":{"type":"number"},"totalIncomesWithoutVatForPeriod":{"type":"number"},"totalIncomesOriginTaxDeductionForPeriod":{"type":"number"},"pendingExpensesTotalWithoutVat":{"type":"number"},"pendingExpensesTotalWithVat":{"type":"number"},"pendingExpensesTotalDeductible":{"type":"number"},"pendingExpensesTotalDeductibleVat":{"type":"number"},"pendingExpensesTotalDeductibleAssetVat":{"type":"number"}}}}}}}},"400":{"description":"Bad Request","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"404":{"description":"No seller has this ID number. Message: `Seller not found`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}}}}}},"operationId":"getcheckpoints","summary":"Get financial checkpoints","tags":["Partners API"],"description":"Retrieve financial checkpoints for a seller"}},"/partner/api/statistic/tax-predictions":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"socialId","in":"query","required":true,"description":"Seller's Israeli ID number: digits only, with a valid check digit.","schema":{"type":"string"}},{"name":"reportingYear","in":"query","required":true,"description":"Reporting year, 4 digits","schema":{"type":"string"}},{"name":"reportingMonths[]","in":"query","required":true,"description":"A month as a two-digit string, `01` to `12`. Repeat the parameter once per month, at most 12: `reportingMonths[]=06&reportingMonths[]=08`. Without the brackets (`reportingMonths=06`) the request is rejected with `400`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"predictions":{"type":"array","items":{"type":"object","properties":{"reportingYear":{"type":"string"},"reportingMonth":{"type":"string"},"totalIncomesWithoutVat":{"type":"number"},"totalIncomesOriginTaxDeduction":{"type":"number"},"totalDeductibleExpenses":{"type":"number"},"yearlyPredictedProfit":{"type":"number"},"predictedTaxAmount":{"type":"number"},"paychecksPredictedSalary":{"type":"number"},"paychecksPredictedTax":{"type":"number"},"refundPointsValue":{"type":"number"},"predictedTaxRateADV":{"type":"number"}}}},"reportingYear":{"type":"string"},"reportingMonths":{"type":"array"},"seller":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"sellerStatus":{"type":"integer","description":"Seller status: `-1` new, `0` closed, `1` active."},"accountEmail":{"type":"string"},"phone":{"type":"string"},"businessNumber":{"type":"integer"},"businessType":{"type":"integer","description":"Business type, the same numeric codes as `businessType` in Create seller (`-1` other)."},"industryClassificationId":{"type":"integer"},"idNumber":{"type":"integer"},"socialSecurityAdvAmount":{"type":"number"}}}}}}}}}},"400":{"description":"Bad Request","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":400,"message":["Validation failed"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer"},"message":{"type":"string"}}},"example":{"statusCode":401,"message":"Unauthorized"}}}},"404":{"description":"No seller has this ID number. Message: `Seller not found`.","x-response-kind":"error","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"integer","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}}}}}},"operationId":"gettaxpredictions","summary":"Get tax predictions","tags":["Partners API"],"description":"Retrieve tax predictions for a seller"}}}}