CustomerGate 365: web service reference

The services

CustomerGate 365 publishes eight web services. The app publishes them itself on installation and on every update: a missing service is created, and a service that already exists under that name is never changed, even if someone unpublished or edited it by hand. The three iFacto services exist only where Steel 365 is installed.

Authentication

The website talks to Business Central as two Microsoft Entra applications. Their client IDs go into CustomerGate Setup, and Repair Permissions there registers them in Business Central and assigns their permission sets.

Neither application can use the other's services: the website application has no execute right on the catalog pages, and the synchronization application has none on voaPortal or voaRequests.

Permission sets

Getting a token

Both applications use the OAuth 2.0 client credentials flow:

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

grant_type=client_credentials
client_id={client id}
client_secret={secret}
scope=https://api.businesscentral.dynamics.com/.default

Send the access token as Authorization: Bearer {token} on every call.

Endpoints and conventions

All services are standard Business Central OData v4 endpoints under https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/ODataV4.

Page services

The catalog pages are read with GET. The reference website addresses the company by name:

GET .../ODataV4/Company('{company name}')/voaItems?$select=No,Description&$filter=...

A company name with an apostrophe has it doubled (O''Brien), as OData requires. Large results are paged: follow @odata.nextLink until it is absent. The records are in value.

Codeunit services

voaRequests and voaPortal expose each public procedure as an unbound action named {service}_{Procedure}. Call it with POST and pass the parameters by name in a JSON body. The reference website addresses the company with its GUID, the id of the company in the standard companies API:

POST https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/ODataV4/voaPortal_ReadSession?company={company id}
Authorization: Bearer {access token}
Content-Type: application/json
Accept: application/json
Accept-Language: en-US

{"token": "<session token>"}

The return value comes back in the OData envelope under value:

{"@odata.context": "…", "value": "{\"email\":\"buyer@example.com\",\"customerNo\":\"C00010\", …}"}

Conventions

• Names are case-sensitive and bound by name. voaPortal_readSession does not exist, and a parameter called emailAddress instead of email gets a 400 with no further explanation.
• Every parameter is a string: all procedure parameters are AL Text.
• A JSON result comes back as a string inside value, because an unbound action cannot return a nested object. Parse value a second time. A Boolean result is a JSON true or false in value.
• An empty string is an answer. For most voaPortal procedures, "" means no valid session, or nothing for you here.
• Optional keys are left out, not sent as null. Treat a missing key as null.
• Dates are YYYY-MM-DD, timestamps are ISO 8601 in UTC (2026-09-19T14:30:00.000Z). An empty date or timestamp is "".
• Numbers and Booleans are JSON numbers and JSON Booleans.
• Accept-Language sets the language of the Business Central session. It affects error messages and the option captions in the catalog, never the fixed values below. The reference website sends nl-NL.

Status codes and retries

Retrying after a 429 is always safe. After a network error, a time-out, a 409 or a 5xx, retry only the reading procedures (ReadSession, MyDetails, MyDeliveryAddresses, MyRequests, MyQuotes, MyOrders, MyShipments, DocumentLines, MyDocuments, Document). Do not retry RequestCode, SignIn, SignOut, LinkRequest or AcceptQuote on your own; for CreateQuoteRequest and CreateAccountRequest, a retry is safe only with the same requestId.

Security model

There are two layers. The Entra application proves that the caller is the website; it never identifies a customer. The portal session token identifies the signed-in person, and Business Central derives the customer from it. The customer number never travels from the website to Business Central: no procedure takes a customer number, an e-mail filter or any other parameter that decides whose data is returned.

Portal users

• A person may use the portal once inside sales has approved their account request. That creates a portal user: an e-mail address linked to one customer, with a role. The website cannot create portal users.
• E-mail addresses are compared in lowercase, with surrounding spaces removed.
• If one address is linked to several customers, the session gets the lowest customer number that is allowed in the portal. The interface has no way to list or switch customers.
• The portal user must be active and not anonymized, and the customer must exist, must not be privacy blocked and must not be blocked for all. Customers blocked for ship or invoice keep portal access.

Sign-in with a one-time code

1. The visitor enters their e-mail address; the website calls RequestCode(email, ipHash).
2. Business Central creates a code, stores only a salted hash of it, and e-mails the code to the address if it belongs to an active portal user.
3. The visitor enters the code; the website calls SignIn(email, code, ipHash) and gets a session token, or "".
4. The website keeps the token, for example in an HttpOnly cookie, and passes it as token to every other voaPortal procedure.
5. SignOut(token) ends the session.

The code is ten characters from the alphabet 0123456789ABCDEFGHJKMNPQRSTVWXYZ (no I, L, O or U) and is shown in the e-mail as two groups of five with a hyphen. It is normalized before comparison: spaces and hyphens removed, uppercased, O read as 0, I and L read as 1. Apply the same rules if you validate the input on the website.

• A code is valid for Sign-in Code Validity (Min.), 15 minutes by default, and works once. After a successful sign-in, every other open code for that address expires.
• Wrong guesses do not lock anyone out. They are counted on the newest open code up to Maximum Code Attempts, as a trace for abuse detection.
• Several codes can be alive at once: a new code does not invalidate earlier ones.
• RequestCode always answers true, whether or not the address is known, linked, blocked or the mail failed, and always takes at least 1.5 seconds. That way the endpoint does not tell anyone which addresses are customers.
• Between two codes for the same address there is a minimum wait of Sign-in Code Wait Time (Sec.), 60 seconds by default. A request within that time is answered true and does nothing.
• The code mail is sent immediately from the RequestCode call, not by the job queue, in the language of the account request the portal user came from, else the customer's language, else the inside sales language.

Session tokens

• A token is 64 characters, two GUIDs as uppercase hex. Treat it as opaque; Business Central stores only its SHA-256 hash. Leading and trailing spaces in token are ignored.
• Sliding expiry: a session expires after Session Duration (Min.), 480 by default, without use. Every successful call extends it, written at most once per minute, so a session can end up to a minute earlier than the nominal time.
• Absolute maximum: no session outlives Maximum Session Age (Hours), 168 by default, after sign-in, however actively it is used.
• Every call checks that the token exists, is not revoked, has not expired and is within the maximum age, that the portal user still exists and is active, and that the customer is still allowed in the portal. If the portal user or customer check fails, the session is revoked at once.
• The role is read from the portal user on every call, not from the session, so a change from Buyer to Viewer applies immediately.
• ReadSession returns expiresAt. Use it for the cookie lifetime.
• Several calls with the same token at the same moment can make Business Central answer 409 to one of them. The reading procedures are safe to retry once.

The customer lock

Everything voaPortal returns is filtered on the customer of the session, and no parameter can remove that filter:

A document number is a parameter in DocumentLines, Document and AcceptQuote. It says what is asked, never whose it is. Document numbers are trimmed and uppercased; a number longer than 20 characters is treated as not found, not truncated.

Uniform empty answers

A document that does not exist and a document of another customer give exactly the same answer. Otherwise a list of numbers would be enough to probe what exists.

Roles

A new portal user is a Viewer unless inside sales chooses Buyer, and an unknown role value is reported as Viewer. A Buyer may do everything a Viewer may, plus LinkRequest, MyDeliveryAddresses and AcceptQuote. For a Viewer those three answer false, "" and refused. A Viewer can still submit a quote request through voaRequests; it is then not linked to the customer, and inside sales handles it like a request from an anonymous visitor. MyDetails returns role, so the form can say so.

IP hash

Several calls take an ipHash. Business Central never receives the visitor's IP address: the website computes a keyed hash. The reference website uses HMAC-SHA256 with a secret key from its own configuration, as 64 lowercase hex characters. Business Central stores the value as received, up to 64 characters, on the sign-in code, the session, the quote acceptance and the requests, uses it only to recognize abuse, and the cleanup job erases it after the retention period. Keep the key secret and stable: without a key, an IPv4 hash can be reversed.

Portal settings

Per company, on CustomerGate Setup:

Catalog services

The catalog services are read-only list pages, meant for a nightly sync rather than for live page views. Use $select to fetch only the properties you need. The OData property names are the names of the page controls listed below and are part of the contract. The values are read live from the tables, including the DXSteel fields, which the app reads by field name so that it does not depend on the DXSteel app: without Steel 365, a DXSteel text field returns "" and a DXSteel number returns 0.

voaItems

Source table: Item. No prices, costs or inventory are exposed.

voaVariants

Source table: Item Variant.

voaCategories

Source table: Item Category, with the properties Code and Description. There is no parent field; the reference website derives the tree from the code (BALK-IPE is under BALK).

voaProfiles, voaGrades, voaItemTypes

These three point at pages of iFacto Steel 365 (DXSteel), not at pages of this app. Their properties are defined by iFacto and can change with iFacto updates; this reference does not specify them. They exist only where Steel 365 is installed.

voaRequests: quote and account requests

Two actions, each taking the whole request as one string parameter payload that contains JSON, and each returning {"number":"…"} as a string. The website account can create requests but cannot read them back: there is no service that lists requests or looks up a customer by e-mail address.

How the payload is read: a missing key and a JSON null both mean empty ("", 0 or false); text values are truncated silently to the field length; Code fields are stored in uppercase; the call runs in one transaction, so if anything fails, nothing is stored. Business Central sets the request number, the status New, the received timestamp, the linked customer and, for account requests, the reviewer and the rejection reason; the payload never does.

CreateQuoteRequest: header keys

CreateQuoteRequest: line keys

Objects in quoteRequestLines, numbered 10000, 20000, … in array order:

An example payload, before it is serialized into payload:

{
  "requestId": "3F2C9A1E7B0D4C5E",
  "languageCode": "NLB",
  "contactName": "Jan Example",
  "companyName": "Example Ltd",
  "email": "jan@example.com",
  "customerReference": "Site 12",
  "address": "Example Street 1",
  "postCode": "2000",
  "city": "Antwerp",
  "countryCode": "BE",
  "deliveryMethod": "Delivery",
  "useShipToAddress": true,
  "shipToName": "Example Ltd",
  "shipToAddress": "Yard Road 5",
  "shipToPostCode": "2100",
  "shipToCity": "Deurne",
  "shipToCountryCode": "BE",
  "requestedDeliveryDate": "2026-10-01",
  "remarks": "Please call before delivery.",
  "privacyAccepted": true,
  "privacyConsentVersion": "2026-09",
  "ipHash": "<64 hex characters>",
  "source": "shop/en/quote-request",
  "quoteRequestLines": [
    {
      "itemNo": "1000",
      "variantCode": "6000",
      "quantity": 4,
      "unitOfMeasureCode": "PCS",
      "lineRemarks": "Cut to 3 m"
    }
  ]
}

What happens next:

• The request lands in its own table, not in a sales quote. Inside sales converts it with one action, from the Business Central client only.
• The mail job sends the requester a confirmation and inside sales a notification, depending on the switches in setup.
• source = counterVisit marks a request entered at the counter. It converts to a sales order instead of a quote, and no confirmation or notification mail is sent. For a pickup, the order gets a text line naming the employee in assistedBy.
• If the visitor is signed in, call LinkRequest right after this call to put the session's customer on the request. The customer number is never part of the payload.
• shipToCode is only trusted after LinkRequest has checked it against the session's customer. On a request that was not linked that way, the conversion refuses the code until inside sales confirms it by hand, so send the address as text as well.

CreateAccountRequest

A request for a portal account. Inside sales links it to a customer and a role, or rejects it.

Idempotency: requestId

Generate one requestId per form submission and send the same value again if you retry that submission. A second request with a requestId that already exists is refused with HTTP 400, and the error message contains the marker [VOA-DUBBEL] and the number of the request that was already stored. Treat that as success: the request is in Business Central, only not from this call. The message text itself is translated, so match on the marker, never on the sentence. Comparison is effectively case-insensitive, because the value is stored uppercase; without a requestId there is no duplicate check. The rule holds for both actions, each in its own table.

Errors

All are raised as AL errors, so the call fails with HTTP 400 and the message in the body. The request is not stored.

voaPortal: the customer portal

Every action is POST .../ODataV4/voaPortal_{Procedure}?company={company id}. These fifteen procedures are the only callable ones; every other procedure in the codeunit is local.

Hard limits

RequestCode, SignIn, SignOut

RequestCode always returns true, after at least 1.5 seconds; do not call it again automatically, because every call can send a mail. SignIn returns the 64-character session token, or "" when the code is wrong, expired or already used, or when the portal user or customer is no longer allowed; the answer never says which. A correct code for a user who has been deactivated in the meantime is used up and returns "". SignOut revokes the session if the token exists and always returns true, also for an unknown token; discard the cookie either way.

ReadSession

Who is behind the token. Call it on every page view of the portal: it checks the session, the portal user and the customer, and extends the session.

MyDetails

The company details of the session's customer, to prefill the quote request form. Every field is a string and can be "". The customer number is deliberately not included, and there are no prices, discounts or credit data. The keys are company, vatRegistrationNo, address, address2, postCode, city, country, phoneNo, email (the portal user's address, not the customer card's) and role.

MyDeliveryAddresses

The registered ship-to addresses of the session's customer, Buyer only: {"addresses": [{"code", "name", "address", "address2", "postCode", "city", "country"}]}, all strings. A Viewer gets "", just like an invalid session. The billing address is not in this list; it is in MyDetails. Send the chosen code as shipToCode in CreateQuoteRequest.

LinkRequest

Puts the session's customer on a quote request that was just submitted, so call it right after CreateQuoteRequest, with the same requestId. It returns true only if the session is valid, the role is Buyer, requestId (trimmed, uppercased, at most 64 characters) is not empty, and a quote request with that Request ID exists and has no customer yet. It then sets the request's customer, keeps shipToCode only if it is a ship-to address of that customer and otherwise clears it (the address text stays), and sets the request's Source to portal. A false is not an error: the request exists either way and inside sales picks it up like any other.

MyRequests

The quote requests linked to the session's customer, newest first, at most 200. Anonymized requests and requests marked as spam are left out.

MyQuotes

The sales quotes of the session's customer: first the live quotes, highest number first, then quotes that exist only in the quote archive (converted or deleted), released versions only, the highest archived version per number. Together at most 100 rows. The answer is {"quotes": [ … ], "truncated": <Boolean>}.

MyOrders

The sales orders of the session's customer: live orders, highest number first, then orders that exist only in the order archive, highest archived version per number, any status. Together at most 100 rows, as {"orders": [ … ], "truncated": <Boolean>}.

MyShipments

The posted sales shipments of the session's customer, newest first, at most 100, as {"shipments": [ … ], "truncated": <Boolean>}.

DocumentLines

Parameters: documentType is quote, order or shipment (case-insensitive; anything else returns ""), and documentNo is the document number. Ownership is checked before any line is read. For quote and order the live document is tried first; if it does not exist, the highest version in the archive, for quotes released versions only. Only lines of type Item are returned, at most 500; text and comment lines are left out. The answer is {"lines": [ … ]}.

Rules for reading lines: Steel 365 text keys are left out when empty, while Steel 365 number keys are present whenever the field exists, so 0 means zero and a missing key means unknown (show a dash, not 0). With Steel 365, pieces, meters and kilograms are three separate quantities: never add them up or pick one yourself, unit says which one leads. Outstanding and shipped values exist only on live order lines; do not calculate them yourself. No price, discount, margin or amount is ever returned.

{
  "lines": [
    {"lineNo": 10000, "itemNo": "1000", "description": "HEA 200 S235JR", "format": "12000",
     "profile": "HEA200", "grade": "S235JR", "unit": "PCS", "quantityPieces": 4,
     "quantityMeters": 48, "quantityKg": 2035.2, "weightType": "Theoretical"}
  ]
}

AcceptQuote

Records that the customer accepts a released sales quote. Buyer only. Nothing is converted or released in Business Central: the acceptance is a signal for inside sales, who convert the quote by hand. It always returns an object with outcome (recorded, already, expired or refused) and acceptedAt (a timestamp, or ""). The checks, in order:

refused never says why, and already is not an error: show that the acceptance is in. Do not retry this call automatically. The recorded acceptance stores the quote number, the customer, the portal user's e-mail, the moment, the IP hash, the document date, the amount including VAT, the currency, the number of lines, the latest archive version and a fingerprint of the lines, so it stays clear what was accepted if the quote changes later. The mail job then sends the customer a confirmation and inside sales a notification.

MyDocuments

The PDFs available to the session's customer, as {"documents": [ … ]}, with no truncated flag. The source is one of two, never both: the Steel 365 document archive when DXSteel Doc Archive is installed, otherwise the report source when Portal Documents from Reports is on. If the archive is not installed and the setting is off, the list is always empty. If anything goes wrong reading the archive, the list is empty rather than an error, and the setup card shows why.

Archive rows. A document is listed only if it hangs on this customer's number, the relation type is Customer, and its category is set up in Archive Categories with a kind other than none. Newest first.

Downloading an archive document. Business Central cannot return the bytes through this codeunit without a dependency on the iFacto app, so the website fetches them from iFacto's API with the id:

POST https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/ifacto/dxsteel/v1.0/companies({company id})/documentArchives({id})/Microsoft.NAV.Download
{}

-> {"value": "<base64>"}

Only download an id that appears in the MyDocuments list you just fetched for the same session. Never take an id from the browser and pass it on unchecked: the website's account needs read access to the archive to download, and the same archive holds purchase invoices and internal correspondence. VOA CG S365 ARCHIVE limits that access to the allowed categories with a security filter, but the ownership check is MyDocuments. An empty value means the archive record has no file.

Report rows. Only document kinds for which a report is set up (a document layout on the customer card, else Report Selections): live quotes and orders, posted shipments, invoices and credit memos, in that order, each highest number first and at most 100 per kind.

Document

The PDF of one document, printed with the report Business Central uses for it, and only with the report source: where the Steel 365 archive is installed this always returns "" and you use the archive download above. documentType is quote, order, shipment, invoice or creditMemo (case-insensitive) and documentNo is the number. It returns "" for an invalid session, an unknown type, a document that does not exist or is not this customer's, a document kind without a report, or an empty print. Quotes and orders must be live; archived versions cannot be printed. Otherwise it returns fileName, contentType and base64, the PDF itself.

The report runs with the permissions of the website account (tenant set VOA CG DOCUMENTS). If the report fails, typically because a customer-specific layout reads a table the set does not cover, the call fails with an error that names the object; add that table to the set. A download does not archive the quote or order, but the standard reports do increase No. Printed. hasDocument in MyQuotes, MyOrders and MyShipments is true exactly when the report source is active and a report is set up for that document kind for this customer.

Fixed values

These values are fixed tokens. They are never translated and never depend on the session language. Compare them exactly.

Request numbers come from number series in setup. On installation they default to WEB000001 to WEB999999 for quote requests and ACC000001 to ACC999999 for account requests, but each company can change them: do not rely on the pattern.

Steel 365 differences

CustomerGate 365 is one app. It checks the environment itself and needs no setting for it: Steel 365 is active when the field Quantity Pieces DMX exists on the sales line, and the Steel 365 document archive is active when the table Document Archive DADMX exists.

The document archive is a separate switch:

Versioning and compatibility

The names are the contract. Websites call them literally, so each of these is part of the interface: the service names, the procedure and parameter names including their case, the catalog property names, the JSON keys in payloads and responses, and every fixed value above. Renaming one breaks every website built on the app, silently in many cases: a renamed catalog property just leaves a column empty, and a renamed JSON key reads as null. There are no aliases for earlier names.

For consumers:

• Ignore keys you do not know. New keys can be added in a compatible release.
• Treat a missing optional key as null, and "" as no value.
• Treat an unknown token value as unknown. Do not map it to a default that claims something, for example by treating an unknown outcome as recorded.
• Keep the session token, the requestId and the IP-hash key on the server side.

Adding a key, a procedure or a catalog property is a compatible change; removing or renaming one is not. Installation and updates create missing services but never change an existing one, so a renamed service would appear next to the old one while the old one keeps pointing where it did.