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 e un link di redirect.

Endpoint

Sandbox: https://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à (Comune di residenza o di domicilio)
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 di default del tuo negozio.
successUrl No Stringa URL URL sul tuo sito, verso il quale reindirizzare l'utente in caso di pagamento andato a buon fine
errorUrl No Stringa URL URL sul tuo sito, verso il quale reindirizzare l'utente in caso di errore, rifiuto del pagamento o abbandono dell'utente
callbackUrl No Stringa URL URL di un tuo server per le chiamate di callback automatizzate.
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 più info in merito a questa feature, contatta il nostro supporto dedicato ai partner a partner@soisy.it.

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 e un link utilizzabile per il redirect dell'utente alla nostra webapp.

{
     "token": <stringa>
     "redirectUrl": <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 alcuni 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}
}

Possibilità di redirect

In questa fase puoi decidere se continuare l'integrazione o reindirizzare l'utente alla nostra webapp. Reindirizza il richiedente su Soisy utilizzando il campo redirectUrl, che trovi nel payload di risposta.