Skip to content

Integration Flow

Push order

Some calls happen once (before go-live or when codes change); the rest happen every business date.

sequenceDiagram
    autonumber
    participant P as Partner
    participant API as POS Ingest API
    Note over P,API: Before go-live, or when codes / stores change
    P->>API: GET /reference/transaction-types
    API-->>P: 200 standard codes
    P->>API: PUT /mappings/transaction-types
    API-->>P: 202 Accepted
    P->>API: PUT /stores
    API-->>P: 202 Accepted
    Note over P,API: Every business date
    P->>API: PUT /products (changed products only)
    API-->>P: 202 Accepted
    loop One or more batches
        P->>API: POST /trade-records
        API-->>P: 202 Accepted
    end
    P->>API: POST /daily-close (after the last batch)
    API-->>P: 202 Accepted
    Note over P,API: About 30 minutes later
    P->>API: GET /daily-close/{store_id}/{business_date}
    API-->>P: 200 MATCHED / MISMATCHED
Step Call When
0 GET /reference/transaction-types Before go-live, or when HQ announces a code update
1 PUT /mappings/transaction-types Before go-live, or when your own codes change
2 PUT /stores Before go-live, or when a store changes
3 PUT /products Every day before pushing transactions; changed products only
4 POST /trade-records After the store closes; may be split into several batches
5 POST /daily-close Last, after every transaction batch of that business date
6 GET /daily-close/{store_id}/{business_date} About 30 minutes after sending the daily close

How the API tolerates mistakes

  • Wrong order is not rejected. If a transaction references an unknown product_id or an unmapped transaction type, it is still accepted. HQ re-maps the record once the master data or mapping arrives. Following the order above avoids reconciliation delays.
  • Same transaction sent more than once. The record with the higher version wins. With equal versions, the later last_modified_at wins.
  • Changes to a business date that is already closed. Resend the changed transaction with version + 1, then **resend that day