{ "openapi": "3.0.0", "info": { "title": "API Datasure", "description": "Timestamp or Certify any file with Datasure services.", "contact": { "email": "contact@datasure.net" }, "version": "1.0.0" }, "servers": [ { "url": "https://my.datasure.net", "description": "Production Server" }, { "url": "https://pp-my.datasure.net", "description": "Staging Server" } ], "paths": { "/api/secusign/batch": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a batch signing workflow (legacy path)", "operationId": "96e8117cafc87ac7cc94d7fdd733cf01", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "items" ], "properties": { "strict_mode": { "type": "string", "enum": [ "EMAIL", "NAME", "NONE" ], "nullable": true }, "callback": { "description": "Webhook URL called when batch status changes.", "type": "string", "nullable": true }, "items": { "type": "array", "items": { "required": [ "transaction_uid", "signatory_uid" ], "properties": { "transaction_uid": { "type": "string", "format": "uuid" }, "signatory_uid": { "type": "string", "format": "uuid" } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "201": { "description": "Batch created" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation failed" } }, "deprecated": false, "security": [ { "basicauth": [] } ] } }, "/api/secusign/batch/{uuid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Get a batch signing workflow (legacy path)", "operationId": "dfe268b99cacdc14202a04503174d320", "parameters": [ { "name": "uuid", "in": "path", "description": "Batch UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch fetched" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Batch not found" } }, "deprecated": false, "security": [ { "basicauth": [] } ] } }, "/api/secusign/batch/{uuid}/signatory": { "patch": { "tags": [ "Datasure SecuSign" ], "summary": "Update all signatories attached to a batch signing workflow", "description": "Updates the shared signatory details for every batch item. At least one signatory field must be provided. The update is rejected if any attached signatory has already signed.", "operationId": "443f5a1c0c2355d6c70a6cb4c8135aee", "parameters": [ { "name": "uuid", "in": "path", "description": "Batch UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "minProperties": 1, "properties": { "firstname": { "type": "string", "maxLength": 255, "example": "Jean" }, "lastname": { "type": "string", "maxLength": 255, "example": "Dupont" }, "email": { "type": "string", "format": "email", "maxLength": 255, "example": "jean.dupont@example.com", "nullable": true }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization.", "type": "string", "example": "0612345678", "nullable": true }, "language": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "example": "fr" } }, "type": "object" } } } }, "responses": { "200": { "description": "Batch signatories updated" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Batch not found" }, "422": { "description": "Validation failed or one batch signatory already signed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "properties": { "signatory": { "type": "array", "items": { "type": "string", "example": "Batch signatory details cannot be updated after a signatory has signed." } }, "signed_items": { "type": "array", "items": { "properties": { "transaction_uid": { "type": "string", "format": "uuid" }, "signatory_uid": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } } }, "deprecated": false, "security": [ { "basicauth": [] } ] } }, "/api/secusign/group": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a signatory group", "operationId": "0279dbb9ff01edf5c9c7973fb43dc29c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "transaction_uid", "label", "rule" ], "properties": { "transaction_uid": { "type": "string", "example": "uuid-de-transaction" }, "label": { "type": "string", "example": "Parents" }, "rule": { "type": "string", "enum": [ "REQUIRED_NONE", "REQUIRED_1", "REQUIRED_ALL" ], "example": "REQUIRED_1" } }, "type": "object" } } } }, "responses": { "201": { "description": "Group created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "uid": { "type": "string" }, "label": { "type": "string" }, "rule": { "type": "string" }, "transaction_uid": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive subscription or forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/group/transaction/{transactionUid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "List groups of a transaction", "operationId": "05c3455e18d89512c98b0adb70b07088", "parameters": [ { "name": "transactionUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Groups list", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "properties": { "uid": { "type": "string" }, "label": { "type": "string" }, "rule": { "type": "string" }, "transaction_uid": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive subscription or forbidden" }, "404": { "description": "Transaction not found" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/space": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a SecuSign Space", "operationId": "18cf6b8797cfc684e6e0cbddee30a198", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "label" ], "properties": { "label": { "type": "string", "example": "My Space" }, "is_encrypted": { "description": "Enable encryption (default: true)", "type": "boolean", "example": true }, "is_default": { "description": "Use as the company default space when no space_id is provided on transaction creation. Default: false. A company can only have one default space.", "type": "boolean", "example": false }, "company_id": { "description": "Optional, admin override", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Space created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "is_encrypted": { "type": "boolean" }, "is_default": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive subscription or quota reached" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/space/{space}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Get a SecuSign Space", "operationId": "4387704806c2bb65421332219b75e5ad", "parameters": [ { "name": "space", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Space retrieved", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "company_id": { "type": "integer" }, "is_encrypted": { "type": "boolean" }, "is_default": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated or forbidden company" }, "403": { "description": "Inactive subscription" }, "404": { "description": "Space not found" } }, "security": [ { "basicauth": [] } ] }, "patch": { "tags": [ "Datasure SecuSign" ], "summary": "Update a SecuSign Space", "operationId": "14450d9bd9940abe4d61e4f2fccf64dc", "parameters": [ { "name": "space", "in": "path", "description": "Space ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "label": { "type": "string", "example": "Updated Space" }, "is_encrypted": { "description": "Enable encryption. Once enabled, it cannot be disabled.", "type": "boolean", "example": true }, "is_default": { "description": "Set to true to make this space the company default. The previous default is automatically unset. Setting the current default space to false is not allowed.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Space updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "company_id": { "type": "integer" }, "is_encrypted": { "type": "boolean" }, "is_default": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive subscription or forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/transaction/{uid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Get a transaction with signatories and groups", "operationId": "0aaed98e3adb23a0eaa7671b648bbb1d", "parameters": [ { "name": "uid", "in": "path", "description": "Transaction UID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction fetched", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "transaction": { "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "sent_date": { "type": "string", "format": "date-time", "nullable": true }, "completed_date": { "type": "string", "format": "date-time", "nullable": true }, "cancel_date": { "type": "string", "format": "date-time", "nullable": true }, "customer_user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "space_id": { "type": "string", "nullable": true }, "type": { "type": "string" }, "add_final_page": { "type": "boolean" }, "debug": { "type": "boolean" }, "filename": { "type": "string", "nullable": true }, "file_size": { "type": "integer", "nullable": true }, "file_hash": { "type": "string", "nullable": true }, "download_completed_pdf_url": { "type": "string", "nullable": true }, "external_proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionExternalProofResource" } }, "signatories": { "type": "array", "items": { "type": "object" } }, "groups": { "type": "array", "items": { "type": "object" } }, "ungrouped_signatories": { "type": "array", "items": { "type": "object" } }, "completion": { "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Transaction not found" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/transaction/compose": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a transaction with groups and signatories in one call", "operationId": "018a6d97db0929776caf0502b2971031", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "pdf" ], "properties": { "name": { "type": "string", "nullable": true }, "language": { "type": "string", "example": "fr" }, "add_final_page": { "description": "Add final page with signature certificates", "type": "boolean", "default": true }, "debug": { "description": "Deprecated. The legacy signatory frontend debug tools are disabled; use /api/secusign/transaction/composer to debug field placement.", "type": "boolean", "default": false }, "pdf": { "description": "PDF base64, with or without data:application/pdf;base64, prefix", "type": "string" }, "white_label_uid": { "description": "UID de white label (interdit sur type=external)", "type": "string", "nullable": true }, "callback": { "description": "Webhook URL appelée sur changement d'état", "type": "string", "nullable": true }, "callback_secret": { "description": "Secret partagé pour sécuriser les callbacks/webhooks", "type": "string", "nullable": true }, "external_proofs": { "description": "Client-collected proof elements preserved in the evidence file. Each value may be scalar, JSON object, JSON array, or null.", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignTransactionExternalProofInput" }, "maxItems": 100, "nullable": true }, "expiration_in_days": { "description": "Number of days before the transaction expires (only for internal transactions). If not provided, uses the company subscription setting.", "type": "integer", "maximum": 365, "minimum": 1, "nullable": true }, "groups": { "type": "array", "items": { "required": [ "label", "rule", "signatories" ], "properties": { "label": { "type": "string" }, "rule": { "type": "string", "enum": [ "REQUIRED_NONE", "REQUIRED_1", "REQUIRED_ALL" ] }, "signatories": { "type": "array", "items": { "required": [ "firstname", "lastname", "language", "authentication_type" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "description": "Required when authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "nullable": true }, "external_signatory_id": { "description": "Optional external signatory identifier from integrator systems.", "type": "string", "nullable": true }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when authentication_type is 'sms' or level is not 'simple'.", "type": "string", "example": "0612345678", "nullable": true }, "language": { "type": "string", "example": "fr" }, "authentication_type": { "type": "string", "enum": [ "none", "email", "sms", "url_secret" ] }, "level": { "type": "string", "default": "simple", "enum": [ "simple", "advanced", "qualified" ], "nullable": true }, "signature_method": { "type": "string", "enum": [ "click", "handwritten" ], "nullable": true }, "certificate_type": { "type": "string", "nullable": true }, "visible_signature": { "description": "Visible signature areas (required when add_final_page=false)", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignVisibleSignatureInput" }, "nullable": true }, "document_fields": { "description": "Fill & Sign fields attached to this signatory", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignDocumentFieldInput" }, "nullable": true } }, "type": "object" } } }, "type": "object" } }, "signatories": { "description": "Ungrouped signatories", "type": "array", "items": { "required": [ "firstname", "lastname", "language", "authentication_type" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "description": "Required when authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "nullable": true }, "external_signatory_id": { "description": "Optional external signatory identifier from integrator systems.", "type": "string", "nullable": true }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when authentication_type is 'sms' or level is not 'simple'.", "type": "string", "example": "0612345678", "nullable": true }, "language": { "type": "string", "example": "fr" }, "authentication_type": { "type": "string", "enum": [ "none", "email", "sms", "url_secret" ] }, "level": { "type": "string", "default": "simple", "enum": [ "simple", "advanced", "qualified" ], "nullable": true }, "signature_method": { "type": "string", "enum": [ "click", "handwritten" ], "nullable": true }, "certificate_type": { "type": "string", "nullable": true }, "visible_signature": { "description": "Visible signature areas (required when add_final_page=false)", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignVisibleSignatureInput" }, "nullable": true }, "document_fields": { "description": "Fill & Sign fields attached to this signatory", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignDocumentFieldInput" }, "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Transaction created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Resource created successfully" }, "data": { "properties": { "transaction": { "properties": { "uid": { "type": "string", "example": "4b553f9b-8f46-446f-9cc3-20b4552a2d88" }, "name": { "type": "string", "example": "Foo Bar" }, "status": { "type": "string", "example": "created" }, "sent_date": { "type": "string", "format": "date-time", "nullable": true }, "completed_date": { "type": "string", "format": "date-time", "nullable": true }, "cancel_date": { "type": "string", "format": "date-time", "nullable": true }, "customer_user_id": { "type": "integer", "example": 2 }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "expiration_in_days": { "type": "integer", "nullable": true }, "space_id": { "type": "string", "nullable": true }, "type": { "type": "string", "example": "internal" }, "add_final_page": { "type": "boolean", "example": true }, "debug": { "type": "boolean", "example": false }, "webhook_url": { "type": "string", "nullable": true }, "callback_secret": { "type": "string", "nullable": true }, "white_label_uid": { "type": "string", "nullable": true }, "filename": { "type": "string", "nullable": true }, "file_size": { "type": "integer", "nullable": true }, "file_hash": { "type": "string", "nullable": true }, "download_completed_pdf_url": { "type": "string", "nullable": true }, "external_proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionExternalProofResource" } }, "signatories": { "type": "array", "items": { "$ref": "#/components/schemas/SignatoryResource" } }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/GroupResource" } }, "ungrouped_signatories": { "type": "array", "items": { "$ref": "#/components/schemas/SignatoryResource" } }, "completion": { "properties": { "is_completed": { "type": "boolean", "example": false }, "status": { "type": "string", "example": "created" }, "summary": { "properties": { "totalSignatories": { "type": "integer", "example": 5 }, "signedCount": { "type": "integer", "example": 0 }, "pendingCount": { "type": "integer", "example": 5 }, "completionPercentage": { "type": "number", "format": "float", "example": 0 } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Inactive subscription or forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/v1/transaction/{uid}/external-proof": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Add one or more external proofs to an existing transaction", "description": "Adds one or more client-collected proof elements after transaction creation. The authenticated user must belong to the same company as the transaction owner. Proofs are stored and rendered in the evidence file.", "operationId": "9c6da64a696d20066597fbca8edc2f76", "parameters": [ { "name": "uid", "in": "path", "description": "Transaction UID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SecuSignTransactionExternalProofInput" }, { "type": "array", "items": { "$ref": "#/components/schemas/SecuSignTransactionExternalProofInput" }, "maxItems": 100 } ] }, "example": [ { "key": "client_context", "value": { "provider": "client_app", "metadata": { "ip": "82.12.34.56", "consent": true } } }, { "key": "client_ip", "value": "82.12.34.56" } ] } } }, "responses": { "201": { "description": "External proof created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "external_proof": { "$ref": "#/components/schemas/TransactionExternalProofResource" }, "external_proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionExternalProofResource" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated or unauthorized company" }, "403": { "description": "Inactive subscription or forbidden" }, "404": { "description": "Transaction not found" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/transaction/{uid}/external-proof": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Add one or more external proofs to an existing transaction", "description": "Adds one or more client-collected proof elements after transaction creation. The authenticated user must belong to the same company as the transaction owner. Proofs are stored and rendered in the evidence file.", "operationId": "7adfac16a9c1c4eccce90a371e894602", "parameters": [ { "name": "uid", "in": "path", "description": "Transaction UID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SecuSignTransactionExternalProofInput" }, { "type": "array", "items": { "$ref": "#/components/schemas/SecuSignTransactionExternalProofInput" }, "maxItems": 100 } ] }, "example": [ { "key": "client_context", "value": { "provider": "client_app", "metadata": { "ip": "82.12.34.56", "consent": true } } }, { "key": "client_ip", "value": "82.12.34.56" } ] } } }, "responses": { "201": { "description": "External proof created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "properties": { "external_proof": { "$ref": "#/components/schemas/TransactionExternalProofResource" }, "external_proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionExternalProofResource" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated or unauthorized company" }, "403": { "description": "Inactive subscription or forbidden" }, "404": { "description": "Transaction not found" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/transaction/{uid}/complete": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Complete a transaction even if required signatures are missing", "operationId": "7cda8b46ecbd2283819401ddce86bb7e", "parameters": [ { "name": "uid", "in": "path", "description": "Transaction UID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction forced to completed" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Transaction not found" }, "409": { "description": "Transaction already completed/canceled" }, "422": { "description": "Validation error" } }, "security": [ { "basicauth": [] } ] } }, "/api/secusign/check-identification-status/{signatoryUid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Check the identification status of a signatory", "description": "Retrieves the current status of the identification process associated with a signatory.", "operationId": "8301d1a37b9fb27b5e7d149c2feb8544", "parameters": [ { "name": "signatoryUid", "in": "path", "description": "UID of the signatory", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signatory's identification status retrieved successfully" }, "404": { "description": "No signatory or transaction found using the provided signatory UID" } } } }, "/api/secusign/generate-certificate": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Generate a certificate", "description": "Generates a certificate for the specified signatory UID.", "operationId": "40eb709f30c8d6be22bb3bb1dc20d55e", "requestBody": { "description": "Signatory UID required to generate the certificate", "required": true, "content": { "application/json": { "schema": { "required": [ "signatoryUid" ], "properties": { "signatoryUid": { "description": "UID of the signatory", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "Certificate successfully generated." }, "403": { "description": "The signatory's identification transaction status is not successful" }, "404": { "description": "No signatory found for the provided UID" } } } }, "/api/secusign/check-identification-status-external/{externalId}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Check the identification status of a signatory", "description": "Retrieves the current status of the identification process associated with a signatory.", "operationId": "130c284ed38e85bcfaea088ea6a3d006", "parameters": [ { "name": "externalId", "in": "path", "description": "The external ID provided during transaction creation.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signatory's identification status retrieved successfully" }, "404": { "description": "No signatory or transaction found for the provided external ID" } } } }, "/api/baillif_report/create": { "post": { "tags": [ "Datasure Proof Vault" ], "summary": "Request a new baillif report", "description": "Create a new baillif report with given uids of files and an optional callback URL. All files must have a baillif_deposit_date.", "operationId": "8b54589999b028fa089e4a4921b7fed8", "requestBody": { "description": "Data payload for creating the baillif report", "required": true, "content": { "application/json": { "schema": { "properties": { "files": { "description": "An array of UIDs for vault files to be included in the baillif report. All files must have been deposited to Baillif.", "type": "array", "items": { "type": "string", "example": "1234abcdZYXW" } }, "callback_url": { "description": "An optional callback URL to be invoked upon report creation", "type": "string", "example": "http://your.callback.url/here", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Successfully created request of the baillif report", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "BaillifReport created successfully" }, "baillif_report": { "properties": { "uid": { "type": "string", "example": "1634140799ABCDEFGHJ" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Baillif deposit Validation error : occurs when all the files are not yet deposited to baillif office. You need to retry later.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Baillif deposit Validation error" }, "errors": { "properties": { "files": { "type": "array", "items": { "type": "string", "example": "The following files haven't been deposited to Baillif yet: 1234abcdZYXW, 5678efghIJLK" } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Error creating the Baillif Report request", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Error creating BaillifReport" }, "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/clickncert/pdf/new": { "post": { "tags": [ "Click&Cert" ], "summary": "Sign a PDF document with a Click&Cert keys and certificate, and return PDF signed document (PAdES).", "operationId": "signPDF", "requestBody": { "description": "Pass user credentials and file details for PDF signing", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "certificate_uid", "pdf" ], "properties": { "certificate_uid": { "description": "Unique identifier for the digital certificate provided by Datasure", "type": "string" }, "pdf": { "description": "PDF file to be signed", "type": "string", "format": "binary" }, "visible_seal": { "description": "Optional visible seal details for positioning and style", "required": [ "x", "y", "page", "type" ], "properties": { "x": { "description": "X-coordinate for the seal's position on the PDF page", "type": "integer" }, "y": { "description": "Y-coordinate for the seal's position sur le PDF", "type": "integer" }, "page": { "description": "Page number for the seal. Use -1 for last page, or any positive integer (1, 2, 3, ...) for specific pages", "type": "integer", "example": 1 }, "type": { "description": "Type of seal: 'inline' (fixed size) or 'box' (customizable width/height)", "type": "string", "enum": [ "inline", "box" ] }, "width": { "description": "Width of the seal in pixels. Only applicable for type 'box'. Defaults to 100. Min: 50, Max: 600", "type": "integer", "maximum": 600, "minimum": 50, "nullable": true }, "height": { "description": "Height of the seal in pixels. Only applicable for type 'box'. Defaults to 40. Min: 20, Max: 200", "type": "integer", "maximum": 200, "minimum": 20, "nullable": true }, "logo": { "description": "Base64 encoded logo image (PNG or JPG). Only applicable for type 'box'. Takes priority over subscription logo. Max size: 2MB", "type": "string", "nullable": true }, "signing_reason": { "description": "Custom text to display in the visible signature. Only applicable for type 'box'.", "type": "string", "maxLength": 100, "nullable": true }, "logo_opacity": { "description": "Opacity of the logo (0.0 to 1.0). Only applicable for type 'box'. If not provided, defaults to 0.3", "type": "number", "format": "float", "maximum": 1, "minimum": 0, "example": 0.5, "nullable": true } }, "type": "object", "example": { "x": 100, "y": 150, "page": 1, "type": "box", "width": 150, "height": 60, "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==", "signing_reason": "Document validé pour conformité réglementaire", "logo_opacity": 0.5 } }, "certification_level": { "description": "Optional certification level for the signature. Acceptable values: 'CERTIFICATION_LEVEL_NONE', 'CERTIFICATION_LEVEL_NO_CHANGES_ALLOWED', 'CERTIFICATION_LEVEL_FORM_FILLING', 'CERTIFICATION_LEVEL_FORM_FILLING_AND_ANNOTATIONS'. Defaults to 'CERTIFICATION_LEVEL_NONE'.", "type": "string", "enum": [ "CERTIFICATION_LEVEL_NONE", "CERTIFICATION_LEVEL_NO_CHANGES_ALLOWED", "CERTIFICATION_LEVEL_FORM_FILLING", "CERTIFICATION_LEVEL_FORM_FILLING_AND_ANNOTATIONS" ] }, "totp": { "description": "6-digit TOTP code. Required only when using a QCP-N-QSCD certificate.", "type": "string", "example": "123456" }, "response_content_disposition": { "description": "Optional response content disposition. Defaults to 'inline'. Use 'attachment' to force a file download.", "type": "string", "default": "inline", "enum": [ "inline", "attachment" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "The signed PDF document is returned", "content": { "application/pdf": {} } }, "422": { "description": "Validation error, such as incorrect JSON format for 'visible_seal' or 'certification_level'." }, "403": { "description": "Unauthorized to sign documents for this company." }, "500": { "description": "Internal Server Error." } }, "security": [ { "basicAuth": [] } ] } }, "/api/clickncert/hash/new": { "post": { "tags": [ "Click&Cert" ], "summary": "Sign a SHA256 hash using Click&Cert keys, and get a PKCS#1 Signature", "operationId": "hashSigning", "requestBody": { "description": "Pass user credentials and hash for signing", "required": true, "content": { "application/json": { "schema": { "required": [ "certificate_uid", "hash" ], "properties": { "certificate_uid": { "description": "Unique identifier for the digital certificate provided by Datasure", "type": "string" }, "hash": { "description": "Hexadecimal SHA256 hash to be signed", "type": "string" } }, "type": "object", "example": { "certificate_uid": "297e52b2-8e10-47eb-9d77-36d948df832a", "hash": "a0f820f17d289d873bafd7cf3bb9819499439f7cb55fd7f94a6ad658b80af64e" } } } } }, "responses": { "200": { "description": "The signed hash and related details", "content": { "application/json": { "schema": { "properties": { "certificate_uid": { "description": "The unique identifier of the certificate used", "type": "string" }, "hash": { "description": "The signed hash in hexadecimal format", "type": "string" }, "algorithm OID": { "description": "The OID of the signing algorithm", "type": "string" }, "signature": { "description": "Base64-encoded PKCS#1 signature", "type": "string" }, "verification": { "description": "Signature verification status", "type": "string", "example": "OK" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access to the certificate" }, "422": { "description": "Validation error, such as missing certificate_uid or hash" }, "500": { "description": "Internal Server Error" } }, "security": [ { "basicAuth": [] } ] } }, "/api/clickncert/file/new": { "post": { "tags": [ "Click&Cert" ], "summary": "Sign a file using Click&Cert keys and return a PKCS#1 signature.", "operationId": "fileSigning", "requestBody": { "description": "Pass user credentials and the file to be signed", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "certificate_uid", "file" ], "properties": { "certificate_uid": { "description": "Unique identifier for the digital certificate provided by Datasure", "type": "string" }, "file": { "description": "File to be signed", "type": "string", "format": "binary" } }, "type": "object", "example": { "certificate_uid": "297e52b2-8e10-47eb-9d77-36d948df832a", "file": "(binary file data)" } } } } }, "responses": { "200": { "description": "The signed file and related details", "content": { "application/json": { "schema": { "properties": { "certificate_uid": { "description": "The unique identifier of the certificate used", "type": "string" }, "file_name": { "description": "Original file name", "type": "string" }, "hash": { "description": "The SHA-256 hash of the signed file in hexadecimal format", "type": "string" }, "algorithm OID": { "description": "The OID of the signing algorithm", "type": "string" }, "signature": { "description": "Base64-encoded PKCS#1 signature", "type": "string" }, "verification": { "description": "Signature verification status", "type": "string", "example": "OK" } }, "type": "object" } } } }, "422": { "description": "Validation error, such as missing file or invalid certificate_uid", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "ValidationError" }, "message": { "description": "Detailed validation error message", "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access to the certificate", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "You are not authorized to sign documents for this company." } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "ServerError" }, "message": { "type": "string", "example": "An internal server error occurred." } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/clickncert/certificate": { "get": { "tags": [ "Click&Cert" ], "summary": "Retrieve digital certificate data", "description": "This endpoint allows you to retrieve the certificate data.", "operationId": "getCertificate", "parameters": [ { "name": "id", "in": "query", "description": "ID of the digital certificate", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Certificate data successfully retrieved", "content": { "application/json": { "schema": { "properties": { "certificate_data": { "description": "The digital certificate data", "type": "string" } }, "type": "object" } } } }, "404": { "description": "Certificate not found" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/authentication-token/create": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Send an OTP to a signatory", "description": "Sends an OTP to the specified signatory UID.", "operationId": "766069b250821344bcf9b9ea9f9171a4", "requestBody": { "description": "Signatory UID required to send an OTP", "required": true, "content": { "application/json": { "schema": { "required": [ "signatoryUid" ], "properties": { "signatoryUid": { "description": "UID of the signatory", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP successfully sent" }, "404": { "description": "No signatory found for the provided UID" } } } }, "/api/secusign/verify-otp": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Verify an OTP code sent to a signatory", "description": "Verifies that the OTP code sent to a signatory is correct.", "operationId": "4c3ecbaf974b5cfe9a09bc87e5481529", "requestBody": { "description": "Authentication token UID and OTP code required for verification.", "required": true, "content": { "application/json": { "schema": { "required": [ "auth_token_uid", "otp_code" ], "properties": { "auth_token_uid": { "description": "UID of the authentication token", "type": "string", "format": "uuid" }, "otp_code": { "description": "4-digit OTP code received by the signatory", "type": "string", "pattern": "^\\d{4}$" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP successfully verified" }, "422": { "description": "Validation failed" }, "403": { "description": "Invalid OTP" } } } }, "/api/secusign/transaction/generate-evidence-file/pdf/{transactionUid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Generate evidence file in PDF format", "description": "Generates an evidence file in PDF format for a given transaction UID.", "operationId": "d208f0e22092ec2cf5139a441c560f2d", "parameters": [ { "name": "transactionUid", "in": "path", "description": "UID of the transaction", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Optional PDF language. Supported values: fr, en, es. Defaults to fr when omitted; unsupported values silently fallback to en.", "required": false, "schema": { "type": "string", "default": "fr", "enum": [ "fr", "en", "es" ] } } ], "responses": { "200": { "description": "PDF evidence file generated successfully" }, "404": { "description": "Transaction not found" } } } }, "/api/secusign/transaction/generate-evidence-file/json/{transactionUid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Generate evidence file in JSON format", "description": "Generates an evidence file in JSON format for a given transaction UID.", "operationId": "addd9baf74dc252b64ca6fd42b5a29d6", "parameters": [ { "name": "transactionUid", "in": "path", "description": "UID of the transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON evidence file generated successfully" }, "404": { "description": "Transaction not found" } } } }, "/api/secusign/transaction/generate-evidence-file/xml/{transactionUid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Generate evidence file in XML format", "description": "Generates an evidence file in XML format for a given transaction UID.", "operationId": "13fbf20027e2cbb5ee6afc1d93799a3d", "parameters": [ { "name": "transactionUid", "in": "path", "description": "UID of the transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "XML evidence file generated successfully" }, "404": { "description": "Transaction not found" } } } }, "/api/secusign/identity-provider/validate-signatory": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Validate a signatory using an identity provider", "description": "Validates a signatory by verifying the provided credentials against the identity provider.", "operationId": "b771e74e1c837bea2f9d9beae43ab74f", "requestBody": { "description": "Identity provider and signatory credentials", "required": true, "content": { "application/json": { "schema": { "required": [ "identity_provider_uid", "private_key", "signatory_uid" ], "properties": { "identity_provider_uid": { "description": "UID of the identity provider", "type": "string" }, "private_key": { "description": "Private key of the identity provider", "type": "string" }, "signatory_uid": { "description": "UID of the signatory to validate", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Signatory successfully validated" }, "422": { "description": "Invalid input" }, "403": { "description": "Invalid identity provider credentials" }, "404": { "description": "Identity provider or signatory not found" } } } }, "/api/secusign/signatory/new": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a new signatory", "description": "Create a new signatory for a specified transaction. Accepts JSON and form-data. The 'identity_provider_uid' field is required only if 'level' is 'advanced' ou 'qualified'. If 'level' is not provided, it defaults to 'simple'. Email is required when authentication_type is 'email' or 'sms', and also when level is not 'simple'. Phone is required when authentication_type is 'sms' or level is not 'simple'.", "operationId": "1f44f72050425ae5e06569c07aa365b8", "requestBody": { "description": "Signatory information and related transaction details.", "required": true, "content": { "application/json": { "schema": { "required": [ "firstname", "lastname", "language", "transaction_uid", "authentication_type" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when authentication_type is 'sms' or level is not 'simple'.", "type": "string", "example": "0612345678", "nullable": true }, "email": { "description": "Required when authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "nullable": true }, "external_signatory_id": { "description": "Optional external signatory identifier from integrator systems.", "type": "string", "nullable": true }, "language": { "description": "Language code (2 lowercase characters, e.g., 'fr', 'en')", "type": "string", "maxLength": 2, "minLength": 2 }, "transaction_uid": { "type": "string" }, "group_uid": { "description": "Optional. Attach signatory to an existing group for the transaction.", "type": "string", "nullable": true }, "identity_provider_uid": { "description": "Required only for 'advanced' ou 'qualified' levels.", "type": "string" }, "authentication_type": { "type": "string", "enum": [ "none", "email", "sms", "url_secret" ] }, "authentication_secret": { "description": "Requis si authentication_type = url_secret.", "type": "string", "nullable": true }, "signature_image": { "description": "Optional PNG data URL for pre-captured visual signatures.", "type": "string", "nullable": true }, "signature_input_mode": { "description": "Capture mode used to create signature_image.", "type": "string", "enum": [ "draw", "text", "image" ], "nullable": true }, "level": { "description": "Optional. Defaults to 'simple' if not provided.", "type": "string", "enum": [ "simple", "advanced", "qualified" ] }, "visible_signature": { "description": "Optional visible signature placements.", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignVisibleSignatureInput" } }, "document_fields": { "description": "Optional array of Fill & Sign definitions (text, checkbox, radio).", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignDocumentFieldInput" } }, "lastpageshow_name": { "description": "Optional. If false, hides the name in the last page signature certificate.", "type": "boolean" }, "lastpageshow_phone": { "description": "Optional. If false, hides the phone in the last page signature certificate.", "type": "boolean" }, "lastpageshow_mail": { "description": "Optional. If false, hides the email in the last page signature certificate.", "type": "boolean" }, "lastpageshow_ip": { "description": "Optional. If false, hides the IP address in the last page signature certificate.", "type": "boolean" }, "automation": { "description": "Optional automation flag.", "type": "boolean" }, "certificate_type": { "description": "Optional certificate types on advanced and qualified levels", "type": "string", "enum": [ "QCP-N-QSCD-REMOTE", "NCP+ Person", "LCP Person", "Biometric", "NCP+", "LCP", "QES" ] }, "initial_geolocation": { "description": "Optional JSON object representing the initial geolocation", "type": "string", "format": "json" } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "firstname", "lastname", "language", "transaction_uid", "authentication_type" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when authentication_type is 'sms' or level is not 'simple'.", "type": "string", "example": "0612345678", "nullable": true }, "email": { "description": "Required when authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "nullable": true }, "external_signatory_id": { "description": "Optional external signatory identifier from integrator systems.", "type": "string", "nullable": true }, "language": { "type": "string" }, "transaction_uid": { "type": "string" }, "group_uid": { "description": "Optional. Attach signatory to an existing group for the transaction.", "type": "string", "nullable": true }, "authentication_type": { "type": "string" }, "signature_image": { "description": "Optional PNG data URL for pre-captured visual signatures.", "type": "string", "nullable": true }, "signature_input_mode": { "description": "Capture mode used to create signature_image.", "type": "string", "enum": [ "draw", "text", "image" ], "nullable": true }, "identity_provider_uid": { "description": "Required only for 'advanced' ou 'qualified' levels.", "type": "string" }, "level": { "description": "Optional. Defaults to 'simple' if not provided.", "type": "string", "enum": [ "simple", "advanced", "qualified" ] }, "visible_signature": { "description": "Optional JSON-encoded string representing an array of objects with 'x', 'y', 'page', 'type', 'width' and 'height'.", "type": "string" }, "document_fields": { "description": "Optional JSON-encoded array of Fill & Sign definitions (same structure as SecuSignDocumentFieldInput).", "type": "string" }, "lastpageshow_name": { "description": "Optional. If false, hides the name in the last page signature certificate.", "type": "boolean" }, "lastpageshow_phone": { "description": "Optional. If false, hides the phone in the last page signature certificate.", "type": "boolean" }, "lastpageshow_mail": { "description": "Optional. If false, hides the email in the last page signature certificate.", "type": "boolean" }, "lastpageshow_ip": { "description": "Optional. If false, hides the IP address in the last page signature certificate.", "type": "boolean" }, "automation": { "description": "Optional automation flag.", "type": "boolean" }, "certificate_type": { "description": "Optional certificate types on advanced and qualified levels", "type": "string", "enum": [ "QCP-N-QSCD-REMOTE", "NCP+ Person", "LCP Person", "Biometric", "NCP+", "LCP", "QES" ] }, "initial_geolocation": { "description": "Optional JSON object representing the initial geolocation", "type": "string", "format": "json" } }, "type": "object" } } } }, "responses": { "201": { "description": "Signatory created successfully", "content": { "application/json": { "schema": { "properties": { "uid": { "description": "Unique identifier of the signatory", "type": "string" }, "firstname": { "description": "First name of the signatory", "type": "string" }, "lastname": { "description": "Last name of the signatory", "type": "string" }, "phone": { "description": "Phone number of the signatory", "type": "string" }, "email": { "description": "Email address of the signatory", "type": "string", "nullable": true }, "external_signatory_id": { "description": "External signatory identifier from integrator systems", "type": "string", "nullable": true }, "language": { "description": "Language preference", "type": "string" }, "transaction_uid": { "description": "Transaction UID", "type": "string" }, "signatory_url": { "description": "URL of the signatory's workflow page", "type": "string" }, "signatory_url_direct": { "description": "Présent si authentication_type = url_secret, contient l’URL de workflow avec le paramètre secret.", "type": "string", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Invalid or missing data" }, "403": { "description": "No active Secusign Subscription for a given certificate_type" }, "404": { "description": "Transaction not found" }, "422": { "description": "Invalid input" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/signatory/delegated_ra/new": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a new signatory as Delegated Registration Authority", "description": "Create a new Delegated Registration Authority signatory for a specified transaction. Accepts JSON and form-data. The 'identity_provider_uid' field is required only if 'level' is 'advanced' ou 'qualified'. If 'level' is not provided, it defaults to 'simple'. Email is required when authentication_type is 'email' or 'sms', and also when level is not 'simple'. Phone is required when authentication_type is 'sms' or level is not 'simple'.", "operationId": "1f450af5876b40ee07172e350357566c", "requestBody": { "description": "Signatory information and related transaction details.", "required": true, "content": { "application/json": { "schema": { "required": [ "firstname", "lastname", "language", "transaction_uid", "authentication_type" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when authentication_type is 'sms' or level is not 'simple'.", "type": "string", "example": "0612345678", "nullable": true }, "email": { "description": "Required when authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "nullable": true }, "language": { "description": "Language code (2 lowercase characters, e.g., 'fr', 'en')", "type": "string", "maxLength": 2 }, "transaction_uid": { "type": "string" }, "identity_provider_uid": { "description": "Required only for 'advanced' ou 'qualified' levels.", "type": "string" }, "authentication_type": { "type": "string", "enum": [ "none", "email", "sms", "url_secret" ] }, "authentication_secret": { "description": "Requis si authentication_type = url_secret.", "type": "string", "nullable": true }, "level": { "description": "Optional. Defaults to 'simple' if not provided.", "type": "string", "enum": [ "simple", "advanced", "qualified" ] }, "visible_signature": { "description": "Optional JSON-encoded string representing an array of objects with 'x', 'y', et 'page' keys.", "type": "array", "items": { "required": [ "x", "y", "page", "type" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "page": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "enum": [ "inline", "box" ] }, "width": { "description": "Optional. Default: 180 for box, 480 for inline", "type": "number" }, "height": { "description": "Optional. Default: 90 for box, 22 for inline", "type": "number" } }, "type": "object" } }, "lastpageshow_name": { "description": "Optional. If false, hides the name in the last page signature certificate.", "type": "boolean" }, "lastpageshow_phone": { "description": "Optional. If false, hides the phone in the last page signature certificate.", "type": "boolean" }, "lastpageshow_mail": { "description": "Optional. If false, hides the email in the last page signature certificate.", "type": "boolean" }, "lastpageshow_ip": { "description": "Optional. If false, hides the IP address in the last page signature certificate.", "type": "boolean" }, "automation": { "description": "Optional automation flag.", "type": "boolean" }, "certificate_type": { "description": "Optional certificate types on advanced and qualified levels", "type": "string", "enum": [ "QCP-N-QSCD-REMOTE", "NCP+ Person", "LCP Person", "Biometric", "NCP+", "LCP", "QES" ] }, "initial_geolocation": { "description": "Optional JSON object representing the initial geolocation", "type": "string", "format": "json" } }, "type": "object" } }, "multipart/form-data": { "schema": { "required": [ "firstname", "lastname", "language", "transaction_uid", "authentication_type" ], "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when authentication_type is 'sms' or level is not 'simple'.", "type": "string", "example": "0612345678", "nullable": true }, "email": { "description": "Required when authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "nullable": true }, "language": { "type": "string" }, "transaction_uid": { "type": "string" }, "authentication_type": { "type": "string" }, "identity_provider_uid": { "description": "Required only for 'advanced' ou 'qualified' levels.", "type": "string" }, "level": { "description": "Optional. Defaults to 'simple' if not provided.", "type": "string", "enum": [ "simple", "advanced", "qualified" ] }, "visible_signature": { "description": "Optional JSON-encoded string representing an array of objects with 'x', 'y', 'page', 'type', 'width' and 'height'.", "type": "string" }, "lastpageshow_name": { "description": "Optional. If false, hides the name in the last page signature certificate.", "type": "boolean" }, "lastpageshow_phone": { "description": "Optional. If false, hides the phone in the last page signature certificate.", "type": "boolean" }, "lastpageshow_mail": { "description": "Optional. If false, hides the email in the last page signature certificate.", "type": "boolean" }, "lastpageshow_ip": { "description": "Optional. If false, hides the IP address in the last page signature certificate.", "type": "boolean" }, "automation": { "description": "Optional automation flag.", "type": "boolean" }, "certificate_type": { "description": "Optional certificate types on advanced and qualified levels", "type": "string", "enum": [ "QCP-N-QSCD-REMOTE", "NCP+ Person", "LCP Person", "Biometric", "NCP+", "LCP", "QES" ] }, "initial_geolocation": { "description": "Optional JSON object representing the initial geolocation", "type": "string", "format": "json" } }, "type": "object" } } } }, "responses": { "201": { "description": "Signatory created successfully", "content": { "application/json": { "schema": { "properties": { "uid": { "description": "Unique identifier of the signatory", "type": "string" }, "firstname": { "description": "First name of the signatory", "type": "string" }, "lastname": { "description": "Last name of the signatory", "type": "string" }, "phone": { "description": "Phone number of the signatory", "type": "string" }, "email": { "description": "Email address of the signatory", "type": "string", "nullable": true }, "language": { "description": "Language preference", "type": "string" }, "transaction_uid": { "description": "Transaction UID", "type": "string" }, "signatory_url": { "description": "URL of the signatory's workflow page", "type": "string" }, "signatory_url_direct": { "description": "Présent si authentication_type = url_secret, contient l’URL de workflow avec le paramètre secret.", "type": "string", "nullable": true } }, "type": "object" } } } }, "400": { "description": "Invalid or missing data" }, "403": { "description": "No active Secusign Subscription for a given certificate_type or Delegated Registration Authority role missing" }, "404": { "description": "Transaction not found" }, "422": { "description": "Invalid input" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/signatory/update/{uid}": { "put": { "tags": [ "Datasure SecuSign" ], "summary": "Update an existing signatory", "description": "Updates a signatory for a specified transaction, with the same validation rules as in the create method.", "operationId": "b8c4b5910bc41cea4a8609ec99a48b6d", "parameters": [ { "name": "uid", "in": "path", "description": "UID of the signatory to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Signatory information to update", "required": true, "content": { "application/json": { "schema": { "properties": { "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "phone": { "description": "When provided, must contain digits only or be a valid international phone number. The value is stored without normalization. Required when the resulting authentication_type is 'sms' or the existing level is not 'simple'.", "type": "string", "example": "0612345678" }, "email": { "description": "Required when the resulting authentication_type is 'email' or 'sms', and when level is not 'simple'.", "type": "string", "format": "email", "example": "john.doe@example.com", "nullable": true }, "language": { "type": "string", "enum": [ "UK", "FR" ], "example": "FR" }, "authentication_type": { "type": "string", "enum": [ "none", "email", "sms", "url_secret" ], "example": "email" }, "authentication_secret": { "description": "Requis si authentication_type = url_secret.", "type": "string", "nullable": true }, "lastpageshow_name": { "description": "Optional. If false, hides the name in the last page signature certificate.", "type": "boolean" }, "lastpageshow_phone": { "description": "Optional. If false, hides the phone in the last page signature certificate.", "type": "boolean" }, "lastpageshow_mail": { "description": "Optional. If false, hides the email in the last page signature certificate.", "type": "boolean" }, "lastpageshow_ip": { "description": "Optional. If false, hides the IP address in the last page signature certificate.", "type": "boolean" } }, "type": "object" }, "example": { "firstname": "John", "lastname": "Doe", "phone": "+12025550123", "email": "john.doe@example.com", "language": "FR", "authentication_type": "email", "lastpageshow_name": true, "lastpageshow_phone": true, "lastpageshow_mail": true, "lastpageshow_ip": true } } } }, "responses": { "200": { "description": "Signatory updated successfully" }, "400": { "description": "Invalid transaction status for update" }, "404": { "description": "Signatory or transaction not found" }, "422": { "description": "Validation error" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/signatory/details/{uid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Get details of a signatory", "description": "Retrieves detailed information about a specific signatory.", "operationId": "1b56dab4da3d44f4b580e80e0dad69f7", "parameters": [ { "name": "uid", "in": "path", "description": "UID of the signatory", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signatory details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "uid": { "description": "Unique identifier of the signatory", "type": "string" }, "firstname": { "description": "First name of the signatory", "type": "string" }, "lastname": { "description": "Last name of the signatory", "type": "string" }, "phone": { "description": "Phone number of the signatory", "type": "string" }, "email": { "description": "Email address of the signatory", "type": "string" }, "language": { "description": "Language preference", "type": "string" }, "identity_provider_uid": { "description": "UID of the associated identity provider", "type": "string" }, "approved_date": { "description": "Date when the signatory was approved", "type": "string", "format": "date-time" }, "authentication_type": { "description": "Type of authentication used", "type": "string" }, "visible_signature": { "description": "Information about the visible signature", "type": "string" }, "pad_signature_path": { "description": "Path to the pad signature, if any", "type": "string" }, "authentication_success_token_id": { "description": "Authentication success token ID", "type": "string", "nullable": true }, "transaction_id": { "description": "ID of the associated transaction", "type": "integer" }, "signed_date": { "description": "Date when the signatory signed", "type": "string", "format": "date-time", "nullable": true }, "refused_date": { "description": "Date when the signatory refused", "type": "string", "format": "date-time", "nullable": true }, "hash_presented_pdf": { "description": "Hash of the presented PDF", "type": "string" }, "customer_user_id": { "description": "ID of the customer user", "type": "integer" }, "created_at": { "description": "Creation date of the signatory", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last update date of the signatory", "type": "string", "format": "date-time" }, "initial_geolocation": { "description": "Pair of GPS coordinates in JSON, optional", "type": "string" }, "level": { "description": "Level of the signatory: simple, advanced, or qualified", "type": "string" }, "lastpageshow_name": { "description": "Display signatory's name on the last page", "type": "boolean" }, "lastpageshow_phone": { "description": "Display signatory's phone on the last page", "type": "boolean" }, "lastpageshow_mail": { "description": "Display signatory's email on the last page", "type": "boolean" }, "lastpageshow_ip": { "description": "Display signatory's IP address on the last page", "type": "boolean" }, "automation": { "description": "Enable automatic signature for specific cases, defaults to false", "type": "boolean" } }, "type": "object" } } } }, "404": { "description": "Signatory not found", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access to this signatory", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string" } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/downloads/{token}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Download a signed PDF with a short-lived capability", "operationId": "downloadSignedPdfByToken", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Capability or PDF not found" }, "410": { "description": "Capability expired" } } } }, "/api/secusign/signatory/download_completed_pdf/{uid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Download a signed PDF as its owning customer", "operationId": "downloadSignedPdf", "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Signatory or PDF not found" } }, "deprecated": true, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/signatory/verify-identity/{uid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Verify the identity of a signatory", "description": "Checks and returns the verification status of a signatory's identity.", "operationId": "f1d460da6f733bab994cc5281cab11cd", "parameters": [ { "name": "uid", "in": "path", "description": "UID of the signatory to verify", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Identity verification status returned" }, "404": { "description": "Signatory not found" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/sign": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Sign a document", "description": "Signs a document with hash signing.", "operationId": "1d6811ab30b02795cbd2b8bb85da6728", "requestBody": { "description": "Document data to sign, signatory and authentication validation.", "required": true, "content": { "application/json": { "schema": { "required": [ "signatoryUid" ], "properties": { "hash": { "description": "Hexadecimal SHA256 hash of the document to sign", "type": "string", "maxLength": 64, "minLength": 64, "pattern": "^[A-Fa-f0-9]{64}$" }, "signatoryUid": { "description": "UID of the signatory", "type": "string", "format": "uuid", "nullable": true }, "auth_token_uid": { "description": "Authentication token ID (requise sauf pour authentication_type = url_secret)", "type": "string", "format": "uuid", "nullable": true }, "secret": { "description": "Secret d'URL requis lorsque authentication_type = url_secret", "type": "string", "nullable": true }, "signature_image": { "description": "PNG data URL generated from the handwritten, typed, or imported signature image.", "type": "string", "nullable": true }, "signature_input_mode": { "description": "Capture mode used to create signature_image.", "type": "string", "enum": [ "draw", "text", "image" ], "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Document signed successfully" }, "422": { "description": "Validation failed" }, "400": { "description": "Invalid or missing data" }, "403": { "description": "Unauthorized user or invalid authentication token" }, "404": { "description": "No valid signing context found using data provided" }, "409": { "description": "Certificate data not yet delivered" } } } }, "/api/secusign/signatory/delete/{uid}": { "delete": { "tags": [ "Datasure SecuSign" ], "summary": "Deletes a signatory and its related data", "description": "This endpoint deletes a signatory, its associated authentication tokens, and removes related files from S3 storage.", "operationId": "570440c246f5d99803db2cca6ff3b665", "parameters": [ { "name": "uid", "in": "path", "description": "UID of the signatory to be deleted", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signatory and related data deleted successfully" }, "404": { "description": "Signatory not found" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/get-certificate-form/{signatoryUid}/{type}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Generate a certificate form as string or pdf", "description": "Generates a certificate form for a given signatory UID and type (text or pdf).", "operationId": "21d2199b0d631e9c291fedd2caf2dcde", "parameters": [ { "name": "signatoryUid", "in": "path", "description": "UID of the signatory", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "description": "Response format: 'text' returns a plain string, 'pdf' returns a PDF document.", "required": true, "schema": { "type": "string", "enum": [ "text", "pdf" ] } } ], "responses": { "200": { "description": "Certificate form generated successfully" }, "400": { "description": "Invalid signatory UID or type" }, "404": { "description": "No signatory found for the provided UID" } } } }, "/api/secusign/check-certificate-data/{signatoryUid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Check and retrieve certificate status and data", "description": "Checks the certificate issuance status and returns the certificate data if it has been delivered.", "operationId": "d4fe8db43fef65ff14f017e65fbb48df", "parameters": [ { "name": "signatoryUid", "in": "path", "description": "UID of the signatory", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate successfully delivered" }, "202": { "description": "Certificate generation is still in progress" }, "400": { "description": "Invalid signatory UID format" }, "404": { "description": "No signatory found for the provided UID" } } } }, "/api/secusign/accept-certificate-form-cgu": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Register certificate form acceptance", "description": "Registers the acceptance of the certificate form for a given signatory UID.", "operationId": "1f21c317270d60a1fc8aadd72ba9776f", "requestBody": { "description": "Signatory UID required to register acceptance", "required": true, "content": { "application/json": { "schema": { "required": [ "signatoryUid" ], "properties": { "signatoryUid": { "description": "UID of the signatory", "type": "string", "format": "uuid" } }, "type": "object" } } } }, "responses": { "200": { "description": "Acceptance date successfully registered" }, "422": { "description": "Validation error" }, "404": { "description": "No signatory found for the provided UID" } } } }, "/api/secusign/signatory/{signatoryUid}/approved_date": { "patch": { "tags": [ "Datasure SecuSign" ], "summary": "Validate the identity of a signatory as Delegated Registration Authority", "description": "Validates the identity of a signatory created by a Delegated Registration Authority company using the specified signatoryUid", "operationId": "6939f46f78a0ac3bbf31af00065f8100", "parameters": [ { "name": "signatoryUid", "in": "path", "description": "UID of the signatory", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signatory's identification successfully validated" }, "403": { "description": "Unauthorized user, signatory or company's SecuSign subscription" }, "404": { "description": "No signatory found using the provided UID" } } } }, "/api/secusign/transaction/new": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Create a new SecuSign transaction", "operationId": "48f673477a48975ddbd097eb622b62eb", "requestBody": { "description": "PDF file and eventually callback URL", "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "type": { "type": "string", "enum": [ "internal", "external" ], "nullable": true }, "pdf": { "description": "PDF file to sign (filename must not exceed 255 characters)", "type": "string", "format": "binary" }, "documentHash": { "description": "Hexadecimal SHA256 hash of the document (required if type is external)", "type": "string", "maxLength": 64, "minLength": 64, "pattern": "^[A-Fa-f0-9]{64}$" }, "external_id": { "description": "External ID (required if type is external)", "type": "string" }, "callback": { "description": "Callback URL to call when completed (optional)", "type": "string", "format": "uri", "maxLength": 1000 }, "callback_secret": { "description": "Secret to validate callback authenticity for client side (optional). It will be passed to the url trigger as parameter.", "type": "string" }, "white_label_uid": { "description": "White label UID for branding purposes (optional)", "type": "string" }, "name": { "description": "Optional name for the transaction. if empty, it will automatically take the name of the PDF file", "type": "string", "maxLength": 255 }, "language": { "description": "Language code (2 lowercase characters). Supported languages: 'fr', 'es', 'en'. Default: 'fr'. Fallback: 'en' if the specified language is not supported.", "type": "string", "maxLength": 2, "minLength": 2 }, "space_id": { "description": "Optional SecuSign space ID. If omitted, the only or default company space is selected automatically.", "type": "string", "format": "uuid", "nullable": true }, "add_final_page": { "description": "Whether to add the final certificate page to the signed PDF. Default: true. If set to false, all signatories must provide visible_signature parameter.", "type": "boolean", "nullable": true }, "expiration_in_days": { "description": "Number of days before the transaction expires (only for internal transactions). If not provided, uses the company subscription setting.", "type": "integer", "maximum": 365, "minimum": 1, "nullable": true }, "debug": { "description": "Deprecated. The legacy signatory frontend debug tools are disabled; use /api/secusign/transaction/composer to debug field placement.", "type": "boolean", "nullable": true }, "external_proofs": { "description": "JSON-encoded array of client-collected proof elements. Each item must contain key and value. Value may be scalar, object, or array.", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Transaction successfully created" }, "200": { "description": "Transaction already created" }, "422": { "description": "Invalid data" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/transaction/update/{uid}": { "post": { "tags": [ "Datasure SecuSign" ], "summary": "Updates an existing transaction", "description": "This endpoint updates an existing transaction and returns the updated details.", "operationId": "b29f89159358554bba79935323be88e0", "parameters": [ { "name": "uid", "in": "path", "description": "Unique identifier of the transaction", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Data for updating the transaction", "required": true, "content": { "application/json": { "schema": { "properties": { "callback": { "description": "New callback URL", "type": "string", "format": "uri" }, "name": { "description": "New name for the transaction", "type": "string" }, "white_label_uid": { "description": "White label UID for the company", "type": "string" }, "callback_secret": { "description": "Optional secret for webhook URL", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Transaction updated successfully", "content": { "application/json": { "schema": { "properties": { "uid": { "description": "Unique identifier of the transaction", "type": "string" }, "name": { "description": "Name of the transaction", "type": "string" }, "white_label_uid": { "description": "White label UID, if any", "type": "string" }, "sent_date": { "description": "Date the transaction was sent", "type": "string", "format": "date-time" }, "completed_date": { "description": "Date the transaction was completed", "type": "string", "format": "date-time" }, "cancel_date": { "description": "Date the transaction was canceled", "type": "string", "format": "date-time", "nullable": true }, "status": { "description": "Current status of the transaction", "type": "string" }, "user_firstname": { "description": "First name of the user", "type": "string" }, "user_lastname": { "description": "Last name of the user", "type": "string" }, "company_name": { "description": "Name of the company", "type": "string" }, "webhook_url": { "description": "Webhook URL for callbacks", "type": "string" }, "webhook_secret": { "description": "Secret for webhook security", "type": "string" }, "signatories": { "description": "List of signatory UIDs", "type": "array", "items": { "type": "string" } }, "created_at": { "description": "Creation date of the transaction", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last update date of the transaction", "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Validation error message", "type": "string" }, "details": { "description": "Details of the validation error", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/transaction/details/{uid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Retrieves details of a transaction", "description": "This endpoint returns the details of a specific transaction based on its UID.", "operationId": "2fd88cc6946f65d725659e7027db7a77", "parameters": [ { "name": "uid", "in": "path", "description": "Unique identifier of the transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "uid": { "description": "Unique identifier of the transaction", "type": "string" }, "name": { "description": "Name of the transaction", "type": "string" }, "white_label_uid": { "description": "White label UID, if any", "type": "string" }, "sent_date": { "description": "Date the transaction was sent", "type": "string", "format": "date-time" }, "completed_date": { "description": "Date the transaction was completed", "type": "string", "format": "date-time" }, "cancel_date": { "description": "Date the transaction was canceled", "type": "string", "format": "date-time", "nullable": true }, "status": { "description": "Current status of the transaction", "type": "string" }, "user_firstname": { "description": "First name of the user", "type": "string" }, "user_lastname": { "description": "Last name of the user", "type": "string" }, "company_name": { "description": "Name of the company", "type": "string" }, "webhook_url": { "description": "Webhook URL for callbacks", "type": "string" }, "webhook_secret": { "description": "Secret for webhook security", "type": "string" }, "signatories": { "description": "List of signatory UIDs", "type": "array", "items": { "type": "string" } }, "created_at": { "description": "Creation date of the transaction", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last update date of the transaction", "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string" } }, "type": "object" } } } }, "403": { "description": "Unauthorized access to this transaction", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string" } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/transaction/delete/{uid}": { "delete": { "tags": [ "Datasure SecuSign" ], "summary": "Deletes a transaction and its related data", "description": "This endpoint deletes a transaction along with its associated signatories and authentication tokens, and removes related files from S3 storage.", "operationId": "8df83509aac09076cae5d36e71c59505", "parameters": [ { "name": "uid", "in": "path", "description": "UID of the transaction to be deleted", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction and related data deleted successfully" }, "404": { "description": "Transaction not found" } }, "security": [ { "basicAuth": [] } ] } }, "/api/secusign/transaction/download_completed_pdf/{uid}": { "get": { "tags": [ "Datasure SecuSign" ], "summary": "Download the completed PDF", "description": "Download the completed PDF for a transaction, if the transaction status is 'completed'.", "operationId": "downloadCompletedPdf", "parameters": [ { "name": "uid", "in": "path", "description": "The unique identifier of the transaction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Transaction not found or PDF not available" }, "403": { "description": "Transaction is not completed" }, "500": { "description": "Failed to retrieve PDF" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/get-tsr/{serialNumber}": { "get": { "tags": [ "Datasure TSA" ], "summary": "Download TSR - Timestamping Response (Premium)", "description": "Download the Timestamping Response (TSR) for a given serial number, encoded in DER format complying RFC 3161.", "operationId": "3766af250328ae8ab87c89072377db62", "parameters": [ { "name": "serialNumber", "in": "path", "description": "Serial number of the timestamp record", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "TSR downloaded successfully", "content": { "application/octet-stream": {} } }, "404": { "description": "TSR not available or not found" }, "500": { "description": "Internal server error" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/get-details/{serialNumber}": { "get": { "tags": [ "Datasure TSA" ], "summary": "Get Details of a Timestamp Record (Premium)", "description": "Retrieves detailed information of a Timestamp Record based on its serial number. The 'token' is the TSR, encoded base64.", "operationId": "f1bfb5981f1960a42d93166d86b9673b", "parameters": [ { "name": "serialNumber", "in": "path", "description": "Serial number of the Timestamp Record", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Timestamp Record details", "content": { "application/json": { "schema": { "properties": { "serial_number": { "type": "string" }, "fingerprint": { "type": "string" }, "hash_algorithm": { "type": "string" }, "nonce": { "type": "string" }, "oid": { "type": "string" }, "timestamp": { "type": "string" }, "unix_time": { "type": "integer" }, "version": { "type": "string" }, "token": { "description": "TSR according to RFC3161, encoded in DER format", "type": "string" } }, "type": "object" } } } }, "404": { "description": "Timestamp Record not found" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/find-timestamps/{fingerprint}": { "get": { "tags": [ "Datasure TSA" ], "summary": "Search Timestamp Records by Fingerprint (Premium)", "description": "Searches for all Timestamp Records containing the given fingerprint and returns an array of their serial numbers.", "operationId": "1c9e44068452e7edc1718c9d807e049e", "parameters": [ { "name": "fingerprint", "in": "path", "description": "Fingerprint hash to search for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of serial numbers", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "404": { "description": "No records found for the given fingerprint" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/tsr-from-hash": { "post": { "tags": [ "Datasure TSA" ], "summary": "Generate Timestamp Response (TSR) directly from a SHA-256 hash (Premium)", "description": "Validate a SHA-256 hash and generate a Timestamping Response (TSR) if the hash is valid.", "operationId": "3bd4c5c684e91316ff7c4f1b8dcde269", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "hash" ], "properties": { "hash": { "description": "SHA-256 hash for which the TSR is to be generated", "type": "string", "example": "your_sha256_hash_here" } }, "type": "object" } } } }, "responses": { "200": { "description": "TSR generated successfully", "content": { "application/timestamp-reply": {} } }, "400": { "description": "Invalid hash format. Hash must be a valid SHA-256." }, "500": { "description": "Internal server error" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/tsr-from-file": { "post": { "tags": [ "Datasure TSA" ], "summary": "Generate Timestamp Response (TSR) directly from a file you submit. (Premium)", "description": "This endpoint compute the hash SHA-256 of the file you provide and directly return the Timestamp Response (TSR). The limitation of the size is 100MB per file. Only 1 file should be send / POST request.", "operationId": "f86b3c8e761c4688358e069ce2631b44", "requestBody": { "description": "A file to be send for timestamping.", "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "file": { "description": "File to upload", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "TSR done successfully", "content": { "application/timestamp-reply": {} } }, "400": { "description": "No file given or too big size (100MB)." }, "500": { "description": "Server internal error" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/pdf": { "post": { "tags": [ "Datasure TSA" ], "summary": "Sign a PDF with a timestamp (Premium)", "description": "This endpoint accepts a PDF file as input and returns the same PDF signed with a timestamp (PAdES format). It requires user authentication and checks for user roles and token balances before processing.", "operationId": "storePremiumTimestampPdf", "requestBody": { "description": "Upload a PDF file to be signed with a timestamp", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "pdf" ], "properties": { "pdf": { "description": "PDF file to be signed", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successfully signed PDF returned", "content": { "application/pdf": {} } }, "400": { "description": "Bad request (No file uploaded, unsupported file format, or signing error)" }, "401": { "description": "Unauthorized (Missing or invalid authorization header, or unauthorized user)" }, "403": { "description": "Forbidden (No remaining tokens or user without appropriate role)" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp/premium/get-certificate/{serial_number}": { "get": { "tags": [ "Datasure TSA" ], "summary": "Download a PDF Certificate signed by Datasure to confirm a timestamp operation (Premium)", "description": "Generates and downloads a signed timestamp certificate based on the provided serial number. The returned PDF is a certificate of the timestamp operation, signed by the Timestamp Authority itself with a qualified electronic certificate, attesting to the reality of the operation. Each certificate generated costs 1 timestamp token consumption.", "operationId": "203233d301b0cb0085ab683575378839", "parameters": [ { "name": "serial_number", "in": "path", "description": "Serial number for the timestamp record", "required": true, "schema": { "type": "string", "example": "0x1121D13C6BDC319D5FA3D3BFDD2DFCF31243" } } ], "responses": { "200": { "description": "Signed timestamp certificate returned successfully", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized access - Missing or invalid authentication, or user lacks necessary role" }, "403": { "description": "Forbidden - No remaining tokens or user lacks necessary role for the operation" }, "404": { "description": "Not Found - Serial number not found" } }, "security": [ { "basicAuth": [] } ] } }, "/api/timestamp": { "post": { "tags": [ "Datasure TSA" ], "summary": "Generates a Timestamp Response (TSR) from a Timestamp Query (TSQ)", "description": "This RFC3161 endpoint facilitates the creation of a qualified eIDAS electronic timestamp. It requires a properly formatted TSQ (Timestamp Query) as input and returns a valid TSR (Timestamp Response) if the TSQ is valid.", "operationId": "handleClientRequest", "requestBody": { "description": "Formatted TSQ (Timestamp Query) according to RFC3161", "required": true, "content": { "application/timestamp-query": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Successful response with TSR (Timestamp Response)", "content": { "application/timestamp-reply": {} } }, "400": { "description": "Invalid request (Invalid TSQ or problem with the request)" }, "401": { "description": "Unauthorized (Missing authorization header or unauthorized user)" }, "403": { "description": "Forbidden (No remaining tokens or user without appropriate role)" } }, "security": [ { "basicAuth": [] } ] } }, "/api/vault/add": { "post": { "tags": [ "Datasure Proof Vault" ], "summary": "Add a file to Datasure Proof Vault", "operationId": "347ad58ff0db243dc979e65dd2ba7528", "requestBody": { "description": "Upload a file to the Datasure Proof Vault. The file should be sent as-is, without any additional encoding. The filename should remain unaltered.", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "The file to upload. The filename should remain unaltered.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "File uploaded and certification handled", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "File certified successfully" }, "uid": { "type": "string", "example": "1693387849E1N9KO4UCR" }, "filename": { "type": "string", "example": "2023_07_BP_juillet.pdf" }, "filesize": { "type": "integer", "example": 36272 }, "filehash": { "type": "string", "example": "20c40d4323afa50ead4ca502faf3b03a35a92ea3ff07a3d0e337e12fbe92295d" }, "timestamp_serialnumber": { "type": "string", "example": "0x11214FAC7038488651B64D6DBECC96BBF973" }, "certified_unixtime": { "type": "integer", "example": 1693387850 }, "temporary_download_url": { "type": "string", "example": "https://datasure-platform.oos.cloudgouv-eu-west-1.outscale.com/vault/1693389232_2022_2583_np-6.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=LS85LOM2POPOIRZZ834H%2F20230830%2Fcloudgouv-eu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230830T114323Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Signature=0eca1a27a8b8c151cf130327d5e02c8be7224dbf4c3ad6eb93ad953e93dd7154" } }, "type": "object" } } } }, "400": { "description": "Validation error or other errors", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Unauthorized user due to missing or invalid Authorization header", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Missing authorization header" } }, "type": "object" } } } }, "403": { "description": "Forbidden, user doesn't have required role or tokens", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } }, "/api/vault/get/{uid}/json": { "get": { "tags": [ "Datasure Proof Vault" ], "summary": "Get JSON metadata for a previously certified file", "operationId": "f65e02c9c6b73931ce67e703915bc569", "parameters": [ { "name": "uid", "in": "path", "description": "The UID of the file to get", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON metadata returned", "content": { "application/json": { "schema": { "properties": { "uid": { "type": "string", "example": "1693389232NSPL3HCXG7" }, "filename": { "type": "string", "example": "2022_2583_np-6.pdf" }, "filesize": { "type": "number", "example": 0.36 }, "filehash": { "type": "string", "example": "f9b98930a5e35a03e0eeb56e049eaa9c94ce0eabe9c7f1587b466dcb7dbec670" }, "timestamp_serialnumber": { "type": "string", "example": "0x112100FBB7CEB307160189FC518A51057984" }, "certified_unixtime": { "type": "integer", "example": 1693389233 }, "temporary_download_url": { "type": "string", "example": "https://datasure-platform.oos.cloudgouv-eu-west-1.outscale.com/vault/1693389232_2022_2583_np-6.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=LS85LOM2POPOIRZZ834H%2F20230830%2Fcloudgouv-eu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20230830T114323Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Signature=0eca1a27a8b8c151cf130327d5e02c8be7224dbf4c3ad6eb93ad953e93dd7154" } }, "type": "object" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "408": { "description": "Request Timeout" } }, "security": [ { "basicAuth": [] } ] } }, "/api/vault/get/{uid}/certificate": { "get": { "tags": [ "Datasure Proof Vault" ], "summary": "Get the PDF certificate for a previously certified file", "operationId": "9668d1fa8167da9aabc0f32f9e2ed583", "parameters": [ { "name": "uid", "in": "path", "description": "The UID of the file to get", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF certificate generated and returned", "headers": { "Content-Type": { "description": "Media type", "schema": { "type": "string", "default": "application/pdf" } }, "Content-Disposition": { "description": "Content disposition", "schema": { "type": "string", "example": "attachment; filename=0x1121EC63DB6177EE12F82803DE83E0D86028_signed.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "408": { "description": "Request Timeout" } }, "security": [ { "basicAuth": [] } ] } }, "/api/vault/get/{uid}/file": { "get": { "tags": [ "Datasure Proof Vault" ], "summary": "Get the original file for a previously certified file", "operationId": "5c77f97afecc423059c7f71a9ba25198", "parameters": [ { "name": "uid", "in": "path", "description": "The UID of the file to get", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original file returned", "headers": { "Content-Type": { "description": "Media type", "schema": { "type": "string" } }, "Content-Disposition": { "description": "Content disposition", "schema": { "type": "string", "example": "attachment; filename=originalfile.pdf" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "408": { "description": "Request Timeout" } }, "security": [ { "basicAuth": [] } ] } }, "/api/vault/delete": { "delete": { "tags": [ "Datasure Proof Vault" ], "summary": "Delete files from the vault", "operationId": "d7f8cff30c0d5d1eca55a5ebc6912813", "parameters": [ { "name": "files", "in": "query", "description": "Comma-separated list of file UIDs to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "success": { "properties": { "deleted_files": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "errors": { "type": "array", "items": { "properties": { "uid": { "type": "string" }, "error": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "basicAuth": [] } ] } } }, "components": { "schemas": { "SecuSignDocumentFieldOptionInput": { "required": [ "value", "page", "x", "y" ], "properties": { "value": { "type": "string", "example": "option_yes" }, "label": { "type": "string", "example": "Oui", "nullable": true }, "page": { "type": "integer", "minimum": 1, "example": 2 }, "x": { "type": "number", "format": "float", "example": 260 }, "y": { "type": "number", "format": "float", "example": 355 }, "size": { "type": "number", "format": "float", "example": 16, "nullable": true }, "font_size": { "type": "number", "format": "float", "maximum": 72, "minimum": 1, "example": 12, "nullable": true }, "color": { "type": "string", "example": "#000000", "nullable": true }, "label_position": { "type": "string", "enum": [ "left", "right" ], "example": "right", "nullable": true } }, "type": "object" }, "SecuSignVisibleSignatureInput": { "required": [ "x", "y", "page", "type" ], "properties": { "x": { "type": "number", "format": "float", "example": 260 }, "y": { "type": "number", "format": "float", "example": 70 }, "width": { "type": "number", "format": "float", "example": 100, "nullable": true }, "height": { "type": "number", "format": "float", "example": 60, "nullable": true }, "page": { "type": "integer", "minimum": 1, "example": 2 }, "type": { "type": "string", "enum": [ "inline", "box" ], "example": "box" } }, "type": "object" }, "SecuSignDocumentFieldInput": { "description": "Fill & Sign field definition. text/checkbox need page+x+y. radio needs options[] with value+page+x+y for each option.", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "example": "comment_0" }, "type": { "type": "string", "enum": [ "text", "checkbox", "radio" ], "example": "text" }, "page": { "type": "integer", "minimum": 1, "example": 2, "nullable": true }, "x": { "type": "number", "format": "float", "example": 260, "nullable": true }, "y": { "type": "number", "format": "float", "example": 135, "nullable": true }, "width": { "type": "number", "format": "float", "example": 220, "nullable": true }, "height": { "type": "number", "format": "float", "example": 26, "nullable": true }, "size": { "type": "number", "format": "float", "example": 16, "nullable": true }, "label": { "type": "string", "example": "J'accepte", "nullable": true }, "label_position": { "type": "string", "enum": [ "left", "right" ], "example": "right", "nullable": true }, "font_size": { "type": "number", "format": "float", "maximum": 72, "minimum": 1, "example": 14, "nullable": true }, "required": { "type": "boolean", "example": true }, "color": { "type": "string", "example": "#000000", "nullable": true }, "value": { "type": "string", "nullable": true }, "options": { "description": "Required for radio fields", "type": "array", "items": { "$ref": "#/components/schemas/SecuSignDocumentFieldOptionInput" }, "nullable": true } }, "type": "object" }, "GroupResource": { "properties": { "uid": { "type": "string", "example": "4c65a500-db5e-40d9-b78a-d87178df6753" }, "label": { "type": "string", "example": "parents" }, "rule": { "type": "string", "example": "REQUIRED_1" }, "signed_count": { "type": "integer", "example": 0 }, "total_signatories": { "type": "integer", "example": 2 }, "is_completed": { "type": "boolean", "example": false }, "signatories": { "type": "array", "items": { "$ref": "#/components/schemas/SignatoryResource" } } }, "type": "object" }, "SignatoryResource": { "properties": { "uid": { "type": "string", "example": "707bbdeb-6a4c-47e4-9ced-39c3bdf3a25a" }, "firstname": { "type": "string", "example": "Marie" }, "lastname": { "type": "string", "example": "Durand" }, "email": { "type": "string", "format": "email", "example": "marie@example.com", "nullable": true }, "external_signatory_id": { "type": "string", "example": "crm-user-42", "nullable": true }, "phone": { "type": "string", "example": "0612345678", "nullable": true }, "authentication_type": { "type": "string", "example": "url_secret" }, "url_secret": { "type": "string", "example": "vm0skcjtq8nmVTzzFjW44Neczhw7vzzo", "nullable": true }, "signature_method": { "type": "string", "example": "handwritten" }, "signature_input_mode": { "type": "string", "enum": [ "draw", "text", "image" ], "example": "draw", "nullable": true }, "visible_signature": { "type": "array", "items": { "properties": { "x": { "type": "number", "example": 100 }, "y": { "type": "number", "example": 300 }, "page": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "box" } }, "type": "object" }, "nullable": true }, "document_fields": { "type": "array", "items": { "type": "object" }, "nullable": true }, "group_uid": { "type": "string", "example": "4c65a500-db5e-40d9-b78a-d87178df6753", "nullable": true }, "signed_date": { "type": "string", "format": "date-time", "nullable": true }, "is_signed": { "type": "boolean", "example": false }, "signatory_url": { "type": "string", "example": "https://example.com/secusign/transaction/{transactionUid}/{signatoryUid}/workflow", "nullable": true }, "signatory_url_direct": { "type": "string", "example": "https://example.com/secusign/transaction/{transactionUid}/{signatoryUid}/workflow?secret=...", "nullable": true }, "download_signed_pdf_url": { "type": "string", "nullable": true } }, "type": "object" }, "SecuSignTransactionExternalProofInput": { "required": [ "key", "value" ], "properties": { "key": { "type": "string", "maxLength": 255, "example": "client_ip" }, "value": { "description": "Client-collected proof value. It may be a scalar value, a JSON object, a JSON array, or null. String and serialized JSON values are limited to 20000 characters. HTML tags and unsafe control characters are stripped from string keys and values before storage.", "nullable": true, "oneOf": [ { "type": "string", "maxLength": 20000, "example": "82.12.34.56" }, { "type": "number", "example": 42 }, { "type": "boolean", "example": true }, { "type": "object", "example": { "provider": "client_app", "metadata": { "ip": "82.12.34.56" } } }, { "type": "array", "items": { "type": "string" }, "example": [ "sms", "email" ] } ] }, "sort_order": { "description": "Optional display order. If omitted, the next order is assigned automatically.", "type": "integer", "minimum": 0, "example": 0, "nullable": true } }, "type": "object" }, "TransactionExternalProofResource": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "key": { "type": "string", "example": "client_ip" }, "value": { "description": "Stored client-collected proof value. It may be scalar, JSON object, JSON array, or null. String keys and values are returned after HTML tag and unsafe control character stripping.", "nullable": true, "oneOf": [ { "type": "string", "example": "82.12.34.56" }, { "type": "number", "example": 42 }, { "type": "boolean", "example": true }, { "type": "object", "example": { "provider": "client_app", "metadata": { "ip": "82.12.34.56" } } }, { "type": "array", "items": { "type": "string" }, "example": [ "sms", "email" ] } ] }, "sort_order": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "tags": [ { "name": "Datasure SecuSign", "description": "Datasure SecuSign" }, { "name": "Datasure Proof Vault", "description": "Datasure Proof Vault" }, { "name": "Click&Cert", "description": "Click&Cert" }, { "name": "Datasure TSA", "description": "Datasure TSA" } ] }