API de taux de taxe
Instruction pour l’intégration technique avec l’API de taux d’imposition par LOVAT
Introduction
La documentation suivante couvre les informations sur les éléments de l’API OMP, y compris les demandes, les réponses et les codes d’erreur.
Pour intégrer l’API de taux de taxe OMP:
- Enregistrez un compte Lovat OMP.
- Remplissez un profil d’entreprise.
- Choisissez un forfait.
- Configurez des Webhooks.
- Obtenez un jeton.
- Définissez des règles fiscales.
Termes et abréviations
API – Interface de programmation d’applications. Un ensemble d’appels fournis par le système demande une intégration avec des produits logiciels externes.
Marchand – le propriétaire d’une boutique en ligne.
Client – une personne qui paie des biens ou des services.
Transaction – transfert de fonds pour des biens ou des services reçus par le client du commerçant.
Jeton – une chaîne secrète utilisée par le système pour identifier le commerçant et le site Web par l’intermédiaire duquel la transaction est enregistrée.
Référence API
L’API Lovat utilise l’architecture REST. L’API a des URL prévisibles et orientées ressources et utilise des codes de réponse HTTP pour indiquer les erreurs d’API. L’API répond toujours au format JSON, y compris en cas d’erreurs.
Authentification
L’authentification auprès de l’API Tax Rate s’effectue via l’authentification de base de l’en-tête HTTP. Les abonnés doivent fournir un jeton comme valeur d’authentification de base. Si vous êtes nouveau sur Lovat, vous devrez créer un compte pour obtenir votre clé API. L’API utilise des fonctionnalités HTTP intégrées telles que l’authentification HTTP et les verbes HTTP, qui peuvent être interprétées par des clients HTTP prêts à l’emploi. Il prend également en charge le partage de ressources cross-origin, vous permettant d’y accéder en toute sécurité à partir d’une application Web cliente.
URL
L’API Lovat utilise les chemins de point de terminaison suivants:
- Région de fabrication:
https://merchant.vatcompliance.co/api/1/tax_rate — Tax Rate API
- Région d’essai:
sandbox.vatcompliance.co/api/1/tax_rate
Méthode
Le type de requête: POST
https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}
Paramètres JSON
Paramètre |
Taper |
Description |
Requis |
| transaction_id | Chaîne | Maximum 255 caractères. | Facultatif |
| сurrency
|
Chaîne
|
Devise de la transaction. Code de devise à trois lettres selon ISO 4217. | Facultatif |
| If_digital | Il était | Obligatoire pour les services numériques | Facultatif |
| transaction_sum | Flotter | Montant total de la commande | Facultatif |
| delivery_fee | Flotter | Montant total des frais de port pour la commande | Facultatif |
| arrival_country
|
Chaîne
|
Un pays où la commande a été expédiée. Code pays à trois lettres majuscules selon la norme ISO 3166-1 alpha-3 | Requis |
| arrival_zip | Chaîne | Obligatoire pour les commandes aux États-Unis: code postal où la commande a été expédiée | Requis pour les commandes américaines |
| arrival_state | Chaîne | Pour les États-Unis, le Canada et le Royaume-Uni: code d’état ISO à deux lettres où la commande a été expédiée | Facultatif |
| departure_country | Chaîne | Code pays ISO à trois lettres du pays d’où la commande a été expédiée. Tous les pays sont spécifiés sous forme de chaînes conformément à la norme ISO 3166-1 alpha-3 | Facultatif
|
| departure_zip | Chaîne | Pour les commandes aux États-Unis: code postal d’où la commande a été expédiée | Facultatif |
| departure_state | Chaîne | Pour les États-Unis et le Canada: code d’état ISO à deux lettres d’où la commande a été expédiée | Facultatif |
| service_code | Chaîne | Obligatoire pour les services fournis numériquement. Catégories fiscales des services numériques | Facultatif |
| good_code | Chaîne | Сode d’une marchandise selon le système de codage à huit chiffres de l’UE La nomenclature combinée (NC) | Facultatif |
| vat_number_of_buyer | Chaîne | Numéro fiscal de l’acheteur | Facultatif |
| buyer_ip | Chaîne | Adresse IP de l’acheteur. Obligatoire pour les services numériques | Requis pour les services numériques |
| exemption_type | Chaîne | Pour les commandes aux États-Unis uniquement | Facultatif |
| phone_number_of_buyer | Chaîne | Facultatif pour les services numériques. Au moins 5 premiers chiffres consistent en un code de pays | Facultatif |
| bank_country_of_buyer | Chaîne | Facultatif pour les services numériques. Code pays à trois lettres majuscules selon la norme ISO 3166-1 alpha-3 | Facultatif |
Liste des erreurs
Liste des erreurs HTTP prises en charge:
200, 201, 204
Pas d’erreur
400 Mauvaise demande
Cela indique souvent qu’un paramètre obligatoire est manquant. Reportez-vous au corps de la réponse pour plus de détails
401 Non autorisé
Aucune clé API valide fournie
Échec de la demande 402
Échec de la requête malgré des paramètres valides
403 Interdit
Aucune autorisation. Reportez-vous au corps de la réponse pour plus de détails
404 Non trouvé
L’élément demandé n’existe pas
409, 422
Paramètres de requête non valides
412 Échec de la précondition
Le projet n’a pas encore été activé (utilisé dans la méthode Get Token)
415 Type de support non pris en charge
‘Content-Type: application/json’ manquant dans l’en-tête HTTP
500, 502, 503, 504 Erreurs de serveur
Quelque chose s’est mal passé
Exemple de demande de requête
Exemple de requête depuis la console:
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" }
Éléments de réponse
Paramètre |
Genre/Exemple |
Description |
| transaction_type | “export/import”, “b2c_distance_sales”, “reverse_charge” | |
| transaction_jurisdiction | “ITA”, “GBR” | Code pays ISO à trois lettres du pays où la commande est taxable. Tous les pays sont spécifiés sous forme de chaînes conformément à la norme ISO 3166-1 alpha-3 |
| taxable_state | “NY” | Pour les États-Unis, le Canada et le Royaume-Uni: code d’état ISO à deux lettres où la commande est taxable |
| sales_tax_rate | 8 | Taux de taxe de vente |
| vat_rate | 20 | Taux de TVA |
| export_country | “USA”, “GBR” | Pays d’exportation pour les commandes avec type de transaction exportation/importation |
| import_country | “USA”, “GBR” | Pays d’importation pour les commandes avec type de transaction exportation/importation |
Exemple de réponse
{ "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 }
Format de date
Toutes les dates sont spécifiées sous forme de chaînes conformément à la norme ISO 8601. Vous pouvez spécifier des chaînes de date soit en UTC (par exemple, 2013-01-15T00:00:00Z), soit en indiquant le décalage UTC (par exemple, 2013-01-15T00:00:00 -08:00 pour huit heures de retard UTC). Dans ce dernier cas, assurez-vous de tenir compte de l’heure d’été, le cas échéant.
Des pays
Nous soutenons les pays suivants dans le monde: États-Unis, pays de l’UE, Royaume-Uni, Russie, Ukraine, Biélorussie, Norvège, Canada, Australie, Japon.
Catégories fiscales des services numériques
| Contenu audiovisuel | 1 |
| Diffusion en direct | 2 |
| Services téléphoniques | 3 |
| Téléphonie Internet | 4 |
| Services de gestion des appels | 5 |
| Services de radiomessagerie | 6 |
| Accès Internet | 7 |
| Images | 8 |
| Musique | 9 |
| Jeux | 10 |
| Journaux électroniques | 11 |
| Hébergement Web | 12 |
| Maintenance à distance des programmes | 13 |
| Espace publicitaire sur un site internet | 14 |
| Livres électroniques | 15 |
| Licences | 16 |
| Datation | 17 |
| L’enseignement à distance | 18 |
| Jeu d’argent | 19 |
Limitation des appels
Nous limitons les requêtes API à 1 000 par minute pour les forfaits marchands. Vous pouvez avoir plus d’appels que la limite de votre forfait mensuel. Les frais de dépassement sont facturés séparément si vous dépassez la limite de votre forfait au cours du mois suivant.
Types d’exemption
Pour les commandes aux États-Unis uniquement, les types d’exemption : vente en gros, gouvernement, place de marché, autre, non_exempt ou néant.