# Steueradressen auflösen Überprüfen Sie die Genauigkeit der Adresse, bevor Sie die Steuer berechnen. Stripe Tax berechnet Steuersätze auf der Grundlage von Kundenadressen, doch manche Adressen enthalten nicht genügend Angaben, um einen genauen Steuersatz zu ermitteln. Beispielsweise kann eine Postleitzahl in den USA steuerliche Zuständigkeitsbereiche umfassen, sodass Stripe Tax den Steuersatz eher schätzen als den genauen Steuersatz für diese Adresse berechnen könnte. Verwenden Sie die Address Resolution API, um zu überprüfen, wie genau Stripe Tax den Steuersatz für eine bestimmte Adresse ermitteln kann, bevor Sie diese in einer Steuerberechnung verwenden. Die API gibt Folgendes zurück: - Die Genauigkeit, mit der Stripe Tax den Steuersatz für die jeweilige Adresse ermitteln kann - Die Adressfelder, die erfasst oder aktualisiert werden müssen, damit Stripe Tax einen genaueren Steuersatz ermitteln kann {% collect-email list=“address-resolution-waitlist@stripe.com” send_direct_email=true intro_text=“Möchten Sie frühzeitig Zugang zur Address Resolution API erhalten?” form_cta_text=“Absenden” success_text="Vielen Dank! Wir melden uns in Kürze bei Ihnen.“ show_email_confirmation=true %} Die Address Resolution API befindet sich in der privaten Vorschau. Geben Sie Ihre E-Mail-Adresse an, um in die Warteliste aufgenommen zu werden. Wir werden uns bei Ihnen melden, um zu bestätigen, ob Sie teilnahmeberechtigt sind, und Ihnen Anweisungen zur Einrichtung zukommen lassen. Wenn Sie bereits über ein Stripe-Konto verfügen, melden Sie sich bitte an, bevor Sie sich registrieren. ## Bevor Sie beginnen [Richten Sie Stripe Tax ein](https://docs.stripe.com/tax/set-up.md) und nehmen Sie Ihre Steuereinstellungen vor. ## Eine Adresse auflösen ### Anfrage `POST /v2/tax/address_resolution` ```json { "address": { "country": "US", "state": "CA", "city": "South San Francisco", "postal_code": "94080", "line1": "354 Oyster Point Blvd" } } ``` ### Antwort ```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" } } ``` ## Wissenswertes über Genauigkeitsstufen Das Feld `Genauigkeit` gibt an, mit welcher Detailgenauigkeit Stripe Tax den Steuersatz bei der Steuerberechnung für die angegebene Adresse ermitteln kann. Die Genauigkeitsstufen, von der höchsten bis zur niedrigsten Detailgenauigkeit, sind: | Genauigkeit | Beschreibung | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | Wir können den Steuersatz für eine bestimmte Adresse ermitteln. Dies ist die detaillierteste Angabe und nur in den USA verfügbar. | | `street` | Wir können den Steuersatz für eine Straße ermitteln. Für manche Adressen ist dies die höchste Detailstufe. | | `postal_code` | Wir können den Steuersatz für ein Postleitzahlengebiet ermitteln. In den USA führt diese Ebene in der Regel zu Steuersatzschätzungen. | | `city` | Wir können den Steuersatz für ein Gebiet auf Stadtebene ermitteln. | | `state` | Wir können den Steuersatz für einen Bundesstaat oder eine Provinz ermitteln. Für Länder wie Kanada und Indien ist dies die höchste verfügbare Detailstufe. | | `country` | Wir können den Steuersatz für ein Land ermitteln. Für die meisten Länder außerhalb Nordamerikas gilt landesweit ein einheitlicher Steuersatz. | | `none` | Die Adresse enthält nicht genügend Informationen, um einen Steuersatz zu ermitteln. | Wenn die `precision` nicht `none` ist, können wir die Adresse für Steuerberechnungen verwenden. Eine geringere Detailgenauigkeit (geringere Genauigkeit) kann jedoch dazu führen, dass ein ungefährer Steuersatz verwendet wird, obwohl für diesen Standort ein genauerer Steuersatz vorliegt. ### Inwiefern hängt Genauigkeit mit Steuergenauigkeit zusammen? Das Schlüsselsignal ist die Kombination aus `precision` und `precision_details.issues`: - **Leeres Array `issues`**: Stripe Tax ermittelt den genauestmöglichen Steuersatz für diese Adresse. Es gibt keine weiteren Informationen, die Sie vom Kunden einholen könnten, um einen präziseren Steuersatz zu erhalten. Wenn beispielsweise eine Adresse in den USA auf `Straßenebene` ohne „issues“ angegeben wird, bedeutet dies, dass für jede Adresse in dieser Straße derselbe Steuersatz gilt. - **Nicht leeres Array `issues`**: Möglicherweise gibt es für diesen Standort einen genaueren Steuersatz, doch die eingegebene Adresse enthält nicht genügend Angaben, um diesen zu ermitteln. Bitte erfassen oder aktualisieren Sie die in `issues` aufgeführten Felder, um die Genauigkeit zu verbessern. ### Höchste Genauigkeit nach Ländern Die Anzahl der verfügbaren Angaben zur Ermittlung der Steuersätze variiert je nach Land. Sobald die Adresse die für das jeweilige Land höchstmögliche Genauigkeit erreicht hat, ist das Array `issues` leer: | Land | Höchste Genauigkeit | Erforderliche Felder | | ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | USA | `address` | `country`, `state`, `city`, `postal_code`, `line1` | | Kanada | `state` | `country` und `state` oder `postal_code` | | Indien | `state` | `country` und `state` oder `postal_code` | | Spanien | `state` | `country` und `state` oder `postal_code` (für die Kanarischen Inseln und Ceuta; im übrigen Spanien reicht eine Genauigkeit von `country` aus) | | Andere Länder | `country` | `country` | ## Fehlende Felder mit Hinweisen erfassen Wenn ein genauerer Steuersatz vorliegt, die Adresse jedoch nicht detailliert genug ist, um diesen zu ermitteln, gibt das Array `precision_details.issues` an, welche Angaben Sie von den Kundinnen und Kunden einholen müssen. Jeder Eintrag enthält: - `field`: Das Adressfeld zum Erfassen oder Aktualisieren von (`line1`, `city`, `postal_code`, `state` oder `country`). - `code`: Die Art des Problems. Derzeit ist der einzige Wert `required_for_improved_precision`, was bedeutet, dass die Angabe dieses Feldes es Stripe Tax ermöglichen könnte, einen genaueren Steuersatz zu ermitteln. Wird beispielsweise eine Adresse in den USA nur anhand der Postleitzahl aufgelöst, liefert die Genauigkeit `postal_code` Fehlermeldungen wegen fehlender Felder: ```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" } } ``` Wenn `precision_details.issues` leer ist, liefert die Adresse den genauesten Steuersatz, den Stripe Tax für diesen Standort ermitteln kann. Sie müssen keine weiteren Informationen von den Kundinnen und Kunden einholen. ## Adressen in Ihrer Integration validieren Der typische Ablauf für die Verwendung der Adressauflösung in Ihrer Integration ist wie folgt: 1. Erfassen Sie die Adresse Ihres Kunden. 1. Rufen Sie die Address Resolution API auf, um die Genauigkeit zu überprüfen. 1. Wenn `precision_details.issues` Einträge enthält, bitten Sie den Kunden bzw. die Kundin, die aufgeführten Felder auszufüllen oder zu aktualisieren. Das bedeutet, dass ein genauerer Steuersatz ermittelt werden kann, wenn der Kunde oder die Kundin detailliertere Adressangaben macht. 1. Wenn `precision_details.issues` leer ist, liefert die Adresse den genauesten möglichen Steuersatz. ### Vor der Erstellung eines Kunden oder einer Kundin überprüfen Überprüfen Sie zunächst die Adresse. Wenn `precision` auf `none` gesetzt ist, können wir die Adresse nicht für Steuerberechnungen verwenden. Wenn `precision_details.issues` leer ist, ist der Steuersatz so genau wie möglich, und Sie können den Kunden oder die Kundin anlegen. ```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" } } ``` Falls die Antwort Unvollständigkeiten enthält, bitten Sie die Kundinnen und Kunden, die fehlenden Angaben zu ergänzen, bevor Sie die Kundinnen und Kunden anlegen: ```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" } } ``` ### Überprüfen Sie die Absenderadresse eines Händlers bzw. einer Händlerin Sie können Ihre eigene Absenderadresse überprüfen, bevor Sie Ihre [Steuereinstellungen](https://docs.stripe.com/tax/settings-api.md) konfigurieren. ```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" } } ``` ## Länderspezifische Beispiele ### USA Bei Adressen in den USA ist die bestmögliche Genauigkeit die `address`. Da die Steuersätze in den USA bis auf die Ebene der Straßenadresse variieren können, liefert die Angabe aller Felder den genauesten Steuersatz. Eine unvollständige Adresse führt zu einer geringeren Genauigkeit und weist auf mögliche Probleme hin, was darauf hindeutet, dass möglicherweise ein genauerer Steuersatz vorliegt: ```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"} ] }, } ``` Eine Adresse in den USA, die nur den Bundesstaat und keine Postleitzahl enthält, liefert die Genauigkeitsstufe `none`, da die Mindestanforderungen an die Pflichtfelder für eine US-Adresse nicht erfüllt sind: ```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"} ] } } ``` ### Kanada Wir ermitteln Steuersätze für kanadische Adressen auf Provinzebene. Die bestmögliche Genauigkeit ist die Ebene des `state`. Wenn Sie den Bundesstaat oder die Postleitzahl angeben, ist das Array `issues` leer, da der Steuersatz bereits so genau wie möglich ist: ```json // Request {"address": {"country": "CA", "postal_code": "T2P 2P2"}} ``` ```json // Response { "precision": "state", "precision_details": { "issues": [] }, } ``` Die Angabe nur des Landes liefert Ergebnisse mit der Genauigkeit `country`, was zu Problemen führt. Da in Kanada die Steuersätze je nach Provinz unterschiedlich sind, weist das Array `issues` darauf hin, dass Sie eine Provinz oder eine Postleitzahl erfassen müssen, um den korrekten Provinzsteuersatz zu ermitteln: ```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"} ] }, } ``` ### Spanien Spanien verfügt über autonome Regionen (Kanarische Inseln und Ceuta), in denen andere Steuersätze gelten als auf dem spanischen Festland. Wenn die Adresse auf eine dieser Regionen hinweist, lautet die Genauigkeitsangabe `state` mit einem leeren Array `issues`, was bedeutet, dass der Steuersatz so genau wie möglich angegeben ist: ```json // Request {"address": {"country": "ES", "postal_code": "38003"}} ``` ```json // Response { "precision": "state", "precision_details": { "issues": [] }, } ``` Wenn die Adresse auf eine Region mit bekanntem Status (z. B. Málaga) zurückgeführt wird, ist die Genauigkeit `country` und das Array `issues` ist leer. Das bedeutet, dass der nationale Steuersatz gilt und keine weiteren Adressangaben zu einem anderen Steuersatz führen: ```json // Request {"address": {"country": "ES", "state": "MA"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [] }, } ``` Wenn Sie nur das Land angeben, schlägt das Array `issues` vor, den `state` oder `postal_code` zu erfassen. Der Grund dafür ist, dass die API ohne weitere Angaben nicht feststellen kann, ob sich der Kunde bzw. die Kundin in einer autonomen Region mit einem anderen Steuersatz befindet oder nicht: ```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"} ] }, } ``` Wenn Sie eine Postleitzahl ohne Bundesstaat angeben, schlägt das Array `issues` stets vor, das Feld `state` zu erfassen, da die API nicht überprüfen kann, ob die Postleitzahl einer autonomen Region zugeordnet ist: ```json // Request {"address": {"country": "ES", "postal_code": "29001"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [ {"field": "state", "code": "required_for_improved_precision"} ] }, } ``` ### Andere Länder Die meisten Länder wenden auf ihrem gesamten Staatsgebiet einen einheitlichen Steuersatz an. Für diese Länder ergibt sich der genaueste Steuersatz, wenn lediglich die Länderkennung angegeben wird. Das leere Array `issues` bestätigt, dass kein genauerer Steuersatz ermittelt werden kann: ```json // Request {"address": {"country": "DE", "postal_code": "12345"}} ``` ```json // Response { "precision": "country", "precision_details": { "issues": [] }, } ``` ## Einschränkungen - **`line2` wird nicht unterstützt**: Die Stripe-Tax-Engine verwendet`line2` nicht zur Ermittlung des Steuersatzes, daher akzeptiert die API diesen Wert nicht. - **Die Genauigkeitsgarantien gelten ausschließlich für die Stripe-Tax-Engine**: Wenn Sie eine Steuerberechnungs-Engine eines Drittanbieters verwenden, garantieren die Genauigkeitsstufen dieser API nicht dieselben Ergebnisse. - **Es gelten tägliche Nutzungslimits.** Die API unterliegt sowohl im Live-Modus als auch im Test-Modus täglichen Nutzungslimits. Wenden Sie sich an den [Stripe-Support](https://support.stripe.com/), falls Sie die Nutzungslimits erreichen. ## Nächste Schritte - [Erfassen Sie Kundenadressen](https://docs.stripe.com/tax/customer-locations.md), um zu verstehen, wie Stripe Tax diese Adressen für Berechnungen verwendet. - [Berechnen Sie die Steuer mit der Tax API](https://docs.stripe.com/tax/custom.md), um validierte Adressen bei der Steuerberechnung zu verwenden.