Send ID documents

This endpoint is used to upload customer documents. Our application will memorize the documents and respond with a success code if everything went well or otherwise with a code and an error message.

Request

Endpoint

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

Accepted methods

POST

Authentication

This API requires authentication via shopId and headerX-Auth-Token.

Prerequisites

To access this endpoint, you must have successfully requested the [approval of a request](../ 21_Request / 02_Get_request_approval.md).

Parameters

Parameter Required Type Format Description
identityFrontFile Yes Images Jpg, Png, Pdf Image of the front of the ID card
identityBackFile Yes Images Jpg, Png, Pdf Image of the back of the identity document
fiscalCodeFrontFile Yes Images Jpg, Png, Pdf Image of the front of the fiscal code
fiscalCodeBackFile Yes Images Jpg, Png, Pdf Image of the back of the fiscal code
selfieFile Yes Images Jpg, Png, Pdf User selfie
incomeDeclarationFile No* Images Jpg, Png, Pdf A user income document. Required if additionalDataNeeded is true. A pay stub, the CUD, the 730 or the Single form [modello Unico] is valid
residencePermitFile No* Images Jpg, Png, Pdf Residency permit [Permesso di soggiorno]. Required for users not coming from the European Community.

The maximum size of each document is 15MB.

(*) This parameter may be mandatory in certain situations. See the description column next to the item.

Response

The API returns a JSON array.

HTTP Error codes

Code Description
201 Resource created
400 Syntax or domain error
403 The request could not be authenticated
500 System error

Valid response

[
    {"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>},
]

Error response

The JSON object returned in the event of an error varies depending on the HTTP response code.

Error 400

Responses with this HTTP code indicate a client-side error. The request sent contained a formally incorrect parameter.

For each parameter the following errors are possible:

  • Failed to send the parameter

    {
        "errors": {
            {parameter}: [
                "This value should not be blank." 
            ]
        }
    }
    
  • Empty file

    {
        "errors": {
            "file": [
                "An empty file is not allowed." 
            ]
        }
    }
    
  • File sent with dimensions greater than those allowed

    {
        "errors": {
            "file": [
                "The file is too large ({size} MB). The maximum size allowed is 15 MB." 
            ]
        }
    }
    
  • File sent with Media Type other than application/pdf, application/x-pdf, image/jpeg, image/pjpeg o image/png

    {
        "errors": {
            "file": [
                "You can only upload pdf files, jpg or png images" 
            ]
        }
    }
    

Error 403

The request sent contains invalid credentials. Check the shopId and the X-Auth-Token header. Find more info on credentials in the paragraph about authentication.

 {
     "error": "Access denied"
 }

Error 500

Replies with this HTTP code indicate that a system error has occurred.

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