ACP / Instant Checkout: standart və onun ChatGPT-də reallaşdırılması

1. Niyə ACP lazımdır və bu niyə «sadəcə daha bir REST API» deyil

Sinizcə baxsaq, ACP adi HTTP‑endpoint-ləri və JSON‑strukturlarının toplusu kimi görünür: hansısa /checkout_sessions, hansısa webhook-lar, hansısa tokenlər. Asanlıqla belə düşünmək olar: «Yaxşı, bu da növbəti platformadan daha bir xüsusi API-dir». Amma ACP ideyası daha dərindir.

ACP üç iştirakçı arasında açıq qarşılıqlı əlaqə protokolu kimi nəzərdə tutulub: süni intellekt (məsələn, ChatGPT) platforması, sizin commerce‑backend-iniz və ödəniş provayderi. Məqsəd — məhsulların və qiymətlərin necə təsvir olunacağını, AI-nin istifadəçinin alma niyyətini necə bildirəcəyini, checkout sessiyasının necə yaradılacağını, ödənişin necə icra olunacağını və bütün iştirakçıların yekun statusu necə biləcəklərini standartlaşdırmaqdır.

Əsas fikir: ACP-ni reallaşdıran eyni satıcı backend-i potensial olaraq təkcə ChatGPT ilə deyil, həm də bu standartı dəstəkləyən digər LLM‑platformaları ilə işləyə bilər. Yəni siz «xüsusi ChatGPT API-si» yazmırsınız, növbəti nəsil commerce‑inteqrasiyası protokolunu həyata keçirirsiniz.

ChatGPT-də Instant Checkout — ACP standartının ilk böyük reallaşdırılmasıdır. ChatGPT bu protokola əməl edərək sizin ACP‑endpoint-lərinizi çağırır və istifadəçiyə səliqəli UI göstərir, amma oyunun qaydaları ACP spesifikasiyalarında təsvir olunub, «GPT sehri» kimi haradasa qara qutunun içində gizlənməyib.

2. ACP-nin üç dayağı: Product Feed, Agentic Checkout, Delegated Payment

ACP-nin üç əsas spesifikasiyası var və biz onları tez‑tez xatırladacağıq:

Product Feed-i əvvəlki mühazirələrdə artıq nəzərdən keçirmişdik. İndi isə bizi son iki blok maraqlandırır: Agentic Checkout və Delegated Payment.

Üç səviyyəni fərqləndirmək vacibdir:

1. Standart (SPEC). Rəsmi sənədlər hansı sahələrin və endpoint-lərin olmalı olduğunu, hansı statusların qanuni olduğunu və hansı təminatları üzərinizə götürdüyünüzü təsvir edir.
2. Memarlıq pattern-i (ARCH). Məsələn, SKU və sifarişləri ayrı cədvəllərdə saxlamaq, ACP ətrafında servis‑wrapper qurmaq və ya webhook-lar üçün növbədən istifadə etmək. Bunlar yaxşı təcrübələrdir, amma standartın bir hissəsi deyil.
3. Konkret reallaşdırma (GiftGenius nümunəsi). Bu bizim tədris layihəmizdir: cədvəllərimizin quruluşu, TypeScript-də dəqiq tip adları, sifarişləri necə log-layırıq və s. Bunların hamısı nümunədir, normativ sənəd deyil.

Biz SPEC-in harada bitdiyini və memarlığınızın harada başladığını daima vurğulayacağıq — ki, «mühazirədə persona_tags sahəsini gördüm və elə bildim ki, bu rəsmi spesifikasiya hissəsidir» kimi nəticə çıxmasın.

3. Checkout session daxildən: quruluş və statuslar

Agentic Checkout Spec-in mərkəzi obyekti sizin backend-dəki checkout_session-dır. Məntiqcə bu alışın vəziyyətidir: hansı məhsullar, hansı məbləğə, hansı çatdırılma variantları ilə və hazırda ödəniş cəhdi hansı statusdadır.

Spec təxminən belə məcburi sahələri təsvir edir (formulyasiyalar orijinaldan sadələşdirilib və qismən qısaldılıb):

• id — sizin yaratdığınız və qaytardığınız sətir identifikatoru. ChatGPT sonrakı bütün çağırışlarda onu istifadə edəcək.
• buyer — alıcı haqqında məlumat: ad, email, telefon, bəzən ünvan. Real spec-də bu obyekt PSP və sistemlərinizin etibarlı istifadə edə bilməsi üçün strukturlaşdırılıb.
• status — alışın cari vəziyyətini əks etdirən sətir enum-u. Baza statuslar:
  • not_ready_for_payment — hələ ödəniş etmək olmaz (məsələn, çatdırılma variantı seçilməyib və ya vergilər hesablanmayıb).
  • ready_for_payment — hər şey hazırdır, ödəniş tokeni tələb etmək və məbləği tutmaq olar.
  • completed — ödəniş uğurla keçdi, sifariş yaradıldı.
  • canceled — alış ləğv edildi (istifadəçi təşəbbüsü ilə və ya xəta səbəbi ilə).
• currency — ISO 4217 formatında kiçik hərflərlə valyuta kodu ("usd", "eur" və s.).
• line_items — səbətdəki mövqelər siyahısı, hər biri öz SKU-su, miqdarı və hesablanmış dəyəri ilə.
• fulfillment_address — çatdırılma ünvanı (əgər uyğundursa).
• fulfillment_options və fulfillment_option_id — mümkün çatdırılma (və ya icra) variantları və hazırda seçilmiş variant.
• totals — cəmlənmiş məbləğlər: məhsulların dəyəri, vergilər, çatdırılma, yekun məbləğ.
• order — sessiya uğurla başa çatdıqdan sonra yaradılacaq sifarişi təsvir edən obyekt.
• messages — ChatGPT-nin alıcıya göstərə biləcəyi istifadəçi mesajları: məsələn, xəbərdarlıqlar və ya xətalar.
• links — keçidlər siyahısı, məsələn, geri qaytarma siyasəti, Privacy Policy və Terms of Service-ə.

Demoda bütün sahələri reallaşdırmağımız vacib deyil, amma ideyanı başa düşmək vacibdir: checkout_session — «bir alış cəhdinin hekayəsi və cari vəziyyəti»dir və ChatGPT düzgün UX üçün lazımi hər şeyi burada görməyi gözləyir.

Sadlətmək üçün tədris kodumuzda sadələşdirilmiş tip təqdim edək:

// GiftGenius üçün sadələşdirilmiş checkout_session modeli (tam SPEC deyil)
type GGCheckoutStatus = 'not_ready_for_payment' | 'ready_for_payment' | 'completed' | 'canceled';

type GGLineItem = { skuId: string; quantity: number; total: number };

type GGCheckoutSession = {
  id: string;
  status: GGCheckoutStatus;
  currency: 'usd';
  lineItems: GGLineItem[];
  grandTotal: number;
};

Bu model rəsmi spesifikasiyadan qəsdən sadədir, amma praktika üçün əladır: yüzlərlə sahədə boğulmadan statusları və keçidləri yadda saxlamağı öyrənmək.

4. checkout_session-in həyat dövrü

Agentic Checkout spesifikasiyası checkout_session üzərində bir neçə əməliyyat təsvir edir. Sadə formada həyat dövrü belə görünür:

1. Sessiyanın yaradılması: POST /checkout_sessions.
2. Sessiyanın yenilənməsi: POST /checkout_sessions/{id}.
3. Sessiyanın tamamlanması (complete): POST /checkout_sessions/{id}/complete.
4. (Bəzən) Ləğv: ayrıca cancel‑endpoint və ya yeniləmə ilə canceled-ə keçid.

Statuslar baxımından belə bir diaqram çəkmək olar:

stateDiagram-v2
    [*] --> not_ready_for_payment
    not_ready_for_payment --> ready_for_payment: çatdırılma/vergilərin hesablanması
variantların seçilməsi
    ready_for_payment --> completed: uğurlu POST /complete
    ready_for_payment --> canceled: istifadəçi tərəfindən ləğv etmə və ya xəta
    not_ready_for_payment --> canceled: xəta, uyğunsuz məlumatlar

Yaradılma checkout_session adətən not_ready_for_payment vəziyyətində başlayır və ya hər şey ödəniş üçün artıq məlumdursa (məsələn, çatdırılma və vergisiz rəqəmsal məhsul), birbaşa ready_for_payment ola bilər. Yeniləmələr məlumat əlavə etmək (ünvan, promo kodlar, çatdırılma variantı) və məbləğləri yenidən hesablamaq üçün istifadə olunur. Tamamlama — Delegated Payment-in işə düşdüyü və pulun həqiqətən tutulduğu andır.

Burada rolların bölgüsünü başa düşmək vacibdir:

• ChatGPT istifadəçi ilə dialoqa əsaslanaraq sessiyanın yaradılmasını, yenilənməsini və tamamlanmasını başladır.
• Sizin backend (satıcı) düzgün biznes‑logikaya cavabdehdir: SKU, əlçatanlıq, qiymət və vergilərin hesablanması, statusların dəyişdirilməsi, sifarişlərin yaradılması.
• PSP (Stripe və s.) real ödənişi aparır və satıcının vəsaiti tutması üçün Shared Payment Token verir.

Bir azdan bu state‑diaqramı konkret HTTP‑sorğular və kiçik kod nümunələri ilə üst‑üstə qoyacağıq.

5. checkout_session-in yaradılması: ChatGPT bizdən nə gözləyir

ChatGPT (və ya agent) istifadəçinin həqiqətən nəsə almaq istədiyinə qərar verəndə, Product Feed əsasında line item-lər toplusu formalaşdırır: SKU siyahısı, miqdar, ehtimal olunan valyuta və bəlkə də çatdırılmaya dair əlavə istəklər. Sonra sizin POST /checkout_sessions endpoint-inizi çağırır.

Satıcı tərəfində bu anda etmək lazım olanlar:

1. Giriş məlumatlarını yoxlayın: bütün SKU-ların mövcud olduğuna, satışa açıq olduğuna, siyasəti pozmadığına (məsələn, yetkinlik yaşına çatmayan üçün alkoqol yoxdur) əmin olun.
2. Öz qaydalarınız əsasında qiymətləri və vergiləri hesablayın.
3. Məhsul fiziki isə çatdırılma variantlarını (fulfillment options) hazırlayın.
4. Status və məbləğlərlə düzgün checkout_session qaytarın.

GiftGenius üçün ən sadə Express handler-i belə görünə bilər:

// Psevdokod: sadələşdirilmiş checkout_session yaradılması
app.post('/checkout_sessions', async (req, res) => {
  const items = req.body.lineItems as GGLineItem[];  // skuId + quantity
  const pricedItems = await priceItems(items);       // hər SKU üçün total-u hesablayırıq
  const grandTotal = sum(pricedItems.map(i => i.total));

  const session: GGCheckoutSession = {
    id: generateId(),
    status: 'ready_for_payment', // rəqəmsal hədiyyələr üçün dərhal ödənişə hazır etmək olar
    currency: 'usd',
    lineItems: pricedItems,
    grandTotal,
  };

  res.status(201).json(session);
});

Burada bir neçə şey edirik:

• Müştəridən (ChatGPT) gələn qiymətlərə etibar etmirik və onları öz məlumatlarımız əsasında yenidən hesablayırıq — bu, commerce təhlükəsizliyi üçün kritikdir.
• Öz id sessiya identifikatorumuzu yaradırıq (məsələn, gg_chk_... prefiksi ilə).
• Əlavə addımlar yoxdursa (çatdırılma yoxdur, avtomatik vergilər, sadə model), ready_for_payment statusu qaytarırıq.

Real ACP‑uyğun backend-də əlavə olaraq messages, links və mürəkkəb totals obyektini qaytaracaq, həmçinin spesifikasiyada təsvir olunduğu kimi order-i (heç olmasa qaralama kimi) dolduracaqsınız.

6. checkout_session-in yenilənməsi və idempotentlik

Sessiya yaradıldıqdan sonra ChatGPT istifadəçidən əlavə detallar istəyə bilər: çatdırılma ünvanı, kuponun tətbiqi, icra variantının dəyişdirilməsi. Bu məlumatlar göründükdə, platforma POST /checkout_sessions/{id} çağırışını edərək hesablamaları yeniləməyinizi istəyir.

Kod baxımından bu, yaradılmaya çox bənzəyir, amma yeni sessiya yaratmaq əvəzinə siz:

• id üzrə mövcud sessiyanı tapırsınız;
• dəyəşiklikləri tətbiq edirsiniz (məsələn, fulfillment_option_id-i dəyişmək və ya endirim əlavə etmək);
• məbləğləri yenidən hesablamaq;
• yenilənmiş checkout_session qaytarmaq.

Vacibdir ki, spesifikasiya təkrar çağırışlara icazə verir (şəbəkə nasazlıqları və ya ChatGPT tərəfindən təkrarlar səbəbilə). Ona görə də, əvvəlki modullarda alətlər və webhook-lar üçün idempotentlikdən danışdığımız kimi, burada da sorğu başlıqlarında Idempotency-Key-dən istifadə etməyi və təkrarlara diqqətlə yanaşmağı tövsiyə edir.

Şərti yeniləmə handler-i belə ola bilər:

app.post('/checkout_sessions/:id', async (req, res) => {
  const id = req.params.id;
  const key = req.header('Idempotency-Key'); // eyni açar => eyni effekt
  const existing = await loadSessionWithIdempotency(id, key, req.body);

  // applyUpdates içəridə qiymətləri, çatdırılmanı və s. yenidən hesablaya bilər
  const updated = await applyUpdates(existing, req.body);
  await saveSession(updated, key);

  res.json(updated);
});

Burada SPEC-in konkret strukturuna sərt uyğunlaşmırıq, ideyanı göstəririk: girişdə — dəyişikliklər və idempotent açar, çıxışda — checkout_session-in konsistent vəziyyəti. Eyni açarla eyni sorğu gəlsə, əlavə sifarişlər və ya log‑larda dublikatlar yaratmadan eyni nəticəni qaytarmalısınız.

7. checkout_session-in tamamlanması və Delegated Payment: Shared Payment Token necə işləyir

Ən maraqlı və gərgin an — checkout_session-in tamamlanmasıdır, yəni pul həqiqətən tutulur. Burada ikinci spesifikasiya işə düşür: Delegated Payment.

Delegated Payment ideyası

İstifadəçi ödəniş məlumatlarını ChatGPT interfeysində daxil edir və ya seçir (kart, cüzdan, yadda saxlanmış ödəniş üsulu). Platforma bu məlumatları sizə birbaşa göndərmir — bunun əvəzinə o, PSP-dən (məsələn, Stripe) xüsusi token, Shared Payment Token (SPT) istəyir ki:

• satıcı və konkret sessiya ilə birmənalı bağlı olsun;
• məbləğ və ömür müddəti ilə məhdudlaşdırılsın;
• sizə real kart nömrəsini açıqlamasın.

Nəticədə mənzərə belədir:

Belə dizayn satıcını ödəniş rekvizitlərini saxlamaqdan azad edir və sifarişin biznes‑logikasına fokuslanmağa imkan verir, uyğunluq (compliance) problemlərini isə PSP və platforma öz üzərinə götürür.

Insight

Shared Payment Token-in mənası ondan ibarətdir ki, kart məlumatları backend-dənizdən gizli qalsın, amma ödənişi məhz siz aparasınız. Amma ona bir az fərqli də baxmaq olar.

Yəqin belə situasiyaya rast gəlmisiniz: mağaza və ya otel əvvəlcə kartınızda vəsaiti hold edir, sonra isə bir müddət sonra tutur. Elə baxın: Shared Payment Token-i hold‑token kimi düşünün. ChatGPT istifadəçinin hesabında vəsaiti hold edib, amma tutmayıb. Bu hold‑token-i sizə ötürüb və siz indi onu Stripe-a göndərib pulu tuta bilərsiniz.

Burada iki vacib nüans var:

• hold və tutma məbləğləri ciddi fərqlənməməlidir, ən yaxşısı ümumiyyətlə üst‑üstə düşməlidir.
• siz ChatGPT vasitəsilə abunəliyin ilk ayını $1-a sata, sonra isə hər ay $49.99 tuta bilərsiniz.

POST /checkout_sessions/{id}/complete sorğusu

İstifadəçi Instant Checkout-da ödənişi təsdiqlə düyməsini basanda, ChatGPT:

1. PSP-dən SPT istəyir (məsələn, Stripe ACP API vasitəsilə).
2. Bu token-i alıcı məlumatları ilə birlikdə POST /checkout_sessions/{id}/complete vasitəsilə backend-inizə göndərir.

Spec sorğunun bədənini təxminən belə təsvir edir (aşağıda rəsmi sənəddən uyğunlaşdırılmış və qısaldılmış nümunə):

POST /checkout_sessions/checkout_session_123/complete

{
  "buyer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "johnsmith@mail.com"
  },
  "payment_data": {
    "token": "spt_123",
    "provider": "stripe"
  }
}

Sizin backend bunları etməlidir:

1. checkout_session_123 id-si ilə checkout_session-i tapın.
2. Statusun tamamlanmaya icazə verdiyini yoxlayın (adətən ready_for_payment).
3. PSP-də spt_123 token-dən istifadə etməklə ödəniş yaradın (üsul PSP-dən asılıdır, Stripe üçün — müəyyən endpoint və payment method tipi).
4. Ödəniş əməliyyatının təsdiqini gözləyin.
5. checkout_session-i completed-ə yeniləyin, sifariş yaradın və saxlayın, sessiya strukturunda order sahəsini doldurun.
6. Cavabda aktual checkout_session-i qaytarın.

Çox sadələşdirilmiş TypeScript psevdokodunda bu belə görünə bilər:

app.post('/checkout_sessions/:id/complete', async (req, res) => {
  const { id } = req.params;
  const { buyer, payment_data } = req.body;
  const session = await loadSession(id);

  await chargeWithSharedToken(payment_data.token, session.grandTotal);
  const completed = await markSessionCompleted(session, buyer);

  res.json(completed);
});

Real dünyada bu sətirlər arasında xəta emalı, təkrar cəhdlər, loglama və sifariş modelinizlə inteqrasiya gizlənəcək.

Nəsə səhv gedərsə (məsələn, ödəniş rədd edilərsə), checkout_session-i not_ready_for_payment və ya canceled statusu ilə qaytarmalı və messages-i elə doldurmalısınız ki, ChatGPT istifadəçiyə baş verəni düzgün izah edə bilsin.

8. ChatGPT-də Instant Checkout: hamısı bir axında necə birləşir

İndi bu parçaları ChatGPT-də «niyyətdən ödənişə» qədər bütöv ssenaridə toplayaq. Mühazirəni vidcetdəki «Al» düyməsinin arxasında gizlənənləri «dekodlama» kimi qəbul edə bilərsiniz.

Sadələşdirilmiş ssenari:

1. İstifadəçi yazır: «Dosta $50-a qədər rəqəmsal hədiyyə seç və elə indi alışı tamamla».
2. Agent (və ya birbaşa ChatGPT App) büdcə daxilində uyğun SKU-ları tapmaq üçün Product Feed-dən istifadə edir.
3. ChatGPT söhbətdə bir neçə hədiyyə kartı (sizin GiftGenius vidcetiniz vasitəsilə) göstərir və birini seçməyi təklif edir.
4. Seçimdən sonra ChatGPT line item-ləri formalaşdırır və sizin ACP backend-inizdə POST /checkout_sessions çağırır, məbləğlər və statusla checkout_session alır.
5. Instant Checkout UI-da istifadəçi yekun məbləği, məhsulun adını, geri qaytarma siyasətini və təsdiq düyməsini görür.
6. Təsdiq zamanı ChatGPT PSP-dən Shared Payment Token alır və yuxarıda müzakirə etdiyimiz kimi POST /checkout_sessions/{id}/complete çağırır.
7. Sizin backend ödənişi aparır, sifarişi yaradır, checkout_session-i completed statusu ilə qaytarır.
8. ChatGPT istifadəçiyə təsdiqi göstərir, sizin backend isə (Agentic Checkout Spec üzrə webhook-lar vasitəsilə) hadisəni OpenAI-ə geri göndərə bilər ki, platforma sifarişin taleyindən xəbərdar olsun.

Sequence‑diaqramında bu belə görünür:

sequenceDiagram
    actor U as İstifadəçi
    participant GPT as ChatGPT
    participant GG as GiftGenius ACP backend
    participant PSP as Stripe (PSP)

    U->>GPT: Mən $50-a qədər hədiyyə istəyirəm və elə burada almaq istəyirəm
    GPT->>GG: POST /checkout_sessions (line_items)
    GG-->>GPT: checkout_session (ready_for_payment)
    GPT->>U: Instant Checkout-u göstərir (məhsul, qiymət, ToS)
    U->>GPT: «Ödənişi təsdiqlə» düyməsini basır
    GPT->>PSP: Məbləğ və satıcı üçün SPT sorğusu
    PSP-->>GPT: Shared Payment Token (spt_xxx)
    GPT->>GG: POST /checkout_sessions/{id}/complete (token + buyer)
    GG->>PSP: SPT ilə ödəniş
    PSP-->>GG: Ödəniş uğurludur
    GG-->>GPT: checkout_session (completed + order)
    GPT-->>U: Alış təsdiqini göstərir

Bu ssenaridə nə «ixtiyari» baza çağırışı, nə də qəribə daxili endpoint-lər meydana çıxır. Hər şey ACP-nin dəqiq təsvir olunmuş kontraktına sığır — hər iştirakçı öz rolunu bilir.

9. Mini‑praktika: GiftGenius üçün sadələşdirilmiş ACP backend

Bu mühazirə nəzəriyyədə qalmaması üçün tədris layihəmiz üçün ACP qatının reallaşdırılmasını «zehni olaraq işlədək».

Təsəvvür edin ki, GiftGenius-da artıq var:

• Product Feed-i formalaşdırdığımız SKU və qiymətlər bazası (bunu əvvəlki mühazirələrdə modelləşdirmişdik).
• Sadə sifariş modeli: orders cədvəli və id, userId, skuId, amount, currency, status, createdAt sahələri.
• ChatGPT App interfeysi və hədiyyə tövsiyə edə bilən MCP qatı (bunu kursun əvvəlki modullarında qurmuşduq).

İndi sizin vəzifəniz — bunun üzərinə daha bir kiçik servis gg-acp əlavə etməkdir:

• POST /checkout_sessions endpoint-i:
  • SKU siyahısını və miqdarı qəbul edir.
  • Məbləğləri sizin DB-niz əsasında yenidən hesablayır.
  • Qaralama sifariş yaradır (məsələn, pending statusu ilə) və checkout_session-i ready_for_payment statusu ilə.
  • checkout_session qaytarır.
• POST /checkout_sessions/{id} endpoint-i:
  • Sessiyanı və sifarişi tapır.
  • Dəyişiklikləri tətbiq edir (məsələn, yekun məbləği azaldan promo kod dəstəyi).
  • Yenilənmiş checkout_session-i qaytarır.
• POST /checkout_sessions/{id}/complete endpoint-i:
  • SPT, məbləğ və alıcı məlumatlarını qəbul edir.
  • Demo versiyada real PSP çağırışı olmadan sifarişi «ödənilib» kimi işarələyə bilər (və ya Stripe-ı simulyasiya edə bilərsiniz).
  • checkout_session-i completed statusuna yeniləyir və ona order_id bağlayır.

Bu xidmətin hamısını kiçik bir Node/Express tətbiqində və ya Next.js App Router endpoint-lərində reallaşdırmaq olar. Əsas — hətta ödənişi emulyasiya etsəniz belə, format və statuslar üzrə kontrakta əməl etməkdir.

TypeScript-də şərti sifariş modeli belə görünə bilər:

// GiftGenius üçün sadələşdirilmiş sifariş modeli
type GGOrderStatus = 'pending' | 'paid' | 'canceled';

type GGOrder = {
  id: string;
  userId: string;
  skuId: string;
  amount: number;
  currency: 'usd';
  status: GGOrderStatus;
};

Prodakşnda bunun üzərinə Auth/Identity ilə əlaqələr (chat-in hansı istifadəçi olduğunu bilmək üçün), OpenAI-ə webhook-lar və daha mürəkkəb refund ssenariləri əlavə olunacaq. Amma bu mühazirə çərçivəsində tədris addımı kimi pul itirmədən və sağlam düşüncəni qoruyaraq etibarlı şəkildə bu dövrü yeriməyi öyrənmək kifayətdir: sessiya yarat → yenilə → tamamla.

10. ACP / Instant Checkout dizaynında tipik səhvlər

Səhv №1: rolların qarışdırılması («ChatGPT — mənim mağazamdır»).
Bəzən tərtibatçılar ChatGPT-ni «mərkəzi uçot sistemi» kimi düşünür və sifarişin biznes vəziyyətini platforma tərəfində saxlamağa çalışırlar: «orada checkout_session var, deməli, sifariş tarixçəsini OpenAI-dən oxuyacağam». Bu, dalana aparır. checkout_session — protokol obyekti, sifarişlərin həqiqət mənbəyi deyil. Həqiqət mənbəyi — sizin commerce backend: məhz orada sifarişlər, statuslar, refund-lar və hesabatlar yaşamalıdır. Bu sxemdə ChatGPT sadəcə etibarlı «chat içində frontend»dir.

Səhv №2: ChatGPT-dən gələn giriş qiymətlərinə etibar.
Belə düşünmək asandır: «agent artıq SKU seçib və hətta məbləği hesablayıb, gəlin bu məbləği qəbul edib pulu tutaq». Belə etmək olmaz. ChatGPT-dən gələn (line items, ehtimal olunan qiymətlər) məlumatı göstəriş yox, təklif kimi qəbul etmək lazımdır. Backend-iniz SKU, qiymətlər, mövcudluq, endirimlərin tətbiqolunması və s. məsələləri öz DB-niz və Product Feed ilə tutuşduraraq mütləq yoxlamalıdır. Əks halda «model yuvarlaqlaşdırdı deyə istifadəçi məhsulu $0.01-a aldı» tipli gülməli bug sinfi yaranacaq.

Səhv №3: statusları və state‑maşını görməməzlikdən gəlmək.
Erkən prototiplərdə tez‑tez «deşiyi» olan reallaşdırma edirlər: sessiyanın statusu həmişə completed və ya sadəcə ok olur, faktiki ödəniş vəziyyətindəki uyğunsuzluqları isə içəridə gizlədirlər. Nəticədə ChatGPT istifadəçiyə baş verəni düzgün göstərə bilmir: ödəniş yoldadır, artıq tamamlanıb, yoxsa ləğv edilib. Daha etibarlısı not_ready_for_payment → ready_for_payment → completed/canceled state‑maşınını dürüst reallaşdırmaq və backend-dən real statusu qaytarmaqdır, uydurma ad‑hoc sahələr yox.

Səhv №4: Shared Payment Token-i «çoxistifadəli kart» kimi istifadə etmək.
SPT nəzərdə tutulduğuna görə birdəfəlik və ya sərt məhdudlaşdırılmış token-dir: konkret əməliyyata, məbləğə və satıcıya bağlıdır. Onu «birdən lazım olar» deyə keşləmək və ya başqa alış üçün təkrar istifadə etmək pis fikirdir. Yaxşı halda PSP ikinci cəhddə imtina edəcək; pis halda ödəniş və sifariş uçotunu dolaşdıracaqsınız. Hər bir checkout_session.complete üçün təzə token olmalıdır, ödəniş alınmadısa — yenisini istəmək lazımdır.

Səhv №5: /checkout_sessions və webhook-larda idempotentliyin olmaması.
Real şəbəkədə sorğular dublikat ola bilər: ChatGPT taym‑outdan sonra POST /checkout_sessions-i təkrarlaya, PSP isə müvəqqəti xətadan sonra webhook-u yenidən göndərə bilər. Reallaşdırmanız hər dəfə yeni sifariş və DB-də yeni qeyd yaradırsa, tezliklə xaos olacaq: ikiqat tutmalar, sifariş dublikatları və sistemlər arasında qəribə uyğunsuzluqlar. Idempotency-Key-dən istifadə, təkrarların yoxlanması və əvvəlki çağırışların nəticələrinin saxlanması «opsional optimizasiya» deyil, etibarlı ACP inteqrasiyasının zəruri elementidir.

Səhv №6: Product Feed ilə əlaqəni unutmaq.
Bəzən ACP qatı «vakuumda» dizayn edilir: SKU və qiymətlər Product Feed-ə düşənlərlə üst‑üstə düşməyən hansısa daxili cədvəllərdən götürülür. Nəticədə ChatGPT istifadəçiyə birini (feed üzrə) göstərir, checkout vasitəsilə ACP-də isə tamam başqa şey gedir. Bu sürprizlərdən qaçmaq üçün SKU və qiymət modelinizin vahid olması vacibdir: feed, ACP backend və daxili baza eyni həqiqət mənbəyinə baxmalıdır, hətta üstündə müxtəlif proyeksiyalar və keşlər olsa belə.