API - crea un ordine
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
| Parametro | Richiesto | Tipo | Formato | Descrizione |
|---|---|---|---|---|
| No | Stringa | Un indirizzo email valido | ||
| firstname | No | Stringa | Nome dell’utente | |
| lastname | No | Stringa | Cognome dell’utente | |
| amount | Si | 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. | |
| fiscalCode | No | Stringa | 16 caratteri | Codice fiscale |
| mobilePhone | No | Stringa | Numero di cellulare, senza prefisso internazionale | |
| 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 |
|---|---|
| Questo valore non è un indirizzo email valido. | |
| amount | Questo valore dovrebbe essere compreso tra 5000 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.
