Service Layer Basics

Everything SAP Business One does is captured as documents, but those documents have to be reachable by software — by integrations, by reports, and by an assistant like Norma. The way in is the Service Layer: the official web API that SAP provides for SAP Business One. It is the single door through which all programmatic access passes. When Norma reads a sales order or drafts a quotation, it is talking to the Service Layer, not to the database and not to the SAP B1 desktop client.

This document explains what the Service Layer is at a grounding level — enough to understand how Norma reaches SAP B1 and what shape the conversation takes. It is not a developer walk-through of every operation.

What the Service Layer is

The Service Layer is a REST API over HTTP that exposes SAP Business One’s business objects as OData services. Two ideas are doing the work in that sentence:

• REST over HTTP means the Service Layer is reached the same way a website is: by making HTTP requests to URLs. A GET request reads data; a POST request creates something. There is no special protocol and no proprietary driver — it is ordinary web traffic.
• OData is a widely used standard for exposing business data as entities that can be queried in a uniform way. It gives every entity a predictable URL and a common set of query options — filter, select, sort, page — so that reading a business partner and reading an invoice work the same way, differing only in the entity name.

Underneath, the Service Layer sits on top of SAP B1’s own business logic. A request does not touch the database directly; it flows through the same core that the desktop client uses, so the tax calculations, posting rules, and validations that apply when a person creates a document apply identically when the Service Layer creates one. The API is a faithful front door to the real system, not a shortcut around it.

Entities are documents

The most important thing to hold onto is that the Service Layer’s entities are the documents from the mental model. Each document type is an OData entity set reached at its own path:

Reading Orders returns sales orders; reading Invoices returns A/R invoices. Each entity carries the same header-and-lines shape the document has everywhere else in SAP B1 — a header with the partner, dates, and totals, and a DocumentLines collection with the items, quantities, and prices. The BaseType, BaseEntry, and BaseLine reference fields that link the document chain are line fields on those same entities, so a chain can be traced through the Service Layer exactly as it exists in the system.

Internally SAP B1 treats every transactional document as one universal Document object, distinguished by a type code, and the metadata reflects this. But in practice each document type is reached through its own named entity path — Orders for sales orders, PurchaseOrders for purchase orders — which is the level Norma works at.

How Norma talks to the Service Layer

Norma reaches SAP B1 through the Service Layer using the /b1s/v1/<Docs> paths — for example /b1s/v1/Orders for sales orders or /b1s/v1/Quotations for quotations. The <Docs> part is the entity name from the table above; the /b1s/v1/ prefix is the Service Layer’s root.

A note on versions: SAP B1 also offers a newer /b1s/v2/ root built on a later edition of OData. Both expose the same documents; they differ in protocol details. Norma’s connector and its mock SAP Service Layer standardise on /b1s/v1/ — that is the path Norma uses when it reads or creates a document.

The conversation takes a few basic shapes:

• Reading a document is a GET against its entity — for instance a request to /b1s/v1/Orders narrowed with a filter to the orders in question. The Service Layer returns the matching documents as JSON.
• Creating a document is a POST to its entity with the header and lines in the body. Because the request flows through SAP B1’s business logic, the system computes totals and tax and applies its validations, producing a real document with a real DocEntry — the same outcome as if a person had entered it.
• Querying across many documents uses OData’s query options: filtering to a partner or a date range, selecting only the fields needed, sorting, and paging through large result sets. These keep responses focused instead of pulling back whole tables.

The overall path from Norma to the data looks like this:

flowchart TD
    K[Norma connector] -- HTTP request /b1s/v1/Orders --> SL[Service Layer]
    SL --> BL[SAP B1 business logic]
    BL --> DB[(SAP B1 database)]
    DB --> BL
    BL --> SL
    SL -- JSON documents --> K

Every read and every write Norma performs follows this route: a request to a /b1s/v1/<Docs> path, through the Service Layer, through SAP B1’s own business logic, to the database and back as JSON.

Sessions and authentication, at a high level

Access to the Service Layer is session-based and scoped to a single company database. Before any document can be read or written, a session is established by logging in with a company database, a user name, and a password. On success the Service Layer issues a session identifier, and every subsequent request carries that session so the server knows who is asking and against which company’s data. Sessions expire after a period of inactivity, at which point a fresh login is needed.

Two consequences of this model are worth understanding at a grounding level. First, a session is bound to one company database — the Service Layer does not span companies, so working with a different company means a different session. Second, the session carries the user’s identity and permissions — a request does only what that user is allowed to do, exactly as the same person would be constrained in the desktop client. The API does not bypass who a user is or what they may touch.

Norma manages this login-and-session mechanics on the user’s behalf so that a conversation about SAP data does not turn into a conversation about credentials. The point to retain is simply that access is authenticated, per-user, and per-company — the Service Layer is a controlled door, not an open one.

What to keep in mind

At grounding level, the Service Layer comes down to a few durable facts. It is the official REST/OData API for SAP Business One and the only sanctioned way in for software. Its entities are the documents, reached at named paths that carry the familiar header-and-lines shape and the chain reference fields. Norma talks to it over /b1s/v1/<Docs> — reading documents with GET, creating them with POST, and narrowing large results with OData query options — always through an authenticated session scoped to one company and constrained to one user’s permissions. Reads and writes both pass through SAP B1’s real business logic, so what the Service Layer produces is a genuine SAP B1 document, not a side channel around the system.