API de taux de taxe
Instructions pour l’intégration technique avec l’API de taux de taxe de LOVAT
Introduction
La documentation suivante couvre les informations sur les éléments de l’API OMP, notamment les requêtes, les réponses et les codes d’erreur.
Pour intégrer l’API de taux de taxe OMP:
- Enregistrez un compte OMP Lovat.
- Remplissez un profil d’entreprise.
- Choisissez un plan.
- Configurez des Webhooks.
- Obtenez un jeton.
- Définissez des règles fiscales.
Termes et abréviations
API – interface de programmation d’application. Ensemble d’appels fournis par le système pour l’intégration avec des produits logiciels externes.
Commerçant – propriétaire d’une boutique en ligne.
Client – personne qui paie des biens ou des services.
Transaction – transfert de fonds pour des biens ou des services reçus par le client auprès du commerçant.
Jeton – chaîne secrète utilisée par le système pour identifier le commerçant et le site Web via lequel la transaction est enregistrée.
Référence API
L’API Lovat utilise l’architecture REST. L’API dispose d’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’erreur.
Authentification
L’authentification à 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 débutez avec 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. Elle prend également en charge le partage de ressources entre origines, ce qui vous permet 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 production:
https://merchant.vatcompliance.co/api/1/tax_rate — Tax Rate API
- Région de test:
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 transaction. Code de devise à trois lettres selon la norme ISO 4217 | facultatif |
| If_digital | Bol | Obligatoire pour les services numériques | facultatif |
| transaction_sum | Flotter | Montant total de la commande d’achat | facultatif |
| delivery_fee | Flotter | Montant total des frais de livraison pour la commande | facultatif |
|
arrival_country
|
Chaîne
|
Pays vers lequel la commande est expédiée. Code de pays à trois lettres majuscules selon la norme ISO 3166-1 alpha-3 | required |
| arrival_zip | Chaîne | Obligatoire pour les commandes aux États-Unis: code postal où la commande est 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 vers lequel la commande est expédiée | facultatif |
| departure_country | Chaîne | Code ISO à trois lettres du pays d’expédition de la commande. 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 est expédiée | facultatif |
| service_code | Chaîne | Obligatoire pour les services fournis par voie numérique. Catégories fiscales des services numériques | facultatif |
| good_code | Chaîne | code d’un bien selon le système de codification à 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. Nécessaire 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 les 5 premiers chiffres sont constitués du code du 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
Aucune erreur
400 Demande incorrecte
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
402 Échec de la demande
La demande a échoué malgré des paramètres valides
403 Interdit
Aucune autorisation. Reportez-vous au corps de la réponse pour plus de détails
404 Introuvable
L’élément demandé n’existe pas
409, 422
Paramètres de demande non valides
412 Échec de la condition préalable
Le projet n’a pas encore été activé (utilisé dans la méthode Get Token)
415 Type de média non pris en charge
«Content-Type: application/json» manquant dans l’en-tête HTTP
500, 502, 503, 504 Erreurs du serveur
Une erreur s’est produite
Exemple de requête 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 | Type/Exemple | Description |
| transaction_type | “export/import”, “b2c_distance_sales”, “reverse_charge” | |
| transaction_jurisdiction | “ITA”, “GBR” | Code 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 le type de transaction export/import |
| import_country | “USA”, “GBR” | Pays d’importation pour les commandes avec le type de transaction export/import |
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 sur UTC). Dans ce dernier cas, veillez à prendre en compte l’heure d’été, le cas échéant.
Pays
Nous prenons en charge 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 de services numériques
| Contenu audio/visuel | 1 |
| Diffusion en direct | 2 |
| Services téléphoniques | 3 |
| Services de téléphonie par Internet | 4 |
| Services de gestion des appels | 5 |
| Services de téléavertissement | 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 web | 14 |
| Livres électroniques | 15 |
| Licences | 16 |
| Datation | 17 |
| 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’exonération
Pour les commandes aux États-Unis uniquement, types d’exonération: vente en gros, gouvernement, marché, autre, non-exonéré ou nul.