Sandbox Guide (v1.0)

This guide explains how the sandbox environment behaves and how to test your integration reliably without touching production.

Overview

• Authentication: Same OAuth 2.0 flows as production (see auth.md). Use sandbox-issued credentials.
• Base URLs: Use your sandbox API base. Endpoints are the same as production unless noted.
• Determinism: Sandbox uses simple, deterministic rules so you can simulate specific outcomes.

Transactions (Commerce API)

Create a Sale

• Endpoint: POST /commerce/generate-sale
• Required fields: total, storeId, folioExternal, and exactly one of (clientId, clientUsername); exactly one of (salesmanId, salesmanIdentifier).

Sandbox outcome rules

• If folioExternal contains REJECTED (case-insensitive):
  • Immediate status: IN_PROGRESS
  • After ~5 seconds: status becomes REJECTED
• Else if folioExternal contains NO_CANCEL:
  • Status remains IN_PROGRESS (no auto transition). You must cancel manually.
• Else:
  • Immediate status: IN_PROGRESS
  • After ~5 seconds: status becomes APPROVED

Cancellation

• Endpoint: POST /commerce/cancel-transaction
• Precondition: Transaction must be IN_PROGRESS.
• Result: status changes to CANCELED.

Status lookup

• Endpoint: POST /commerce/transaction-status
• Input: folio
• Returns: status and transaction context (storeId, salesmanId, total, clientId, timestamps, comments).

Validation rules (sandbox)

• Minimum amount: total >= 500 is required; otherwise rejected with SALE-CREATION-03.
• Credit line: total must be <= availableAmount + lineExtensionAvailable of the client, otherwise SALE-CREATION-04.
• Store/Salesman/Client existence: Must exist and belong to the same company; otherwise the corresponding error code (SALE-CREATION-01/02/05).

Webhooks in sandbox

• On create: A "transaction created" event is sent with status IN_PROGRESS.
• On auto transition (~5s): A second event is sent with final status (APPROVED or REJECTED).
• On manual cancel: A cancellation event is sent with status CANCELED.
• Delivery: POST requests only; retries with exponential backoff on failures. Implement HMAC or Bearer verification (see webhooks.md).

Transaction test matrix

Case	Input (key fields)	Expected status progression
Approve after delay	folioExternal = "ANYTHING"	IN_PROGRESS → (≈5s) APPROVED
Force rejection	folioExternal contains REJECTED	IN_PROGRESS → (≈5s) REJECTED
No auto transition	folioExternal contains NO_CANCEL	IN_PROGRESS (stays)
Cancel in progress	status=IN_PROGRESS, call cancel	CANCELED
Below minimum	total < 500	Error SALE-CREATION-03
Exceeds line	total > available + extension	Error SALE-CREATION-04

Web Component / Hosted Checkout

Generate link

• Endpoint: POST /sale-link/generate
• Optional inputs: amount, clientUsername, salesmanIdentifier, storeId, description, externalId, ticket, callbackUri.
• Response: link, token (checkout token).

Validate link

• Endpoint: GET /sale-link/validate
• Uses the checkout token to return the current state (transactionId, status, client, amounts, store/salesman IDs).

Sandbox notes

• If you do not provide amount, the embedded UI prompts the value.
• callbackUri is honored to redirect the enclosing app/site at completion.
• Link expiry is handled by the platform; use /sale-link/validate to refresh state if needed.

Preview and Sale Request Flow (token-protected)

These endpoints are used by the embedded flow and require a checkout token.

Preview endpoints

• GET /preview/stores — list stores for the company
• GET /preview/salesmen — list salesmen, typically filtered by storeId
• GET /preview/line-extension — requires storeId; returns the line extension available
• GET /preview/client-search — requires username; returns a simplified client or null

Sale request endpoints

• POST /sale-request/confirm-client — body: clientId; returns true if accepted
• POST /sale-request/confirm-sale — body: storeId, salesmanId, amount, description, optional ticket, externalId; returns confirmation data
• GET /sale-request/status — returns the current sale request summary
• POST /sale-request/cancel — cancels the current sale request

Client search behavior (sandbox)

• Use realistic username values (e.g., phone or email) to simulate existing clients.
• After 10 searches for a single sale request, sandbox responds with 429 (TOO_MANY_CLIENT_SEARCHES).
• Invalid usernames return null.

Parameters and conventions

• folioExternal: External identifier for idempotency and to drive sandbox scenarios (contains REJECTED or NO_CANCEL).
• ticket: Optional POS receipt/reference; free-form string (recommended ≤ 64 chars).
• One-of semantics: Provide either clientUsername or clientId; either salesmanIdentifier or salesmanId.

Best practices for testing

1. Start with a normal approval flow (no special keywords) and verify status after ~5 seconds.
2. Test rejection by including REJECTED in folioExternal.
3. Test manual cancellation by including NO_CANCEL and calling /commerce/cancel-transaction.
4. Validate webhook reception and HMAC/Bearer verification.
5. Exercise preview endpoints to ensure your selection UI behaves as expected.