{ "openapi": "3.0.3", "info": { "title": "BCC-CA eSign API", "version": "draft", "description": "Integration flow:\n\n1. Register the signer in the QuickPass app, using their mobile number as the username. This is needed only once per user.\n\n2. Get an access token using your client username and password.\n\n3. Get the user’s certificate from your business app.\n\n4. Generate the digest of the PDF or XML data in your business app, using the user certificate.\n\n5. Send a sign request for the digest on the user’s behalf. The user authorises it in QuickPass.\n\n6. If authorisation succeeds, merge the returned signature into the document in your business app.\n\nFull Postman documentation: https://documenter.getpostman.com/view/6271383/2sB3Wtqxve" }, "servers": [ { "url": "https://staging-esign.bcc-ca.gov.bd:8443", "description": "Staging" } ], "paths": { "/api/auth/signin": { "post": { "operationId": "get-access-token", "summary": "Get access token", "description": "Authenticate your business app with its client credentials. Use the returned access token as a Bearer token in the other calls.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Client username" }, "password": { "type": "string", "description": "Client password" } }, "required": [ "username", "password" ] }, "example": { "username": "", "password": "" } } } }, "responses": { "200": { "description": "Success / Invalid credentials", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "username": { "type": "string", "description": "Authenticated username" }, "email": { "type": "string", "description": "Authenticated user’s email" }, "accessToken": { "type": "string", "description": "Access token, if authentication succeeded" }, "tokenType": { "type": "string", "description": "Token type (Bearer)" }, "roles": { "type": "array", "description": "Roles for this user", "items": { "type": "string" } } } }, { "$ref": "#/components/schemas/Envelope" } ] }, "examples": { "success": { "summary": "Success", "value": { "id": 17, "username": "", "email": "client@example.com", "roles": [ "ROLE_USER" ], "accessToken": "", "tokenType": "Bearer" } }, "invalid-credentials": { "summary": "Invalid credentials", "value": { "statusCode": 0, "statusText": null, "datetime": "2022-10-25 07:01:07 AM", "status": false, "data": null, "message": "Error: Username or password is invalid", "path": null } } } } } } } } }, "/api/v1/user-certificate": { "post": { "operationId": "get-user-certificate", "summary": "Get user certificate", "description": "Fetch the signer’s certificate. Use the certificate to build the digest, and pass key_alias as credId when you sign.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user’s 11-digit mobile number, starting with 0 and without the country code, e.g. 0174519****." } }, "required": [ "userId" ] }, "example": { "userId": "01XXXXXXXXX" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "string", "description": "The user’s mobile number" }, "key_alias": { "type": "string", "description": "Credential ID of the remote key and certificate" }, "key_status": { "type": "string", "description": "Status of the key and certificate, e.g. ACTIVE" }, "certificate": { "type": "string", "description": "Base64-encoded user certificate" }, "certificate_chain": { "type": "string", "description": "Base64-encoded user certificate chain" } }, "nullable": true } } } ] }, "examples": { "success": { "summary": "Success", "value": { "statusCode": 200, "statusText": "OK", "datetime": "2022-10-27 12:22:36 PM", "status": true, "data": { "user_id": "01XXXXXXXXX", "key_alias": "01XXXXXXXXX_", "key_status": "ACTIVE", "certificate": "", "certificate_chain": "" } } } } } } }, "400": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "user-not-found": { "summary": "User not found", "value": { "statusCode": 400, "statusText": "BAD_REQUEST", "datetime": "2022-10-27 12:29:27 PM", "status": false, "data": null, "message": "UserId doesn't exist - 123456", "path": null } } } } } } } } }, "/api/v1/sign": { "post": { "operationId": "sign-digest", "summary": "Sign data or digest", "description": "Request a signature on a digest you calculated in your business app. The user must authorise the request in QuickPass before the signature is returned.\n\n- Calculate the digest of the PDF or XML document in your business app, using the user certificate.\n\n- Pass the key_alias from Get user certificate as credId.\n\n- The data type is always HASH, so there is no dataType parameter.", "security": [ { "bearerAuth": [], "idToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user’s 11-digit mobile number, starting with 0 and without the country code, e.g. 0174519****." }, "tranId": { "type": "string", "description": "A tracking ID defined by your business app" }, "credId": { "type": "string", "description": "The key_alias value from Get user certificate" }, "documentName": { "type": "string", "description": "Document name" }, "inputData": { "type": "string", "description": "Base64-encoded digest of the PDF or XML data" } }, "required": [ "userId", "tranId", "credId", "documentName", "inputData" ] }, "example": { "userId": "01XXXXXXXXX", "tranId": "123456", "credId": "", "documentName": "test name", "inputData": "MUswGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAvBgkqhkiG9w0BCQQxIgQgP5zPV3pkDnR3G4BPWUajE1gicNR1xOpVbODgUlHm7S8=" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user’s mobile number" }, "tranId": { "type": "string", "description": "Your tracking ID" }, "signature": { "type": "string", "description": "Signature value of the digest" } }, "nullable": true } } } ] }, "examples": { "success": { "summary": "Success", "value": { "statusCode": 200, "statusText": "OK", "datetime": "2023-08-11 01:48:48 AM", "status": true, "data": { "userId": "01XXXXXXXXX", "tranId": "123456", "signature": "" }, "message": "Signing is successful", "path": "/api/v1/sign" } } } } } }, "400": { "description": "Invalid credential / Invalid digest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "invalid-credential": { "summary": "Invalid credential", "value": { "statusCode": 400, "statusText": "BAD_REQUEST", "datetime": "2022-10-25 08:28:03 AM", "status": false, "data": null, "message": "Invalid CredId - Please try with a valid certificate", "path": null } }, "invalid-digest": { "summary": "Invalid digest", "value": { "statusCode": 400, "statusText": "BAD_REQUEST", "datetime": "2022-10-25 08:28:21 AM", "status": false, "data": null, "message": "Failed to process request - DTBS is an invalid base64 data", "path": null } } } } } } } } }, "/api/v1/bulk/sign": { "post": { "operationId": "bulk-sign", "summary": "Bulk sign", "description": "Request signatures on several digests for the same user and credential in one call.", "security": [ { "bearerAuth": [], "idToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user’s 11-digit mobile number, starting with 0 and without the country code, e.g. 0174519****." }, "credId": { "type": "string", "description": "The key_alias value from Get user certificate" }, "tranId": { "type": "string", "description": "A tracking ID defined by your business app" }, "data": { "type": "array", "description": "The documents to sign", "items": { "type": "object", "properties": { "documentName": { "type": "string", "description": "Document name" }, "inputData": { "type": "string", "description": "Base64-encoded digest of the PDF or XML data" } } } } }, "required": [ "userId", "credId", "tranId", "data" ] }, "example": { "userId": "01XXXXXXXXX", "credId": "", "tranId": "123456", "data": [ { "documentName": "test name", "inputData": "MUswGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAvBgkqhkiG9w0BCQQxIgQgP5zPV3pkDnR3G4BPWUajE1gicNR1xOpVbODgUlHm7S8=" }, { "documentName": "test name", "inputData": "MUswGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAvBgkqhkiG9w0BCQQxIgQgP5zPV3pkDnR3G4BPWUajE1gicNR1xOpVbODgUlHm7S8=" } ] } } } }, "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "nullable": true } } } ] } } } } } } }, "/api/v1/user/info": { "post": { "operationId": "get-user-info", "summary": "Get user info (optional)", "description": "Look up a registered user’s details and status.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The user’s 11-digit mobile number, starting with 0 and without the country code, e.g. 0174519****." } }, "required": [ "userId" ] }, "example": { "userId": "01XXXXXXXXX" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Mobile number used as the user ID" }, "user_name": { "type": "string", "description": "The user’s full name" }, "user_email": { "type": "string", "description": "Registered email" }, "status": { "type": "string", "description": "Current status" } }, "nullable": true } } } ] }, "examples": { "success": { "summary": "Success", "value": { "statusCode": 200, "statusText": "OK", "datetime": "2024-05-09 01:46:53.128 PM", "status": true, "data": { "user_id": "01XXXXXXXXX", "user_name": "FULL NAME", "app_name": "SigningHubApp", "user_email": "user@example.com", "user_mobile": "+8801XXXXXXXXX", "status": "ACTIVE", "created_at": "2024-01-11 11:55:48", "profile_id": "adss:sam:profile:004" }, "message": "User info is found", "path": null } } } } } }, "400": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "user-not-found": { "summary": "User not found", "value": { "statusCode": 400, "statusText": "BAD_REQUEST", "datetime": "2022-10-27 12:29:27 PM", "status": false, "data": null, "message": "UserId doesn't exist - 123456", "path": null } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Access token from Get access token" }, "idToken": { "type": "apiKey", "in": "header", "name": "id-token", "description": "Organisation identity token" } }, "schemas": { "Envelope": { "type": "object", "properties": { "statusCode": { "type": "integer", "description": "HTTP status code, e.g. 200, 400, 500" }, "statusText": { "type": "string", "description": "HTTP status text, e.g. OK, BAD_REQUEST" }, "datetime": { "type": "string", "description": "Response time" }, "status": { "type": "boolean", "description": "true or false. Always check this to see whether the request succeeded." }, "data": { "type": "object", "description": "The result if the request succeeded; otherwise the reasons for failure, if available." }, "message": { "type": "string", "description": "Summary of the response" }, "path": { "type": "string", "description": "Request path (optional)" } } } } } }