POST /api/billing/v1/create-document

Issues a numbered, immutable document and returns it. Idempotent by apiIdentifier.

Two request shapes are accepted, detected by whether the JSON body has a top-level doc:

Use the compatible shape only to migrate a site that already calls Invoice4U's CreateDocument (change the URL and the token, nothing else). New code should use the native shape.

Native shape#

POST /api/billing/v1/create-document
X-Api-Key: bk_…
Content-Type: application/json

{
  "apiIdentifier": "order-12345",
  "document": {
    "docType": 3,
    "customerName": "אורן כהן — סטודיו לעיצוב",
    "customerUniqueId": "515131274",
    "customerEmail": "[email protected]",
    "subject": "תשלום על בניית אתר תדמית",
    "taxIncluded": true,
    "vatBp": 1800,
    "issueDate": "2026-09-29",
    "lines": [{ "name": "בניית אתר תדמית", "quantityMilli": 1000, "unitPriceAgorot": 450000 }],
    "payments": [{ "paymentType": 3, "amountAgorot": 450000, "date": "2026-09-29" }]
  }
}

Response 200:

{
  "id": "3f2b7c1e-9d4a-4c55-8a51-6d1e0f6b7a10",
  "docNumber": 1042,
  "status": 1,
  "totalAgorot": 450000,
  "alreadyExisted": false,
  "viewUrl": "https://invoice.slk.co.il/billing/documents/3f2b7c1e-9d4a-4c55-8a51-6d1e0f6b7a10/view"
}

alreadyExisted: true means this apiIdentifier was used before and you are seeing the stored document. In sandbox mode: docNumber is "SBX-000003", status is 0, sandbox: true is present and there is no viewUrl.

Document fields (document)#

Required: docType, customerName, subject, taxIncluded, vatBp, issueDate, lines.

Lines#

Mixed baskets work: give each line its own vatBp; VAT is computed and summed per line.

Payments#

Payment documents (types 2, 3, 9, 11) must satisfy sum(payments.amountAgorot) + withholdingAgorot == total, or the call fails with 422. Deductions at source (payment types 6, 21, 22) are never sent as payment rows — use withholdingAgorot.

Document types#

(There is no type 10.)

Examples per document type#

All examples use the native shape; add "apiIdentifier" at the top level as shown in the first example.

Receipt against an invoice#

Issued invoice 3f2b7c1e-… (₪1,180) is paid by Bit. The receipt's single line is the amount received; VAT is 0 on receipts.

{
  "apiIdentifier": "receipt-for-inv-1042",
  "document": {
    "docType": 2,
    "customerName": "נועה לוי",
    "subject": "קבלה על חשבונית מס 1042",
    "taxIncluded": true,
    "vatBp": 0,
    "issueDate": "2026-09-29",
    "referenceDocIds": ["3f2b7c1e-9d4a-4c55-8a51-6d1e0f6b7a10"],
    "lines": [{ "name": "תשלום עבור חשבונית מס 1042", "quantityMilli": 1000, "unitPriceAgorot": 118000 }],
    "payments": [{ "paymentType": 8, "amountAgorot": 118000, "date": "2026-09-29" }]
  }
}

When the receipt brings the invoice's open balance to zero, a document.paid webhook fires for the invoice.

Credit note#

{
  "apiIdentifier": "credit-inv-1042",
  "document": {
    "docType": 4,
    "customerName": "נועה לוי",
    "customerUniqueId": "301234567",
    "subject": "זיכוי על חשבונית מס 1042",
    "taxIncluded": true,
    "vatBp": 1800,
    "issueDate": "2026-09-29",
    "referenceDocIds": ["3f2b7c1e-9d4a-4c55-8a51-6d1e0f6b7a10"],
    "lines": [{ "name": "ייעוץ שעתי — זיכוי", "quantityMilli": 1000, "unitPriceAgorot": 35000 }]
  }
}

The credited total may not exceed the referenced document's total; a fully credited or cancelled document cannot be credited again.

חשבונית מס (no payment)#

{
  "apiIdentifier": "inv-2026-0917",
  "document": {
    "docType": 1,
    "customerName": "חנות הפרחים של דנה בע\"מ",
    "customerUniqueId": "514987654",
    "subject": "שירותי תחזוקה — ספטמבר",
    "taxIncluded": false,
    "vatBp": 1800,
    "issueDate": "2026-09-29",
    "dueDate": "2026-10-29",
    "lines": [{ "name": "מנוי תחזוקה חודשי", "quantityMilli": 1000, "unitPriceAgorot": 29000 }]
  }
}

Here taxIncluded: false, so ₪290 is the price before VAT and the total is ₪342.20.

Donation receipt#

{
  "apiIdentifier": "donation-2026-00871",
  "document": {
    "docType": 11,
    "customerName": "משפחת אברהם",
    "customerUniqueId": "300123456",
    "subject": "תרומה לקרן מלגות",
    "taxIncluded": false,
    "vatBp": 0,
    "issueDate": "2026-09-29",
    "lines": [{ "name": "תרומה", "quantityMilli": 1000, "unitPriceAgorot": 36000, "vatBp": 0 }],
    "payments": [{ "paymentType": 1, "amountAgorot": 36000, "date": "2026-09-29", "cardLast4": "4242" }]
  }
}

Caveat: a donation is never subject to VAT, so use vatBp: 0. A document issued through this endpoint goes through the generic engine only. The dashboard's donation flow additionally checks the organisation's §46 details, prints the §46 legal text and reports the donation to the Tax Authority; the API does not. Use the dashboard flow for donations that must be reported.

Foreign currency#

{ "currency": "USD", "fxRateMillionths": 3710000 }

Add these two fields to any document; without an exchange rate a non-ILS document is refused, because the books need the shekel value.

Invoice4U-compatible shape#

{
  "doc": {
    "DocumentType": 3,
    "Subject": "תשלום חודשי",
    "ClientName": "לקוח בע\"מ",
    "ClientEmail": "[email protected]",
    "UniqueID": "515131274",
    "TaxIncluded": true,
    "TaxPercentage": 18,
    "ApiIdentifier": "order-12345",
    "Items": [{ "Name": "מנוי חודשי", "Quantity": 1, "Price": 1180, "TaxPercentage": 18 }],
    "Payments": [{ "PaymentType": 3, "Amount": 1180, "Date": "/Date(1723372800000)/" }]
  },
  "token": "bk_…"
}

Response:

{ "d": { "DocumentNumber": 5001, "ID": "…", "UniqueID": "…", "IsSuccess": true, "ErrorMessage": null,
         "PrintOriginalPDFLink": "https://…/view", "PrintCertifiedCopyPDFLink": "https://…/view" } }

Field mapping and rules:

• Items[].Price is shekels (float) and becomes agorot; Quantity becomes quantityMilli; TaxPercentage (document or line) must be 0 or 18.
• Payments[].Date accepts /Date(1723372800000)/ or an ISO date/datetime.
• ApiIdentifier is required and non-blank (it is the idempotency key). Items is required and non-empty.
• ClientName is required for DocumentType 1 and 4; for 2 and 3 a blank name falls back to "לקוח/ה".
• Currency ≠ ILS needs ExchangeRate (ILS per unit, float).
• RoundAmount non-zero rounds the total to whole shekels.
• UniqueID maps to the buyer's ID. Total and Items[].Total are accepted and ignored.
• The issue date is always today (UTC). There is no way to back-date in this shape, and no referenceDocIds, so credit notes (4), return notes (12), self-credits (15) and receipts that must reference an invoice cannot be issued this way — use the native shape.
• DocumentNumber is an integer; in sandbox it is the string "SBX-000123".
• Errors come as {"d":{"IsSuccess":false,"ErrorMessage":"…"}} with the HTTP status of the failure.

Validation (native shape)#

Checked in this order, first failure wins, each answers 422 with a specific message:

Plan refusals are also 422: the free plan cannot issue through the API, and past the monthly allowance issuing is refused, both with a Hebrew message.

Send subject and customerName on every document; the engine requires them.

Webhooks and side effects#

A newly issued document fires document.issued; a settled reference additionally fires document.paid. A repeat call for an existing apiIdentifier fires nothing. Fiscal documents are hash-chained and digitally signed at issue (unless unsigned is set). Do not rely on the API to email the customer: store customerEmail on the document and deliver the document yourself.

Status codes#

200 issued or existing · 400 body is not JSON · 401 bad key · 403 dormant · 422 refused · 429 rate limited. See errors.