# Create manual income document

Building with an AI agent? Start at https://docs.payme.io/agents.md

- 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

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

## Code samples

### curl

```bash
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

```javascript
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

```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
<?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 |

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

### 401 — Unauthorized (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer |  |
| `message` | string |  |

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