Invia i documenti

Utilizza questo endpoint per caricare i documenti dei clienti. La nostra applicazione memorizzerà i documenti dei clienti e risponderà con un codice di successo nel caso sia tutto a posto o con un codice e un messaggio di errore in caso contrario. L'elenco dei documenti varia a seconda del tipo di richiesta. In generale dovrai richiedere ai tuoi clienti fronte e retro della carta d'identità e del codice fiscale e un suo selfie. Sì, hai capito bene :)

Il selfie deve essere fatto tenendo il documento in mano, chiaramente visibile. A cosa ci serve? Ad associare il volto del cliente a quello rappresentato sul documento, per attestare che sia effettivamente il cliente ad effetture la richiesta.

Il selfie è il più delicato dei documenti richiesti, nel senso che molto spesso ci arrivano immagini in cui non si vede bene il documento, o non si vede bene la persona, quindi assicurati di specificare bene come fare la foto. Abbiamo anche una guida molto dettagliata che spiega bene tutti gli aspetti legati al selfie, e che puoi usare come spunto per i testi da utilizzare sulla tua piattaforma.

Inoltre, a seconda dei casi, può essere richiesto qualche altro documento. Ad esempio il permesso di soggiorno, se l'utente non proviene dalla Comunità Europea, o un documento di reddito, che è obbligatorio se nella prima chiamata delle API Complete abbiamo restituito il parametro additionalDataNeeded = true.

Richiesta

Endpoint

Sandbox: http://api.sandbox.soisy.it/api/shops/{shopId}/requests/{fiscalCode}/documents
Produzione: https://api.soisy.it/api/shops/{shopId}/requests/{fiscalCode}/documents

Metodi accettati

POST

Autenticazione

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

Prerequisiti

Per accedere a questo endpoint è necessario aver richiesto con successo l'approvazione di una richiesta.

Parametri

Parametro Obbligatorio Tipo Formato Descrizione
identityFrontFile Immagine Jpg, Png, Pdf Immagine del fronte del documento d'identità
identityBackFile Immagine Jpg, Png, Pdf Immagine del retro del documento d'identità
fiscalCodeFrontFile Immagine Jpg, Png, Pdf Immagine del fronte del codice fiscale
fiscalCodeBackFile Immagine Jpg, Png, Pdf Immagine del retro del codice fiscale
selfieFile Immagine Jpg, Png, Pdf Selfie dell'utente
incomeDeclarationFile No* Immagine Jpg, Png, Pdf Un documento di reddito dell'utente. Obbligatorio se additionalDataNeeded è true. È valida la busta paga, il CUD, il 730 o il modello Unico
residencePermitFile No* Immagine Jpg, Png, Pdf Permesso di soggiorno. Obbligatorio per utenti non provenienti dalla Comunità Europea.

La dimensione massima di ogni documento è di 15MB.

Risposta

L'API restituisce un array JSON.

Codici HTTP di risposta

Codice Descrizione
201 Risorsa creata
400 Errore di sintassi o di dominio
403 Impossibile autenticare la richiesta
500 Errore di sistema

Risposta valida

[
    {"fileName: "identityFrontFile", "id": <UUID>},
    {"fileName: "identityBackFile", "id": <UUID>},
    {"fileName: "fiscalCodeFrontFile", "id": <UUID>},
    {"fileName: "fiscalCodeBackFile", "id": <UUID>},
    {"fileName: "selfieFile", "id": <UUID>},
    {"fileName: "incomeDeclarationFile", "id": <UUID>},
    {"fileName: "residencePermitFile", "id": <UUID>},
]

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.

Per ogni parametro sono possibili i seguenti errori:

  • Mancato invio del parametro

    {
        "errors": {
            {parametro}: [
                "Questo valore non dovrebbe essere vuoto." 
            ]
        }
    }
    
  • File vuoto

    {
        "errors": {
            "file": [
                "Un file vuoto non è consentito." 
            ]
        }
    }
    
  • File inviato con dimensioni superiori a quelle consentite

    {
        "errors": {
            "file": [
                "Il file è troppo grande ({size} MB). La dimensione massima consentita è 15 MB." 
            ]
        }
    }
    
  • File inviato con Media Type diverso da application/pdf, application/x-pdf, image/jpeg, image/pjpeg o image/png

    {
        "errors": {
            "file": [
                "Puoi caricare solo file pdf, immagini jpg o png" 
            ]
        }
    }
    

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.

 {
     "error": "Access denied"
 }

Errore 500

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

{
    "errors": {
        "system": [
            "System error"
        ]
    }
}