API - 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

ParametroRichiestoTipoFormatoDescrizione
emailNoStringaUn indirizzo email valido
firstnameNoStringaNome dell’utente
lastnameNoStringaCognome dell’utente
amountNoInteroTotale dell’ordine, in centesimi di €
instalmentsNoInteroIl numero di rate, compreso fra 3 e 60. 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.
vatIdNoStringa11 caratteriPartita IVA, Esempio: 12345678912
vatCountryNoStringa2 caratteriPaese partita IVA, Esempio: IT
fiscalCodeNoStringa16 caratteriCodice fiscale
mobilePhoneNoStringaNumero di cellulare, senza prefisso internazionale
cityNoStringaCittà (Comune di residenza o di domicilio)
provinceNoStringa2 caratteri maiuscoliProvincia. Esempio: MI
addressNoStringaVia. Esempio Via Roma, senza virgole né numero civico
civicNumberNoStringaNumero civico
postalCodeNoStringa5 cifreCAP. Esempio: 20100
zeroInterestRateNoBooleanoAbilita il tasso zero.(*) Se omesso, verrà utilizzata l’impostazione di default del tuo negozio.
successUrlNoStringaURLURL sul tuo sito, verso il quale reindirizzare l’utente in caso di pagamento andato a buon fine
errorUrlNoStringaURLURL sul tuo sito, verso il quale reindirizzare l’utente in caso di errore, rifiuto del pagamento o abbandono dell’utente
callbackUrlNoStringaURLURL di un tuo server per le chiamate di callback automatizzate.
orderReferenceNoStringCodice 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.

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

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>
}
				
			

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

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:

ParametroMessaggio
emailQuesto valore non è un indirizzo email valido.
amountQuesto valore dovrebbe essere compreso tra 5000 e 1500000
fiscalCode  Codice fiscale non valido
addressLa combinazione di address, city, province, civicNumber e postalCode per ‘{address}’ non è valida. Esempio valido: via Dei Plauti 2, 10100 Milano (MI)

 

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"
 }
				
			

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

				
					{
    "errors": {errorMessage}
}
				
			

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.

Ciao!

Siamo on line dal lunedì al venerdì dalle 9.30 alle 12.30 e dalle 14.30 alle 17.30

Scrivici in questi orari, grazie!