Cum să configurezi notificările despre finalizarea comenzilor API

Ce evenimente sunt considerate finalizare a comenzii

Mai întâi stabiliți ce status din API înseamnă finalizarea efectivă a comenzii. La diferiți furnizori acestea pot fi comanda executată, livrată, anulată, respinsă, returnată sau parțial executată. Nu legați automatizarea doar de cuvântul „succes”: comanda poate trece prin mai multe stări intermediare și apoi se poate opri din cauza unei limite, a unei verificări sau a unei anulări.

Trebuie procesat nu doar rezultatul pozitiv. Dacă serviciul trimite o notificare despre eroare, anulare, returnare sau execuție parțială, aceasta trebuie de asemenea înregistrată în sistemul intern. Altfel, în panou, CRM sau bot comanda va rămâne în așteptare, deși execuția ulterioară nu va mai avea loc.

Întocmiți un tabel de corespondență a statusurilor

Nu transmiteți statusul API în interfață fără procesare. Denumirile și logica furnizorului se pot schimba, iar același status intern uneori înglobează mai multe statusuri externe. Păstrați valoarea originală separat: va fi utilă pentru analiza erorilor și reconcilierea cu documentația.

• pending, created, queued — comandă nouă sau în așteptarea procesării.
• processing, in_progress, running — comanda este în curs de execuție.
• completed, delivered, success — comandă executată.
• partial, partially_completed — comandă parțial executată.
• cancelled, rejected, failed — comandă anulată sau încheiată cu eroare.
• refunded, returned — comanda necesită returnare sau ajustare.
• Status necunoscut — nu modifică automat fișa și este transmis pentru verificare.

Denumirile de mai sus sunt prezentate ca exemplu de schemă. Tabelul final trebuie construit pe baza statusurilor API-ului concret. Dezavantajul mapării manuale este că, după actualizarea API-ului, aceasta trebuie întreținută: un status nou poate ajunge în handler înainte să apară o regulă pentru el.

Alegeți webhook-uri, polling API sau ambele scheme

Webhook-ul este o cerere de la serviciu către URL-ul dvs. la schimbarea statusului comenzii. Polling-ul API funcționează invers: sistemul dvs. solicită informații despre comandă la un anumit interval. Pentru notificările despre finalizare, de obicei sunt mai comode webhook-urile, deoarece actualizarea vine fără cereri constante către metoda de verificare a statusului.

• Webhook-urile sunt potrivite pentru reacție rapidă: actualizarea fișei, lansarea următoarei etape sau trimiterea unui mesaj către responsabil.
• Polling-ul este potrivit dacă furnizorul nu suportă notificări callback sau serverul nu acceptă cereri externe.
• Schema combinată folosește webhook-urile ca canal principal, iar polling-ul — pentru găsirea comenzilor ratate sau blocate.

Dezavantajul polling-ului este întârzierea și încărcarea suplimentară a API-ului. Dezavantajul webhook-urilor este că endpoint-ul trebuie securizat, duplicatele trebuie luate în considerare și nu trebuie să vă bazați pe ordinea de livrare a evenimentelor.

Configurați endpoint-ul pentru primirea evenimentelor

Pentru notificări este nevoie de o adresă HTTPS publică, accesibilă din partea serviciului API. În setările integrării de obicei se indică URL-ul handler-ului, secretul semnăturii și lista de evenimente: schimbarea statusului, finalizarea, anularea, eroarea sau execuția parțială.

Alocați o rută separată doar pentru evenimentele API. Astfel este mai simplu să configurați jurnalizarea, să limitați accesul, să stabiliți limite de cereri și să nu amestecați traficul de serviciu cu formularele site-ului. Nu folosiți adresa mediului de test pentru comenzile reale: după actualizarea mediului, furnizorul va continua să trimită evenimente către URL-ul salvat.

Înainte de lansare verificați metoda cererii și formatul corpului conform documentației. Cel mai des este POST cu JSON, dar există și form-data, parametri query sau o schemă proprie de serializare. Eroarea de parsare trebuie înregistrată în jurnal, altfel va fi greu să distingeți un payload incorect de o defecțiune a aplicației.

Păstrați legătura dintre comandă și eveniment

La crearea comenzii prin API, salvați identificatorul returnat de furnizor. Alături păstrați numărul intern al comenzii, tipul serviciului, statusul original, ora ultimei modificări și răspunsul original al API-ului într-o formă sigură. Webhook-ul primit trebuie corelat după ID-ul furnizorului, nu după linkul către canal, denumirea serviciului sau numele clientului.

Dacă API-ul permite transmiterea unui identificator extern la creare, adăugați numărul dvs. de comandă într-un câmp precum external_id sau client_reference. Acest lucru simplifică căutarea în loguri și analiza situațiilor controversate. Dar nu faceți din numărul extern singura cheie: unii furnizori nu îl returnează în fiecare notificare.

Nu creați o comandă nouă pe baza unui ID necunoscut din webhook. Evenimentul necunoscut trebuie salvat în jurnal și verificat separat. Crearea automată a unei înregistrări poate duce la date eronate sau la procesarea unei cereri falsificate.

Folosiți o structură clară a payload-ului

Denumirile exacte ale câmpurilor depind de API. Mai jos nu este contractul unui serviciu concret, ci un exemplu de eveniment JSON pe care vă puteți orienta la proiectarea handler-ului intern. Sunt importante identificatorul evenimentului, ID-ul comenzii la furnizor, statusul, ora modificării și datele pentru diagnosticare.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Nu folosiți cantitatea de unități executate ca semn de finalizare fără status. Comanda poate fi executată parțial, iar numărul din payload poate fi rotunjit, actualizat cu întârziere sau deloc transmis. Dezavantajul stocării corpului complet al evenimentului este că acesta poate conține date personale sau câmpuri de serviciu, astfel încât astfel de înregistrări trebuie mascate și limitate ca durată de păstrare.

Verificați semnătura pe baza corpului original al cererii

URL-ul deschis al handler-ului poate primi o cerere nu doar de la serviciul API. Dacă furnizorul transmite o semnătură, un secret sau un token, verificați-le înainte de a modifica comanda. O schemă răspândită este HMAC-SHA256: furnizorul calculează semnătura din octeții corpului cererii și secretul comun, apoi transmite rezultatul într-un header HTTP.

Principiul de calcul este următorul: se ia corpul original al cererii, de exemplu octeții JSON fără modificări, și secretul integrării. Apoi se calculează HMAC-SHA256. Dacă rezultatul în formă hexazecimală coincide cu valoarea din header, corpul nu a fost modificat după semnare și cererea a fost probabil trimisă de o parte care cunoaște secretul.

Exemplu condiționat: HMAC_SHA256(secret, raw_body) = semnătura din header-ul X-Signature. Denumirea header-ului, algoritmul și formatul rezultatului trebuie preluate doar din documentația API. Unele servicii adaugă un timestamp sau ID-ul evenimentului în șirul pentru semnătură. În acest caz nu se poate verifica doar corpul JSON.

Nu modificați JSON înainte de verificarea semnăturii

Semnătura se verifică pe baza octeților originali ai cererii, nu pe baza obiectului JSON pe care aplicația l-a parsat deja și l-a reasamblat. La reserializare se poate schimba ordinea câmpurilor, spațiile, escaparea caracterelor, trecerea la linie nouă sau codificarea. Pentru om JSON-ul va rămâne același, dar setul de octeți se va schimba, iar HMAC nu va mai coincide.

Pentru a evita acest lucru, obțineți mai întâi raw body ca bytes sau buffer, salvați-l în memorie, calculați semnătura și doar după verificarea reușită parsați JSON-ul. Nu aplicați corpului trim, conversie de codificare, sortare a cheilor și formatare. În middleware-ul framework-ului verificați dacă JSON-ul nu este parsat automat înainte de accesarea corpului original.

Dezavantajul acestei scheme este că handler-ul devine dependent de ordinea middleware-ului. Cu o configurare incorectă, aplicația va vedea doar obiectul transformat, iar notificările legitime vor începe să fie respinse.

Exemplu de handler cu verificare HMAC

Mai jos este un exemplu condiționat în Python. El arată ordinea acțiunilor, nu o integrare gata făcută: header-ele, algoritmul, formatul semnăturii și câmpurile payload-ului trebuie înlocuite cu valorile din documentația furnizorului.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Pentru comparație folosiți o funcție care nu se oprește la primul caracter nepotrivit. Aceasta reduce riscul de scurgere a datelor despre semnătură prin timpul de răspuns. Nu transmiteți secretul în codul clientului, nu îl adăugați în URL și nu îl înregistrați integral în loguri.

Faceți procesarea evenimentelor idempotentă

Furnizorul poate livra același eveniment de mai multe ori. Motivele sunt obișnuite: serverul dvs. a răspuns lent, conexiunea s-a întrerupt după salvarea datelor, endpoint-ul a returnat temporar o eroare sau serviciul a lansat o livrare repetată conform propriilor reguli. Repetarea nu înseamnă că API-ul a creat o comandă nouă.

Idempotența înseamnă că un eveniment identic modifică rezultatul o singură dată. Dacă nu țineți cont de această regulă, duplicatul va retrimite mesajul clientului, va crea mai multe sarcini pentru manager, va acorda compensație sau va lansa o operațiune repetată.

Cel mai bine este să folosiți event_id din payload. Salvați-l într-un tabel separat sau într-un jurnal al evenimentelor procesate cu o constrângere de unicitate. Dacă nu există un ID separat, formați cheia din câmpuri stabile: ID-ul comenzii la furnizor, tipul evenimentului, statusul și ora modificării. Această variantă este mai slabă: cu timestamp-uri inexacte, evenimente diferite pot părea identice.

Salvați evenimentul și statusul într-o singură operațiune

Verificarea „a fost procesat evenimentul” și înregistrarea rezultatului trebuie efectuate atomic. Altfel, două cereri identice sosite simultan vor vedea amândouă absența înregistrării și vor lansa acțiunea de două ori. O variantă practică este un index unic pe event_id și o tranzacție a bazei de date.

Continuarea condiționată a handler-ului arată astfel:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Dezavantajul răspunsului cu cod de succes pentru o comandă necunoscută este că furnizorul poate să nu repete livrarea. De aceea, evenimentele necunoscute trebuie monitorizate separat și analizate rapid. Dacă documentația API recomandă un alt cod de răspuns pentru astfel de cazuri, urmați-o.

Luați în considerare încălcarea ordinii evenimentelor

Webhook-urile nu vin întotdeauna strict în ordinea temporală a schimbării statusului. Mai întâi poate sosi evenimentul despre finalizare, iar apoi — notificarea întârziată despre statusul „în lucru”. Dacă pur și simplu înregistrați ultima valoare primită, comanda executată va redeveni activă.

Stabiliți tranzițiile permise. De exemplu, un status intermediar nu poate suprascrie unul final, iar o comandă anulată nu trece în executată fără o verificare separată. Dacă API-ul permite corectarea statusului final, păstrați motivul, valoarea originală și sursa modificării.

Dacă payload-ul conține ora modificării comenzii, comparați exact aceasta, nu ora primirii webhook-ului. Când API-ul nu transmite o astfel de marcă, folosiți prioritățile stărilor și reconcilierea prin metoda de obținere a comenzii. Dezavantajul priorităților este că nu înlocuiesc secvența reală, mai ales dacă furnizorul permite returnarea dintr-un status final.

Confirmați rapid livrarea și mutați acțiunile în coadă

Nu efectuați operațiuni lungi înainte de a răspunde furnizorului. Verificarea semnăturii, căutarea comenzii, înregistrarea evenimentului și actualizarea statusului de obicei pot fi finalizate rapid. Trimiterea mesajului, sincronizarea cu CRM, generarea raportului sau cererile către sisteme terțe este mai bine să fie transmise unei cozi de sarcini.

Ordinea de lucru este următoarea: verificați semnătura, salvați atomic evenimentul și schimbarea statusului, returnați un răspuns de succes, apoi efectuați acțiunile secundare. Dacă răspundeți înainte de salvare, la o defecțiune datele se vor pierde. Dacă răspundeți după o trimitere îndelungată a notificării, furnizorul poate considera livrarea nereușită și poate trimite un duplicat.

Dezavantajul cozii este că apare un component separat care trebuie monitorizat: erori ale sarcinilor, întârzieri și relansări. În schimb, o defecțiune în notificarea managerului nu blochează primirea statusurilor comenzilor.

Configurați notificări pentru echipă și client

După schimbarea statusului nu este nevoie să notificați pe toți la fel. Pentru manager de obicei sunt importante anulările, erorile, execuția parțială și comenzile care nu se schimbă mult timp. Pentru client de cele mai multe ori este suficient un rezultat clar: comanda este executată, anulată sau necesită clarificări.

• Comandă finalizată — actualizare în contul personal sau un mesaj scurt către client.
• Eroare de execuție — notificare către responsabil cu motivul transmis de API.
• Execuție parțială — sarcină de verificare a ajustării, returnării sau a acțiunii următoare.
• Status necunoscut — înregistrare în jurnal și mesaj către specialistul tehnic.
• ID de comandă necunoscut — verificare separată a legăturii dintre sistemul dvs. și furnizor.

Nu trimiteți un mesaj la fiecare tranziție tehnică. Fluxul se va transforma rapid în zgomot, iar o problemă importantă va rămâne neobservată. Notificarea internă trebuie să conțină numărul comenzii, serviciul, statusul curent, ID-ul extern și un link către fișă.

Țineți un jurnal și reconciliați comenzile nefinalizate

Logurile sunt necesare pentru a înțelege dacă serviciul a trimis un eveniment, ce corp a sosit, de ce nu a trecut semnătura și în ce etapă s-a oprit procesarea. Salvați ora primirii, ID-ul evenimentului, ID-ul comenzii, tipul evenimentului, rezultatul verificării semnăturii, statusul intern și codul de răspuns. Mascați secretele, token-urile și datele personale.

Urmăriți separat erorile de livrare, semnăturile invalide, comenzile necunoscute, statusurile nesuportate, duplicatele și evenimentele care nu pot fi aplicate din cauza ordinii stărilor. Creșterea unor astfel de înregistrări poate însemna o schimbare a schemei API, un secret expirat, o defecțiune a rutei sau o eroare în logica handler-ului.

Periodic reconciliați comenzile aflate în statusuri intermediare prin metoda de obținere a datelor API. Această verificare nu înlocuiește webhook-urile, dar ajută la detectarea unui eveniment ratat, a unei defecțiuni a cozii sau a unui caz în care statusul extern s-a schimbat fără o notificare corectă.