Anatomia unei integrări

Lectură estimată: 4 minute

Estimare pentru text, la un ritm de 180 de cuvinte pe minut. Timpul pentru analizarea codului, exerciții și proiecte se adaugă separat și depinde de ritmul tău.

Problema pe care o vei rezolva: Webhook duplicat și timeout

Furnizor fictiv livrează evt-7 de două ori pentru aceeași operație. Înainte de webhook, cererea inițială a expirat și starea locală este necunoscută.

Rezultatul urmărit

Definește stările pending, confirmed și failed, verificarea semnăturii și identificatorul unic. Simulează ambele livrări și reconcilierea stării.

Cum recunoști o soluție corectă

Un singur efect de business este creat. Timeout-ul inițial nu dovedește eșecul definitiv. Semnătura invalidă nu modifică date, iar secretul nu apare în jurnal.

Parcurge lecțiile în ordine și păstrează exercițiile în registrul descărcabil. Ultima lecție include atelierul de 40 de minute în care combini conceptele și testezi o variație a situației inițiale. Exemplele comerciale sunt fictive; nu reprezintă rezultate ale unor clienți.

Aproape orice aplicație modernă vorbește cu servicii externe: plăți (Stripe), email (Postmark), curierat, hărți, SMS, AI. O integrare bună nu înseamnă „am chemat endpointul o dată și a mers" — înseamnă cum se comportă aplicația ta când serviciul celălalt e lent, întoarce o eroare, își schimbă formatul sau te limitează.

Ce citești din documentație, înainte de a scrie cod

Cum te autentifici (cheie, OAuth, semnătură).
Ce limite de rată are (câte cereri pe minut/zi).
Ce coduri de eroare întoarce și ce înseamnă fiecare.
Ce structură are răspunsul (și cum semnalează erorile în corp).
Cum notifică evenimente asincrone (webhooks).
Dacă are un mediu de sandbox pentru teste.

Izolează integrarea

Nu împrăștia apeluri către serviciul extern prin tot codul. Creezi o clasă client (`StripeClient`, `CurierClient`) care e singurul loc care știe de acel serviciu. Restul aplicației vorbește cu clientul tău. Așa poți schimba furnizorul, îl poți testa cu mock-uri, și tratezi erorile într-un singur loc.

Timeout, mereu

Fiecare apel HTTP către un serviciu extern are un timeout explicit (5-15 secunde de obicei). Fără el, dacă serviciul „atârnă", cererea ta atârnă cu el, ținând ocupat un worker.

Gândește la eșec de la început

Pentru fiecare integrare, întreabă: ce se întâmplă dacă apelul eșuează? Blochează utilizatorul? Se poate reîncerca mai târziu (pune-l pe coadă)? Are un fallback? Răspunsul modelează unde pui apelul (sincron în cerere vs. job asincron).

Exercițiu

Alege un serviciu extern pe care l-ai folosi (plăți, email, SMS). Citește-i documentația și notează: metoda de autentificare, limitele de rată, 3 coduri de eroare posibile, dacă are webhooks și sandbox. Schițează o clasă client cu 2-3 metode.

Greșeli frecvente

Apeluri către serviciul extern împrăștiate în controllere și modele.
Fără timeout — o cerere lentă la ei blochează worker-ul tău.
Presupui că apelul reușește mereu — nicio cale de eroare.
Nu citești despre limitele de rată până nu le lovești în producție.

De reținut

Citește documentația: auth, rate limits, erori, format, webhooks, sandbox.
Izolează fiecare integrare într-o clasă client.
Timeout explicit pe fiecare apel.
Proiectează pentru eșec de la început.

Pe scurt

O integrare e cum se comportă aplicația ta când celălalt serviciu are o zi proastă. Izoleaz-o, pune timeout, planifică eșecul.

Contract de integrare înaintea primului apel

O integrare are nevoie de autentificare, scheme de cerere și răspuns, limite, erori și reguli de reluare. Citește documentația endpointului concret și folosește sandboxul când există. Nu conecta o operație reală cu efect financiar doar pentru a verifica formatul. Păstrează identificatorul intern și cel al furnizorului pentru reconciliere. O integrare este completă când poate trata și eșecurile, nu doar un răspuns de succes ales manual.

Exemplu de lucru

Fișă: scop; mediu sandbox; metodă și URL; autentificare; câmpuri obligatorii; statusuri; timeout; idempotență; webhook; log minim; responsabil.
Test minim: succes, validare, acces invalid, limită, timeout, răspuns neașteptat.
Date: numai fictive în laborator.

Interpretarea rezultatului

Un 200 poate conține un status de business care cere altă acțiune, potrivit contractului furnizorului. Nu deduce succesul dintr-un singur câmp fără să verifici documentația. Păstrează adapterul furnizorului separat de regula principală a aplicației.

Exercițiu de consolidare

Completează fișa pentru o integrare de generare AWB fără a executa o expediere reală.

Aplicație practică

Sarcina

Documentează contractul unei integrări de plăți fictive.

Rezolvare orientativă și verificare

Separă cererea inițială, confirmarea server-to-server și starea locală. Folosește sandbox, nu bani reali.

Greșeală de evitat

Redirectul utilizatorului nu este dovadă suficientă a plății.

Documentație și surse

HTTP overview — MDN
OWASP Top 10 — OWASP