Common Rules

The rules on this page apply to every endpoint of the Physical POS management API. The endpoint pages link here.

Response envelope

On success the data is under data. In this API every endpoint that returns a single record wraps it under the entity name; related data sits in sibling fields:

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "store": {
      "id": "00000000-0000-0000-0000-000000000101",
      "code": "IST-KADIKOY",
      "name": "Kadıköy Store",
      "storeStatus": "ACTIVE",
      "rowVersion": 1
    },
    "replayed": false
  },
  "statusCode": 201,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

The store object is shortened in the example; the response contains every field.

• Create endpoints return 201 for a new record and 200 for a repeat with the same Idempotency-Key. → Idempotency-Key
• On list endpoints pageInfo is also at the top level of the envelope; both copies are identical.
• Envelope fields not shown in the examples for brevity (message, timestamp …) are also in the response. All envelope fields and the error envelope: Error Handling.
• On errors, branch on code, not on message. This product's codes: Error Codes.
• For physical_pos.* errors the response carries a docsUrl field that links to that code's row on the Error Codes page.
• Error details are in details: single-field errors carry details.field and details.reason; a validation error covering several fields (physical_pos.validation.invalid) carries a details.errors array, each item { field, errors: [<reason>] }. The value you sent is never echoed in details.

Field rules

Pagination

List endpoints use cursor-based pagination:

"pageInfo": { "hasMore": true, "nextCursor": "eyJ0IjoiMjAyNi0…", "totalCount": null }

• Every list is sorted newest first (createdAt descending, ties by id descending); the order cannot be changed.
• If pageInfo.hasMore is true, request the next page with cursor=<nextCursor>; on the last page nextCursor is null.
• totalCount is null unless you send includeTotal=true. Counting is expensive; hasMore is enough to page through.
• Do not build or modify the cursor yourself. A broken cursor returns 400 physical_pos.cursor.invalid; start again from the first page.
• Reset the cursor when you change filters.

Catalog endpoints are not paginated; the whole list comes back as an array in one response.

Idempotency-Key

Endpoints that create something require an Idempotency-Key header so you can safely retry after a network failure:

Format: 8–200 printable ASCII characters without spaces. The value is not trimmed or corrected. A missing header gets 400 physical_pos.idempotency.key_required, a malformed one 400 physical_pos.idempotency.key_invalid.

Behaviour:

• Bodies are compared after the field rules are applied; field order does not matter.
• For operations tied to another record, such as creating a register or adding a bank row, the path parameter is part of the comparison: using the same key for another store gets 409.
• A key can be used for one operation only in your key's environment and is kept indefinitely. Do not reuse a used key for a new operation.
• Values used with test and live keys are kept apart.

The other write endpoints (PATCH, archive, restore, close a terminal, assign a device, replace the device) do not use Idempotency-Key; the header is ignored there. These endpoints are protected by rowVersion: if the first attempt had completed, the retry gets 409 physical_pos.version_conflict (409 physical_pos.terminal.closed when closing a terminal). In that case read the record and check whether your change was applied.

Concurrency: rowVersion

Every changeable record (store, register, logical terminal, bank row) carries a rowVersion integer. In requests that change a record you send the rowVersion you last read in the body:

{ "rowVersion": 3, "name": "Kadıköy Store (New)" }

• rowVersion is required; it is a JSON integer between 1 and 2147483647. Sending a string ("3") gets 400 VALIDATION_ERROR.
• If the record was changed by another request after you read it, the request gets 409 physical_pos.version_conflict and nothing is changed. Read the record again, apply your change to its current state and resend with the new rowVersion.
• After every successful change, use the current rowVersion from the response.
• A bank row update takes the row's own rowVersion, device link operations take the terminal's rowVersion, and device operations take the device's rowVersion.

Code rules

Store, register and terminal codes are stored in canonical form:

• A code with non-ASCII characters is rejected, not converted: KADIKÖY is not accepted, write KADIKOY.
• A malformed code gets 400 physical_pos.input.code_invalid, a malformed vendor code 400 physical_pos.input.vendor_code_invalid, a malformed external reference 400 physical_pos.input.ref_invalid.
• Codes do not change after creation.

Text rules

These rules apply to free-text fields (name, displayName, city, district, addressLine, label, the q search parameter):

1. The text is normalized to Unicode NFC and leading and trailing spaces are trimmed.
2. Text that is empty after trimming is rejected.
3. These characters are rejected: control characters, zero-width and invisible characters, characters that change text direction, space characters other than the normal space (no-break space etc.), variation selectors and tag characters.
4. Length is counted in characters (Unicode code points); the limits are listed in each field table.

Text that breaks the rules is not corrected; the request gets 400 physical_pos.input.text_invalid. details.field gives the field name and details.reason the cause. The same violation in a list search (q) gets 400 physical_pos.input.filter_invalid.

Visible characters such as Turkish letters and emoji can be used in free text.

Time zone

A store's timezone field is an IANA time zone name (e.g. Europe/Istanbul). If you do not send it, Europe/Istanbul is used.

• The accepted names are the zone names of the IANA time zone database (tzdb) and UTC. The name must match exactly, including case.
• Old or renamed names are stored under their current name; responses always return the current name:

• Unknown names, and old names and abbreviations that do not map to a single zone (such as EET, HST, Turkey), are rejected: 400 physical_pos.validation.invalid with details.errors[0] = { "field": "timezone", "errors": ["iana_unknown"] }.

Reason codes

Archiving, restoring, closing a terminal, device link and device operations require a reasonCode. The codes come from fixed lists and are written in upper case exactly as listed; a code that is not on the list or does not fit the operation gets 400 physical_pos.input.reason_code_invalid.

• When a store is archived, its active registers are archived in the same operation; their change history gets the STORE_ARCHIVED code and the store's reason is kept in changes.storeReason.
• Use OTHER only for cases that have no match in the list.

Rate limits

Write endpoints (POST and PATCH) have a 60-second window per organization and API key. All writes of an endpoint family share one counter; reads are not limited:

Over the limit the request gets 429 RATE_LIMITED; the Retry-After header and details.retryAfterSeconds give the seconds to wait. Platform-wide limits: Rate Limits.

Change history

Every change to a store, register or terminal is written to the change history in the same operation. You read the history page by page from the GET …/audit endpoints.

Store, register and device events also carry requestId (the ID of the request that made the change); terminal events carry entityType, entityId and environment.

Retries

• 4xx errors are not fixed by retrying; correct the request.
• 503 physical_pos.service.busy (details.retryable: true) means the record was busy with another operation at that moment; retry the same request after a short wait.
• For other 5xx errors, retry with backoff. For create requests, reuse the same Idempotency-Key.