{"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":"Seller API"}],"paths":{"/seller/api/documents/income":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"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"}},{"name":"documentTypes","in":"query","required":false,"description":"Filter by document type. Repeat for several types. Allowed values: `invoice`, `receipt`, `invrec`, `deal`, `refund`, `offer`.","schema":{"type":"string"}},{"name":"fromDate","in":"query","required":false,"description":"Filter documents from this date","schema":{"type":"string"}},{"name":"toDate","in":"query","required":false,"description":"Filter documents until this date","schema":{"type":"string"}},{"name":"documentNumber","in":"query","required":false,"description":"Document number, digits","schema":{"type":"string"}},{"name":"clientEmail","in":"query","required":false,"description":"Client email","schema":{"type":"string"}},{"name":"field","in":"query","required":false,"description":"Sort field. Default `docValueDate`.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort direction: `asc` or `desc`. Default `desc`.","schema":{"type":"string"}}],"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"},"type":{"type":"string"},"docValueDate":{"type":"string"},"title":{"type":"string"},"docLang":{"type":"string"},"docRegulationId":{"type":"string"},"currency":{"type":"string"},"discount":{"type":"number"},"vatAmount":{"type":"number"},"totalWithVat":{"type":"number"},"url":{"type":"string"}}}}}}}}}}},"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","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":401,"message":"Unauthorized","error":"Unauthorized"}}}}},"operationId":"listsellerincomedocuments","summary":"List income documents","tags":["Seller API"],"description":"Retrieve a list of income documents for the authenticated seller. Documents the seller created in the Keep app are included."},"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Document type\n\nAllowed values: `invoice`, `receipt`, `invrec`, `deal`, `refund`, `offer`."},"client":{"type":"object","properties":{"name":{"type":"string","description":"Client/customer name, at most 255 characters."},"email":{"type":"string","description":"Client email address"},"phone":{"type":"string","description":"Client phone number"},"socialId":{"type":"string","description":"Client's social/business ID number (ת.ז. / ח.פ.). Exactly 9 digits. Required when the document total is 23,600 ILS or more."}},"required":["name"]},"currency":{"type":"string","description":"Document currency (currently only ILS supported)"},"docValueDate":{"type":"string","description":"Document value date"},"dueDate":{"type":"string","description":"Payment due date (optional)."},"title":{"type":"string","description":"Document title (optional), at most 255 characters."},"docLang":{"type":"string","description":"Document language\n\nAllowed values: `he`, `en`."},"items":{"type":"array","description":"Document line items","items":{"type":"object","properties":{"name":{"type":"string","description":"Item name/description, at most 255 characters."},"quantity":{"type":"number","description":"Item quantity, at least 1."},"itemNetPrice":{"type":"number","description":"Item net price (before VAT)"},"itemTotalPrice":{"type":"number","description":"Item total price (calculated). Required for `invoice`, `invrec`, `deal`, `refund` and `offer`."},"itemSumNetTotalPrice":{"type":"number","description":"Item sum net total price (quantity * itemNetPrice)"},"itemCurrency":{"type":"string","description":"Item currency"},"isNoItemVat":{"type":"boolean","description":"VAT exempt flag (true = no VAT for this item). Required for `invoice`, `invrec`, `deal`, `refund` and `offer`."}},"required":["name","quantity","itemNetPrice","itemCurrency"]}},"bankDetails":{"type":"object","description":"Bank account details for payment","properties":{"bankName":{"type":"string","description":"Bank name"},"branchNumber":{"type":"number","description":"Branch number"},"accountNumber":{"type":"number","description":"Account number"},"accountName":{"type":"string","description":"Account holder name"},"IBAN":{"type":"string","description":"IBAN number"}}},"subTotal":{"type":"number","description":"Subtotal before discount. Required for `invoice`, `invrec`, `deal`, `refund` and `offer`."},"discount":{"type":"number","description":"Discount amount"},"totalWithoutVatAmount":{"type":"number","description":"Total amount without VAT. Required for `invoice`, `invrec`, `deal`, `refund` and `offer`."},"vatAmount":{"type":"number","description":"VAT amount. Required for `invoice`, `invrec`, `deal`, `refund` and `offer`."},"totalAmount":{"type":"number","description":"Total amount including VAT"},"totalPaid":{"type":"number","description":"Total amount paid. Required for `receipt` and `invrec`, and must equal `totalAmount`."},"originTaxDeduction":{"type":"number","description":"Tax deduction at source (ניכוי מס במקור). Required for `receipt` and `invrec`; send `0` when there is none."},"comment":{"type":"string","description":"Document comments/notes, at most 255 characters."},"cash":{"type":"object","description":"Cash payment details","properties":{"date":{"type":"string","description":"Payment date"},"amount":{"type":"number","description":"Payment amount"}},"required":["date","amount"]},"cc":{"type":"object","description":"Credit card payment details","properties":{"date":{"type":"string","description":"Payment date"},"amount":{"type":"number","description":"Payment amount"},"last4Digits":{"type":"string","description":"Last 4 digits of card"}},"required":["date","amount"]},"bank-transfer":{"type":"object","description":"Bank transfer payment details","properties":{"date":{"type":"string","description":"Payment date"},"amount":{"type":"number","description":"Payment amount"},"bankNumber":{"type":"string","description":"Bank code"},"branchNumber":{"type":"integer","description":"Branch number"},"accountNumber":{"type":"integer","description":"Account number"}},"required":["date","amount","accountNumber"]},"cheque":{"type":"object","description":"Cheque payment details","properties":{"date":{"type":"string","description":"Cheque date"},"receivedDate":{"type":"string","description":"Date cheque was received"},"amount":{"type":"number","description":"Payment amount"},"chequeNumber":{"type":"number","description":"Cheque number"},"bankNumber":{"type":"string","description":"Bank code"},"branchNumber":{"type":"integer","description":"Branch number"},"accountNumber":{"type":"integer","description":"Account number"}},"required":["date","receivedDate","amount","chequeNumber"]},"e-wallet":{"type":"object","description":"E-wallet payment details (PayPal, Bit, etc.)","properties":{"date":{"type":"string","description":"Payment date"},"amount":{"type":"number","description":"Payment amount"},"appType":{"type":"string","description":"Wallet app name"},"nameOfPayingAccount":{"type":"string"},"transactionRefNumber":{"type":"string"},"additionalDetails":{"type":"string","description":"At most 255 characters."}},"required":["date","amount","appType"]},"payment":{"type":"object","description":"Payment link settings (for invoice/deal)","properties":{"isEnabled":{"type":"boolean","description":"Enable payment link"},"clientEmail":{"type":"string","description":"Email to send payment link to. One of the two is required when `isEnabled` is true."},"clientPhone":{"type":"string","description":"Phone to send payment link to. One of the two is required when `isEnabled` is true."}},"required":["isEnabled"]},"callbacks":{"type":"object","description":"Callback URLs for the asynchronous result. Each must be an `http` or `https` URL on a public host.","properties":{"success":{"type":"array","description":"URLs called when the document is issued. Body: `{ \"payload\": <the document, as Get income document returns it> }`."},"error":{"type":"array","description":"URLs called when issuing fails. Body: `{ \"document\": { \"id\": \"<id from the 202>\" }, \"error\": <reason> }`. A failed document is removed: a later Get income document with that id returns `payload: null`."}}}},"required":["type","client","currency","docValueDate","docLang","items","totalAmount"]},"example":{"type":"invoice","client":{"name":"Example Buyer","email":"buyer@example.com","phone":"0500000002","socialId":"123456782"},"currency":"ILS","docValueDate":"2024-01-15","dueDate":"2024-02-15","docLang":"he","items":[{"name":"Consulting Service","quantity":1,"itemNetPrice":100000,"itemTotalPrice":117000,"itemCurrency":"ILS","isNoItemVat":false}],"subTotal":100000,"totalWithoutVatAmount":100000,"vatAmount":17000,"totalAmount":117000,"comment":"Thank you for your business"}}}},"responses":{"202":{"description":"Document accepted","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"string","description":"Created document ID"},"url":{"type":"string","description":"URL to download/view the document"}}}}}}}},"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","description":"HTTP status code"},"message":{"type":"string","description":"Error message(s)"},"error":{"type":"string","description":"Error type"}}},"example":{"statusCode":401,"message":"Unauthorized","error":"Unauthorized"}}}},"403":{"description":"Forbidden. The seller cannot issue documents now: invoicing is not set up, the trial has ended, or the seller is closed.","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. Messages include: the client `socialId` is required for documents of 23,600 ILS and above; `Your invoice Israel token is invalid` (with `renewTokenUrl`, where the seller renews the Israel Tax Authority connection); `Record already exists`.","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":"Too many requests. The body is plain text.","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":"createsellerincomedocument","summary":"Create income document","tags":["Seller API"],"description":"Create a new income document (invoice, receipt, deal, etc.) using the new invoicing service.\n\n## More examples\n\nAmounts are in agorot (1 ILS = 100 agorot).\n\n### Receipt (cash)\n\n```json\n{\n  \"type\": \"receipt\",\n  \"client\": {\n    \"name\": \"Example Buyer\",\n    \"email\": \"buyer@example.com\"\n  },\n  \"currency\": \"ILS\",\n  \"docValueDate\": \"2024-01-15\",\n  \"docLang\": \"he\",\n  \"items\": [\n    {\n      \"name\": \"Product Sale\",\n      \"quantity\": 2,\n      \"itemNetPrice\": 50000,\n      \"itemTotalPrice\": 58500,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": false\n    }\n  ],\n  \"totalAmount\": 117000,\n  \"totalPaid\": 117000,\n  \"originTaxDeduction\": 0,\n  \"cash\": {\n    \"date\": \"2024-01-15\",\n    \"amount\": 117000\n  }\n}\n```\n\n### Invoice + Receipt (bank transfer)\n\n```json\n{\n  \"type\": \"invrec\",\n  \"client\": {\n    \"name\": \"Example Buyer\",\n    \"email\": \"buyer@example.com\",\n    \"socialId\": \"123456782\"\n  },\n  \"currency\": \"ILS\",\n  \"docValueDate\": \"2024-01-15\",\n  \"docLang\": \"he\",\n  \"items\": [\n    {\n      \"name\": \"Annual Subscription\",\n      \"quantity\": 1,\n      \"itemNetPrice\": 240000,\n      \"itemTotalPrice\": 280800,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": false\n    }\n  ],\n  \"subTotal\": 240000,\n  \"totalWithoutVatAmount\": 240000,\n  \"vatAmount\": 40800,\n  \"totalAmount\": 280800,\n  \"totalPaid\": 280800,\n  \"originTaxDeduction\": 0,\n  \"bank-transfer\": {\n    \"date\": \"2024-01-15\",\n    \"amount\": 280800,\n    \"bankNumber\": \"12\",\n    \"branchNumber\": 456,\n    \"accountNumber\": 123456\n  }\n}\n```\n\n### Receipt with multiple payments\n\n```json\n{\n  \"type\": \"receipt\",\n  \"client\": {\n    \"name\": \"Example Buyer\",\n    \"email\": \"buyer@example.com\"\n  },\n  \"currency\": \"ILS\",\n  \"docValueDate\": \"2024-01-15\",\n  \"docLang\": \"he\",\n  \"items\": [\n    {\n      \"name\": \"Professional Services\",\n      \"quantity\": 10,\n      \"itemNetPrice\": 20000,\n      \"itemTotalPrice\": 23400,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": false\n    }\n  ],\n  \"totalAmount\": 234000,\n  \"totalPaid\": 234000,\n  \"originTaxDeduction\": 0,\n  \"cash\": {\n    \"date\": \"2024-01-15\",\n    \"amount\": 34000\n  },\n  \"cc\": {\n    \"date\": \"2024-01-15\",\n    \"amount\": 200000,\n    \"last4Digits\": \"5678\"\n  }\n}\n```\n\n### Invoice with payment link\n\n```json\n{\n  \"type\": \"invoice\",\n  \"client\": {\n    \"name\": \"Example Buyer\",\n    \"email\": \"buyer@example.com\"\n  },\n  \"currency\": \"ILS\",\n  \"docValueDate\": \"2024-01-15\",\n  \"dueDate\": \"2024-01-30\",\n  \"docLang\": \"en\",\n  \"items\": [\n    {\n      \"name\": \"Online Course Subscription\",\n      \"quantity\": 1,\n      \"itemNetPrice\": 79900,\n      \"itemTotalPrice\": 93483,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": false\n    }\n  ],\n  \"subTotal\": 79900,\n  \"totalWithoutVatAmount\": 79900,\n  \"vatAmount\": 13583,\n  \"totalAmount\": 93483,\n  \"payment\": {\n    \"isEnabled\": true,\n    \"clientEmail\": \"buyer@example.com\"\n  }\n}\n```\n\n### Receipt with cheque\n\n```json\n{\n  \"type\": \"receipt\",\n  \"client\": {\n    \"name\": \"Example Buyer\",\n    \"socialId\": \"123456782\"\n  },\n  \"currency\": \"ILS\",\n  \"docValueDate\": \"2024-01-15\",\n  \"docLang\": \"he\",\n  \"items\": [\n    {\n      \"name\": \"Equipment Purchase\",\n      \"quantity\": 1,\n      \"itemNetPrice\": 1500000,\n      \"itemTotalPrice\": 1755000,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": false\n    }\n  ],\n  \"totalAmount\": 1755000,\n  \"totalPaid\": 1755000,\n  \"originTaxDeduction\": 0,\n  \"cheque\": {\n    \"date\": \"2024-02-15\",\n    \"receivedDate\": \"2024-01-15\",\n    \"amount\": 1755000,\n    \"chequeNumber\": 1234567,\n    \"bankNumber\": \"10\",\n    \"branchNumber\": 123,\n    \"accountNumber\": 987654\n  }\n}\n```\n\n### VAT-exempt items\n\n```json\n{\n  \"type\": \"invoice\",\n  \"client\": {\n    \"name\": \"Example Buyer\",\n    \"socialId\": \"123456782\"\n  },\n  \"currency\": \"ILS\",\n  \"docValueDate\": \"2024-01-15\",\n  \"dueDate\": \"2024-02-15\",\n  \"docLang\": \"he\",\n  \"items\": [\n    {\n      \"name\": \"Consulting Services (VAT exempt)\",\n      \"quantity\": 1,\n      \"itemNetPrice\": 500000,\n      \"itemTotalPrice\": 500000,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": true\n    },\n    {\n      \"name\": \"Training Materials\",\n      \"quantity\": 1,\n      \"itemNetPrice\": 100000,\n      \"itemTotalPrice\": 117000,\n      \"itemCurrency\": \"ILS\",\n      \"isNoItemVat\": false\n    }\n  ],\n  \"subTotal\": 600000,\n  \"totalWithoutVatAmount\": 600000,\n  \"vatAmount\": 17000,\n  \"totalAmount\": 617000\n}\n```\n\n## After the 202\n\nThe document is issued asynchronously. The `202` response gives its `id` and `url` at once; the result reaches each URL in `callbacks`. A callback delivery that fails is retried after 60 seconds, three attempts in all."}},"/seller/api/documents/income/{id}":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Document ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. When no document matches, `payload` is null.","x-response-kind":"success","content":{"application/json":{"schema":{"type":"object","properties":{"payload":{"type":"object","properties":{"id":{"type":"string"},"sellerId":{"type":"string"},"type":{"type":"string"},"clientId":{"type":"string"},"dueDate":{"type":"string"},"docValueDate":{"type":"string"},"title":{"type":"string"},"docLang":{"type":"string"},"items":{"type":"array","description":"Document line items: `itemId`, `quantity`, `itemNetPrice`, `itemTotalPrice`, `itemCurrency`, `isNoItemVat`. The item name is not returned."},"currency":{"type":"string"},"discount":{"type":"number"},"totalWithoutVatAmount":{"type":"number"},"vatAmount":{"type":"number"},"totalAmount":{"type":"number"},"totalPaid":{"type":"number"},"originTaxDeduction":{"type":"number"},"cash":{"type":"object","description":"Cash payment details"},"cc":{"type":"object","description":"Credit card payment: `date` and `amount`."},"bank-transfer":{"type":"object","description":"Bank transfer payment details"},"cheque":{"type":"object","description":"Cheque payment details"},"e-wallet":{"type":"object","description":"E-wallet payment details"},"comment":{"type":"string"},"url":{"type":"string"},"bankDetails":{"type":"object","description":"Bank account details for payment"},"docRegulationId":{"type":"string"},"payment":{"type":"object","description":"Payment link settings"},"createdAt":{"type":"string"}}}}}}}},"400":{"description":"Bad Request. `id` is not a UUID.","x-response-kind":"error"},"401":{"description":"Unauthorized","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":401,"message":"Unauthorized","error":"Unauthorized"}}}}},"operationId":"getsellerincomedocument","summary":"Get income document","tags":["Seller API"],"description":"Retrieve a specific income document by ID. Documents the seller created in the Keep app are returned too."}}}}