Skip to content

Integration guide

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

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

Implementation checklist

  1. Keep credentials server-side

    Load the supplied credential from a secret store, never from browser code.

  2. Bind the workspace

    Use the workspace context approved for the customer and operation.

  3. Set a timeout

    Bound every provider call and do not silently convert a timeout into success.

  4. Record correlation

    Store 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

API 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.