Postes récapitulatifs de factureVersion bêta privée

Comment utiliser les API Invoicing pour grouper et masquer des sous-postes de facture.

Ce guide décrit comment utiliser l’API sous-jacente de postes récapitulatifs de facture (Invoice summary items), qui permet de regrouper des sous-postes de facture. La fonctionnalité de postes récapitulatifs de facture permet de regrouper des sous-postes de facture à l’aide de l’API.

Si vous souhaitez catégoriser et afficher les postes de facture de manière dynamique, consultez la section dédiée au regroupement des sous-postes de facture.

Créer des postes récapitulatifs

Pour un brouillon de facture existant, créez un poste récapitulatif de facture comme décrit ci-dessous. Le poste récapitulatif représente un groupe auquel vous pouvez affecter des postes de facture, et le champ description du poste récapitulatif affiche l’en-tête du groupe pour ces postes de facture.

Par défaut, Stripe affiche tous les postes de facture affectés au poste récapitulatif. Vous pouvez aussi cacher tous les postes de factures affectés au poste récapitulatif et n’afficher que l’en-tête du groupe en définissant display_items=none comme paramètre du poste récapitulatif. Si vous définissez display_items=none, tous les postes de facture affectés au poste récapitulatif seront cachés. Il n’est pas possible de cacher certains postes de factures spécifiques sans en cacher d’autres, sauf si le poste de facture est de 0 USD (pour en savoir plus, consultez la section Cacher les postes de facture de 0 $ individuels).

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/summary_items \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d description="Summary item 1" \
  -d display_items="none"

Pour éviter de créer chaque poste récapitulatif l’un après l’autre, vous pouvez les créer en groupe via les endpoints de création ou de mise à jour de facture. L’exemple de code ci-dessous permet de créer un brouillon de facture avec deux postes récapitulatifs vides.

Command Line
curl https://api.stripe.com/v1/invoices \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "rendering[summary_items_data][0][description]"="Summary item 1" \
  -d "rendering[summary_items_data][0][display_items]"="none" \
  -d "rendering[summary_items_data][1][description]"="Summary item 2" \
  -d "expand[]"="rendering.summary_items"

Pensez à développer rendering.summary_items pour voir la liste des postes récapitulatifs dans la réponse.

Affecter un poste récapitulatif

Maintenant que la facture contient des postes récapitulatifs vides (en partant du principe que la facture contient des postes de facture), nous pouvons affecter un poste récapitulatif au poste de facture.

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/lines/{{INVOICE_LINE_ITEM_ID}} \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "rendering[summary_item]"={{SUMMARY_ITEM_ID}}

Vous pouvez modifier le poste récapitulatif auquel le poste de facture appartient, ou vous pouvez dégrouper le poste de facture en utilisant le même endpoint.

Mettre à jour des postes récapitulatifs

En utilisant l’endpoint de mise à jour de facture, vous pouvez réorganiser, supprimer ou modifier les postes récapitulatifs. Par exemple, dans le code ci-dessous, l’ordre du premier et du deuxième poste récapitulatif est inversé.

Command Line
curl https://api.stripe.com/v1/invoices \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "rendering[summary_items_data][0][id]"="{{SUMMARY_ITEM_2_ID}}" \
  -d "rendering[summary_items_data][1][id]"="{{SUMMARY_ITEM_1_ID}}" \
  -d "expand[]"="rendering.summary_items"

Pour supprimer tout poste récapitulatif existant d’une facture, utilisez le même endpoint pour réinitialiser le champ rendering[summary_items_data] comme ci-après :

Command Line
curl https://api.stripe.com/v1/invoices \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "rendering[summary_items_data]"="" \
  -d "expand[]"="rendering.summary_items"

Lorsque vous supprimez les postes récapitulatifs, tous les postes de facture associés ne sont plus regroupés.

Vous pouvez aussi supprimer un seul poste récapitulatif comme ci-après :

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/summary_items/{{SUMARY_ITEM_ID}} \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -x DELETE

Cacher les postes de facture de 0 $ individuels

L’API permet aussi de cacher des postes de facture de 0 $ individuels. Vous pouvez définir rendering[display]=hidden_if_zero pour un poste de facture spécifique, comme ci-après :

Command Line
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}
/lines/{{INVOICE_LINE_ITEM_ID}} \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "rendering[display]"= "hidden_if_zero"

Puis, si le poste de facture est de 0 USD, il est automatiquement caché là où le client voit la facture.