Alimentazione API

Istruzioni per l’integrazione tecnica con i sistemi LOVAT

Termini e abbreviazioni

API – Application Programming Interface (Interfaccia di programmazione dell’applicazione). Un insieme di chiamate fornite dal sistema per l’integrazione con prodotti software esterni.

Commerciante – il proprietario di un negozio online.

Cliente – un individuo che paga per beni o servizi.

Transazione – trasferimento di fondi per beni o servizi ricevuti dal cliente da parte del commerciante.

Token – una stringa segreta utilizzata dal sistema per identificare il commerciante e il sito web attraverso il quale viene registrata la transazione.

Descrizione API

Metodo di invio.

Descrizione del metodo.

Il metodo INVIO implementa la ricezione dei dati della 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 call

I parametri di chiamata si dividono in due tipi:

Parametri di percorso (token)
Parametri di interrogazione (dati della transazione)

Il token viene generato nell’account interno dell’esercente nella prima fase di aggiunta del sito web. È possibile ottenerlo dal proprio manager o trovarlo nella sezione Store -Settings.

The request parameters are generated by the merchant and sent to the server using the POST method
in the application 
/ x-www-form-urlencoded or application / json format

Servizi digitali

Parameter	Type/Example	Example Description	Validation
transaction_id	String/ 555-yyy	Transaction ID	Maximum 255 characters. Not an empty value.
transaction_datetime	DateTime / 2017-01-09T08:27:22 +00:00	Date and time of the transaction in accordance with ISO 8601 GMT	Not an empty value.
transaction_sum	String / 25	Transaction Amount	Maximum 45 characters. Not an empty value.
customer_ip	String / 127.0.0.1	Customer’s IP address	Maximum 45 characters.
currency	String / “usd”, “eur”, “rub”, “gbp”	Transaction Currency	Maximum 3 characters. Not an empty value.
customer_phone_number	String / “+7 AAA BBB BB BB”	Customer’s phone number	Maximum 100 characters.
arrival_country	String / “GBR”	All countries are specified as strings according to ISO 3166-1 alpha-3	Maximum 3 characters.
arrival_city	String / “London”	Arrival city	Maximum 255 characters.
arrival_address_line	String / “Peckham Road”	Arrival address line	Maximum 255 characters.
transaction_status	String / “Success”, “Charge back”, “refund”, “Movement own goods”	Transaction Status	Not an empty value.
service_code	String / “1”	Merchant service type code If the merchant does not send data on the type of service provided, the transaction is assigned the nominal principal type of merchant’s service that was specified at registration	Maximum 255 characters. Not an empty value.
bank_card_number	String / “1234-**--**”	Bank card number of the buyer	Maximum 19 characters.
payment_operator	String / “payonline” paypal”	Payment Operator	Maximum 45 characters. Not an empty value.
payment_method_country	String / “USA”	Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3	Maximum 3 characters. Not an empty value.
billing_country	String / “USA”	Billing country (address of the payment owner). All countries are specified as strings according to ISO 3166-1 alpha-3	Maximum 3 characters. Not an empty value.
billing_address	String / “111 First Street,Saratoga, CA 95070, US”	Billing address (address of the payment owner)	Maximum 255 characters. Not an empty value.

Codice di risposta del server

La risposta alla query utilizza il codice HTTP di base

Code	Explanation	Response Content
200 OK	Request Processed
400 BadRequest	Invalid request	{ error : “Problem with data” }
401 Unauthorized	Unauthorized access	{ error : “Token is invalid.” }

Esempio di richiesta di servizi digitali:
Esempio di richiesta 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 ** * **",
}'

Merci

Parameter	Type/Example	Example Description	Validation
transaction_id	String/ 555-yyy	Transaction ID	Maximum 255 characters. Not an empty value.
transaction_datetime	DateTime / 2017-01-09T08:27:22 +00:00	Date and time of the transaction in accordance with ISO 8601 GMT	Not an empty value.
transaction_sum	String / 25	Transaction Amount	Maximum 45 characters. Not an empty value.
currency	String / “GBP”, “EUR”, “RUB”	All currencies are specified as strings according to ISO 4217	Maximum 3 characters. Not an empty value.
arrival_country	String / “GBR”	All countries are specified as strings according to ISO 3166-1 alpha-3	Maximum 3 characters.
arrival_city	String / “London”	Arrival city	Maximum 255 characters.
arrival_address_line	String / “Peckham Road”	Arrival address line	Maximum 255 characters.
transaction_status	String / “Success”, “Charge back”, “refund”, “Movement own goods”	Transaction Status	Not an empty value.
good_code	String / “62160000”	code of a good according to EU’s eight-digit coding system The Combined Nomenclature (CN)	Maximum 8 characters.
vat_percent	Float / 20.00	vat percent	Maximum 8 characters.
vat	Float / 28.73	VAT Amount	Float
departure_country	String / “AUS”	Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3	Maximum 3 characters. Not an empty value.
taxable_jurisdiction	String / “GBR”	Payment option by country. All countries are specified as strings according to ISO 3166-1 alpha-3	Maximum 3 characters.
buyer_vat_number	String / “UK123123123”	Buyer vat number EU	Maximum 255 characters.

Esempio di richiesta per le merci:
Esempio di richiesta dalla console

curl-v POST
https://merchant.vatcompliance.co/api/1/send/5aae918d97964ff88df64b059c2cc0f8?if_digital=false&if_vat_calculate=false
--header "Content-Type: application/json" 
-d '{
                "transaction_id ": " ttt4565-85546",
                "transaction_datetime": "2017-01-09T08:27:22 +00:00",
                "transaction_sum ": 158.04,
                "currency": "GBP",
                "arrival_country" : " GBR",
                "arrival_city" : " London",
                "arrival_address_line" : " Peckham Road",
                "transaction_status" : "Success",
                "good_code": "62160000",
                "vat_percent": 20.00,
                "vat": 28.73,
                "departure_country" : "AUS",
}'

Elenco dei codici di servizio

contenuti audiovisivi	1
streaming in diretta	2
servizi telefonici	3
servizi telefonici via internet	4
servizi di gestione delle chiamate	5
servizi di cercapersone	6
accesso a Internet	7
immagini	8
musica	9
giochi	10
Giornali elettronici	11
hosting web	12
mantenimento a distanza dei programmi	13
spazio pubblicitario su un sito web	14
libri elettronici	15
licenze	16
incontri	17
educazione a distanza	18
gioco d’azzardo	19
fornitura di beni	20
altro digitale	21