การลองใหม่อย่างปลอดภัย
เมื่อการเชื่อมต่อขาด คุณไม่มีทางรู้ว่าคำสั่งซื้อสำเร็จหรือไม่ ดังนั้นให้ส่งอีกครั้ง ภายใน 7 วัน คีย์ idempotency เดียวกันหมายถึงคำสั่งซื้อเดียวกัน และถูกเรียกเก็บเงินเพียงครั้งเดียว
วิธีการทำงาน
POST /orders ต้องมีเฮดเดอร์ Idempotency-Key (คีย์ idempotency) เป็นอักขระ ASCII ไม่เกิน 200 ตัวโดยไม่มีช่องว่าง ซึ่งคุณสร้างเองและเก็บไว้กับบันทึกคำสั่งซื้อของคุณ ใช้ UUID ได้ดี ใช้คีย์ idempotency ใหม่สำหรับคำสั่งซื้อใหม่
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'สิ่งที่คุณจะได้รับกลับมา
201 และคำสั่งซื้อใหม่200 คำสั่งซื้อเดิม และ Idempotent-Replay: true ไม่มีการเรียกเก็บเงินเพิ่ม แม้ราคาจะเปลี่ยนไปแล้วก็ตามorder_status_unknown หรือ rate_limited409 idempotency_conflict ไม่มีการสร้างคำสั่งซื้อinsufficient_balance409 price_changed และคีย์ idempotency ใหม่จะสั่งซื้อในราคาใหม่เมื่อคุณไม่รู้สถานะ
การตอบกลับที่สูญหาย order_status_unknown และการตอบกลับที่ไม่ใช่ JSON เช่น 502 หรือ 504 จากเกตเวย์ ล้วนมีความหมายเดียวกัน คือให้ส่งคำขอซ้ำด้วยคีย์ idempotency เดิมเพื่อดูสถานะจริง ซึ่งจะไม่เรียกเก็บเงินซ้ำเด็ดขาด ห้ามสร้างคีย์ idempotency ใหม่เพราะคำขอหมดเวลาหรือล้มเหลว เพราะนั่นคือคำสั่งซื้อใหม่และจะถูกเรียกเก็บเงิน
รอหนึ่งนาทีระหว่างการส่งซ้ำแต่ละครั้ง หากยังตอบกลับ order_status_unknown หลังผ่านไปหลายนาที ให้หยุดและติดต่อฝ่ายสนับสนุนพร้อม request_id อย่าสร้างคีย์ idempotency ใหม่
คีย์ idempotency มีอายุนานเท่าใด
คีย์ idempotency จะถูกจดจำเป็นเวลา 7 วันนับจากที่ส่งครั้งแรก หลังจากนั้นคีย์เดิมจะสร้างคำสั่งซื้อใหม่ ดังนั้นให้ลองใหม่ภายในไม่กี่วัน และเตรียมคีย์ idempotency ใหม่สำหรับแต่ละคำสั่งซื้อใหม่