串接流程

推送順序

合作夥伴須依下列順序推送資料：

sequenceDiagram
    autonumber
    participant P as Partner / POS
    participant A as POS Ingest API
    Note over P,A: 上線前，或代碼／門市異動時
    P->>A: GET /reference/transaction-types
    A-->>P: 200 標準交易型態清單
    P->>A: PUT /mappings/transaction-types
    A-->>P: 202 ACCEPTED
    P->>A: PUT /stores
    A-->>P: 202 ACCEPTED
    Note over P,A: 每個營業日
    P->>A: PUT /products（只送異動商品）
    A-->>P: 202 ACCEPTED
    loop 每一批交易（每批最多 500 筆）
        P->>A: POST /trade-records
        A-->>P: 202 ACCEPTED
    end
    P->>A: POST /daily-close（所有交易送完後最後送）
    A-->>P: 202 ACCEPTED
    Note over P,A: 約 30 分鐘後
    P->>A: GET /daily-close/{store_id}/{business_date}
    A-->>P: 200 MATCHED / MISMATCHED

順序	動作	時機
0	GET /reference/transaction-types	上線前，或總部通知代碼更新時
1	PUT /mappings/transaction-types	上線前，或自家代碼異動時
2	PUT /stores	上線前，或門市異動時
3	PUT /products	每日推送交易之前，只送有異動的商品
4	POST /trade-records	門市日結後，可分多批
5	POST /daily-close	該營業日所有交易批次送完後最後送
6	GET /daily-close/{store_id}/{business_date}	送出日結約 30 分鐘後查詢

接收端容錯

• 順序錯誤不會被拒收：交易中出現未知的 product_id 或未對照的交易型態，API 照收，總部會在主檔或對照表到齊後重新對應。但仍請依上述順序推送，以免對帳延遲。
• 同一筆交易重送：以 version 較大者為準；version 相同時以 last_modified_at 較晚者為準。
• 已日結的營業日有異動：重送該筆交易（version + 1），並重送該日 /daily-close，控制總數需更新為異動後的值。

對帳不一致時

查詢結果為 MISMATCHED 時，請補送缺漏的交易（或以 version + 1 更正），再以新的 batch_id 重送日結。