# Ampliare le risposte Ridurre il numero di richieste all'API Stripe ampliando gli oggetti nelle risposte Questa guida descrive come richiedere proprietà supplementari all’API. Imparerai a modificare le richieste in modo che le risposte includano: - proprietà di oggetti correlati - proprietà di oggetti con correlazione distante - proprietà supplementari di tutti gli oggetti di un elenco - le proprietà che non sono incluse per impostazione predefinita in una risposta ## Come funziona L’API Stripe è organizzata in risorse rappresentate da oggetti con proprietà di stato, configurazione e contesto. Tutti questi oggetti hanno ID univoci che è possibile utilizzare per recuperarli, aggiornarli ed eliminarli. L’API utilizza anche questi ID per collegare insieme gli oggetti correlati. Una [sessione di checkout](https://docs.stripe.com/api/checkout/sessions/object.md), ad esempio, si collega a un [cliente](https://docs.stripe.com/api/customers/object.md) tramite l '[ID cliente](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer). ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": "cus_HQmikpKnGHkNwW", ... } ``` Qualora tu abbia bisogno di informazioni provenienti da un oggetto collegato, puoi recuperare tale oggetto in una nuova chiamata mediante il suo ID. Tuttavia, questo approccio richiede l’invio all’API di due richieste per accedere a un solo valore. Se hai bisogno di informazioni provenienti da più oggetti collegati, devi inviare una richiesta per ciascuno di essi, il che aumenta la latenza e la complessità dell’applicazione. L’API offre la funzione Expand che consente di recuperare gli oggetti collegati in una singola chiamata, sostituendo l’ID dell’oggetto con tutti i suoi valori e le sue proprietà. Ad esempio, supponiamo che tu voglia accedere ai dettagli di un cliente associati a una determinata sessione di Checkout. Devi recuperare tale sessione e passare la proprietà `customer` alla matrice `expand` per indicare a Stripe di includere nella risposta l’intero oggetto Customer: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" ``` L’esempio sopra restituisce la sessione di Checkout con l’oggetto Customer completo anziché il suo ID: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ..."customer": { "id": "cus_HQmikpKnGHkNwW", "object": "customer", ... "metadata": { "user_id": "user_xyz" }, ... } } ``` > Non tutte le proprietà possono essere ampliate. La documentazione di riferimento dell’API contrassegna le proprietà che possono esserlo con l’etichetta “Ampliabile”. ## Ampliare più proprietà Per ampliare più proprietà in una sola chiamata, aggiungi elementi supplementari alla matrice Expand. Ad esempio, per ampliare entrambi gli oggetti [customer](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer) e [payment_intent](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-payment_intent) per una determinata sessione di Checkout, devi passare alla matrice `expand` entrambe le stringhe `customer` e `payment_intent`: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=customer" \ -d "expand[]=payment_intent" ``` ## Ampliare più livelli Se il valore desiderato è nidificato in profondità in più risorse collegate, puoi raggiungerlo mediante ampliamento ricorsivo utilizzando la notazione con punto. Ad esempio, se vuoi conoscere il tipo di modalità di pagamento utilizzato per una determinata sessione di Checkout, devi prima recuperare il Payment Intent della sessione, quindi la modalità di pagamento ad esso collegata. Con `expand` puoi eseguire questa operazione in una sola chiamata: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=payment_intent.payment_method" ``` L’esempio sopra restituisce la sessione di Checkout con gli oggetti [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) e [PaymentMethod](https://docs.stripe.com/api/payment_methods/object.md) completi anziché i loro ID: ```json { "id": "cs_test_KdjLtDPfAjT1gq374DMZ3rHmZ9OoSlGRhyz8yTypH76KpN4JXkQpD2G0", "object": "checkout.session", ... "mode": "payment","payment_intent": { "id": "pi_1GkXXDLHughnNhxyLlsnvUuY", "object": "payment_intent", "amount": 100, ... "charges": {...}, "client_secret": "pi_1GkXXDLHughnNhxyLlsnvUuY_secret_oLbwpm0ME0ieJ9Aykz2SwKzj5", ... "payment_method": { "id": "pm_1GkXXuLHughnNhxy8xpAdGtf", "object": "payment_method", "billing_details": {...}, "card": {...}, "created": 1589902798, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {}, "type": "card" }, "payment_method_options": {...}, "payment_method_types": [ "card" ], "receipt_email": "jenny.rosen@gmail.com", "review": null, "setup_future_usage": null, "shipping": null, "source": null, "statement_descriptor": null, "statement_descriptor_suffix": null, "status": "succeeded", "transfer_data": null, "transfer_group": null }, "payment_method_types": [ "card" ], "setup_intent": null, "shipping": null, "shipping_address_collection": null, "submit_type": null, "subscription": null, "success_url": "http://localhost:5000" } ``` > Gli ampliamenti hanno una profondità massima di quattro livelli, il che significa che una stringa `expand` non può contenere più di quattro proprietà: `property1.property2.property3.property4`. ## Ampliare le proprietà negli elenchi Quando l’API restituisce un elenco di oggetti, puoi utilizzare la parola chiave `data` per ampliare una determinata proprietà per ogni oggetto di tale elenco. Ad esempio, supponiamo che tu abbia bisogno di informazioni sui metodi di pagamento utilizzati da uno dei tuoi clienti. Per ottenerle, devi creare un [elenco dei PaymentIntent del cliente](https://docs.stripe.com/api/payment_intents/list.md#list_payment_intents-customer), che restituisce un oggetto con la seguente struttura: ```json { "object": "list","data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ..."payment_method": "pm_1GrvBxLHughnNhxyJjtBtHcc", ... }, { "id": "pi_1Grv8tLHughnNhxyflPG4bMG", "object": "payment_intent", "amount": 4000, ..."payment_method": "pm_1Grv9zLHughnNhxyv6uMNomv", ... } ], "has_more": false, "url": "/v1/payment_intents" } ``` > Tutti gli elenchi restituiti nell’API hanno la struttura sopra indicata, dove la proprietà `data` contiene la matrice degli oggetti elencati. Puoi utilizzare la parola chiave `data` in qualsiasi posizione di una stringa Expand per spostare il cursore di ampliamento all’interno dell’elenco. Anziché riprodurre a ciclo continuo ogni Payment Intent dell’elenco e recuperare le modalità di pagamento collegate in chiamate distinte, puoi ampliare tutte le modalità di pagamento contemporaneamente utilizzando la parola chiave `data`: ```curl curl -G https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "expand[]=data.payment_method" ``` L’elenco include quindi l’oggetto modalità di pagamento completo in ciascun Payment Intent: ```json { "object": "list", "data": [ { "id": "pi_1GrvBKLHughnNhxy6N28q8gt", "object": "payment_intent", "amount": 1000, ..."payment_method": { "id": "pm_1GrvBxLHughnNhxyJjtBtHcc", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", ... "country": "US", "exp_month": 2, "exp_year": 2022, "fingerprint": "1212u2LvSFqEHu3h", "funding": "credit", "last4": "4242", ... }, "created": 1591661989, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {...}, "type": "card" }, ... }, { "id": "pi_1Grv8tLHughnNhxyflPG4bMG", "object": "payment_intent", "amount": 4000, ..."payment_method": { "id": "pm_1Grv9zLHughnNhxyv6uMNomv", "object": "payment_method", "billing_details": {...}, "card": { "brand": "visa", "checks": {...}, "country": "US", "exp_month": 2, "exp_year": 2025, "fingerprint": "1212u2LvSFqEHu3h", "funding": "credit", "generated_from": null, "last4": "0341", "three_d_secure_usage": {...}, "wallet": null }, "created": 1591661989, "customer": "cus_HQmikpKnGHkNwW", "livemode": false, "metadata": {...}, "type": "card" }, ... } ], "has_more": false, "url": "/v1/payment_intents" } ``` > L’ampliamento delle risposte ha un impatto sulle prestazioni. Per preservare la velocità delle risposte, prova a limitare il numero di ampliamenti nidificati nelle richieste di elenchi. ## Utilizzo dell’espansione per richiedere le proprietà che possono essere incluse In alcuni casi le risorse hanno proprietà che non sono incluse per impostazione predefinita. La proprietà [line_items](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-line_items) della sessione Checkout rappresenta un buon esempio: essa viene inclusa nelle risposte solo se richiesta mediante il parametro `expand`. Ad esempio: ```curl curl -G https://api.stripe.com/v1/checkout/sessions/{{CHECKOUTSESSION_ID}} \ -u "<>:" \ -d "expand[]=line_items" ``` > Come le altre proprietà ampliabili, la documentazione di riferimento dell’API contrassegna le proprietà che possono essere incluse con l’etichetta “Ampliabile”. ## Utilizzo dell’espansione con i webhook Non puoi ricevere eventi *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) con le proprietà ampliate automaticamente. Gli oggetti inviati negli eventi sono sempre presentati nella loro forma minima. Per accedere ai valori nidificati nelle proprietà ampliabili, devi recuperare l’oggetto con una chiamata distinta nel tuo gestore webhook.