{ "openapi": "3.1.0", "info": { "title": "Lean Disposable Services", "description": "REST API for enrolling and managing lean disposable certificates for secure digital signatures.\n\nAuthenticate every request with Basic Auth credentials and a client SSL certificate (mTLS). All requests require the `Content-Type: application/json` header.\n\nFor the full integration guide, see the [Lean Disposable documentation](https://docs.namirial.app/products/leandisposable/homepage).", "version": "26.1.0.3" }, "servers": [ { "url": "https://lean.namirialtsp.com/RAWS_DISPOSABLE", "description": "Production environment" }, { "url": "https://lean.test.namirialtsp.com/RAWS_DISPOSABLE", "description": "Development and testing environment" } ], "tags": [ { "name": "Certificate", "description": "Methods to validate holder data, enroll disposable certificates, and send OTP codes.", "externalDocs": { "description": "Certificate API reference", "url": "https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enroll" } }, { "name": "Document", "description": "Methods to retrieve disposable contracts and upload documents related to the issued certificate.", "externalDocs": { "description": "Document API reference", "url": "https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-documents" } }, { "name": "Utility", "description": "Methods to verify service status and retrieve error information.", "externalDocs": { "description": "Error methods reference", "url": "https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-errors" } } ], "paths": { "/api/certificate/sendOtp": { "post": { "tags": [ "Certificate" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOtpDto" }, "examples": { "smsWithText": { "summary": "SMS with custom text", "value": { "certIdOtp": 1234567, "deviceCode": "RHIDP0000000000000", "smsOptions": { "textSMS": "Your OTP code is: $OTP$" } } }, "smsWithTemplate": { "summary": "SMS with template", "value": { "certIdOtp": 1234567, "deviceCode": "RHIDP0000000000000", "smsOptions": { "templateId": "1", "language": "IT" } } }, "email": { "summary": "Email OTP", "value": { "certIdOtp": 1234567, "deviceCode": "RHIDP0000000000000", "emailOptions": { "templateId": "1", "language": "IT" } } } } } } }, "responses": { "200": { "description": "OTP sent successfully. Response body is empty." }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=disposableHolder, message=must not be null}]" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod validateOtp" } }, "certIdOtpNotFound": { "summary": "certIdOtp not found (code 62)", "value": { "code": 62, "message": "idOtp not found" } }, "deviceCodeInvalid": { "summary": "deviceCode not valid (code 249)", "value": { "code": 249, "message": "Invalid Company" } }, "otpNotSent": { "summary": "OTP not sent — smsOptions empty (code 99)", "value": { "code": 99, "message": "OTP was not sent" } } } } } } }, "operationId": "sendOtp", "summary": "Send OTP", "description": "Sends an OTP code to the holder via SMS or email. Use `certIdOtp` and `deviceCode` returned by `enroll`. See [sendOtp](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-send-otp/lean-sendotp-method)." } }, "/api/certificate/validate": { "post": { "tags": [ "Certificate" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateOtpDto" } } } }, "responses": { "200": { "description": "OK" }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=disposableHolder, message=must not be null}]" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod validateOtp" } } } } } } }, "operationId": "validateCertificate", "summary": "Validate certificate data", "description": "Validates the OTP code entered by the holder. See [validate](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-send-otp/lean-sendotp-method)." } }, "/api/certificate/{lraId}/checkData": { "post": { "tags": [ "Certificate" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisposableInputDataDto" }, "examples": { "otpType=SMS": { "summary": "otpType=SMS", "description": "Enroll with otpType=SMS. Requires `disposableContacts.mobile` in E.164 format.", "value": { "disposableHolder": { "firstName": "Mario", "lastName": "Rossi", "identificationType": "ITALIAN_TAX_CODE", "identificationCode": "RSSMRA80A01H501U", "identificationCountry": "IT", "birthDate": "1980-01-01", "birthCity": "Roma" }, "disposableDoc": { "documentType": "CI", "documentNr": "AA0000000", "documentIssuer": "Comune di Roma", "documentIssuerDate": "2020-01-01", "documentIssuerCountry": "IT", "documentExpirationDate": "2030-01-01" }, "disposableCertificate": { "password": "Password01", "securityCode": "Security01", "type": "DISPOSABLE", "otpType": "SMS" }, "disposableContacts": { "mobile": "+390000000000" } } }, "otpType=EMAIL": { "summary": "otpType=EMAIL", "description": "Enroll with otpType=EMAIL. Requires `disposableContacts.email` and EMAIL OTP enabled for the LRA.", "value": { "disposableHolder": { "firstName": "Mario", "lastName": "Rossi", "identificationType": "ITALIAN_TAX_CODE", "identificationCode": "RSSMRA80A01H501U", "identificationCountry": "IT", "birthDate": "1980-01-01", "birthCity": "Roma" }, "disposableDoc": { "documentType": "CI", "documentNr": "AA0000000", "documentIssuer": "Comune di Roma", "documentIssuerDate": "2020-01-01", "documentIssuerCountry": "IT", "documentExpirationDate": "2030-01-01" }, "disposableCertificate": { "password": "Password01", "securityCode": "Security01", "type": "DISPOSABLE", "otpType": "EMAIL" }, "disposableContacts": { "email": "mario.rossi@example.com" } } } } } } }, "responses": { "200": { "description": "OK" }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=disposableHolder, message=must not be null}]" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod validateOtp" } } } } } } }, "operationId": "checkData", "summary": "Check holder data", "description": "Validates holder data, document and certificate parameters before enrolling. Optional step — use it to detect validation errors before calling `enroll`. See [checkData](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-checkdata/lean-checkdata-method)." } }, "/api/certificate/{lraId}/checkDataWitheIDAssertion": { "post": { "tags": [ "Certificate" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisposableEidDataDto" }, "examples": { "IT-EIDNAMIRIAL": { "summary": "IT-EIDNAMIRIAL with SMS OTP", "description": "Check data with IT-EIDNAMIRIAL eID assertion. The assertion is a base64-encoded JSON format with current `iat` timestamp.", "value": { "eidAssertionHolder": { "country": "IT", "eIDType": "EIDNAMIRIAL", "assertion": "eyJnaXZlbl9uYW1lIjoiTWFyaW8iLCJmYW1pbHlfbmFtZSI6IlJvc3NpIiwicGVyc29uX2lkZW50aWZpZXIiOiJUSU5JVC1SU1NNUkE4MEEwMUg1MDFVIiwiYmlydGhfZGF0ZSI6IjE5ODAtMDEtMDEiLCJkb2NfdHlwZSI6Ik5BVElPTkFMX0lERU5USVRZX0NBUkQiLCJjb3VudHJ5IjoiSVQiLCJycF9uYW1lIjoiTmFtaXJpYWwgVGVzdCBSUCIsInJwX2lkIjoidGVzdC1ycC0wMDEiLCJvcmlnaW5hbF9hc3NlcnRpb24iOiJiYXNlNjRfZW5jb2RlZF9zYW1sX2Fzc2VydGlvbl9oZXJlIiwiaWF0IjoxNzA5NTY4MDAwfQ==" }, "contacts": { "mobile": "+390000000000" }, "certificate": { "fullData": false, "otpType": "SMS", "password": "Password01", "securityCode": "Security01", "type": "DISPOSABLE" } } } } } } }, "responses": { "200": { "description": "Validation successful. The holder data is valid and the LRA is authorized for the specified eID type. Response body is empty." }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=eidAssertionHolder, message=must not be null}]" } }, "expiredAssertion": { "summary": "Expired eID assertion (code 237)", "value": { "code": 237, "message": "The input saml assertion is expired" } }, "invalidAssertion": { "summary": "Invalid eID assertion (code 239)", "value": { "code": 239, "message": "Invalid Eid assertion" } }, "lraNotAuthorized": { "summary": "LRA not authorized for eID type (code 244)", "value": { "code": 244, "message": "Error lra not authorize for eID specified" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod checkDataWitheIDAssertion" } } } } } } }, "operationId": "checkDataWitheIDAssertion", "summary": "Check holder data with eID assertion", "description": "Validates holder data using an eID assertion before enrolling. Checks: mandatory fields, allowed values, LRA authorization for the eID type. See [checkDataWitheIDAssertion](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-checkdata/lean-checkdata-eid-assertion-method) and [How to enroll with eID assertion](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-ig-how-to-enroll-disposable-eid-assertion)." } }, "/api/certificate/{lraId}/enroll": { "post": { "tags": [ "Certificate" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisposableInputDataDto" }, "examples": { "otpType=SMS": { "summary": "otpType=SMS", "description": "Enroll with otpType=SMS. Requires `disposableContacts.mobile` in E.164 format.", "value": { "disposableHolder": { "firstName": "Mario", "lastName": "Rossi", "identificationType": "ITALIAN_TAX_CODE", "identificationCode": "RSSMRA80A01H501U", "identificationCountry": "IT", "birthDate": "1980-01-01", "birthCity": "Roma" }, "disposableDoc": { "documentType": "CI", "documentNr": "AA0000000", "documentIssuer": "Comune di Roma", "documentIssuerDate": "2020-01-01", "documentIssuerCountry": "IT", "documentExpirationDate": "2030-01-01" }, "disposableCertificate": { "password": "Password01", "securityCode": "Security01", "type": "DISPOSABLE", "otpType": "SMS" }, "disposableContacts": { "mobile": "+390000000000" } } }, "otpType=EMAIL": { "summary": "otpType=EMAIL", "description": "Enroll with otpType=EMAIL. Requires `disposableContacts.email` and EMAIL OTP enabled for the LRA.", "value": { "disposableHolder": { "firstName": "Mario", "lastName": "Rossi", "identificationType": "ITALIAN_TAX_CODE", "identificationCode": "RSSMRA80A01H501U", "identificationCountry": "IT", "birthDate": "1980-01-01", "birthCity": "Roma" }, "disposableDoc": { "documentType": "CI", "documentNr": "AA0000000", "documentIssuer": "Comune di Roma", "documentIssuerDate": "2020-01-01", "documentIssuerCountry": "IT", "documentExpirationDate": "2030-01-01" }, "disposableCertificate": { "password": "Password01", "securityCode": "Security01", "type": "DISPOSABLE", "otpType": "EMAIL" }, "disposableContacts": { "email": "mario.rossi@example.com" } } } } } } }, "responses": { "200": { "description": "Issued disposable certificate. See [DisposableIssued](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enroll).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisposableIssued" } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=disposableHolder, message=must not be null}]" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod validateOtp" } } } } } } }, "operationId": "enroll", "summary": "Enroll disposable certificate", "description": "Enrolls a disposable certificate for the holder. Returns `certIdOtp` and `deviceCode` required by `sendOtp` and `validate`. See [enroll](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enroll/lean-enroll-method)." } }, "/api/certificate/{lraId}/enrollDisposableWitheIDAssertion": { "post": { "tags": [ "Certificate" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisposableEidDataDto" }, "examples": { "IT-EIDNAMIRIAL": { "summary": "IT-EIDNAMIRIAL with SMS OTP", "description": "Enroll with IT-EIDNAMIRIAL eID assertion. The assertion is a base64-encoded JSON with current `iat` timestamp.", "value": { "eidAssertionHolder": { "country": "IT", "eIDType": "EIDNAMIRIAL", "assertion": "eyJnaXZlbl9uYW1lIjoiTWFyaW8iLCJmYW1pbHlfbmFtZSI6IlJvc3NpIiwicGVyc29uX2lkZW50aWZpZXIiOiJUSU5JVC1SU1NNUkE4MEEwMUg1MDFVIiwiYmlydGhfZGF0ZSI6IjE5ODAtMDEtMDEiLCJkb2NfdHlwZSI6Ik5BVElPTkFMX0lERU5USVRZX0NBUkQiLCJjb3VudHJ5IjoiSVQiLCJycF9uYW1lIjoiTmFtaXJpYWwgVGVzdCBSUCIsInJwX2lkIjoidGVzdC1ycC0wMDEiLCJvcmlnaW5hbF9hc3NlcnRpb24iOiJiYXNlNjRfZW5jb2RlZF9zYW1sX2Fzc2VydGlvbl9oZXJlIiwiaWF0IjoxNzA5NTY4MDAwfQ==" }, "contacts": { "mobile": "+390000000000" }, "certificate": { "fullData": false, "otpType": "SMS", "password": "Password01", "securityCode": "Security01", "type": "DISPOSABLE" } } } } } } }, "responses": { "200": { "description": "Disposable certificate enrolled successfully. Returns certificate details and OTP identifier (if applicable). See [DisposableIssued](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enroll).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisposableIssued" } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=eidAssertionHolder, message=must not be null}]" } }, "expiredAssertion": { "summary": "Expired eID assertion (code 237)", "value": { "code": 237, "message": "The input saml assertion is expired" } }, "invalidAssertion": { "summary": "Invalid eID assertion (code 239)", "value": { "code": 239, "message": "Invalid Eid assertion" } }, "lraNotAuthorized": { "summary": "LRA not authorized for eID type (code 244)", "value": { "code": 244, "message": "Error lra not authorize for eID specified" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod enrollDisposableWitheIDAssertion" } } } } } } }, "operationId": "enrollDisposableWitheIDAssertion", "summary": "Enroll disposable certificate with eID assertion", "description": "Enrolls a disposable certificate using an eID assertion. Returns certificate details and OTP identifier (if `otpType=SMS` or `otpType=EMAIL`). See [enrollDisposableWitheIDAssertion](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enroll/lean-enroll-eid-assertion-method) and [How to enroll with eID assertion](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-ig-how-to-enroll-disposable-eid-assertion)." } }, "/api/document/{lraId}/getAwsParameter": { "get": { "tags": [ "Document" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." }, { "name": "serviceId", "in": "query", "schema": { "type": "string" }, "required": true, "description": "The service name." } ], "responses": { "200": { "description": "AWS credentials for the specified service.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AwsParameterDto" }, "examples": { "awsParameters": { "summary": "AWS parameters", "value": { "serviceId": "SERVICE_NAME", "arn": "arn:aws:iam::000000000000:role/ExampleRole", "accessKey": "AKIAIOSFODNN0EXAMPLE", "secretAccessKey": "wJalrXUtnFEMI0K7MDENG0bPxRfiCYEXAMPLEKEY" } } } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "missingServiceId": { "summary": "serviceId missing (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=serviceId, message=must not be empty}]" } }, "lraNotAuthorized": { "summary": "LRA not authorized for the service (code 245)", "value": { "code": 245, "message": "Error lra not authorize for the specific service" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } } } } } } }, "operationId": "getAwsParameter", "summary": "Get AWS parameters", "description": "Retrieves AWS credentials for the specified LRA and service. Used when a video identification process stores evidence on AWS. See [getAwsParameter](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-documents/lean-getawsparameter-method)." } }, "/api/document/{lraId}/getDisposableContract": { "post": { "tags": [ "Document" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDisposableContractDto" }, "examples": { "pdfOnly": { "summary": "PDF only — blank contract (no holder data)", "value": { "languageCode": [ "EN" ], "docTypes": [ 1 ], "productType": "DISPOSABLE" } }, "pdfAndTxt": { "summary": "PDF and TXT — blank contract", "value": { "languageCode": [ "EN" ], "docTypes": [ 1, 2 ], "productType": "DISPOSABLE" } }, "pdfPrefilled": { "summary": "PDF — pre-filled contract (with holder, doc and contacts)", "value": { "languageCode": [ "EN" ], "docTypes": [ 1 ], "productType": "DISPOSABLE", "disposableHolder": { "firstName": "Test", "lastName": "User", "identificationType": "NATIONAL_IDENTITY_CARD", "identificationCode": "AB0000000", "identificationCountry": "IT", "birthCity": "Rome", "birthDate": "1980-01-01" }, "disposableDoc": { "documentType": "CI", "documentNr": "AB0000000", "documentIssuer": "COMUNE DI TEST", "documentIssuerDate": "2015-01-01", "documentExpirationDate": "2030-01-01", "documentIssuerCountry": "IT" }, "disposableContacts": { "mobile": "+390000000000", "email": "test@example.com" } } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HolderContract" } }, "examples": { "pdfOnly": { "summary": "PDF only — blank contract", "value": [ { "languageCode": "EN", "docTypes": 1, "doc": "", "privacy_link": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ENG_IT.pdf", "termsAndConditions_link": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ENG_IT.pdf", "checkBoxes": [ "In order to sign with electronic signature the Application Form, you need to accept the terms and conditions by checking the boxes below:", "(1) I certify the content of SECTION E - SELF CERTIFICATION BY THE HOLDER", "(2) I accept the General Terms and Conditions (Mod.NAMCA01D) and the one-sided clauses set forth in SECTION F - ONE-SIDED CLAUSES" ] } ] }, "pdfAndTxt": { "summary": "PDF and TXT — blank contract", "value": [ { "languageCode": "EN", "docTypes": 1, "doc": "", "privacy_link": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ENG_IT.pdf", "termsAndConditions_link": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ENG_IT.pdf", "checkBoxes": [ "In order to sign with electronic signature the Application Form, you need to accept the terms and conditions by checking the boxes below:", "(1) I certify the content of SECTION E - SELF CERTIFICATION BY THE HOLDER", "(2) I accept the General Terms and Conditions (Mod.NAMCA01D) and the one-sided clauses set forth in SECTION F - ONE-SIDED CLAUSES" ] }, { "languageCode": "EN", "docTypes": 2, "doc": "", "privacy_link": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ENG_IT.pdf", "termsAndConditions_link": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ENG_IT.pdf", "checkBoxes": [ "In order to sign with electronic signature the Application Form, you need to accept the terms and conditions by checking the boxes below:", "(1) I certify the content of SECTION E - SELF CERTIFICATION BY THE HOLDER", "(2) I accept the General Terms and Conditions (Mod.NAMCA01D) and the one-sided clauses set forth in SECTION F - ONE-SIDED CLAUSES" ] } ] }, "pdfPrefilled": { "summary": "PDF — pre-filled contract (holder data embedded in document)", "value": [ { "languageCode": "EN", "docTypes": 1, "doc": "", "privacy_link": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ENG_IT.pdf", "termsAndConditions_link": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ENG_IT.pdf", "checkBoxes": [ "In order to sign with electronic signature the Application Form, you need to accept the terms and conditions by checking the boxes below:", "(1) I certify the content of SECTION E - SELF CERTIFICATION BY THE HOLDER", "(2) I accept the General Terms and Conditions (Mod.NAMCA01D) and the one-sided clauses set forth in SECTION F - ONE-SIDED CLAUSES" ] } ] } } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=disposableHolder, message=must not be null}]" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod validateOtp" } }, "contractNotFound": { "summary": "Contract template not found for the given languageCode (code 2083)", "value": { "code": 2083, "message": "Contract template not found" } }, "invalidProductType": { "summary": "Invalid or missing productType (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=productType, message=The product type should not be null}]" } }, "invalidDocTypes": { "summary": "Missing or invalid docTypes (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=validDocTypes, message=The doc type parameter should be 1 or 2}, {field=docTypes, message=must not be empty}]" } } } } } } }, "operationId": "getDisposableContract", "summary": "Get disposable contract", "description": "Returns the disposable contract (Mod_NAMCA22D), the privacy document URL, and the T&C document URL for the specified LRA.\n\nThe contract is pre-filled with holder data if `disposableHolder`, `disposableContacts` and `disposableDoc` are all provided. If omitted, the contract is returned blank.\n\nSee [getDisposableContract](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-documents)." } }, "/api/document/{lraId}/getDisposableContractWitheIDAssertion": { "post": { "tags": [ "Document" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDisposableContractWithEidDto" }, "examples": { "IT-EIDNAMIRIAL-prefilled": { "summary": "IT-EIDNAMIRIAL with pre-filled contract", "description": "Get contract with IT-EIDNAMIRIAL eID assertion. The contract will be pre-filled with holder and contact information.", "value": { "eIDAssertionHolder": { "country": "IT", "eIDType": "EIDNAMIRIAL", "assertion": "eyJnaXZlbl9uYW1lIjoiTWFyaW8iLCJmYW1pbHlfbmFtZSI6IlJvc3NpIiwicGVyc29uX2lkZW50aWZpZXIiOiJUSU5JVC1SU1NNUkE4MEEwMUg1MDFVIiwiYmlydGhfZGF0ZSI6IjE5ODAtMDEtMDEiLCJkb2NfdHlwZSI6Ik5BVElPTkFMX0lERU5USVRZX0NBUkQiLCJjb3VudHJ5IjoiSVQiLCJycF9uYW1lIjoiTmFtaXJpYWwgVGVzdCBSUCIsInJwX2lkIjoidGVzdC1ycC0wMDEiLCJvcmlnaW5hbF9hc3NlcnRpb24iOiJiYXNlNjRfZW5jb2RlZF9zYW1sX2Fzc2VydGlvbl9oZXJlIiwiaWF0IjoxNzA5NTY4MDAwfQ==" }, "contacts": { "mobile": "+390000000000", "email": "example@example.com" }, "cert": { "type": "DISPOSABLE", "password": "Password01", "securityCode": "Security01", "withoutUsageLimitLRA": false }, "languageCode": [ "EN" ], "docTypes": [ 1 ] } } } } } }, "responses": { "200": { "description": "Contract documents retrieved successfully. Returns an array of contract documents (Mod_NAMCA22D) with privacy and T&C links. The contract is pre-filled if `eIDAssertionHolder` and `contacts` are provided.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HolderContract" } } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "validationError": { "summary": "Validation error — missing or invalid field (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=languageCode, message=must not be empty}]" } }, "expiredAssertion": { "summary": "Expired eID assertion (code 237)", "value": { "code": 237, "message": "The input saml assertion is expired" } }, "invalidAssertion": { "summary": "Invalid eID assertion (code 235 or 238)", "value": { "code": 235, "message": "Wrong assertion" } }, "contractNotFound": { "summary": "Contract template not found (code 2083)", "value": { "code": 2083, "message": "Contract template not found" } }, "languageNotFound": { "summary": "Language not found (code 2084)", "value": { "code": 2084, "message": "The insert language was not found" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } }, "unauthorizedMethod": { "summary": "Authorization error — user not authorized for this method or LRA (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod getDisposableContractWitheIDAssertion" } } } } } } }, "operationId": "getDisposableContractWitheIDAssertion", "summary": "Get disposable contract with eID assertion", "description": "Retrieves disposable contract documents (Mod_NAMCA22D) using an eID assertion. Returns contract PDF/TXT, privacy document URL (Mod_NAMGDPR03D), and T&C document URL (Mod_NAMCA01D). The contract is pre-filled if `eIDAssertionHolder` and `contacts` are provided. See [getDisposableContractWitheIDAssertion](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-documents/lean-getDisposableContractWithEidAssertion-method) and [How to enroll with eID assertion](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-ig-how-to-enroll-disposable-eid-assertion)." } }, "/api/document/{lraId}/uploadAwsId": { "post": { "tags": [ "Document" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAwsIdDto" } } }, "required": true }, "responses": { "200": { "description": "AWS ID uploaded successfully. Response body is empty." }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "missingFields": { "summary": "Missing required fields (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=deviceCode, message=must not be empty}, {field=awsId, message=must not be empty}]" } }, "invalidDeviceCode": { "summary": "Invalid deviceCode/idOtp pair (code 85)", "value": { "code": 85, "message": "Device type missing or not allowed" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } } } } } } }, "operationId": "uploadAwsId", "summary": "Upload AWS document ID", "description": "Associates an AWS identification reference to an issued disposable certificate. Used when a video identification process stores evidence on AWS.\n\nSee [uploadAwsId](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-documents)." } }, "/api/document/{lraId}/uploadDoc": { "post": { "tags": [ "Document" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDocDto" }, "examples": { "contract": { "summary": "Upload a signed contract (PDF)", "value": { "deviceCode": "RHIDP0000000000000", "idOtp": 1234567, "typeDoc": "CONTRACT", "extension": "pdf", "file": "" } }, "identificationDoc": { "summary": "Upload an identification document (JPEG)", "value": { "deviceCode": "RHIDP0000000000000", "idOtp": 1234567, "typeDoc": "IDENTIFICATION_DOC", "extension": "jpeg", "file": "", "externalKey": "external_key_sample" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedDocumentDto" }, "examples": { "success": { "summary": "Document uploaded successfully", "value": { "deviceCode": "RHIDP0000000000000", "filename": "1234567_a4ece4b3e9626ccfd3bac2eb77c0c1d7950be77e190a64fcf1957279e677ffc7.pdf", "typeDoc": "CONTRACT", "externalKey": null, "uploadDate": 1733496805136 } } } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "missingFields": { "summary": "Missing required fields (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=extension, message=must not be empty}, {field=deviceCode, message=must not be empty}, {field=file, message=must not be empty}, {field=typeDoc, message=must not be empty}]" } }, "invalidTypeDoc": { "summary": "Invalid typeDoc value (code 242)", "value": { "code": 242, "message": "Input parameter invalid: typeDoc" } }, "invalidExtension": { "summary": "Invalid extension value (code 242)", "value": { "code": 242, "message": "Input parameter invalid: extension" } }, "invalidDeviceCode": { "summary": "Invalid deviceCode (code 85)", "value": { "code": 85, "message": "Device type missing or not allowed" } }, "duplicateDocument": { "summary": "Document already uploaded (code 1027)", "value": { "code": 1027, "message": "The file is duplicated" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } } } } } } }, "operationId": "uploadDoc", "summary": "Upload document", "description": "Stores a document linked to an issued disposable certificate. Supported document types: identification evidence, signed contracts (e.g. CA22D), audit logs, identity assertions.\n\n**Note**: if the disposable was issued with `enrollDisposableWitheIDAssertion`, the assertion is stored automatically — do not upload it with this method.\n\nSee [uploadDoc](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-documents)." } }, "/api/utility/errors": { "get": { "tags": [ "Utility" ], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }, "description": "The error code to look up.", "example": 1027 }, { "name": "language", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "EN", "ENG", "IT", "ITA", "DE", "DEU", "ES", "SPA", "RO", "RON" ] }, "description": "Language for the error text. Use ISO 639-1 alpha-2 codes: `EN` (English), `IT` (Italian), `DE` (German), `ES` (Spanish), `RO` (Romanian). ISO 639-2 alpha-3 codes (`ENG`, `ITA`, `DEU`, `SPA`, `RON`) are accepted for legacy compatibility but will not be extended to new languages.", "example": "EN" } ], "responses": { "200": { "description": "Error description returned.\n\n If the error code does not exist, `errorText` is `\"Unspecified error\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorsResponse" }, "examples": { "found": { "summary": "Error code found", "value": { "errorCode": 1027, "errorLanguage": "ENG", "errorLanguage2": "EN", "errorText": "The file is duplicated" } }, "notFound": { "summary": "Error code not found — returns Unspecified error", "value": { "errorCode": 99999, "errorLanguage": "ENG", "errorLanguage2": "EN", "errorText": "Unspecified error" } } } } } }, "500": { "description": "Application error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "invalidLanguage": { "summary": "Invalid language code (code 2084)", "value": { "code": 2084, "message": "The insert language was not found, the allowed languages are: :[de, en, es, it, ro]" } }, "missingParams": { "summary": "Missing required parameters (code 242)", "value": { "code": 242, "message": "Input parameter invalid: [{field=errorLanguage, message=must not be empty}, {field=errorLanguage, message=must not be null}]" } }, "authError": { "summary": "Authentication or authorization error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } } } } } } }, "operationId": "getErrors", "summary": "Get error list", "description": "Returns the human-readable description of an error code in the requested language.\n\n**Note**: requires `Content-Type: application/json` header.\n\n\nSee [getErrors](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-errors)." } }, "/api/utility/verifyLeanStatus": { "get": { "tags": [ "Utility" ], "responses": { "200": { "description": "Service is operational. Response body is empty." } }, "operationId": "verifyLeanStatus", "summary": "Verify Lean service status", "description": "Returns HTTP 200 if the Lean Disposable service is operational. Use this endpoint to monitor service availability.\n\nIf the service is completely unavailable, this endpoint will return 503 Service Unavailable — implement appropriate error handling for this case." } }, "/api/utility/verifyStatusWs": { "get": { "tags": [ "Utility" ], "responses": { "200": { "description": "Service is operational. Response body is empty." } }, "operationId": "verifyStatusWs", "summary": "Verify web service status", "description": "Returns HTTP 200 if the Lean Disposable web service (WS) is operational. Use this endpoint to monitor web service availability.\n\nIf the service is completely unavailable, this endpoint will return 503 Service Unavailable — implement appropriate error handling for this case." } }, "/api/utility/{lraId}/capabilities": { "get": { "tags": [ "Utility" ], "parameters": [ { "name": "lraId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Local Registration Authority (LRA) identifier." } ], "responses": { "200": { "description": "LRA configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LraCapabilitiesResponse" }, "example": { "company": "SPA", "config": { "maxMobileReuseInRangeDaysDisposable": 1, "rangeDaysMobileDisposable": 0 }, "otp": { "allowed": [ "NO_OTP", "EMAIL", "EXTERNAL_OTP", "SMS" ], "constraintsDisposableIdentificationType": [ { "otpType": "NO_OTP", "disposableIdentificationType": [ "DEVISU" ] }, { "otpType": "EMAIL", "disposableIdentificationType": [ "DEVISU" ] } ] }, "disposableIdentificationType": { "allowed": [ "DEVISU", "CNS", "FIRMA", "THIRDPARTY", "WEB", "CIE", "SPID", "ALTRO" ] }, "eid": { "allowed": [ { "country": "IT", "eid": "SPID", "rp": [ { "entityId": "https://esp.test.namirialtsp.com/wizard", "minimumLevel": 2, "expirationTimespanSecond": 1800 } ] }, { "country": "IT", "eid": "CIE", "rp": [] } ] }, "cert": { "allowed": [ "DISPOSABLE", "DISPOSABLE_30_DAYS", "LONG-LIVED" ] }, "op": { "legalEntityId": "00000", "customerId": null, "buReId": { "disposable": "" } }, "legalEntity": { "idLegalEntity": 0, "country": "IT" }, "contract": { "allowed": { "DISPOSABLE": [ { "country": "IT", "language": "IT" }, { "country": null, "language": "EN" } ] } } } } } }, "500": { "description": "Application error. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" }, "examples": { "lraNotFound": { "summary": "LRA not found or not authorized (code 11002)", "value": { "code": 11002, "message": "Unauthorized user to call webmethod getLraCapabilities" } }, "authError": { "summary": "Authentication error (code 11002)", "value": { "code": 11002, "message": "Wrong username or password" } } } } } } }, "operationId": "getLraCapabilities", "summary": "Get LRA capabilities", "description": "Retrieves the configuration of a LRA: allowed OTP types, identification types, eID methods, certificate types, contract templates, and One Platform info. See [getLraCapabilities](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-otherapi/lean-lraCapabilities-method)." } } }, "components": { "schemas": { "AllowedEid": { "type": "object", "properties": { "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2).", "example": "IT" }, "eid": { "type": "string", "description": "eID type.", "example": "SPID" }, "rp": { "type": "array", "items": { "$ref": "#/components/schemas/RelyingPartyDto" }, "description": "List of relying party configurations. Empty if no specific RP is configured." } }, "description": "An allowed eID configuration." }, "AwsParameterDto": { "type": "object", "properties": { "serviceId": { "type": "string", "description": "The service name.", "example": "SERVICE_NAME" }, "arn": { "type": "string", "description": "Amazon Resource Name (ARN) of the IAM role.", "example": "arn:aws:iam::000000000000:role/ExampleRole" }, "accessKey": { "type": "string", "description": "AWS access key ID.", "example": "AKIAIOSFODNN0EXAMPLE" }, "secretAccessKey": { "type": "string", "description": "AWS secret access key.", "example": "wJalrXUtnFEMI0K7MDENG0bPxRfiCYEXAMPLEKEY" } } }, "BuReId": { "type": "object", "properties": { "disposable": { "type": "string" } } }, "Cert": { "type": "object", "properties": { "allowed": { "type": "array", "items": { "type": "string" } } } }, "CompanyCode": { "enum": [ "SPA", "LTD", "NONE" ], "type": "string" }, "ConstraintsDisposableIdentificationType": { "type": "object", "properties": { "otpType": { "type": "string", "description": "OTP type." }, "disposableIdentificationType": { "type": "array", "items": { "type": "string" }, "description": "Identification types allowed for this OTP type." } }, "description": "Constraint between an OTP type and the allowed identification types." }, "Contract": { "type": "object", "properties": { "allowed": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2). Null if the template applies to all countries." }, "language": { "type": "string", "description": "Language code (ISO 639-1 or ISO 639-2)." } } } }, "description": "Map of DisposableType to list of available country/language combinations." } }, "description": "Available contract templates for this LRA, grouped by DisposableType." }, "DisposableAddress": { "type": "object", "properties": { "country": { "type": "string", "description": "Country." }, "province": { "type": "string", "description": "Province." }, "city": { "type": "string", "description": "City." }, "ccat": { "type": "string", "description": "Cadastral code." }, "street": { "type": "string", "description": "Street address." }, "zip": { "type": "string", "description": "Zip/postal code." } }, "required": [ "country", "province", "city", "street", "zip" ] }, "DisposableCertificate": { "type": "object", "properties": { "password": { "type": "string", "description": "Certificate PIN.", "minLength": 8, "maxLength": 32, "pattern": "^[A-Za-z0-9]+$" }, "securityCode": { "type": "string", "description": "Certificate security code.", "minLength": 8, "maxLength": 32, "pattern": "^[A-Za-z0-9]+$" }, "fullData": { "type": "boolean", "description": "Enroll with full profile. Default: `false`." }, "withoutUsageLimitLRA": { "type": "boolean", "description": "Omit LRA limitation of use (LoU). Default: `false`." }, "type": { "$ref": "#/components/schemas/DisposableType", "description": "Disposable certificate type." }, "otpType": { "$ref": "#/components/schemas/DisposableOtpType" }, "transactionLimit": { "$ref": "#/components/schemas/TransactionLimit" }, "limitationOfUse": { "$ref": "#/components/schemas/LimitationOfUse" } }, "required": [ "password", "securityCode" ] }, "DisposableContacts": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the holder. Required if `otpType=EMAIL`.", "format": "email" }, "mobile": { "type": "string", "description": "Mobile phone number in E.164 format with `+` prefix (e.g. `+390000000000`). Required if `otpType=SMS`." } }, "description": "Holder contact information. Required if `otpType=SMS` or `otpType=EMAIL`. Provide `mobile` if `otpType=SMS`, `email` if `otpType=EMAIL`." }, "DisposableDoc": { "type": "object", "properties": { "documentType": { "type": "string", "description": "Identity document type. See [allowed values](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/data-objects#disposabledoc).", "enum": [ "CI", "PASS", "PA", "RP", "CIE", "RT", "DC", "AT" ], "x-enum-descriptions": { "CI": "National identity card", "PASS": "Passport", "PA": "Driving license", "RP": "Residence permit", "CIE": "National Electronic Identity Card", "RT": "Temporary residence permit", "DC": "Documents for embassy/consulate personnel", "AT": "Other" } }, "documentNr": { "type": "string", "description": "Document number." }, "documentIssuer": { "type": "string", "description": "Entity that issued the document." }, "documentIssuerDate": { "format": "date", "type": "string", "description": "Date on which the document was issued. ISO 8601 format `yyyy-MM-dd`. Other formats are not accepted.", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "documentIssuerCountry": { "type": "string", "description": "Country where document was issued. ISO 3166-1 alpha-2 code.", "pattern": "^[A-Z]{2}$" }, "documentExpirationDate": { "format": "date", "type": "string", "description": "Date on which the document was expires. ISO 8601 format `yyyy-MM-dd`. Other formats are not accepted.", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "documentType", "documentNr", "documentIssuerDate", "documentExpirationDate", "documentIssuerCountry" ], "description": "Identity document information.\n\nNot required if one of the following conditions is true:\n- `DisposableIdentification.identificationType` is `AML`\n- `DisposableHolder.identificationType` is one of: `PASSPORT`, `PERSONAL_NUMBER`, `NATIONAL_IDENTITY_CARD`, `DRIVING_LICENSE`, `RESIDENCE_PERMIT`, `RESIDENCE_PERMIT_TEMP`, `EMBASSY_DOCUMENT`" }, "DisposableEidDataDto": { "type": "object", "properties": { "eidAssertionHolder": { "$ref": "#/components/schemas/DisposableeIDAssertionHolder", "description": "eID assertion holder data. Contains the eID type, country, and base64-encoded assertion." }, "certificate": { "$ref": "#/components/schemas/DisposableCertificate", "description": "Certificate configuration. Specifies password, security code, certificate type, and OTP type." }, "contacts": { "$ref": "#/components/schemas/DisposableContacts", "description": "Contact information. Required if `certificate.otpType=SMS` (provide `mobile`) or `certificate.otpType=EMAIL` (provide `email`)." }, "buReId": { "type": "string", "description": "Business relation identifier (optional)." } }, "required": [ "eidAssertionHolder", "certificate" ], "description": "Request body for checkDataWitheIDAssertion. Validates holder data using an eID assertion before enrolling." }, "DisposableHolder": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the holder (UTF-8). See [allowed characters rules](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-faq-allowed-characters).", "maxLength": 64 }, "lastName": { "type": "string", "description": "Last name of the holder (UTF-8). See [allowed characters rules](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-faq-allowed-characters).", "maxLength": 64 }, "identificationType": { "$ref": "#/components/schemas/DisposableHolderIdentificationType", "description": "Type of identification document. Together with `identificationCode` and `identificationCountry` it composes the certificate serial number." }, "identificationCode": { "type": "string", "description": "Unique code of the identification document. Together with `identificationType` and `identificationCountry` it composes the certificate serial number. See [allowed characters rules](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-faq-allowed-characters)." }, "identificationCountry": { "type": "string", "description": "Country where identification was issued. ISO 3166-1 alpha-2 code.", "pattern": "^[A-Z]{2}$" }, "birthDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date of birth in ISO 8601 format (`yyyy-MM-dd`). Example: `1980-01-01`. Note: the date is not validated semantically by the backend.", "example": "1980-01-01" }, "birthCity": { "type": "string", "description": "City of birth. See [allowed characters rules](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/integration-guide/lean-faq-allowed-characters)." }, "citizenShip": { "type": "string", "description": "Citizenship country. ISO 3166-1 alpha-2 code.", "pattern": "^[A-Z]{2}$" } }, "required": [ "firstName", "lastName", "identificationType", "identificationCode", "identificationCountry" ] }, "DisposableIdentification": { "type": "object", "properties": { "identificationType": { "$ref": "#/components/schemas/DisposableIdentificationType", "description": "Identification method type." } }, "required": [ "identificationType" ] }, "DisposableIdentificationType": { "type": "string", "description": "Identification method type. See [allowed values](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enum-types#disposableidentificationtype). Default: `DEVISU`.", "enum": [ "DEVISU", "CNS", "FIRMA", "THIRDPARTY", "WEB", "CIE", "SPID", "AML", "ALTRO" ], "x-enum-descriptions": { "DEVISU": "In person.", "CNS": "Italian National Service Card.", "FIRMA": "Qualified digital signature.", "THIRDPARTY": "Third party.", "WEB": "Video identification.", "CIE": "Italian National Electronic Identity Card.", "SPID": "Italian SPID digital identity.", "AML": "AML identification.", "ALTRO": "Other." } }, "DisposableIdentificationTypeCapabilities": { "type": "object", "properties": { "allowed": { "type": "array", "items": { "type": "string" }, "description": "List of allowed identification types." } }, "description": "Allowed DisposableIdentificationType values for this LRA." }, "DisposableInputDataDto": { "type": "object", "properties": { "disposableHolder": { "$ref": "#/components/schemas/DisposableHolder" }, "disposableContacts": { "$ref": "#/components/schemas/DisposableContacts", "description": "Required if `otpType=SMS` (provide `mobile`) or `otpType=EMAIL` (provide `email`)." }, "disposableDoc": { "$ref": "#/components/schemas/DisposableDoc" }, "disposableCertificate": { "$ref": "#/components/schemas/DisposableCertificate" }, "identification": { "$ref": "#/components/schemas/DisposableIdentification" }, "disposableAddress": { "$ref": "#/components/schemas/DisposableAddress" }, "buReId": { "type": "string", "description": "Business Relation Identifier for One Platform integration.", "maxLength": 255 } }, "required": [ "disposableHolder", "disposableCertificate", "disposableDoc" ] }, "DisposableIssued": { "type": "object", "properties": { "cert": { "type": "string", "format": "binary", "description": "Base64-encoded DER certificate." }, "certType": { "$ref": "#/components/schemas/DisposableType", "description": "Certificate type, as specified in `disposableCertificate.type`." }, "certUsageLimit": { "type": "string", "description": "Limitation of use (LoU) text embedded in the certificate." }, "certSerialNumber": { "type": "string", "description": "Certificate serial number (hex).", "example": "60F2373BFCEB569E" }, "certIdOtp": { "type": [ "integer", "null" ], "format": "int32", "description": "OTP certificate identifier. Pass this value to `sendOtp` and `validate`. `null` if `otpType=NO_OTP` or `otpType=EXTERNAL_OTP`.", "example": 1234567 }, "deviceCode": { "type": "string", "description": "Device code associated with the issued certificate. Pass this value to `sendOtp` and `validate`.", "example": "RHIDP0000000000000" } } }, "DisposableOtpType": { "type": "string", "description": "OTP delivery method. See [allowed values](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enum-types#disposableotptype). Default: `SMS`.", "enum": [ "SMS", "EMAIL", "NO_OTP", "EXTERNAL_OTP" ], "x-enum-descriptions": { "SMS": "OTP sent via SMS.", "EMAIL": "OTP sent via email.", "NO_OTP": "No OTP required.", "EXTERNAL_OTP": "OTP managed externally." } }, "DisposableType": { "type": "string", "description": "Disposable certificate type. See [allowed values](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enum-types#disposabletype). Default: `DISPOSABLE`.", "enum": [ "DISPOSABLE", "DISPOSABLE_30_DAYS", "LONG_LIVED", "DISPOSABLE_FEA" ], "x-enum-descriptions": { "DISPOSABLE": "Valid within 60 minutes and for 60 minutes after enrollment.", "DISPOSABLE_30_DAYS": "Valid within 30 days and for 60 minutes after enrollment.", "LONG_LIVED": "Long-lived disposable certificate.", "DISPOSABLE_FEA": "Non-qualified certificate for Advanced Electronic Signature (AES)." } }, "DisposableeIDAssertionHolder": { "type": "object", "properties": { "country": { "type": "string", "description": "Country code of the eID provider. ISO 3166-1 alpha-2 code. Together with `eIDType` identifies the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID).", "pattern": "^[A-Z]{2}$", "example": "IT" }, "eIDType": { "type": "string", "description": "Type of eID assertion. Together with `country` identifies the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). Allowed values depend on LRA configuration.", "example": "SPID" }, "assertion": { "format": "binary", "type": "string", "description": "Base64-encoded eID assertion. The format depends on `eIDType`." } }, "required": [ "country", "eIDType", "assertion" ], "description": "eID assertion holder data. The `country` and `eIDType` together identify the eID method (e.g., IT-SPID, IT-EIDNAMIRIAL, AT-EID). The `assertion` format depends on the eID type." }, "Eid": { "type": "object", "properties": { "allowed": { "type": "array", "items": { "$ref": "#/components/schemas/AllowedEid" }, "description": "List of allowed eID configurations." } }, "description": "Allowed eID methods for this LRA." }, "EmailOptions": { "type": "object", "properties": { "templateId": { "type": "string", "description": "Identifier of a pre-configured email template." }, "language": { "$ref": "#/components/schemas/EmailTemplateLanguage", "description": "ISO 3166-1 alpha-2 language code." } }, "description": "Email delivery options." }, "EmailTemplateLanguage": { "type": "string", "description": "ISO 3166-1 alpha-2 country code identifying the language of the template (e.g. `IT`, `EN`)." }, "Errors": { "type": "object", "description": "Application error response. The backend returns HTTP 500 for all application errors, including validation failures and authentication errors.", "properties": { "code": { "type": "integer", "format": "int32", "description": "Application error code.", "example": 242 }, "message": { "type": "string", "description": "Human-readable error description. For validation errors (code 242), includes field-level details in the format `Input parameter invalid: [{field=..., message=...}]`.", "example": "Input parameter invalid: [{field=disposableHolder, message=must not be null}]" } }, "required": [ "code", "message" ] }, "GetDisposableContractDto": { "type": "object", "required": [ "languageCode", "docTypes", "productType" ], "description": "Request body for getDisposableContract.", "properties": { "languageCode": { "type": "array", "items": { "type": "string" }, "description": "Languages of the document. ISO 639-1 alpha-2 codes. You can specify more than one value.", "example": [ "IT" ] }, "docTypes": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Type of document to return. `1` = PDF, `2` = TXT. You can specify more than one value.", "example": [ 1, 2 ] }, "productType": { "type": "string", "description": "Type of disposable certificate. See [DisposableType](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enum-types#disposabletype).", "example": "DISPOSABLE" }, "country": { "type": "string", "description": "Country where the end user is located. ISO 3166-1 alpha-2 code. Optional — if not specified, the default template for the given `languageCode` is returned. Required when a LRA needs contracts in the same language but for different legislations (e.g. French contract for France vs Belgium).", "example": "IT" }, "disposableHolder": { "$ref": "#/components/schemas/DisposableHolder", "description": "Holder data. Optional — if provided together with `disposableContacts` and `disposableDoc`, the contract (Mod_NAMCA22D) is pre-filled." }, "disposableContacts": { "$ref": "#/components/schemas/DisposableContacts" }, "disposableDoc": { "$ref": "#/components/schemas/DisposableDoc" }, "disposableCertificate": { "$ref": "#/components/schemas/DisposableCertificate", "description": "Disposable Certificate configuration." } } }, "GetDisposableContractWithEidDto": { "type": "object", "properties": { "eIDAssertionHolder": { "$ref": "#/components/schemas/DisposableeIDAssertionHolder", "description": "eID assertion holder data. If provided, the contract will be pre-filled with holder information." }, "cert": { "$ref": "#/components/schemas/DisposableCertificate", "description": "Certificate configuration. Specifies certificate type and options." }, "contacts": { "$ref": "#/components/schemas/DisposableContacts", "description": "Contact information. If provided, the contract will be pre-filled with contact details." }, "languageCode": { "type": "array", "items": { "type": "string" }, "description": "Languages of the document. ISO 639-1 alpha-2 codes. You can specify multiple values.", "example": [ "EN" ] }, "docTypes": { "type": "array", "items": { "format": "int32", "type": "integer" }, "description": "Document types. Allowed values: `1` (PDF), `2` (TXT). You can specify multiple values.", "example": [ 1 ] }, "country": { "type": "string", "description": "Country code where the final user is located. ISO 3166-1 alpha-2 code. Optional — if not specified, the default template for the specified `languageCode` is returned. Required when a LRA needs contracts in several languages but for different legislations (e.g., French contract for France vs. French contract for Belgium).", "pattern": "^[A-Z]{2}$", "example": "IT" } }, "required": [ "cert", "languageCode", "docTypes" ], "description": "Request body for getDisposableContractWitheIDAssertion. Returns disposable contract (Mod_NAMCA22D), privacy document URL, and T&C document URL." }, "HolderContract": { "type": "object", "description": "A contract document returned by getDisposableContract.", "properties": { "languageCode": { "type": "string", "description": "Language of the document. ISO 639-1 alpha-2 code.", "example": "IT" }, "docTypes": { "type": "integer", "format": "int32", "description": "Document type. `1` = PDF, `2` = TXT.", "example": 2 }, "doc": { "type": "string", "format": "binary", "description": "Base64-encoded document (Mod_NAMCA22D). Pre-filled with holder data if `disposableHolder`, `disposableContacts` and `disposableDoc` were provided in the request." }, "privacy_link": { "type": "string", "description": "URL to download the privacy document (Mod_NAMGDPR03D).", "example": "https://docs.namirialtsp.com/documents/Mod_NAM_GDPR03D_ITA_IT.pdf" }, "termsAndConditions_link": { "type": "string", "description": "URL to download the terms and conditions document (Mod_NAMCA01D).", "example": "https://docs.namirialtsp.com/documents/Mod_NAM_CA01D_ITA_IT.pdf" }, "checkBoxes": { "type": "array", "items": { "type": "string" }, "description": "List of checkbox label strings to be displayed to the user for acceptance." } } }, "LegalEntity": { "type": "object", "properties": { "idLegalEntity": { "format": "int32", "type": "integer", "description": "Legal entity identifier." }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2).", "example": "IT" } }, "description": "Legal entity information stored in the TSP." }, "LimitationOfUse": { "type": "object", "properties": { "withoutUsageLimitLRA": { "type": "boolean", "description": "Omit LRA limitation of use. Default: `false`." }, "language": { "type": "string", "description": "Language of the limitation of use text. ISO 639-1 alpha-2 code." } } }, "LraCapabilitiesResponse": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/CompanyCode" }, "config": { "$ref": "#/components/schemas/LraConfiguration" }, "otp": { "$ref": "#/components/schemas/Otp" }, "disposableIdentificationType": { "$ref": "#/components/schemas/DisposableIdentificationTypeCapabilities" }, "eid": { "$ref": "#/components/schemas/Eid" }, "cert": { "$ref": "#/components/schemas/Cert" }, "op": { "$ref": "#/components/schemas/OnePlatform" }, "legalEntity": { "$ref": "#/components/schemas/LegalEntity" }, "contract": { "$ref": "#/components/schemas/Contract" } }, "description": "LRA configuration returned by getLraCapabilities." }, "LraConfiguration": { "type": "object", "properties": { "maxMobileReuseInRangeDaysDisposable": { "format": "int32", "type": "integer" }, "rangeDaysMobileDisposable": { "format": "int32", "type": "integer" } } }, "OnePlatform": { "type": "object", "properties": { "legalEntityId": { "type": "string" }, "customerId": { "type": [ "string", "null" ] }, "buReId": { "$ref": "#/components/schemas/BuReId" } } }, "Otp": { "type": "object", "properties": { "allowed": { "type": "array", "items": { "type": "string" }, "description": "List of allowed OTP types for this LRA." }, "constraintsDisposableIdentificationType": { "type": "array", "items": { "$ref": "#/components/schemas/ConstraintsDisposableIdentificationType" }, "description": "Constraints between OTP types and identification types. Only present if constraints exist." } }, "description": "Allowed OTP types and their constraints with DisposableIdentificationType." }, "RelyingPartyDto": { "type": "object", "properties": { "entityId": { "type": "string" }, "minimumLevel": { "format": "int32", "type": "integer" }, "expirationTimespanSecond": { "format": "int32", "type": "integer" } } }, "SendOtpDto": { "type": "object", "properties": { "certIdOtp": { "type": "integer", "format": "int32", "description": "OTP certificate identifier returned by `enroll` (`certIdOtp`).", "example": 1234567 }, "deviceCode": { "type": "string", "description": "Device code returned by `enroll` (`deviceCode`).", "example": "RHIDP0000000000000" }, "smsOptions": { "$ref": "#/components/schemas/SmsOptions", "description": "Required if `otpType=SMS`." }, "emailOptions": { "$ref": "#/components/schemas/EmailOptions", "description": "Required if `otpType=EMAIL`." } }, "required": [ "certIdOtp", "deviceCode" ], "description": "Request body for sendOtp. See [sendOtp](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-send-otp/lean-sendotp-method)." }, "SmsOptions": { "type": "object", "properties": { "templateId": { "type": "string", "description": "Identifier of a pre-configured SMS template. Required if `textSMS` is omitted." }, "language": { "$ref": "#/components/schemas/EmailTemplateLanguage", "description": "ISO 3166-1 alpha-2 language code. Required if `templateId` is used." }, "textSMS": { "type": "string", "description": "Custom SMS text. Use `$OTP$` as placeholder for the OTP code. If omitted, the OTP is appended at the end.", "example": "Your OTP code is: $OTP$" } }, "description": "SMS delivery options. Provide either `textSMS` or the `templateId`+`language` pair." }, "TransactionLimit": { "type": "object", "properties": { "value": { "format": "int32", "type": "integer", "description": "Maximum transaction value." }, "currency": { "type": "string", "description": "Currency code. ISO 4217." } } }, "UploadAwsIdDto": { "type": "object", "required": [ "awsId", "deviceCode", "idOtp" ], "description": "Request body for uploadAwsId.", "properties": { "awsId": { "type": "string", "description": "AWS identification reference for the video identification evidence.", "example": "HgI1MM8VuxpoXh6xozcd0gU8rPCvUN6c9HJRY27-K9A2hRm9ZVFFsVx2whuohH63" }, "deviceCode": { "type": "string", "description": "Device code of the issued certificate, returned by `enroll` (`deviceCode`).", "example": "RHIDP0000000000000" }, "idOtp": { "type": "integer", "format": "int32", "description": "OTP certificate identifier returned by `enroll` (`certIdOtp`).", "example": 1234567 }, "externalKey": { "type": "string", "description": "Optional external reference key.", "example": "external_key_sample" } } }, "UploadDocDto": { "type": "object", "required": [ "deviceCode", "file", "typeDoc", "extension" ], "description": "Request body for uploadDoc.", "properties": { "deviceCode": { "type": "string", "description": "Device code of the issued certificate, returned by `enroll` (`deviceCode`).", "example": "RHIDP0000000000000" }, "idOtp": { "type": "integer", "format": "int32", "description": "OTP certificate identifier returned by `enroll` (`certIdOtp`). Use `0` if the disposable has `otpType=NO_OTP`.", "example": 1234567 }, "typeDoc": { "type": "string", "enum": [ "IDENTIFICATION_DOC", "CONTRACT", "AUDIT_LOG", "IDENTITY_ASSERTION" ], "description": "Type of document to upload.", "example": "CONTRACT" }, "extension": { "type": "string", "description": "File extension (not case-sensitive). Allowed values: `pdf`, `zip`, `png`, `jpeg`, `jpg`, `docx`, `doc`, `odt`, `xml`, `json`, `txt`, `mp4`, `m4a`, `m4v`.", "example": "pdf" }, "file": { "type": "string", "description": "Base64-encoded file content.", "example": "" }, "externalKey": { "type": "string", "description": "Optional external reference key.", "example": "external_key_sample" } } }, "UploadedDocumentDto": { "type": "object", "description": "Response returned after a successful document upload.", "properties": { "deviceCode": { "type": "string", "description": "Device code of the certificate the document is linked to.", "example": "RHIDP0000000000000" }, "filename": { "type": "string", "description": "Server-generated filename for the uploaded document.", "example": "1234567_a4ece4b3e9626ccfd3bac2eb77c0c1d7950be77e190a64fcf1957279e677ffc7.pdf" }, "typeDoc": { "type": "string", "enum": [ "IDENTIFICATION_DOC", "CONTRACT", "AUDIT_LOG", "IDENTITY_ASSERTION" ], "description": "Type of the uploaded document.", "example": "CONTRACT" }, "externalKey": { "type": [ "string", "null" ], "description": "External reference key, if provided in the request. `null` if not provided.", "example": "external_key_sample" }, "uploadDate": { "type": "integer", "format": "int64", "description": "Upload timestamp in epoch milliseconds.", "example": 1733496805136 } } }, "ValidateOtpDto": { "type": "object", "required": [ "certIdOtp", "deviceCode", "otpCode" ], "description": "Request body for validateOtp. See [validateOtp](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-validate-otp).", "properties": { "certIdOtp": { "type": "integer", "format": "int32", "description": "OTP certificate identifier returned by `enroll` (`certIdOtp`).", "example": 1234567 }, "deviceCode": { "type": "string", "description": "Device code returned by `enroll` (`deviceCode`).", "example": "RHIDP0000000000000" }, "otpCode": { "type": "string", "description": "OTP code entered by the user.", "example": "123456" } } }, "DisposableHolderIdentificationType": { "type": "string", "description": "Type of document used for holder identification. See [DisposableHolderIdentificationType](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/api-references/lean-enum-types#disposableholderidentificationtype).", "enum": [ "ITALIAN_TAX_CODE", "FOREIGN_TAX_CODE", "PASSPORT", "PERSONAL_NUMBER", "NATIONAL_IDENTITY_CARD", "DRIVING_LICENSE", "RESIDENCE_PERMIT", "RESIDENCE_PERMIT_TEMP", "EMBASSY_DOCUMENT", "AM" ], "x-enum-descriptions": { "ITALIAN_TAX_CODE": "Italy's Codice fiscale (tax code).", "FOREIGN_TAX_CODE": "Personal tax reference number issued by a national tax authority.", "PASSPORT": "Passport number.", "PERSONAL_NUMBER": "National personal/civic registration number.", "NATIONAL_IDENTITY_CARD": "National identity card number.", "DRIVING_LICENSE": "Driving license.", "RESIDENCE_PERMIT": "Residence permit.", "RESIDENCE_PERMIT_TEMP": "Temporary residence permit.", "EMBASSY_DOCUMENT": "Documents for embassy/consulate personnel.", "AM": "AML identification." } }, "ErrorsResponse": { "type": "object", "description": "Error description returned by `getErrors`.", "properties": { "errorCode": { "type": "integer", "format": "int32", "description": "The error code.", "example": 1027 }, "errorLanguage": { "type": "string", "description": "ISO 639-2 alpha-3 language code of the response.", "example": "ENG" }, "errorLanguage2": { "type": "string", "description": "ISO 639-1 alpha-2 language code of the response.", "example": "EN" }, "errorText": { "type": "string", "description": "Human-readable description of the error in the requested language. Returns `\"Unspecified error\"` if the error code does not exist.", "example": "The file is duplicated" } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic Authentication using account credentials.\n\n**Format**: `Authorization: Basic base64(username:password)`\n\nSee [Authentication documentation](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/authentication) for details." }, "sslCertificate": { "type": "mutualTLS", "description": "Mutual TLS (mTLS) authentication using the client SSL certificate provided by Namirial. The certificate must be presented at the TLS handshake level. See [Authentication documentation](https://docs.namirial.app/products/leandisposable/enterprise-documentation/developer-documentation/authentication) for details." } } }, "externalDocs": { "description": "Lean Disposable documentation", "url": "https://docs.namirial.app/products/leandisposable/homepage" }, "security": [ { "basicAuth": [], "sslCertificate": [] } ] }