Integration guide

Start with one customer action, then define authentication, workspace scope, permission, request identity, retries, errors, evidence, and the owner of unresolved work.

Follow the server guide Open the API contract

Keep the browser outside the credential boundary.Server integration pattern. The approved contract determines available operations.

01
Browser
Sends
The customer request
Does not receive
Service credentials
02
Your server
Checks
Identity and workspace
Sets
A bounded timeout
03
Saleringo operation
Returns
A typed outcome
Retains
A request reference

No silent success on error.

Handle invalid input, permission errors, conflicts, throttling, and temporary failures separately.

Contract example and implementation context

Developers reviewing an integration flow on a large screen — Keep credentials server-side and make every outcome observable.

Illustrative contract

GET/knowledge/facts

Runtime: server only
Timeout: bounded
Workspace: explicit
Correlation: retained

The published contract is normative. Examples explain the pattern and do not grant an operation or credential.

Implementation checklist

Build a server-side connection whose scope and failure behavior are visible.

The published contract is normative. Examples explain the pattern and do not grant an operation or credential.

1 · Keep credentials server-sideLoad the supplied credential from a secret store, never from browser code.
2 · Bind the workspaceUse the workspace context approved for the customer and operation.
3 · Set a timeoutBound every provider call and do not silently convert a timeout into success.
4 · Record correlationStore the Saleringo request ID beside a non-sensitive local correlation ID.

Request and result

Server request pattern

const response = await fetch(`${origin}/knowledge/facts`, {
  headers: { Authorization: `Bearer ${token}` },
  signal: AbortSignal.timeout(5000)
});

Outcome branch

if (!response.ok) {
  const failure = await decodeFailure(response);
  return handleByStatus(failure);
}

Failure handling

StatusMeaningClient action

401Credential is missing, expired, or invalidStop; refresh through the approved server flow.

403Identity lacks the exact permission or scopeDo not retry; request an access review.

409State, version, idempotency, or approval conflictsRead the conflict and reconcile before another command.

422The request does not match the published schemaCorrect the named fields; do not retry unchanged.

429The integration is sending too quicklyHonor the supplied wait guidance and apply backoff.

5xxA temporary service failure may have occurredPreserve IDs; retry only when the operation permits it.

Implementation support

Do not send credentials, customer secrets, or raw payment data. Include the contract version, environment, operation, timestamp, and non-sensitive correlation ID.

Open the contact path

Check one integration contract.

Confirm authentication, permissions, timeouts, duplicate handling, and failure evidence for the approved deployment.

Open the API contract