API aliquota fiscale
Istruzioni per l’integrazione tecnica con l’API aliquota fiscale di LOVAT
Introduzione
La seguente documentazione copre le informazioni sugli elementi dell’API OMP, tra cui richieste, risposte e codici di errore.
Per integrare l’API aliquota fiscale OMP:
- Registra un account Lovat OMP.
- Compila un profilo aziendale.
- Scegli un piano.
- Imposta webhook.
- Ottieni un token.
- Imposta le regole fiscali.
Termini e abbreviazioni
API: interfaccia di programmazione dell’applicazione. Un set di chiamate fornite 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: una stringa segreta utilizzata dal sistema per identificare il commerciante e il sito Web tramite il quale viene registrata la transazione.
Riferimento API
L’API Lovat utilizza l’architettura REST. L’API ha 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 errore.
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 un nuovo utente di Lovat, dovrai registrarti per 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 anche la condivisione di risorse multi-origine, 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
Tipo di richiesta: POST
https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}
Parametri JSON
| Parametro | Tipo | Descrizione | Necessario |
| transaction_id | Corda | Massimo 255 caratteri | opzionale |
|
сurrency
|
Corda
|
Valuta della 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 l’ordine è stato spedito. Codice paese di tre lettere maiuscole secondo ISO 3166-1 alpha-3 | necessario |
| arrival_zip | Corda | Obbligatorio per gli ordini negli Stati Uniti: codice postale in cui è stato spedito l’ordine | richiesto dagli ordini degli Stati Uniti |
| arrival_state | Corda | Per Stati Uniti, Canada, Regno Unito: codice ISO di due lettere dello stato in cui è stato spedito l’ordine | opzionale |
| departure_country | Corda | Codice ISO di tre lettere del paese da cui è stato spedito l’ordine. Tutti i paesi sono specificati come stringhe secondo ISO 3166-1 alpha-3 |
opzionale
|
| departure_zip | Corda | Per gli ordini negli Stati Uniti: codice postale da cui è stato spedito l’ordine | opzionale |
| departure_state | Corda | Per Stati Uniti, Canada: codice ISO di due lettere dello stato 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 un bene 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 | necessario per i servizi digitali |
| exemption_type | Corda | Solo per ordini negli Stati Uniti | opzionale |
| phone_number_of_buyer | Corda | Opzionale per i servizi digitali. Almeno 5 prime cifre sono costituite dal codice paese | opzionale |
| bank_country_of_buyer | Corda | Opzionale per i servizi digitali. Codice paese maiuscolo a tre lettere secondo ISO 3166-1 alpha-3 | opzionale |
Elenco errori
Elenco degli errori HTTP supportati:
200, 201, 204
Nessun errore
400 Richiesta non valida
Questo spesso indica un parametro obbligatorio mancante. Per i dettagli, fare riferimento al corpo della risposta
401 Non autorizzato
Nessuna chiave API valida fornita
402 Richiesta non riuscita
Richiesta non riuscita nonostante parametri validi
403 Vietato
Nessuna autorizzazione. Per i dettagli, fare riferimento al corpo della risposta
404 Non trovato
L’elemento richiesto non esiste
409, 422
Parametri di richiesta non validi
412 Precondizione non riuscita
Il progetto non è stato ancora attivato (utilizzato nel metodo Get Token)
415 Tipo di supporto non supportato
‘Content-Type: application/json’ mancante nell’intestazione HTTP
500, 502, 503, 504 Errori del server
Qualcosa è andato storto
Richiesta di query di esempio
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 ISO di tre lettere del paese in cui l’ordine è imponibile. Tutti i paesi sono specificati come stringhe secondo ISO 3166-1 alpha-3 |
| taxable_state | “NY” | Per USA, Canada, Regno Unito: codice ISO di due lettere dello stato 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 |
Esempio di risposta
{
"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. Puoi specificare stringhe di data in 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 dietro UTC). In quest’ultimo caso, assicurati di tenere conto dell’ora legale, se applicabile.
Paesi
Supportiamo i seguenti paesi in tutto il mondo: Stati Uniti, paesi UE, Regno Unito, Russia, Ucraina, Bielorussia, Norvegia, Canada, Australia, Giappone.
Categorie fiscali dei servizi digitali
| Contenuto audio/visivo | 1 |
| Streaming in diretta | 2 |
| Servizi telefonici | 3 |
| Servizi telefonici via Internet | 4 |
| Servizi di gestione delle chiamate | 5 |
| Servizi di paging | 6 |
| Accesso a Internet | 7 |
| Immagini | 8 |
| Musica | 9 |
| Giochi | 10 |
| Giornali elettronici | 11 |
| Hosting Web | 12 |
| Manutenzione a distanza dei programmi | 13 |
| Spazio pubblicitario su un sito web | 14 |
| E-book | 15 |
| Licenze | 16 |
| Datazione | 17 |
| Formazione a distanza | 18 |
| Gioco d’azzardo | 19 |
Limitazione delle chiamate
Limitiamo le richieste API a 1.000 al minuto per i piani commerciali. Potresti avere più chiamate rispetto al limite del tuo piano mensile. Le tariffe per il superamento vengono addebitate separatamente se superi il limite del tuo piano durante il mese successivo.
Tipi di esenzione
Solo per gli ordini negli Stati Uniti, tipi di esenzione: wholesale, government, marketplace, other, non_exempt o nill.