Stripe API: introduzione REST
Le API REST di Stripe sono il cuore della piattaforma: ogni feature è esposta come endpoint HTTP standard con autenticazione semplice e payload JSON. Sono progettate per essere chiare, prevedibili e ben documentate.
Struttura delle API
Stripe usa REST con verbi HTTP standard (GET, POST, DELETE), URL gerarchici (es. /v1/customers/{id}/sources) e JSON sia in input sia in output. L'autenticazione è basic auth con la secret key come username (password vuota). Tutte le risorse hanno un'id univoco, oggetti annidati e timestamp Unix per le date.
Paginazione, idempotency e versioning
Le liste sono paginate con cursor-based pagination (parametri limit, starting_after, ending_before). Per evitare duplicati su retry usa l'header Idempotency-Key con un'UUID univoco per ogni chiamata di creazione. Le versioni API sono pinned per account (es. 2024-04-10); upgradi quando vuoi per ottenere nuove feature senza breaking change.
Expand parameter e response shaping
Il parametro 'expand' permette di espandere oggetti collegati in una singola chiamata: invece di chiamare /v1/charges/{id} e poi /v1/customers/{id}, usa /v1/charges/{id}?expand[]=customer per ottenere il customer object embedded. Si possono espandere fino a 4 livelli di profondita' (es. expand[]=customer.default_source). Riduce drasticamente il numero di round-trip API e migliora performance. Funziona su tutti gli endpoint e su tutti i field id-based. Limite: l'expand impatta latency della singola chiamata, valutato il trade-off rispetto a caching client-side.
Restricted API key e principio least-privilege
Le restricted key sono chiavi API con scope limitato (es. solo read su charges, no access a Connect, no write su customers). Crea una restricted key dedicata per ogni microservizio o integrazione esterna (es. analytics tool, accounting integration). Se la chiave viene compromessa, l'impatto è limitato allo scope concesso. Crea le chiavi in Developers -> API keys -> Create restricted key, seleziona le risorse e i permessi (None/Read/Write). Best practice: una restricted key per uso, mai key condivise tra ambienti o team.
Versioning API e migration guide
Stripe rilascia nuove versioni API trimestralmente (es. 2024-04-10, 2024-06-20, 2024-09-30). Ogni versione include changelog dettagliato con: breaking change, new feature, deprecation. Il tuo account ha un 'default API version' (Settings -> API version), modificabile manualmente. Best practice: pin apiVersion negli SDK per evitare surprise upgrade. Quando vuoi upgrade: leggi changelog, identifica breaking change applicabili, test in Sandbox con nuova version, deploy graduale (canary). Versioni vecchie (oltre 1 anno) restano supportate ma con limitate new feature.
Status page e incident response
Status page Stripe (status.stripe.com) mostra real-time disponibilità' di ogni service: Payments API, Webhooks Delivery, Dashboard, Connect, Issuing, Terminal. Subscribe a email/Slack notification per essere alerted in 1-2 minuti su incident. Per business mission-critical, implementa circuit breaker: se Stripe API timeout > threshold, mostra messaggio cliente 'pagamento temporaneamente non disponibile, riprova in 5 minuti'. Buffer queue per webhook in caso di problemi tuo endpoint (Stripe ritenta per 3 giorni ma è meglio prepararsi). Disaster recovery: dual provider con failover automatico per merchant enterprise.
Documentation e developer experience
Stripe è famoso tra developer per la qualità della documentazione: docs.stripe.com offre tab multi-lingua (PHP/Node/Python/Ruby/Go/Java/.NET) sincronizzate, esempi runnable inline, search-as-you-type rapida, dark mode supportato. Sezioni chiave: API Reference (per ogni endpoint), Guides (best practice tematiche), Tutorials (step-by-step per use case comuni), Changelog (cronologia API version). Stripe ha anche stripe.com/docs/developer-tools con CLI, Postman collection, VS Code extension. Le risorse migliori per developer junior: getting started guides + tutorials. Per senior: API reference + advanced guides. La quality docs riduce time-to-integration vs concorrenti del 50-70%.
Stripe Apps e marketplace developer
Stripe Apps (lanciato 2022) permette di estendere Stripe Dashboard con app custom installate dal marketplace: tab dedicato in Dashboard, accesso API con scope ristretto, UI nativa Stripe. Casi d'uso: integration con ERP/accounting (Quickbooks, Xero), CRM sync (HubSpot, Salesforce), analytics tool, refund automation, customer service helper. Per dev che vogliono build SaaS sopra Stripe ecosystem, Apps è canale di distribuzione efficace - Stripe marketplace ha alto qualified traffic merchant Stripe-customer. Per merchant è zero-friction install (no setup OAuth complicato). Trend in crescita: Stripe Apps marketplace conta 100+ app pubblicate.
Procedura passo-passo
- Recupera la secret key da Dashboard -> Developers -> API keys.
- Configura un client HTTP (curl, axios, requests) con basic auth header.
- Fai la prima chiamata: GET https://api.stripe.com/v1/balance per verificare connettività.
- Crea un Customer: POST /v1/customers con email come campo principale.
- Crea un PaymentIntent: POST /v1/payment_intents con amount, currency e customer.
- Aggiungi Idempotency-Key UUID per ogni POST per evitare duplicati.
- Implementa paginazione lato server con starting_after per scan completi.
- Gestisci errori HTTP (400, 401, 402, 429, 500) con retry e backoff.
Errori comuni e come risolverli
- Mancanza Idempotency-Key: retry crea duplicati; aggiungi sempre per POST critici.
- Hardcode versione API: non upgradare a forza vincola alle feature vecchie; pin via Dashboard.
- Errori 429 ignorati: rate limit raggiunto; implementa exponential backoff.
- Body x-www-form-urlencoded errato: Stripe accetta form-encoded, non JSON nativo; usa la libreria ufficiale.
Domande frequenti
D: Stripe API usa JSON o form-encoded?
R: Accetta form-encoded in input ma restituisce JSON; gli SDK gestiscono tutto.
D: Qual è il rate limit?
R: 100 read/sec e 100 write/sec di default; più alto in Live mode.
D: Posso usare le API senza SDK?
R: Sì, sono REST standard; SDK semplifica auth, retry e tipizzazione.
D: Come testo le API?
R: Usa Test mode con sk_test_ keys e carte di test.
Hai bisogno di aiuto?
Se vuoi integrare Stripe con il team di G Tech Group, scrivici tramite il modulo di contatto.