Create manual income document

Credentials

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, when osek_type does not match the seller's record, Provided Osek Type does not match the one on record. Please update your Osek Type with your courier partner before uploading documents. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type
{
  "statusCode": 400,
  "message": [
    "seller_email must be an email"
  ],
  "error": "Bad Request"
}

401 — Unauthorized (error)

Field Type Description
statusCode integer
message string
{
  "statusCode": 401,
  "message": "Unauthorized"
}

403 — Forbidden: the access token has no scope this endpoint accepts. Message: Forbidden resource. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message
error string Error type
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}