Crea un ordine

Questa API ti consente di creare un ordine sulla nostra piattaforma.

Richiesta

Questo consente di comunicare alla nostra piattaforma, con una semplice chiamata POST, i dati relativi all'ordine fatto dal cliente sul tuo e-commerce, ad esempio il totale dell'ordine, il nome e il cognome del cliente, più altre opzioni avanzate. Tale chiamata restituirà un token identificativo del pagamento.

Endpoint

Sandbox: http://api.sandbox.soisy.it/api/shops/{shopId}/orders
Produzione: https://api.soisy.it/api/shops/{shopId}/orders

Metodi accettati

POST

Autenticazione

Questa API richiede l'autenticazione tramite shopId e header X-Auth-Token.

Parametri

Parametro Richiesto Tipo Formato Descrizione
email No Stringa Un indirizzo email valido
firstname No Stringa Nome dell'utente
lastname No Stringa Cognome dell'utente
amount No Intero Totale dell'ordine, in centesimi di €
instalments No Intero Il numero di rate, compreso fra 3 e 36. Se il parametro viene omesso, il richiedente potrà scegliere il numero di rate una volta atterrato sulla nostra webapp. Se il parametro viene valorizzato, invece, il numero di rate sarà fisso e non modificabile dal richiedente.
vatId No Stringa 11 caratteri Partita IVA, Esempio: 12345678912
vatCountry No Stringa 2 caratteri Paese partita IVA, Esempio: IT
fiscalCode No Stringa 16 caratteri Codice fiscale
mobilePhone No Stringa Numero di cellulare, senza prefisso internazionale
countryCallingCode No Stringa Prefisso internazionale, esempio +39. Valore di default: +39
city No Stringa Città
province No Stringa 2 caratteri maiuscoli Provincia. Esempio: MI
address No Stringa Via. Esempio via roma, senza virgole né numero civico
civicNumber No Stringa Numero civico
postalCode No Stringa 5 cifre CAP. Esempio: 20100
zeroInterestRate No Booleano Abilita il tasso zero.(*) Se omesso, verrà utilizzata l'impostazione del Canale di Vendita.
successUrl No Stringa URL URL sul tuo sito, verso il quale reindirizzare l'utente in caso di successo
errorUrl No Stringa URL URL sul tuo sito, verso il quale reindirizzare l'utente in caso di errore o abbandono dell'utente
callbackUrl No Stringa URL URL di un tuo server per le chiamate di callback automatizzate. Vedi più avanti in questa pagina
orderReference No String Codice di riferimento dell'ordine dell'ecommerce o altro riferimento

(*) Il tasso zero è una opzione che ti consente di non far pagare interessi ai tuoi clienti. Trovi maggiori informazioni sulle nostre FAQ. Per l'attivazione di questa feature, contatta il nostro supporto dedicato ai partner a partner@soisy.it.

Se stai integrando API Basic...

Subito dopo averci comunicato i dati dell'ordine, dovrai reindirizzare il cliente sulla nostra webapp, specificando il token appena rilasciato:

https://shop.soisy.it/{shopId}#/loan-request?token={token}

In sandbox, dovrai reindirizzare il cliente sulla nostra webapp di prova:

http://shop.sandbox.soisy.it/partnershop#/loan-request?token={token}

Giunto sulla nostra webapp, il cliente potrà completare il pagamento, inserendo i documenti e gli altri dati necessari fino alla firma digitale. Riceverai una notifica, via email e/o server to server, quando il pagamento del cliente verrà confermato o in caso di errori.

Se stai integrando API Advanced o Complete...

È necessario che valorizzi solamente i campi orderReference e callbackUrl.

Psst! 😉 Ricordati di valorizzare almeno il campo callbackUrl per beneficiare delle notifiche server to server.

Conserva poi il token rilasciato nella nostra risposta: ti servirà per la seconda chiamata API Advanced o per la seconda chiamata API Complete.

Ora puoi proseguire l'integrazione nelle pagine API Advanced o API Complete.

Risposta

L'API restituisce un oggetto JSON.

Codici HTTP di risposta

Codice Descrizione
200 Richiesta completata con successo
403 Impossibile autenticare la richiesta
404 Risorsa non trovata
500 Errore di sistema

Risposta valida

L'oggetto JSON restituito in caso di successo contiene il token associato all'ordine, necessario per il redirect dell'utente alla nostra webapp, secondo quanto spiegato nell'introduzione.

{
     "token": <stringa>
}

Risposta di errore

L'oggetto JSON restituito in caso di errore varia a seconda del codice HTTP di risposta.

Errore 400

Le risposte con questo codice HTTP indicano un errore lato client. La richiesta inviata conteneva un parametro formalmente errato.

 {
     "errors": {
         {parametro}: [
             {messaggio}
         ]
      }
 }

Di seguito sono elencati gli errori possibili:

Parametro Messaggio
email Questo valore non è un indirizzo email valido.
amount Questo valore dovrebbe essere compreso tra 25000 e 1500000
fiscalCode Codice fiscale non valido
address La combinazione di address, city, province, civicNumber e postalCode per '{address}' non è valida. Esempio valido: via Dei Plauti 2, 10100 Milano (MI)

Errore 403

La richiesta inviata contiene delle credenziali non valide. Controlla lo shopId e l'header X-Auth-Token. Trovi maggiori info sulle credenziali nel paragrafo dell'autenticazione.

 {
     "errors": "Authentication Failed"
 }

Errore 500

Le risposte con questo codice HTTP indicano che si è verificato un errore di sistema.

{
    "errors": {errorMessage}
}

Notifiche server to server

Di seguito viene spiegato come gestire le notifiche server to server o callback.
Quanto spiegato è valido per tutte le API: Basic, Advanced e Complete.

A ogni cambio di stato dell'ordine, il sistema invierà dei messaggi email all'indirizzo utilizzato per la registrazione del partner.

Inoltre utilizzando il parametro callbackUrl riceverai le notifiche di aggiornamento come chiamate POST. Questo parametro dovrà contenere l'URL valido di una risorsa su un tuo server.

Le notifiche server to server sono essenzialmente delle chiamate POST all'URl che ci hai fornito, e il contenuto è inviato in formato application/x-www-form-urlencoded.

Le notifiche server to server che riceverai sono le seguenti: fornendo l'URL di una risorsa su un tuo server, riceverai le seguenti notifiche di aggiornamento come chiamate POST. Il contenuto della chiamata è il seguente:

[
    "eventId": {eventId},
    "eventMessage": {eventMessage},
    "eventDate": {date},
    "orderToken": {token},
    "orderReference": {orderReference}
]

Dove il {token} ti darà il riferimento al tuo ordine identificativo del pagamento, mentre {orderReference} è il tuo codice di rifermento interno che ci hai inviato nella chiamata API. {eventId} e {eventMessage} conterranno i seguenti valori:

Stato eventId eventMessage Descrizione
Richiesta approvata LoanWasApproved loan approved Pagamento approvato: in attesa del caricamento dei documenti da parte dell'utente
In attesa di finanziamento LoanWasVerified waiting for disbursement L'utente ha caricato i propri documenti ed ha firmato il contratto. Il pagamento verrà finanziato.
Finanziato LoanWasDisbursed payment received Il pagamento è stato effettuato
Annullato UserWasRejected documents check KO I documenti del cliente sono stati rifiutati, quindi il pagamento non è andato a buon fine
Annullato UserWasRejected payment failed Il pagamento non è andato a buon fine