> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/identity-api/identity-api-reference/digital-signatures/digital-sign.md). # Digital Sign Este servicio permite agregar firmas digitales de confianza global y marcas de tiempo a documentos PDF. Los certificados y claves de firma se almacenan de forma segura en dispositivos de hardware en la nube compatibles con FIPS. #### Características de seguridad * **Autenticación**: La identidad del firmante es validada por una autoridad de certificación (CA) pública de confianza. * **Integridad**: El documento no ha sido alterado después de ser firmado. * **No repudio**: El firmante no puede negar haber firmado el documento. * **Validación a largo plazo (LTV)**: Las firmas incluyen validación a largo plazo, asegurando que permanezcan válidas incluso después de que el certificado expire o sea revocado. El servicio es totalmente compatible con productos Adobe (incluyendo Acrobat) y productos Microsoft Office (incluyendo Word) en plataformas como Windows y Linux. ### Endpoint ``` POST /services/digitalSign ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ------------- | ------ | --------- | ---------------------------------- | | **x-api-key** | string | **Sí** | API key de autorización de acceso. | ### Cuerpo de la solicitud **Content-Type:** `application/json` #### Parámetros | Parámetro | Tipo | Requerido | Descripción | | -------------------------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------- | | `endUserContactInfo` | string | **Sí** | Dirección de correo electrónico para contactar al usuario final. | | `file` | string | **Sí** | Archivo PDF codificado en **Base64** a ser firmado. | | `signingData` | object | **Sí** | Objeto con los datos de firma. | | `signingData.facialAuthenticationHash` | string | **Sí** | Hash del proceso de autenticación facial. | | `signingData.serviceTransactionId` | string | **Sí** | ID de transacción del servicio de autenticación previo. | | `signingLocation` | object | **Sí** | Objeto con la ubicación de la firma. | | `signingLocation.city` | string | **Sí** | Ciudad donde se realiza la firma. | | `signingLocation.country` | string | **Sí** | Código de país en formato **ISO 3166-1 alpha-3**. | | `signingLocation.geoLocationPosition` | string | No | Coordenadas geográficas (opcional). Usar `"null"` si no está disponible. | | `signingLocation.ipAddress` | string | No | Dirección IP del firmante (opcional). Usar `"null"` si no está disponible. | | `signingType` | string | **Sí** | Tipo de firma a realizar. Valor: `"1"` para firma predeterminada. | | `signatureData` | object | No | Objeto opcional para incluir imagen de firma manuscrita, número de página y posición del campo. | | `signatureData.handSignature` | string | No | Imagen codificada en **Base64** de la firma manuscrita. | | `signatureData.pageNumber` | integer | No | Número de página donde colocar la firma (indexado desde 0). | | `signatureData.signatureFieldPosition` | string | No | Posición y tamaño del campo de firma en formato `"x,y,width,height"`. | #### Ejemplo de solicitud ```json { "endUserContactInfo": "user@email.com", "file": "JVBERi0xLjUKJbXtrvsKNCAwIG9iag...", "signingData": { "facialAuthenticationHash": "facialAuthenticationHash", "serviceTransactionId": "serviceTransactionId" }, "signingLocation": { "city": "City", "country": "ISO Alfa-3", "geoLocationPosition": "null", "ipAddress": "null" }, "signingType": "1", "signatureData": { "handSignature": "iVBORw0KGgoAAAANSUhEUgAAAEoAAABKCAYAA...", "pageNumber": 0, "signatureFieldPosition": "100,160,50,50" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `serviceTransactionId` | string | Identificador único de transacción para rastrear la operación de firma. | | `serviceResultCode` | integer | Código que indica el **resultado general** de la ejecución del servicio. Ver [Service Result Code](#service-result-code) | | `serviceResultLog` | string | Mensaje descriptivo relacionado al resultado de la operación. | | `timestamp` | string | Fecha y hora en que se completó la operación de firma en formato **ISO 8601**. | | `serviceDocument` | string | Documento PDF firmado codificado en **Base64**. | #### Service Result Code El `serviceResultCode` indica el resultado general de la ejecución del servicio: | serviceResultCode | Descripción | Código HTTP | | ----------------- | ------------------------------------------------------------------------------------ | ----------- | | 0 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200 | #### Ejemplo de respuesta ```json { "serviceTransactionId": "19624424-018c-4e48-b0d6-498c3a497792", "serviceResultCode": 0, "serviceResultLog": "Executed OK", "timestamp": "2025-02-11T11:46:32.190Z", "serviceDocument": "JVBERi0xLjUKJbXtrvsK...." } ``` #### `400` Bad Request ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Unauthorized ```json { "message": "Unauthorized" } ``` #### `403` Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Bad Gateway ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "Endpoint request timed out" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.facephi.com/api-rest/identity-api/identity-api-reference/digital-signatures/digital-sign.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.