Create manual income document

Sandbox: your partner domain on the Keep sandbox: POST https://<partner_domain>.keep.co.il/partner/api/documents/income/manual
Production: your partner domain: POST https://<partner_domain>.keep.co.il/partner/api/documents/income/manual

Credentials

Header Authorization: Bearer <token>

Create a new income document manually

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Field	Type	Required	Description
`seller_email`	string	yes	Seller's email address
`seller_social_id_number`	string	yes	Seller's ID or business number, 9 digits
`osek_type`	integer	yes	`1` Osek Murshe or `2` Osek Patur. Must match the seller's record.
`doc_type`	integer	yes	Send a supported numeric document code: `300` deal invoice, `305` invoice, `320` invoice with receipt, `330` refund, `400` receipt, `600` offer
`value_date`	string	yes	Document date: `YYYY-MM-DD`, `DD.M.YYYY` or `DD.MM.YYYY`
`currency`	string	yes	Allowed values: `ILS`.
`doc_language`	string	yes	Allowed values: `he`.
`client_type`	string	yes	Allowed values: `ConsumerPrivate`, `Business`.
`client_name`	string	yes	Client name
`client_id`	string	no	Client's ID or business number, 9 digits
`document_number`	string	yes	Document number. Must be unique for the seller and must not start with `514` or `515`.
`document_id`	string	no	Your identifier for the document
`total_sum_including_vat`	number	yes	Total including VAT, in shekels
`total_vat_number`	number	yes	VAT amount, in shekels
`item_description`	string	yes	Item description
`item_type`	string	yes	Allowed values: `Service`, `PhysicalGoods`, `VirtualGoods`.
`sale_currency`	string	yes	Allowed values: `ILS`.
`sale_vat_rule_vat_exempt`	boolean	yes	`true` when the item is VAT exempt
`unit_price`	number	yes	Unit price before VAT, in shekels
`quantity`	number	yes	Quantity
`sum_amount_paid_with_this_payment_method`	number	yes	Amount paid, in shekels
`payment_methods`	string	yes	Allowed values: `bank_transfer`, `credit_card`, `pay_pal`.
`origin_tax_deduction`	number	yes	Tax deducted at source, in shekels. Send `0` when there is none.
`file_id`	string	no	ID of an already uploaded file. Required when `file_name` and `file_path` are not sent.
`file_name`	string	no	Document file name. Required with `file_path` when `file_id` is not sent.
`file_path`	string	no	Object key of the file in Keep storage — not a URL. Required with `file_name` when `file_id` is not sent.

Request 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"
}

Code samples

curl

curl -X POST 'https://<partner_domain>.keep.co.il/partner/api/documents/income/manual' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "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"
}'

Node.js

const response = await fetch("https://<partner_domain>.keep.co.il/partner/api/documents/income/manual", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "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"
  }),
});

console.log(await response.text());

Python

import requests

response = requests.post(
    "https://<partner_domain>.keep.co.il/partner/api/documents/income/manual",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "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",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "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"
}
BODY;

$ch = curl_init('https://<partner_domain>.keep.co.il/partner/api/documents/income/manual');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Responses

201 — Document created (success)

Field	Type	Description
`payload`	object
`payload.id`	string	Document ID

400 — 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. (error)

Field	Type	Description
`statusCode`	integer	HTTP status code
`message`	string	Error message(s)
`error`	string	Error type

{
  "statusCode": 400,
  "message": [
    "Validation failed"
  ],
  "error": "Bad Request"
}

401 — Unauthorized (error)

Field	Type	Description
`statusCode`	integer
`message`	string

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Create manual income document

Credentials

Parameters

Request body

Request example

Code samples

curl

Node.js

Python

PHP

Responses

201 — Document created (success)

400 — 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. (error)

401 — Unauthorized (error)

400 — 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. (error)