| %

Istruzioni per l’integrazione tecnica con i sistemi LOVAT

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.

Descrizione dell’API

Invia metodo.

Descrizione del metodo.

La modalità SEND implementa la ricezione dei dati relativi alla transazione, tenendo conto dell’elaborazione e del calcolo dell’IVA e degli oneri di sistema.

URL di riferimento

Il metodo è disponibile al seguente URL:

https://merchant.vatcompliance.co/api/1/ send/{access_token}?if_digital={true/false}&if_vat_calculate={true/false}

Opzioni di chiamata

I parametri di chiamata sono divisi in due tipologie:

Parametri del percorso (token)
Parametri di query (dati delle transazioni)

Il token viene generato nell’account interno del commerciante nella prima fase di aggiunta del sito web. Puoi ottenerlo dal tuo manager o trovarlo nella sezione Negozio –Impostazioni.

I parametri della richiesta vengono generati dall’esercente ed inviati al server tramite la modalità POST
nell’applicazione

/ x-www-form-urlencoded or application / json format

Servizi digitali

Parametro	Tipo/Esempio	Descrizione di esempio	Validazione
transaction_id	String/ 555-yyy	ID della transazione	Massimo 255 caratteri. Non un valore vuoto.
transaction_datetime	DateTime / 2017-01-09T08:27:22 +00:00	Data e ora della transazione secondo ISO 8601 GMT	Non un valore vuoto.
transaction_sum	String / 25	Importo della transazione	Massimo 45 caratteri. Non un valore vuoto.
customer_ip	String / 127.0.0.1	L’indirizzo IP del cliente	Massimo 45 caratteri.
currency	String / “usd”, “eur”, “rub”, “gbp”	Valuta di transazione	Massimo 3 caratteri. Non un valore vuoto.
customer_phone_number	String / “+7 AAA BBB BB BB”	Numero di telefono del cliente	Massimo 100 caratteri.
arrival_country	String / “GBR”	Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3	Massimo 3 caratteri.
arrival_city	String / “London”	Città di arrivo	Massimo 255 caratteri.
arrival_address_line	String / “Peckham Road”	Riga dell’indirizzo di arrivo	Massimo 255 caratteri.
transaction_status	String / “Success”, “Charge back”, “refund”, “Movement own goods”	Stato della transazione	Non un valore vuoto.
service_code	String / “1”	Codice del tipo di servizio del commerciante Se il commerciante non invia dati sul tipo di servizio fornito, alla transazione viene assegnato il tipo principale nominale di servizio del commerciante specificato al momento della registrazione	Massimo 255 caratteri. Non un valore vuoto.
bank_card_number	String / “1234-**--**”	Numero della carta bancaria dell’acquirente	Massimo 19 caratteri.
payment_operator	String / “payonline” paypal”	Operatore di pagamento	Massimo 45 caratteri. Non un valore vuoto.
payment_method_country	String / “USA”	Opzione di pagamento per paese. Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3	Massimo 3 caratteri. Non un valore vuoto.
billing_country	String / “USA”	Paese di fatturazione (indirizzo del titolare del pagamento). Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3	Massimo 3 caratteri. Non un valore vuoto.
billing_address	String / “111 First Street,Saratoga, CA 95070, US”	Indirizzo di fatturazione (indirizzo del titolare del pagamento)	Massimo 255 caratteri. Non un valore vuoto.

Codice di risposta del server

La risposta alla query utilizza il codice HTTP di base

Codice	Spiegazione	Contenuto della risposta
200 OK	Richiesta elaborata
400 Richiesta errata	Richiesta non valida	{errore: “Problema con i dati” }
401 Non autorizzato	Accesso non autorizzato	{errore: “Il token non è valido.” }

Query di esempio per i servizi digitali:

Richiesta di esempio dalla console

curl -v POST 'http://https://merchant.vatcompliance.co/api/1/
send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=true' --header "Content-Type: application/json"
-d '{ 
    "transaction_id": " ttt4565-85546",
    "transaction_datetime": "2017-01-09T08:27:22 +00:00",
    "transaction_sum": 25.99,
    "customer_ip": "127.0.0.1",
    "customer_phone_number": "+7 677 ** * **",
}'

Merce

Parametro	Tipo/Esempio	Descrizione di esempio	Validazione
transaction_id	String/ 555-yyy	ID della transazione	Massimo 255 caratteri. Non un valore vuoto.
transaction_datetime	DateTime / 2017-01-09T08:27:22 +00:00	Data e ora della transazione secondo ISO 8601 GMT	Non un valore vuoto.
transaction_sum	String / 25	Importo della transazione	Massimo 45 caratteri. Non un valore vuoto.
currency	String / “GBP”, “EUR”, “RUB”	Tutte le valute sono specificate come stringhe secondo ISO 4217	Massimo 3 caratteri. Non un valore vuoto.
arrival_country	String / “GBR”	Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3	Massimo 3 caratteri.
arrival_city	String / “London”	Città di arrivo	Massimo 255 caratteri.
arrival_address_line	String / “Peckham Road”	Riga dell’indirizzo di arrivo	Massimo 255 caratteri.
transaction_status	String / “Success”, “Charge back”, “refund”, “Movement own goods”	Stato della transazione	Non un valore vuoto.
good_code	String / “62160000”	codice di una merce secondo il sistema di codifica a otto cifre dell’UE La nomenclatura combinata (NC)	Massimo 8 caratteri.
vat_percent	Float / 20.00	percentuale iva	Massimo 8 caratteri.
vat	Float / 28.73	Importo IVA	Galleggiante
departure_country	String / “AUS”	Opzione di pagamento per paese. Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3	Massimo 3 caratteri. Non un valore vuoto.
taxable_jurisdiction	String / “GBR”	Opzione di pagamento per paese. Tutti i paesi sono specificati come stringhe secondo la norma ISO 3166-1 alpha-3	Massimo 3 caratteri.
buyer_vat_number	String / “UK123123123”	Partita IVA acquirente UE	Massimo 255 caratteri.

Query di esempio per le merci: