A developer's guide to the Rivhit Online API and iCredit - the Document.New endpoint, why document type decides whether a payment object is mandatory, the retry problem with issued documents, and what to settle before you write code.
Key takeaways
- The document type decides the required fields. A receipt or a combined invoice-receipt demands a payment object, and each payment method has its own mandatory fields - a plain invoice does not.
- This is a WCF-style service, not a modern REST API. Operations are named endpoints like Document.New rather than resources with HTTP verbs, so REST habits will mislead you.
- An issued document cannot be edited or deleted. Design retries around that: a timed-out request may have succeeded, and a blind retry produces a duplicate tax document.
- Rivhit ships both a documents API and iCredit, its payment gateway. Decide early whether you are issuing documents, taking payments, or both - they are separate integrations with separate credentials.
Rivhit is one of the long-established accounting systems in Israel, and it exposes two separate interfaces: an API for issuing documents in Rivhit Online, and iCredit, its payment gateway. Untangling the two is the first thing worth settling, because they serve different purposes and use different credentials.
What this actually is: not modern REST
The base is https://api.rivhit.co.il/online/RivhitOnlineAPI.svc, and creating a document is the Document.New operation.
Note the shape: this is a WCF-style service - named operations, not resources with verbs. There is no POST /documents and no DELETE /documents/123. There is one endpoint per operation, and they all take POST. If you are coming from REST, that expectation will confuse you more than anything else in the interface.
Official documentation lives at rivhit-api.readme.io, and a live operations list is available at the service's /help path. That is the page to open before writing a line - it shows the operations that exist and the request shape of each, against the version actually running.
Document.New: the fields you send and what comes back
The Rivhit API reference marks five fields of Document.New as required: api_token, document_type, customer_id, last_name and items. Everything travels in the JSON body, the token included - there is no Authorization header.
| Field | What it holds | Watch out for |
|---|---|---|
api_token | The business's API token | In Rivhit Online it is under Settings, Online Settings, API tab; in Invoice Online under Settings, System Settings |
document_type | An integer document type | Read the codes your account uses from Document.TypeList rather than hard-coding them |
customer_id, last_name | The Rivhit customer id, and the customer's last name or company name | last_name is limited to 30 characters, first_name and city to 20 |
acc_ref | Your own system's identifier for the customer | Up to 9 characters, so a long CRM id will not fit |
items | Rows with catalog_number, description, quantity, price_nis | The whole request is capped at 64 KB; above that you get HTTP 413 |
payments | Required for a receipt or a tax invoice-receipt | payment_type 1 is a cheque, 2 is cash, 4 to 8 are credit cards according to your payment settings |
send_mail | Whether Rivhit emails the document to the customer | Defaults to true, so set it explicitly while testing |
A successful response returns document_number, document_link and confirmation_number - the allocation number from the Tax Authority, when one applies. If a document was issued without it because the connection to the Tax Authority failed, the documentation points to Document.InvoiceApproval for requesting the number retroactively.
The decision that drives everything: document type
The document type field is not a technical detail - it determines both the legal meaning and which fields the request must contain.
The central rule: documents representing receipt of money require a payment object. A receipt, and a combined invoice-receipt (document type 2), will not be created without payment detail. Moreover, each payment method has its own mandatory fields - cash, cheque, credit card and bank transfer do not share a structure. Sending a generic payment object will fail.
By contrast, an invoice not accompanied by payment, a delivery note or an order does not need one.
The design consequence: do not build one generic function that takes a "document type" parameter and hopes for the best. For every document type your system issues, build an explicit path with its own validation. A document that fails on a missing field is far better than one created incorrectly.
The problem that catches every first integration: retries
An issued tax document cannot be edited and cannot be deleted. Cancellation is done with an offsetting document.
Hence the recurring scenario: you send a create request, the server issues the document, and the connection drops before the response arrives. Your code sees a timeout, reads it as failure, and retries - and now there are two tax documents with two sequential numbers, one of which needs a manual cancellation in the books.
Three rules:
- Do not retry automatically after a timeout. A timeout is not a failure - it is an absence of knowledge.
- Store your own unique reference on the order or transaction, and before any retry check whether a matching document already exists.
- A missing document beats a duplicate. The first is handled in a minute; the second needs a cancellation and a paper trail.
Rivhit has a built-in guard for exactly this. Its "Prevent Duplicates" guide documents two request parameters on Document.New and Receipt.New: request_reference, a unique key you generate per operation (an order id or a UUID), and prevent_duplicates: true. Sent together, a repeated request with the same key and payload produces the document only once. Use your order reference as the key and a retry after a timeout stops being dangerous - but keep the lookup-before-retry rule for documents created before you turned the guard on.
iCredit - the other side of Rivhit
iCredit is the payment gateway. It covers dynamic payment pages, tokenising payment methods, recurring charges, and automatic document production following a payment.
The decision to make early: who issues the document? If the gateway is configured to produce a document automatically on successful payment, and your system also issues its own, you get two documents for one transaction. This is not a rare glitch; it is the common design mistake when payments and accounting land in the same project.
Pick one side and document it.
If iCredit reports payments to your server, that notification (IPN) has its own timing rule: the listener must answer 200 OK within 1.25 seconds, or iCredit sends the message again. So the listener should store the message, answer at once and process it afterwards, and it must treat a second IPN for the same sale as a duplicate. Before marking an order paid, the documentation has you confirm the message with the Verify method, passing GroupPrivateToken, TotalAmount and SaleId.
Is there a test environment for the Rivhit API?
Yes, but not a separate server. Rivhit's test environment page says the API uses the production URL in every environment; testing means calling it with the credentials of a shared demo account that the documentation publishes. Four points on that page matter before you rely on it:
- The demo account is shared, and everything in it is visible to every other tester, so real customer data never goes there.
- Test accounts must not be used to produce real legal documents.
- The demo account is not connected to iCredit, so card payments cannot be tested through it.
- The API rate limit is 200 requests per minute. A nightly sync that pulls documents one by one needs pacing.
The same page states that the API exists only for Rivhit Online and Invoice Online. The local desktop version of Rivhit has no API, so a business still on it has to move to the online product before any integration is possible.
What do Rivhit API errors look like?
Rivhit reports an error on two layers: the HTTP status, and a JSON body with error_code, client_message (usually Hebrew), debug_message (an English identifier) and data. Log all four; the Hebrew message is for a person, and the debug code is what your code should branch on.
| Code | debug_message | Usual cause |
|---|---|---|
| -20 | CUSTOMER_NOT_EXISTS | A customer_id that does not exist in this business |
| -23 | HENTYPE_NOT_EXISTS | A document type code that does not exist in this account |
| -28 | INVALID_ID_NUMBER | An invalid Israeli ID number |
| -29 | INVALID_VAT_NUMBER | An invalid dealer (VAT) number |
| -94 | INVALID_AMOUNT | An amount the service rejects |
A 400 that comes back as an HTML page titled "Request Error" is a different problem: the WCF layer could not parse the request at all. The usual causes are malformed JSON, a missing Content-Type header, or JSON sent to an endpoint that expects SOAP.
What to persist
- The document id and its sequential number
- The document link, so you never regenerate it
- The document type and timestamp
- The full API response, including on success - it is the only evidence in a dispute or an accounting query
What should you settle before writing code?
- Document types. Which documents the system issues, and at what point in the process. That is the business accountant's decision, not the developer's, because it determines when revenue is recognised.
- VAT. Whether the amounts you send are inclusive or exclusive. Verify against a real document rather than assuming.
- Exempt dealers. An exempt dealer does not issue a tax invoice. If the system serves more than one dealer type, that changes the document type.
- Allocation numbers. Confirm the flow handles the Tax Authority requirement before go-live. See invoice allocation numbers for developers.
- Secrets. The credentials permit issuing tax documents on behalf of the business. Environment variables or a secrets manager only - not source control, not logs, not client-side code.
For a comparison of the Israeli systems by how easy they are to connect to, see comparing the Israeli invoicing APIs, and for the customer-sync side, connecting invoicing software to a CRM.
Sources
Frequently asked questions
Does Rivhit have an API?
Yes. Rivhit Online exposes a documents API at https://api.rivhit.co.il/online/RivhitOnlineAPI.svc, where creating a document is the Document.New operation. Rivhit also ships iCredit, a separate payment gateway with its own credentials. Documentation is published at rivhit-api.readme.io, and the live operation list is at the service's /help path.
Why does creating a receipt in Rivhit fail with missing fields?
Because documents that represent receipt of money require a payment object, and each payment method has its own mandatory fields. A receipt, and a combined invoice-receipt (type 2), will not be created without it, while a plain invoice or delivery note does not need one. Sending a generic payment structure across all methods will fail - build an explicit path per document type.
Is the Rivhit API a REST API?
Not in the modern sense. It is a WCF-style service built around named operations such as Document.New, all invoked by POST, rather than resources addressed with HTTP verbs. There is no DELETE on a document and no resource-per-entity URL structure, so REST assumptions will mislead you when reading the documentation.
How do you avoid duplicate invoices when a Rivhit call times out?
Do not retry automatically. A timeout means you do not know whether the document was issued, and an issued tax document cannot be deleted - only offset with a counter-document. Store your own unique reference on the order, and before any retry query whether a document already exists for it. A missing document takes a minute to fix; a duplicate needs a cancellation and a paper trail.
Should iCredit or my own system issue the invoice?
One of them, never both. iCredit can be configured to produce a document automatically on a successful payment; if your system also issues its own, a single transaction ends up with two tax documents. This is the most common design mistake when a project connects payments and accounting together. Decide which side owns document production and write it down.
Is there a Rivhit API sandbox?
Not a separate server. The Rivhit API uses its production URL in every environment, and testing is done with a shared demo account whose credentials the documentation publishes. Its data is visible to every tester, it must not produce real legal documents, and it is not connected to iCredit, so card payments cannot be tested there.
What is the Rivhit API rate limit?
Rivhit documents a cap of 200 requests per minute, and a maximum request size of 64 KB - a larger body returns HTTP 413, usually because one document carries too many rows or very long descriptions. A sync job that reads documents one at a time should be paced to stay under the per-minute cap.
Where do I find the Rivhit API token?
In Rivhit Online it is under Settings, Online Settings, on the API tab; in Invoice Online it is under Settings, System Settings. The token is sent as the api_token field in the JSON body of every call, not in a header, and it allows issuing tax documents for the business - keep it server-side only.
Keep reading
Related service
Integrations
Make the systems you already pay for talk to each other.
Have a project like this?
Tell me what you're trying to automate or build. I reply within 24 business hours with a few targeted questions, then we walk through it on a free 30-minute call, with no commitment. You come away with a scope, a timeline and a fixed price - or a straight answer that it isn't worth building.