Most ZATCA Phase 2 projects on SAP Business One don't stall on XML. They stall on onboarding: who generates the OTP, how many EGS units you actually have, and what happens when the second branch or the second company database turns up halfway through testing. This piece is about getting that part right the first time.

What is a CSID, and why does SAP Business One need more than one?

A Cryptographic Stamp Identifier (CSID) is the certificate ZATCA issues to each EGS unit, the "e-invoice generation solution" that signs and submits invoices. Each EGS unit gets its own CSID. In SAP Business One terms, every place that independently issues and signs invoices should be treated as its own EGS unit with its own CSID and its own invoice counter.

The detail people miss is that the CSID is tied to the EGS unit, not to the company. A single SAP Business One company database with three branches posting their own A/R invoices is usually not one EGS unit. If you register one unit and let three branches sign through it, you share one invoice counter (ICV) and one previous-invoice-hash chain across all three. That chain breaks the moment two branches post at the same time.

How does the onboarding flow actually work?

ZATCA's flow comes down to four steps: generate an OTP on the FATOORA portal, send a CSR with that OTP to get a compliance CSID, pass the compliance checks with sample documents, then exchange the compliance CSID for a production CSID. Only the production CSID can call the clearance and reporting APIs.

In more detail, from ZATCA's Detailed Technical Guideline and the FATOORA portal manual:

1. Someone with the taxpayer's ERAD credentials logs in to FATOORA, opens "Onboard new solution unit/device" and generates OTP codes. You can request 1 to 100 codes at once. Each code is valid for one hour.
2. The EGS unit builds a CSR and calls the compliance endpoint (/e-invoicing/core/compliance) with the OTP in the header. The response gives a binarySecurityToken, a secret and a requestID. That token and secret are the compliance CSID.
3. Using the compliance CSID as Basic Auth, the unit sends sample documents to /compliance/invoices.
4. With all checks passed, the unit calls /production/csids with the requestID and receives the production CSID.

If any compliance test fails or is skipped, the guideline says the unit has to start again from a new OTP and a new CSR. That one-hour OTP window is why I never let anyone generate codes until the integration is ready to fire the CSR immediately.

What goes into the CSR, and where does it come from in SAP Business One?

The CSR carries the taxpayer and unit identity: the 15-digit VAT number, organisation name, branch or location, industry, a unit serial number in the form 1-<solution name>|2-<version>|3-<unique serial>, and the invoice type flag. Most of these already live in SAP Business One, so read them from there instead of retyping them.

Where I pull them from:

• VAT number: OADM.TaxIdNum for a single-entity company, or the branch record in OBPL when Multiple Branches is enabled. OBPL has both VATRegNum and TaxIdNum (labelled "Branch Reg. No."), and localisations don't always fill the same one, so check which field actually holds the 15-digit VAT number in your database before you map it.
• Organisation name: OADM.CompnyName (or the legal name on the branch).
• Branch / location: OBPL.BPLName for the branch the EGS unit belongs to.
• Unique serial: something stable you control, for example database name plus branch ID. It must never be reused for a different unit.

A quick query to see what you are working with before you count EGS units:

SELECT T0."BPLId", T0."BPLName", T0."VATRegNum", T0."TaxIdNum", T0."MainBPL", T0."Disabled"
FROM OBPL T0
ORDER BY T0."BPLId";

If the VAT values are blank or inconsistent here, fix that in SAP Business One first. A CSR built on a wrong VAT number will happily get a compliance CSID and then fail you later.

Which invoice type flag should you choose: 1000, 0100 or 1100?

The flag tells ZATCA what the unit will issue. 1000 means standard (B2B) tax invoices only, 0100 means simplified (B2C) only, and 1100 means both. It also decides how many compliance samples you must pass: three for 1000 or 0100, six for 1100.

ZATCA's guideline and its developer community answers spell out the samples:

• 1000: standard invoice, standard credit note, standard debit note.
• 0100: simplified invoice, simplified credit note, simplified debit note.
• 1100: all six.

On SAP Business One the safe default for a trading company is 1100, because sooner or later someone issues a cash sale to a walk-in customer from the same database. Choosing 1000 to save three test documents and then discovering B2C sales after go-live means onboarding the unit again.

The sample documents should come out of SAP Business One itself, not from the SDK sample folder. Post a real A/R invoice (OINV), an A/R credit memo (ORIN) and a debit note the way your business actually raises it, for both a business partner with a VAT number in OCRD.LicTradNum and one without. The compliance step is the cheapest place to find out your mapping is wrong.

How should multiple branches and multiple company databases be handled?

Treat each independent signing point as its own EGS unit. One SAP Business One database with branches that post separately usually means one EGS unit per branch. Separate company databases always mean separate EGS units, even when they share a VAT group.

What that means in practice:

• Per-unit storage. Keep the private key, production CSID, secret, ICV counter and last invoice hash per EGS unit, not per database. A user-defined table keyed by database and BPLId works well.
• Per-unit counters. The ICV and previous invoice hash must advance per unit. If two branches share them you will see hash-chain errors on whichever document lost the race.
• OTP batches. Generate OTPs only for the units you can onboard in the next hour. The portal lets you ask for up to 100, but unused codes simply expire.
• New branch later. A branch added after go-live is a new onboarding: new OTP, new CSR, new compliance samples. Put that in your branch-opening checklist so it doesn't surface as rejected invoices.

What about renewal, and testing before production?

Renewal follows the same pattern. FATOORA has a separate "Renewing Existing CSID" option that issues OTPs for units whose certificates need renewing, and the unit sends a new CSR. Run the whole flow in the simulation environment first, using OTPs generated from the simulation portal.

Two habits that save trouble:

• Log the certificate expiry date for every unit and alert someone well before it. A lapsed certificate stops clearance for that branch on the day it lapses.
• Keep simulation and production credentials in separate records. Mixing them up is one of the more common reasons a unit that "passed" in testing fails on day one.

A short checklist before you generate the first OTP

• Count EGS units: one per independent signing point (branch or database).
• Clean OADM and OBPL tax and name fields.
• Pick the invoice type flag per unit (default 1100 unless you are sure).
• Prepare real SAP Business One sample documents for every required type.
• Build per-unit storage for keys, CSIDs, ICV and hash.
• Rehearse in simulation, then onboard production within the OTP's one-hour window.

I'm Zain, founder of Kodenova. I build and support ZATCA Phase 2 integration for SAP Business One, including CSID onboarding for multi-branch setups. If you're working through this and get stuck on a specific step, the comments are open.

A note on how this was written: I drafted this article with help from an AI writing assistant and then checked and edited it myself. The design choices come from SAP Business One integration work; the ZATCA rules are quoted from ZATCA's own published guidelines on zatca.gov.sa.

Most ZATCA Phase 2 conversations about SAP Business One start with the certificate (CSID) and the XML. The question that actually shapes the integration comes earlier: for each document B1 creates, does it have to be cleared by FATOORA before the customer sees it, or can it be reported afterwards? Get that routing wrong and you either block a cashier for no reason or hand a B2B customer an invoice that isn't legally valid yet.

What is the difference between clearance and reporting in ZATCA Phase 2?

Clearance applies to standard Tax Invoices (usually B2B) and their credit and debit notes: your system sends the invoice to FATOORA first, ZATCA validates and stamps it, and only then can you share it with the buyer. Reporting applies to Simplified Tax Invoices (usually B2C) and their notes: you stamp and hand it over immediately, then submit the XML within 24 hours.

ZATCA's Detailed Guideline is explicit on both points. On clearance, it says each tax invoice "must be cleared by the Authority as a prerequisite for sharing them with the buyers and for such Electronic Invoice to be regarded as legal and valid", and that clearance "is not applicable to Simplified Tax Invoices". On reporting, it says taxpayers "will be required to transmit all Simplified Tax Invoices to the FATOORA Portal within (24) hours from its issuance".

Two practical consequences for B1:

• A cleared invoice carries ZATCA's cryptographic stamp. A reported invoice carries your stamp, made with your own CSID, plus the Phase 2 QR code, before it is printed.
• Clearance is synchronous from the user's point of view. Reporting is a background job.

Which SAP Business One documents need clearance, and which need reporting?

In SAP Business One the routing decision belongs to the document, not to the document type. An A/R Invoice (OINV) can be a standard tax invoice for one customer and a simplified invoice for the next. The same goes for A/R Credit Memos (ORIN) and A/R Down Payment Invoices (ODPI). You classify each one when it is added, then route it.

The documents that usually fall in scope on the sales side:

Inside the XML, the invoice type code carries a name attribute whose first two characters say which flow it is: 01 for a standard tax invoice and 02 for a simplified one. That one attribute is what ties the B1 classification to the clearance or reporting API, so it should be set in exactly one place in your code.

A/R Reserve Invoices are the one I would flag in any B1 project. Teams use them for very different business reasons, and the answer on whether and when they are issued as e-invoices is a tax decision for the client's advisor, not something the integration should guess.

How should B1 decide whether a document is standard or simplified?

Classify on the buyer, not on the user's choice of form. A buyer with a valid 15-digit VAT number, or a business buyer that needs the full tax invoice details, goes the standard route. Walk-in and consumer sales go the simplified route. Store the result on the document header so it never gets recalculated later.

In B1 I keep three user-defined fields on each marketing document header (OINV, ORIN, ODPI):

• U_ZATCA_Type: STD or SMP, set once when the document is added.
• U_ZATCA_Status: PENDING, CLEARED, REPORTED, WARNING or REJECTED.
• U_ZATCA_UUID: the UUID that went into the XML, so you can match FATOORA responses back to DocEntry.

The buyer's VAT number normally sits in the business partner's Federal Tax ID (OCRD.LicTradNum), copied onto the document. A quick check that saves a lot of clearance rejections later is to list customers whose tax ID is missing or obviously malformed before go-live:

SELECT T0."CardCode", T0."CardName", T0."LicTradNum"
FROM OCRD T0
WHERE T0."CardType" = 'C'
  AND T0."frozenFor" = 'N'
  AND (T0."LicTradNum" IS NULL
       OR LENGTH(T0."LicTradNum") <> 15
       OR T0."LicTradNum" NOT LIKE '3%3');

That is HANA syntax; on SQL Server use LEN() instead of LENGTH(). Saudi VAT numbers are 15 digits and start and end with 3, so anything this query returns either needs fixing or should be treated as a simplified-invoice customer.

One more rule worth enforcing: once U_ZATCA_Type is set, block changes to it with the B1 transaction notification (SBO_SP_TransactionNotification) or your add-on's validation. A document that silently flips from simplified to standard after printing is a mess to unwind.

What does the clearance flow look like from an SAP B1 user's seat?

The user adds the A/R Invoice, the integration builds and signs the XML, sends it to FATOORA's clearance endpoint, and waits. If ZATCA accepts it, the cleared XML and QR code come back and the print layout uses those. If ZATCA rejects it, the user sees the error before anyone has printed or emailed anything.

Design points that matter in practice:

1. Do not print from the B1 document alone. The Crystal or PLD layout should read the QR and status from the stored ZATCA response, and refuse to print a standard invoice whose status is not CLEARED or WARNING.
2. Decide what happens on a rejection. The document already exists in B1 with its journal entry posted. In most designs the fix is a credit memo plus a corrected invoice, or a correction to master data and a resubmission, depending on the error. Write that rule down with the finance team before go-live, not during the first rejection.
3. Timeouts are not rejections. If FATOORA does not answer, keep the document PENDING and retry. Do not resend under a new UUID, or you end up with two submissions for one invoice.
4. Keep the chain intact. Every Phase 2 XML carries the previous invoice hash and an invoice counter for that EGS unit. If two users post at the same moment through one EGS unit, the hashing and counter assignment must be serialized. A single integration service per EGS unit is far easier to reason about than logic inside each client add-on.

How do you make sure simplified invoices are reported inside 24 hours?

Treat reporting as a queue with an alarm, not a fire-and-forget call. Stamp and print the simplified invoice immediately, insert it as PENDING, and let a background service report it. Then run a check that flags anything still pending after a few hours, long before the 24-hour limit ZATCA sets.

A simple watchdog query I would schedule as a B1 alert or in the service's own monitor:

SELECT 'OINV' AS "Obj", T0."DocEntry", T0."DocNum", T0."CardCode",
       T0."CreateDate", T0."CreateTS", T0."U_ZATCA_Status"
FROM OINV T0
WHERE T0."U_ZATCA_Type" = 'SMP'
  AND T0."U_ZATCA_Status" IN ('PENDING', 'REJECTED')
UNION ALL
SELECT 'ORIN', T0."DocEntry", T0."DocNum", T0."CardCode",
       T0."CreateDate", T0."CreateTS", T0."U_ZATCA_Status"
FROM ORIN T0
WHERE T0."U_ZATCA_Type" = 'SMP'
  AND T0."U_ZATCA_Status" IN ('PENDING', 'REJECTED');

CreateTS in B1 is stored as an integer time (HHMMSS), so combine it with CreateDate in the service code rather than in SQL if you want an exact age in hours. The point of the query is that a non-empty result is somebody's job today.

Things that cause late reporting in real B1 environments are rarely exotic: the integration service stopped after a Windows update, the certificate expired, a branch posted offline, or one rejected document blocked the queue behind it. Report documents independently, keep processing after a single failure, and send the failures to a person, not only to a log file.

Do warnings from FATOORA need action?

Yes, even though the document is accepted. FATOORA can accept a document with warnings, and ZATCA's guideline lists "accepted with one or more warning(s)" as a separate outcome from a clean pass. Store the warning text against the document, review the pattern weekly, and fix the root cause in master data or mapping before it turns into errors.

In B1 that usually means setting U_ZATCA_Status = 'WARNING', keeping the full response in a user-defined table keyed by object type and DocEntry, and giving finance a simple query over it. Rounding on line-level VAT and incomplete buyer address data are the kind of things that show up here first.

Before you build: a short checklist

• Agree with finance and the tax advisor which customers are standard and which are simplified, and encode that on the business partner.
• Clean LicTradNum and buyer addresses for every standard-invoice customer.
• One integration service per EGS unit, serializing hash and counter assignment.
• Print layouts read the ZATCA response, never the raw B1 document.
• A written rule for rejected cleared invoices, and a watchdog for simplified invoices that are not yet reported.
• Validate sample XML from each document type in the sandbox before production onboarding. Kodenova has a free ZATCA Phase 2 invoice XML, QR and hash validator that is handy for checking test output.

About the author

I'm Zain Abbas, founder of Kodenova. I build ZATCA Phase 2 integrations for SAP Business One, along with other SAP B1 add-ons and Service Layer integrations. If you're planning the routing for your own B1 company and want a second pair of eyes, you can reach me at hello@kodenova.com.

Sources: ZATCA, "E-Invoicing Detailed Guideline" (sections 2.15, 2.16, 4.2.2, 6.4) and "E-invoicing Detailed Technical Guidelines" (section 4.3.1), both on zatca.gov.sa; ZATCA, "What is E-invoicing?" and "Roll-out phases" pages, checked 27 Oct 2026.

The SAP Business One Service Layer solves this with OData batch requests and change sets. This post walks through the format, the parts that trip people up, and a minimal Python client. Drafted with AI assistance and reviewed for accuracy by Kodenova. Everything below was checked against SAP's "Working with SAP Business One Service Layer" guide and the SAP Learning lesson "Performing Batch Operations in Service Layer API".

What is a Service Layer $batch request?

A batch request groups several Service Layer operations into one HTTP POST to the $batch endpoint, for example POST https://<host>:50000/b1s/v2/$batch. The body is a multipart/mixed MIME message with a boundary you choose. The Service Layer processes the sub-requests in order, top to bottom.

Each sub-request is its own MIME part with two required headers:

Content-Type: application/http
Content-Transfer-Encoding: binary

After a blank line comes a normal HTTP request line (GET, POST, PATCH, ...), optional headers, a blank line, and the JSON body.

What does a change set add?

A change set is a nested multipart block inside the batch that behaves as one atomic unit: if any sub-request inside it fails, the whole change set is rolled back. Change sets cannot contain GET requests or other change sets. They are what you want for "all or nothing" document creation.

On the /b1s/v2 (OData v4) endpoint, the SAP guide says the Content-ID header is mandatory for every sub-request in a change set, whether you reference it or not. On /b1s/v1 (OData v3) it is only needed when you reference it.

How do I reference a document created earlier in the same change set?

Give the creating sub-request a Content-ID, then use $<Content-ID> in a later sub-request of the same change set. In a URL, $1 stands for the URI of the entity created by Content-ID 1, so PATCH $1 updates it and POST $1/Cancel cancels it. SAP's own examples also use $1 inside JSON bodies, for example as a BaseEntry.

Here is the order-plus-invoice example from the SAP Learning lesson, trimmed and with line breaks restored:

POST https://localhost:50000/b1s/v2/$batch
Content-Type: multipart/mixed;boundary=batch_36522ad7

--batch_36522ad7
Content-Type: multipart/mixed;boundary=changeset_77162fcd

--changeset_77162fcd
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1

POST Orders

{"CardCode":"C20000","DocDueDate":"2024-11-04",
 "DocumentLines":[{"ItemCode":"A00001","Quantity":"2","TaxCode":"A2","UnitPrice":"300"}]}
--changeset_77162fcd
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2

POST Invoices

{"CardCode":"C20000","DocDueDate":"2024-11-04",
 "DocumentLines":[{"BaseType":17,"BaseEntry":$1,"BaseLine":0,"Quantity":"1"}]}
--changeset_77162fcd--
--batch_36522ad7--

Note that "BaseEntry":$1 is not valid JSON. The Service Layer substitutes it before parsing, so don't run the body through a JSON serializer after inserting the placeholder. Build the string yourself.

What does the response look like, and how do I know it worked?

If the batch format is valid, the Service Layer returns 200 OK on v2 (202 Accepted on v1) even when a sub-request failed. The real results are inside the multipart response body, one HTTP status line per sub-response. You must parse those; checking only the outer status code will hide failures.

Two rules from the SAP guide matter here:

1. The batch stops executing at the first failed sub-request.
2. If a change set fails, you get one error response for the whole change set, not one per sub-request.

A malformed body (missing boundary, wrong line endings) returns a 400 with a message like "Incomplete Batch Request Body!".

A minimal Python client

This uses requests. A requests.Session keeps the B1SESSION cookie from /Login, and the ROUTEID cookie if your Service Layer runs behind its load balancer, so every call stays on the same node.

import re
import uuid
import requests

SL = "https://sl.example.local:50000/b1s/v2"
CRLF = "\r\n"

s = requests.Session()
s.verify = "/etc/ssl/certs/sl-ca.pem"   # don't use verify=False outside a lab
s.post(f"{SL}/Login", json={
    "CompanyDB": "SBODEMOGB", "UserName": "manager", "Password": "***"
}).raise_for_status()


def sub_request(method, path, body=None, content_id=None):
    head = ["Content-Type: application/http",
            "Content-Transfer-Encoding: binary"]
    if content_id is not None:
        head.append(f"Content-ID: {content_id}")
    req = [f"{method} {path}"]
    if body is None:
        req += ["", ""]                 # end of headers + empty body
    else:
        req += ["Content-Type: application/json", "", body]
    return CRLF.join(head + [""] + req)


def changeset_batch(parts):
    b, c = f"batch_{uuid.uuid4()}", f"changeset_{uuid.uuid4()}"
    lines = [f"--{b}", f"Content-Type: multipart/mixed;boundary={c}", ""]
    for p in parts:
        lines += [f"--{c}", p]
    lines += [f"--{c}--", f"--{b}--", ""]
    return b, CRLF.join(lines)


order = ('{"CardCode":"C20000","DocumentLines":'
         '[{"ItemCode":"A00001","Quantity":"2"}]}')
invoice = ('{"CardCode":"C20000","DocumentLines":'
           '[{"BaseType":17,"BaseEntry":$1,"BaseLine":0}]}')

boundary, body = changeset_batch([
    sub_request("POST", "Orders", order, content_id=1),
    sub_request("POST", "Invoices", invoice, content_id=2),
])

r = s.post(f"{SL}/$batch", data=body.encode("utf-8"),
           headers={"Content-Type": f"multipart/mixed;boundary={boundary}"})
r.raise_for_status()

statuses = [int(x) for x in re.findall(r"^HTTP/1\.1 (\d{3})", r.text, re.M)]
if not statuses or any(code >= 400 for code in statuses):
    raise RuntimeError(f"Batch failed: {statuses}\n{r.text[:2000]}")
print("Created:", statuses)   # e.g. [201, 201]

The status-line regex is deliberately simple. For production, parse the multipart response properly so you can read the error JSON and the Location headers of created documents.

Which mistakes break batch requests most often?

The usual culprits are LF instead of CRLF line endings, a missing blank line between MIME headers and the request line, a GET placed inside a change set, a missing Content-ID on v2, and treating the outer 200 as success. Fix those five and most "Incomplete Batch Request Body" errors disappear.

A few design notes from real integrations:

• Keep change sets small. One business transaction per change set (order plus invoice, BP plus first order). A 300-document change set holds locks longer and makes one bad line roll back everything.
• Plan for the unknown outcome. If the connection drops after the Service Layer committed but before you read the response, a blind retry creates duplicates. Put your external reference in a field such as NumAtCard or a user-defined field and query for it before retrying.
• Mind the session. A long-running batch job should handle an expired session (the default SessionTimeout is 30 minutes) by logging in again and re-checking state, not by resending everything.
• Don't use batch for bulk reads. For large reads, normal paged GET requests with $select and $filter are easier to reason about.

When should I not use $batch?

Skip batching when operations are independent and can fail separately, for example syncing 500 unrelated item prices. Separate calls with retries give clearer error handling there. Use change sets when partial success would leave inconsistent business data.

I founded Kodenova, where I build SAP Business One integrations, including B1Codex, our own connector that reads and writes through the Service Layer and DI API. If batching is part of your integration work, more of what we do is here: https://kodenova.com/?utm_source=hashnode&utm_medium=social&utm_campaign=daily-20261022