Steuersatz-API
Anleitung zur technischen Integration mit der Steuersatz-API von LOVAT
Einführung
Die folgende Dokumentation enthält Informationen zu Elementen der OMP-API, einschließlich Anfragen, Antworten und Fehlercodes.
So integrieren Sie die OMP-Steuersatz-API:
- Registrieren Sie ein Lovat OMP-Konto.
- Füllen Sie ein Unternehmensprofil aus.
- Wählen Sie einen Plan.
- Richten Sie Webhooks ein.
- Holen Sie sich ein Token.
- Legen Sie Steuerregeln fest.
Begriffe und Abkürzungen
API – Anwendungsprogrammierschnittstelle. Eine Reihe von Aufrufen, die vom System bereitgestellt werden, ruft die Integration mit externen Softwareprodukten auf.
Händler – der Eigentümer eines Online-Shops.
Kunde – eine Person, die für Waren oder Dienstleistungen bezahlt.
Transaktion – Überweisung von Geldern für Waren oder Dienstleistungen, die der Kunde vom Händler erhält.
Token – eine geheime Zeichenfolge, die vom System verwendet wird, um den Händler und die Website zu identifizieren, über die die Transaktion registriert wird.
API-Referenz
Die Lovat-API verwendet die REST-Architektur. Die API verfügt über vorhersehbare, ressourcenorientierte URLs und verwendet HTTP-Antwortcodes, um API-Fehler anzuzeigen. Die API antwortet immer im JSON-Format, auch in Fehlerfällen.
Authentifizierung
Die Authentifizierung bei der Tax Rate API erfolgt über eine grundlegende HTTP-Header-Authentifizierung. Abonnenten müssen ein Token als grundlegenden Authentifizierungswert angeben. Wenn Sie neu bei Lovat sind, müssen Sie ein Konto erstellen, um Ihren API-Schlüssel zu erhalten. Die API verwendet integrierte HTTP-Funktionen wie HTTP-Authentifizierung und HTTP-Verben, die von handelsüblichen HTTP-Clients interpretiert werden können. Sie unterstützt auch die gemeinsame Nutzung von Ressourcen zwischen verschiedenen Ursprüngen, sodass Sie sicher von einer Client-Webanwendung darauf zugreifen können.
URL
Die Lovat API verwendet die folgenden Endpunktpfade:
- Produktionsregion:
https://merchant.vatcompliance.co/api/1/tax_rate — Tax Rate API
- Testregion:
sandbox.vatcompliance.co/api/1/tax_rate
Methode
Der Anfragetyp: POST
https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}
JSON-Parameter
| Parameter | Typ | Beschreibung | Erforderlich |
| transaction_id | Zeichenfolge | Maximal 255 Zeichen | optional |
|
сurrency
|
Zeichenfolge
|
Transaktionswährung. Dreistelliger Währungscode gemäß ISO 4217 | optional |
| If_digital | Bol | Erforderlich für digitale Dienste | optional |
| transaction_sum | Schweben | Gesamtbetrag der Einkaufsbestellung | optional |
| delivery_fee | Schweben | Gesamtversandbetrag für die Bestellung | optional |
|
arrival_country
|
Zeichenfolge
|
Ein Land, in das die Bestellung geliefert wurde. Dreistelliger Ländercode in Großbuchstaben gemäß ISO 3166-1 Alpha-3 | erforderlich |
| arrival_zip | Zeichenfolge | Für Bestellungen aus den USA ist die Postleitzahl erforderlich, an die die Bestellung geliefert wird | erforderlich, um die US-Bestellungen |
| arrival_state | Zeichenfolge | Für die USA, Kanada und Großbritannien: zweistelliger ISO-Code des Staates, in den die Bestellung geliefert wurde | optional |
| departure_country | Zeichenfolge | Dreistelliger ISO-Ländercode des Landes, aus dem die Bestellung versandt wurde. Alle Länder werden als Zeichenfolgen gemäß ISO 3166-1 Alpha-3 angegeben. |
optional
|
| departure_zip | Zeichenfolge | Für Bestellungen aus den USA: Postleitzahl des Versandorts der Bestellung | optional |
| departure_state | Zeichenfolge | Für USA, Kanada: zweistelliger ISO-Code des Staates, aus dem die Bestellung versandt wurde | optional |
| service_code | Zeichenfolge | Erforderlich für digital erbrachte Dienstleistungen. Steuerkategorien digitaler Dienstleistungen | optional |
| good_code | Zeichenfolge | Code einer Ware gemäß dem achtstelligen Kodierungssystem der EU, der Kombinierten Nomenklatur (KN) | optional |
| vat_number_of_buyer | Zeichenfolge | Steuernummer des Käufers | optional |
| buyer_ip | Zeichenfolge | IP-Adresse des Käufers. Erforderlich für digitale Dienste | erforderlich für digitale Dienste |
| exemption_type | Zeichenfolge | Nur für Bestellungen aus den USA | optional |
| phone_number_of_buyer | Zeichenfolge | Optional für digitale Dienste. Mindestens 5 erste Ziffern bestehen aus dem Ländercode | optional |
| bank_country_of_buyer | Zeichenfolge | Optional für digitale Dienste. Dreistelliger Ländercode in Großbuchstaben gemäß ISO 3166-1 Alpha-3 | optional |
Fehlerliste
Liste unterstützter HTTP-Fehler:
200, 201, 204
Kein Fehler
400 Ungültige Anfrage
Dies weist häufig auf einen fehlenden erforderlichen Parameter hin. Weitere Einzelheiten finden Sie im Antworttext.
401 Nicht autorisiert
Kein gültiger API-Schlüssel angegeben
402 Anfrage fehlgeschlagen
Anfrage fehlgeschlagen trotz gültiger Parameter
403 Verboten
Keine Berechtigung. Weitere Einzelheiten finden Sie im Antworttext.
404 Nicht gefunden
Das angeforderte Element existiert nicht
409, 422
Ungültige Anfrageparameter
412 Vorbedingung fehlgeschlagen
Das Projekt wurde noch nicht aktiviert (wird in der Methode „Token abrufen“ verwendet)
415 Nicht unterstützter Medientyp
„Content-Type: application/json“ fehlt im HTTP-Header
500, 502, 503, 504 Serverfehler
Etwas ist schiefgelaufen
Beispiel für eine Abfrageanfrage
Beispielanfrage von der Konsole:
curl-v GET https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8
--header "Content-Type: application/json" \
-d '{
"arrival_country": "ITA",
"departure_country": "GBR",
"transaction_id": "7668999765",
"transaction_sum": 10,
"vat_number_of_buyer": "IT8996543"
}'
{
"arrival_country": "GBP",
"currency": "EUR",
"delivery_fee": 0,
"departure_country": "HUN",
"vat_number_of_buyer": "IT8996543",
"transaction_datetime": "2021-01-09",
"transaction_id": "45000098"
}
{
"arrival_country": "USA",
"arrival_state": "NY",
"arrival_zip": "10034",
"departure_country": "USA",
"departure_state": "TX",
"departure_zip": "77554",
"transaction_datetime": "2021-01-01",
"transaction_id": "788654333"
}
Antwortelemente
| Parameter | Typ/Beispiel | Beschreibung |
| transaction_type | “export/import”, “b2c_distance_sales”, “reverse_charge” | |
| transaction_jurisdiction | “ITA”, “GBR” | Dreistelliger ISO-Ländercode des Landes, in dem die Bestellung steuerpflichtig ist. Alle Länder werden als Zeichenfolgen gemäß ISO 3166-1 Alpha-3 angegeben. |
| taxable_state | “NY” | Für USA, Kanada, Großbritannien: zweistelliger ISO-Code des Staates, in dem die Bestellung steuerpflichtig ist |
| sales_tax_rate | 8 | Umsatzsteuersatz |
| vat_rate | 20 | Mehrwertsteuersatz |
| export_country | “USA”, “GBR” | Exportland für Bestellungen mit Vorgangsart Export/Import |
| import_country | “USA”, “GBR” | Importland für Bestellungen mit Vorgangsart Export/Import |
Beispielantwort
{
"transaction_type": "b2c_distance_sales",
"taxable_jurisdiction": "USA",
"taxable_state": "NY",
"sales_tax_rate": 8.25
}
{
"transaction_type": "export/import",
"taxable_jurisdiction": "GBR",
"vat_rate": 0,
"export_country": "GBR",
"import_country": "ITA"
}
{
"transaction_type": "reverse_charge",
"taxable_jurisdiction": "FRA",
"vat_rate": 0
}
Datumsformat
Alle Daten werden als Zeichenfolgen gemäß ISO 8601 angegeben. Sie können Datumszeichenfolgen entweder in UTC angeben (z. B. 2013-01-15T00:00:00Z) oder den UTC-Offset angeben (z. B. 2013-01-15T00:00:00-08:00 für acht Stunden hinter UTC). Im letzteren Fall müssen Sie ggf. die Sommerzeit berücksichtigen.
Länder
Wir unterstützen die folgenden Länder weltweit: USA, EU-Länder, Großbritannien, Russland, Ukraine, Weißrussland, Norwegen, Kanada, Australien, Japan.
Steuerkategorien für digitale Dienste
| Audiovisuelle Inhalte | 1 |
| Live-Streaming | 2 |
| Telefondienste | 3 |
| Internet-Telefondienste | 4 |
| Anrufverwaltungsdienste | 5 |
| Paging-Dienste | 6 |
| Internetzugang | 7 |
| Bilder | 8 |
| Musik | 9 |
| Spiele | 10 |
| E-Zeitungen | 11 |
| Webhosting | 12 |
| Fernwartung von Programmen | 13 |
| E-Bücher | 14 |
| E-Bücher | 15 |
| Lizenzen | 16 |
| Verabredungen | 17 |
| Fernunterricht | 18 |
| Glücksspiel | 19 |
Anrufbegrenzung
Wir begrenzen API-Anfragen für Händlerpläne auf 1.000 pro Minute. Sie haben möglicherweise mehr Anrufe als Ihr monatliches Planlimit. Überschreitungsgebühren werden separat berechnet, wenn Sie Ihr Planlimit im nächsten Monat überschreiten.
Arten von Ausnahmen
Nur für US-Bestellungen: Arten von Ausnahmen: Großhandel, Regierung, Marktplatz, Sonstiges, Nicht_Ausgenommen oder Null.