API delle aliquote fiscali
Istruzioni per l’integrazione tecnica con l’API delle aliquote fiscali di LOVAT
introduzione
La seguente documentazione copre le informazioni sugli elementi dell’API OMP, comprese richieste, risposte e codici di errore.
Per integrare l’API delle aliquote fiscali OMP:
- Registra un account Lovat OMP.
- Compila un profilo aziendale.
- Scegli un piano.
- Configura i webhook.
- Ottieni un gettone.
- Stabilisci le regole fiscali.
Termini e abbreviazioni
API: interfaccia di programmazione dell’applicazione. Un insieme di chiamate previste dal sistema richiede l’integrazione con prodotti software esterni.
Commerciante: il proprietario di un negozio online.
Cliente: un individuo che paga beni o servizi.
Transazione: trasferimento di fondi per beni o servizi ricevuti dal cliente dal commerciante.
Token – stringa segreta utilizzata dal sistema per identificare l’esercente e il sito web attraverso il quale viene registrata la transazione.
Riferimento API
L’API Lovat utilizza l’architettura REST. L’API dispone di URL prevedibili e orientati alle risorse e utilizza codici di risposta HTTP per indicare errori API. L’API risponde sempre nel formato JSON, inclusi i casi di errori.
Autenticazione
L’autenticazione all’API Tax Rate viene eseguita tramite l’autenticazione di base dell’intestazione HTTP. Gli abbonati devono fornire un token come valore di autenticazione di base. Se sei nuovo su Lovat, dovrai registrare un account per ottenere la tua chiave API. L’API utilizza funzionalità HTTP integrate come l’autenticazione HTTP e i verbi HTTP, che possono essere interpretati da client HTTP standard. Supporta inoltre la condivisione di risorse multiorigine, consentendoti di accedervi in modo sicuro da un’applicazione Web client.
URL
L’API Lovat utilizza i seguenti percorsi endpoint:
- Regione di produzione:
https://merchant.vatcompliance.co/api/1/tax_rate — Tax Rate API
-
- Regione di prova:
sandbox.vatcompliance.co/api/1/tax_rate
Metodo
Il tipo di richiesta: POST
https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}
Parametri JSON
| Parametro | Tipo | Descrizione | Necessaria |
| transaction_id | Corda | Massimo 255 caratteri. | opzionale |
| сurrency
|
Corda
|
Valuta di transazione. Codice valuta di tre lettere secondo ISO 4217. | opzionale |
| If_digital | Bol | Obbligatorio per i servizi digitali | opzionale |
| transaction_sum | Galleggiante | Importo totale dell’ordine di acquisto | opzionale |
| delivery_fee | Galleggiante | Importo totale della spedizione per l’ordine | opzionale |
| arrival_country
|
Corda
|
Un paese in cui è stato spedito l’ordine. Codice paese di tre lettere maiuscole conforme allo standard ISO 3166-1 alpha-3 | necessaria |
| arrival_zip | Corda | Obbligatorio per gli ordini negli Stati Uniti: codice postale di destinazione dell’ordine | richiesto agli ordini degli Stati Uniti |
| arrival_state | Corda | Per Stati Uniti, Canada, Regno Unito: codice dello stato ISO a due lettere in cui è stato spedito l’ordine | opzionale |
| departure_country | Corda | Codice paese ISO di tre lettere del paese da cui è stato spedito l’ordine. Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3 | opzionale
|
| departure_zip | Corda | Per ordini negli Stati Uniti: codice postale da cui è stato spedito l’ordine | opzionale |
| departure_state | Corda | Per Stati Uniti e Canada: codice dello stato ISO a due lettere da cui è stato spedito l’ordine | opzionale |
| service_code | Corda | Obbligatorio per i servizi forniti digitalmente. Categorie fiscali dei servizi digitali | opzionale |
| good_code | Corda | codice di una merce secondo il sistema di codifica a otto cifre dell’UE La nomenclatura combinata (NC) | opzionale |
| vat_number_of_buyer | Corda | Codice fiscale dell’acquirente | opzionale |
| buyer_ip | Corda | Indirizzo IP dell’acquirente. Obbligatorio per i servizi digitali | richiesto agli ordini degli Stati Uniti |
| exemption_type | Corda | Solo per ordini negli Stati Uniti | opzionale |
| phone_number_of_buyer | Corda | Facoltativo per i servizi digitali. Almeno le prime 5 cifre costituiscono il codice paese | opzionale |
| bank_country_of_buyer | Corda | Facoltativo per i servizi digitali. Codice paese di tre lettere maiuscole conforme allo standard ISO 3166-1 alpha-3 | opzionale |
Elenco degli errori
Elenco degli errori HTTP supportati:
200, 201, 204
Nessun errore
400 Richiesta errata
Ciò spesso indica la mancanza di un parametro richiesto. Fare riferimento al corpo della risposta per i dettagli
401 Non autorizzato
Nessuna chiave API valida fornita
402 Richiesta non riuscita
Richiesta non riuscita nonostante i parametri validi
403 Proibito
Nessun permesso. Fare riferimento al corpo della risposta per i dettagli
404 non trovato
L’articolo richiesto non esiste
409, 422
Parametri della richiesta non validi
412 Precondizione non riuscita
Il progetto non è stato ancora attivato (utilizzato nel metodo Get Token)
415 Tipo di supporto non supportato
“Tipo di contenuto: application/json” mancante nell’intestazione HTTP
Errori del server 500, 502, 503, 504
Qualcosa è andato storto
Esempio di richiesta di query
Richiesta di esempio dalla 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" }
Elementi di risposta
| Parametro | Tipo/Esempio | Descrizione |
| transaction_type | “export/import”, “b2c_distance_sales”, “reverse_charge” | |
| transaction_jurisdiction | “ITA”, “GBR” | Codice paese ISO di tre lettere del paese in cui l’ordine è imponibile. Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3 |
| taxable_state | “NY” | Per USA, Canada, Regno Unito: codice dello stato ISO a due lettere in cui l’ordine è imponibile |
| sales_tax_rate | 8 | Aliquota dell’imposta sulle vendite |
| vat_rate | 20 | Aliquota IVA |
| export_country | “USA”, “GBR” | Paese di esportazione per ordini con tipo di transazione esportazione/importazione |
| import_country | “USA”, “GBR” | Paese di importazione per ordini con tipo di transazione esportazione/importazione |
Risposta di esempio
{ "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 }
Formato data
Tutte le date sono specificate come stringhe secondo ISO 8601. È possibile specificare stringhe di date in formato UTC (ad esempio, 2013-01-15T00:00:00Z) o indicando l’offset UTC (ad esempio, 2013-01-15T00:00:00 -08:00 per otto ore indietro rispetto all’UTC). In quest’ultimo caso, assicurati di prendere in considerazione l’ora legale, se applicabile.
Paesi
Supportiamo i seguenti paesi nel mondo: Stati Uniti, paesi dell’UE, Regno Unito, Russia, Ucraina, Bielorussia, Norvegia, Canada, Australia, Giappone.
Categorie fiscali dei servizi digitali
| Contenuti audio/visivi | 1 |
| Diretta streaming | 2 |
| Servizi telefonici | 3 |
| Servizi di telefonia via Internet | 4 |
| Servizi di gestione delle chiamate | 5 |
| Servizi di cercapersone | 6 |
| accesso ad Internet | 7 |
| immagini | 8 |
| Musica | 9 |
| Giochi | 10 |
| Giornali elettronici | 11 |
| web hosting | 12 |
| Manutenzione a distanza dei programmi | 13 |
| Spazio pubblicitario su un sito web | 14 |
| E-book | 15 |
| Licenze | 16 |
| Datazione | 17 |
| Educazione a distanza | 18 |
| Gioco d’azzardo | 19 |
Limitazione delle chiamate
Limitiamo le richieste API a 1.000 al minuto per i piani commerciante. Potresti ricevere più chiamate rispetto al limite del tuo piano mensile. Le tariffe per eccedenza vengono addebitate separatamente se superi il limite del piano durante il mese successivo.
Tipi di esenzione
Solo per gli ordini statunitensi tipi di esenzione: all’ingrosso, governativa, mercato, altro, non_esente o nullo.