# Résoudre les adresses fiscales Valider la précision de l’adresse avant de calculer les taxes. Stripe Tax calcule les taux de taxe en fonction de l’adresse des clients, mais certaines adresses ne contiennent pas suffisamment de détails pour déterminer un taux exact. Par exemple, un code postal aux États-Unis peut s’étendre sur plusieurs juridictions fiscales. Stripe Tax peut donc donner une approximation plutôt que de le taux exact pour cette adresse. Utilisez l’API Address Resolution pour vérifier avec quelle précision Stripe Tax peut déterminer le taux de taxe pour une adresse donnée avant de l’utiliser dans un calcul fiscal. L’API renvoie : - Le niveau de précision avec lequel Stripe Tax peut déterminer le taux de taxe pour l’adresse - Les champs d’adresse à collecter ou à mettre à jour pour que Stripe Tax puisse déterminer un taux de taxe plus précis L’API Address Resolution est en version bêta privée. Fournissez votre adresse e-mail pour qu’elle soit ajoutée à la liste d’attente. Nous reviendrons vers vous pour confirmer si vous êtes admissible et partager les instructions d’onboarding. Si vous avez déjà un compte Stripe, connectez-vous avant de vous inscrire. ## Avant de commencer [Configurez Stripe Tax](https://docs.stripe.com/tax/set-up.md) et configurez vos paramètres fiscaux. ## Résoudre une adresse ### Faire une requête `POST /v2/taxer/address_resolution` ```json { "address": { "country": "US", "state": "CA", "city": "South San Francisco", "postal_code": "94080", "line1": "354 Oyster Point Blvd" } } ``` ### Réponse ```json { "object": "v2.tax.address_resolution", "livemode": false, "precision": "address", "precision_details": { "issues": [] }, "address": { "country": "US", "state": "CA", "city": "South San Francisco", "postal_code": "94080", "line1": "354 Oyster Point Blvd" } } ``` ## Comprendre les niveaux de précision Le champ `precision` vous indique avec quel niveau de détail Stripe Tax peut déterminer le taux de taxe lorsqu’il calcule les taxes pour une adresse donnée. Les niveaux de précision du plus élevé au plus bas sont : | Précision | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | Nous pouvons déterminer le taux de taxe pour une adresse spécifique. Le niveau de détail le plus élevé, et uniquement disponible aux États-Unis. | | `street` | Nous pouvons déterminer le taux de taxe d’une rue. Pour certaines adresses, il s’agit du niveau de détail le plus élevé. | | `postal_code` | Nous pouvons déterminer le taux de taxe pour une zone de code postal. Habituellement, ce niveau conduit à des approximations du taux de taxe aux États-Unis. | | `city` | Nous pouvons déterminer le taux de taxe pour une zone au niveau de la ville. | | `state` | Nous pouvons déterminer le taux de taxe d’un État ou d’une province. Pour des pays comme le Canada et l’Inde, il s’agit du niveau de détail le plus élevé disponible. | | `country` | Nous pouvons déterminer le taux de taxe d’un pays. Pour la plupart des pays hors Amérique du Nord, un taux de taxe unique s’applique à l’échelle nationale. | | `none` | L’adresse ne contient pas suffisamment d’informations pour déterminer un taux de taxe. | Si `precision` a une valeur autre que `none`, nous pouvons utiliser l’adresse pour calculer les taxes. Cependant, un niveau de détail plus faible (moins de précision) peut conduire à un taux de taxe approximatif alors qu’un taux plus précis existe pour cet emplacement. ### Comment la précision est liée à l’exactitude fiscale Le signal clé est la combinaison de `precision` et de `precision_details.issues` : - **Tableau `issues` vide** : Stripe Tax détermine le taux de taxe le plus précis possible pour cette adresse. Il n’y a aucune information supplémentaire que vous pouvez collecter auprès du client pour obtenir un taux plus précis. Par exemple, une adresse aux États-Unis dont la précision est définie sur `street` et ne comportant aucun problème signifie que chaque adresse de cette rue possède le même taux de taxe. - **Tableau `issues` non vide** : un taux de taxe plus précis peut exister pour cet emplacement, mais l’adresse saisie n’a pas assez de détails pour le déterminer. Collectez ou mettez à jour les champs répertoriés dans `issues` pour améliorer la précision. ### Meilleure précision par pays Le nombre d’informations disponibles pour déterminer les taux de taxe varie d’un pays à l’autre. Une fois que l’adresse est la plus précise selon les paramètres de son pays, le tableau `issues` est vide : | Pays | Meilleure précision | Champs obligatoires | | ----------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | États-Unis | `address` | `country`, `state`, `city`, `postal_code`, `line1` | | Canada | `state` | `country`, et `state` ou `postal_code` | | Inde | `state` | `country`, et `state` ou `postal_code` | | Espagne | `state` | `country`, et `state` ou `postal_code` (pour les îles Canaries et Ceuta, dans le reste de l’Espagne, la précision de niveau `country` suffit) | | Autres pays | `country` | `country` | ## Collecter les champs manquants présentant des problèmes Lorsqu’un taux de taxe plus précis existe mais que l’adresse ne dispose pas de suffisamment de détails pour le déterminer, le tableau `precision_details.issues` vous indique les champs à collecter auprès du client. Chaque problème possède : - `field` : le champ de l’adresse à collecter ou à mettre à jour (`line1`, `city`, `postal_code`, `state` ou `country`). - `code` : le type de problème. À l’heure actuelle, la seule valeur est `required_for_improved_precision`, ce qui indique que le fait de renseigner ce champ peut permettre à Stripe Tax de déterminer un taux de taxe plus précis. Par exemple, la résolution d’une adresse aux États-Unis avec uniquement un code postal renvoie une précision `postal_code` avec des problèmes pour les champs manquants : ```json // Request {"address": {"country": "US", "postal_code": "94080"}} ``` ```json // Response { "precision": "postal_code", "precision_details": { "issues": [ {"field": "city", "code": "required_for_improved_precision"}, {"field": "line1", "code": "required_for_improved_precision"} ] }, "address": { "country": "US", "postal_code": "94080" } } ``` Lorsque `precision_details.issues` est vide, l’adresse donne le taux de taxe le plus précis que Stripe Tax peut déterminer pour cet emplacement. Vous n’avez pas besoin de collecter d’informations supplémentaires auprès du client. ## Valider les adresses dans votre intégration Le flux typique pour utiliser la résolution d’adresse dans votre intégration est le suivant : 1. Collectez une adresse auprès de votre client. 1. Appelez l’API Address Resolution pour vérifier la précision. 1. Si `precision_details.issues` contient des entrées, invitez le client à fournir ou à mettre à jour les champs listés. Cela signifie qu’un taux de taxe plus précis est disponible si le client fournit plus de détails sur l’adresse. 1. Lorsque `precision_details.issues` est vide, l’adresse fournit le taux de taxe le plus précis possible. ### Valider avant de créer un client Résolvez d’abord l’adresse. Si `precision` est défini sur `none`, nous ne pouvons pas utiliser l’adresse pour calculer les taxes. Si `precision_details.issues` est vide, le taux de taxe est aussi précis que possible et vous pouvez créer le client. ```json // Request POST /v2/tax/address_resolution { "address": { "country": "US", "state": "CA", "city": "South San Francisco", "postal_code": "94080", "line1": "354 Oyster Point Blvd" } } ``` ```json // Response — precision_details.issues is empty, so the tax rate is as accurate as possible { "precision": "address", "precision_details": { "issues": [] }, "address": { "country": "US", "state": "CA", "city": "South San Francisco", "postal_code": "94080", "line1": "354 Oyster Point Blvd" } } ``` Si la réponse contient des problèmes, invitez le client à renseigner les champs manquants avant de créer le client : ```json // Response — issues present, a more precise tax rate is available { "precision": "postal_code", "precision_details": { "issues": [ {"field": "city", "code": "required_for_improved_precision"}, {"field": "line1", "code": "required_for_improved_precision"} ] }, "address": { "country": "US", "postal_code": "94080" } } ``` ### Valider une adresse d’origine du commerçant Vous pouvez valider votre propre adresse d’origine avant de configurer vos [paramètres fiscaux](https://docs.stripe.com/tax/settings-api.md). ```json // Request POST /v2/tax/address_resolution { "address": { "country": "US", "state": "FL", "city": "Fort Lauderdale", "postal_code": "33301", "line1": "433 NE 8th Ave" } } ``` ```json // Response — no issues, safe to use as your origin address { "precision": "address", "precision_details": { "issues": [] }, "address": { "country": "US", "state": "FL", "city": "Fort Lauderdale", "postal_code": "33301", "line1": "433 NE 8th Ave" } } ``` ## Exemples spécifiques par pays ### États-Unis Pour les adresses aux États-Unis, la meilleure précision disponible est `address`. Les taux de taxe aux États-Unis peuvent varier jusqu’au niveau de l’adresse. Ainsi, fournir tous les champs produit le taux de taxe le plus précis. Une adresse partielle renvoie une précision moindre avec des problèmes, indiquant qu’un taux de taxe plus précis pourrait exister : ```json // Request {"address": {"country": "US", "state": "FL", "postal_code": "32789"}} ``` ```json // Response { "precision": "postal_code", "precision_details": { "issues": [ {"field": "city", "code": "required_for_improved_precision"}, {"field": "line1", "code": "required_for_improved_precision"} ] }, } ``` Une adresse aux États-Unis avec uniquement l’État et sans code postal renvoie une précision `none`, car les champs minimum requis pour une adresse aux États-Unis ne sont pas remplis : ```json // Request {"address": {"country": "US", "state": "FL"}} ``` ```json // Response { "precision": "none", "precision_details": { "issues": [ {"field": "city", "code": "required_for_improved_precision"}, {"field": "postal_code", "code": "required_for_improved_precision"}, {"field": "line1", "code": "required_for_improved_precision"} ] } } ``` ### Canada Nous déterminons les taux de taxe pour les adresses canadiennes au niveau de la province. La meilleure précision disponible est donc `state`. Lorsque vous fournissez l’État ou le code postal, le tableau `issues` est vide car le taux de taxe est aussi précis qu’il peut l’être : ```json // Request {"address": {"country": "CA", "postal_code": "T2P 2P2"}} ``` ```json // Response { "precision": "state", "precision_details": { "issues": [] }, } ``` Le fait de fournir uniquement le pays renvoie une précision de niveau `country` avec des problèmes. Le Canada ayant des taux de taxe différents selon les provinces, le tableau `issues` vous indique de collecter un code d’État ou postal pour déterminer le bon taux provincial : ```json // Request {"address": {"country": "CA"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [ {"field": "state", "code": "required_for_improved_precision"}, {"field": "postal_code", "code": "required_for_improved_precision"} ] }, } ``` ### Espagne L’Espagne a des régions autonomes (îles Canaries et Ceuta) avec des taux de taxe différents de ceux de l’Espagne continentale. Lorsque l’adresse se résout à l’une de ces régions, la précision est au niveau `state` avec un tableau `issues` vide, ce qui signifie que le taux de taxe est aussi précis que possible : ```json // Request {"address": {"country": "ES", "postal_code": "38003"}} ``` ```json // Response { "precision": "state", "precision_details": { "issues": [] }, } ``` Lorsque l’adresse aboutit à une région dont l’état est connu (par exemple, Malaga), la précision correspond au niveau `country` et le tableau `issues` est vide. Cela signifie que le taux de taxe national s’applique et qu’aucune information supplémentaire sur l’adresse ne mènera à un taux différent : ```json // Request {"address": {"country": "ES", "state": "MA"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [] }, } ``` Lorsque vous fournissez uniquement le pays, le tableau `issues` suggère de collecter `state` ou `postal_code`. En effet, l’API ne peut pas déterminer si le client se trouve ou non dans une région autonome avec un taux de taxe différent sans plus de détails : ```json // Request {"address": {"country": "ES"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [ {"field": "state", "code": "required_for_improved_precision"}, {"field": "postal_code", "code": "required_for_improved_precision"} ] }, } ``` Lorsque vous fournissez un code postal sans l’État, le tableau `issues` suggère toujours de collecter le champ `state` car l’API ne peut pas valider si le code postal pointe vers une région autonome : ```json // Request {"address": {"country": "ES", "postal_code": "29001"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [ {"field": "state", "code": "required_for_improved_precision"} ] }, } ``` ### Autres pays La plupart des pays appliquent un taux de taxe unique sur l’ensemble de leur territoire. Pour ces pays, fournir uniquement le code de pays produit le taux de taxe le plus précis. Le tableau `issues` vide confirme qu’il n’y a pas de taux plus précis à déterminer : ```json // Request {"address": {"country": "DE", "postal_code": "12345"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [] }, } ``` ## Limites - **`line2` n’est pas pris en charge** : le moteur Stripe Tax n’utilise pas `line2` pour déterminer le taux de taxe, donc l’API ne l’accepte pas. - **Les garanties de précision s’appliquent uniquement au moteur Stripe Tax** : si vous utilisez un moteur de calcul fiscal tiers, les niveaux de précision de cette API ne garantissent pas les mêmes résultats. - **Des limites de débit quotidiennes s’appliquent.** L’API impose des limites d’utilisation quotidiennes en mode production comme en mode test. Contactez le [service de support Stripe](https://support.stripe.com/) si vous atteignez les limites d’utilisation. ## Étapes suivantes - [Collecter les adresses des clients](https://docs.stripe.com/tax/customer-locations.md) pour comprendre comment Stripe Tax utilise ses adresses pour les calculs. - [Calculer les taxes avec l’API Tax](https://docs.stripe.com/tax/custom.md) pour utiliser des adresses validées dans les calculs fiscaux.