Italiano
Prova gratis
A

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.