Concepts
אידמפוטנטיות (Idempotency)
המצב האמיתי היום — ואיך למנוע חיוב כפול של לקוח בעקבות ניסיון חוזר.
קראו את זה לפני שאתם בונים לוגיקת ניסיון-חוזר (retry). ה-endpoints
POST /api/v1/documents ו-POST /api/v1/clients אינם תומכים כיום במפתח
אידמפוטנטיות. ניסיון חוזר על בקשה שנכשלה (timeout, שגיאת 5xx, חיבור לא יציב) יוצר
מסמך או לקוח שני.
למה זה כך
משטח האינטגרציה המקורי של VUZ — /integrations/*, שנבנה עבור תוסף ה-WooCommerce ועדיין
פעיל כ-alias לתאימות לאחור — כן תומך במפתח אידמפוטנטיות אמיתי: externalReference
(בפורמט source:site:entity:id). ה-endpoints החדשים והנבחרים /api/v1/documents ו-
/api/v1/clients נבנו ישירות מעל ה-DTO-ים של לוח הבקרה, שאין להם שדה כזה — זהו פער אמיתי,
לא השמטה בתיעוד.
מה לעשות היום
- שמרו מיפוי משלכם —
המזהה שלכם → vuz.document.id(וגם ללקוחות) מיד לאחר קבלת201. לפני יצירה, בדקו אם כבר יש מיפוי לפני שאתם שולחים שוב. - אם אתם כבר על WooCommerce — המשיכו להשתמש ב-
/integrations/documents, שיש לו אידמפוטנטיות אמיתית דרךexternalReference. - בכשל לא ברור — לפני ניסיון חוזר, בדקו עם
GET /documents?clientId=...(או המיפוי שלכם) האם הבקשה כבר הצליחה.