> 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"
}
```