SAP Business One Service Layer: A Developer's Integration Guide

SAP Business One exposes the Service Layer - an OData-based REST layer that is the supported way to read and write into the system from outside. It works well, but its login model is unlike any modern API, and that is where most first integrations break.

If you are choosing between systems, see also Priority vs SAP Business One.

Authentication: a session, not a token

There is no API key and no Bearer token. You log in:

POST /b1s/v1/Login
{
  "UserName": "...",
  "Password": "...",
  "CompanyDB": "..."
}

On success the Service Layer returns a B1Session entity carrying a valid session id in the response body, and sends the same id in a Set-Cookie header. You carry that cookie on every subsequent call.

ROUTEID - the cookie that breaks integrations

Alongside B1SESSION, a ROUTEID cookie is also returned. When the Service Layer sits behind a load balancer - which it does in most serious installations - that cookie is what routes you back to the instance where your session was created.

If your HTTP client stores only B1SESSION and ignores ROUTEID, the result is intermittent authentication failures: some calls succeed and some are rejected, with no obvious pattern. Use a cookie jar that carries both rather than copying a single header by hand.

Expiry: 30 minutes and error -5002

The default is expiry after 30 minutes of inactivity. When the session lapses, the call fails with code -5002.

The practical consequence: any process running longer than half an hour must handle this. A nightly import, a scheduled sync, a queue worker - all will die midway unless something catches -5002, re-authenticates, and retries the failed call. This is normal behaviour, not an edge case.

The correct pattern is to wrap every call: on -5002, log in once and retry. If that also fails, stop rather than loop.

One operational point that is easy to miss: each user has a limit on concurrent open sessions. Code that logs in on every call, instead of holding one session, will exhaust that quota and start failing - and it will look like an entirely different problem.

OData v4, not v3

As of Feature Pack 2405, OData v3 is deprecated and v4 is the primary protocol.

This matters for a practical reason: a large share of the examples and blog posts you find by searching were written in the v3 era. Differences in query syntax, metadata and response format will make that code fail on a current installation in confusing ways. Check which version the installation offers before adopting an example from the web.

Creating documents - in one call

The most important rule when writing to an ERP: a document is created in a single request, with its lines nested in the body. Not a header followed by lines in separate calls.

The reason is integrity, not efficiency. If you created an order header and the second call adding lines failed, the system is left holding an empty order with a sequential number that somebody has to clean up by hand. On tax documents it is worse.

The same logic applies to cancellation: an issued document is not deleted. The correct route is an offsetting document or a built-in cancellation depending on the document type - and that decision belongs with the business's accountant, not the developer.

Permissions and what they hide

The Service Layer user's permissions apply to every call. If the user cannot see an object in the interface, they will not see it through the API either.

The trap: this usually manifests as missing records rather than a permission error. A query returns 200 with fewer results than you expected, and your code carries on as normal. Cross-check a count against the interface the first time rather than assuming the response is complete.

Decisions before you start

• A test environment. As with any ERP, a document issued in production by mistake is an accounting problem. Confirm there is a separate CompanyDB for development, and keep the CompanyDB name in an environment variable rather than in code.
• Custom fields. SAP B1 installations accumulate user-defined fields and custom objects. Two clients on the same version can require different code. Read the metadata of that specific installation instead of relying on generic documentation.
• Hebrew and RTL. Hebrew text fields pass through the API normally, but rendering them in PDFs, emails and exports is a separate story. See Hebrew and RTL in business software.
• Who owns the logic. If your system decides which document type to issue and when, that is an accounting decision requiring sign-off, not a technical choice.

A debugging order

1. Confirm /Login returns 200 and that the cookie jar captured both B1SESSION and ROUTEID.
2. Intermittent auth failures - almost always a missing ROUTEID.
3. Failure after a pause - check whether the code is -5002, meaning an expired session.
4. Missing records - check the API user's permissions against the interface.
5. An example from the web that does not work - check whether it was written for OData v3.