> 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/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/digital-signatures/digital-sign.md).

# Assinatura digital

Este serviço permite adicionar assinaturas digitais com confiança global e marcas temporais a documentos PDF. Os certificados e chaves de assinatura são armazenados com segurança em dispositivos de hardware na nuvem compatíveis com FIPS.

#### Recursos de segurança

* **Autenticação**: A identidade do signatário é validada por uma autoridade certificadora (CA) pública confiável.
* **Integridade**: O documento não foi alterado após ser assinado.
* **Não repúdio**: O signatário não pode negar que assinou o documento.
* **Validação de longo prazo (LTV)**: As assinaturas incluem validação de longo prazo, garantindo que permaneçam válidas mesmo depois que o certificado expire ou seja revogado.

O serviço é totalmente compatível com produtos Adobe (incluindo Acrobat) e produtos Microsoft Office (incluindo Word) em plataformas como Windows e Linux.

### Endpoint

```
POST /services/digitalSign
```

### Cabeçalhos

| Nome          | Tipo   | Obrigatório | Descrição                         |
| ------------- | ------ | ----------- | --------------------------------- |
| **x-api-key** | string | **Sim**     | API Key de autorização de acesso. |

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro                              | Tipo    | Obrigatório | Descrição                                                                                          |
| -------------------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `endUserContactInfo`                   | string  | **Sim**     | Endereço de e-mail para contatar o usuário final.                                                  |
| `file`                                 | string  | **Sim**     | Arquivo PDF codificado em **Base64** a ser assinado.                                               |
| `signingData`                          | object  | **Sim**     | Objeto com os dados de assinatura.                                                                 |
| `signingData.facialAuthenticationHash` | string  | **Sim**     | Hash do processo de autenticação facial.                                                           |
| `signingData.serviceTransactionId`     | string  | **Sim**     | ID de transação do serviço de autenticação anterior.                                               |
| `signingLocation`                      | object  | **Sim**     | Objeto com a localização da assinatura.                                                            |
| `signingLocation.city`                 | string  | **Sim**     | Cidade onde a assinatura é realizada.                                                              |
| `signingLocation.country`              | string  | **Sim**     | Código do país no formato **ISO 3166-1 alpha-3**.                                                  |
| `signingLocation.geoLocationPosition`  | string  | Não         | Coordenadas geográficas (opcional). Use `"null"` se não estiver disponível.                        |
| `signingLocation.ipAddress`            | string  | Não         | Endereço IP do signatário (opcional). Use `"null"` se não estiver disponível.                      |
| `signingType`                          | string  | **Sim**     | Tipo de assinatura a ser realizada. Valor: `"1"` para assinatura padrão.                           |
| `signatureData`                        | object  | Não         | Objeto opcional para incluir imagem da assinatura manuscrita, número da página e posição do campo. |
| `signatureData.handSignature`          | string  | Não         | Imagem codificada em **Base64** da assinatura manuscrita.                                          |
| `signatureData.pageNumber`             | integer | Não         | Número da página onde colocar a assinatura (indexado a partir de 0).                               |
| `signatureData.signatureFieldPosition` | string  | Não         | Posição e tamanho do campo de assinatura no formato `"x,y,width,height"`.                          |

#### Exemplo de solicitação

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

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro              | Tipo    | Descrição                                                                                                                   |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `serviceTransactionId` | string  | Identificador único de transação para rastrear a operação de assinatura.                                                    |
| `serviceResultCode`    | integer | Código que indica o **resultado geral** da execução do serviço. Veja [Código de Resultado do Serviço](#service-result-code) |
| `serviceResultLog`     | string  | Mensagem descritiva relacionada ao resultado da operação.                                                                   |
| `timestamp`            | string  | Data e hora em que a operação de assinatura foi concluída no formato **ISO 8601**.                                          |
| `serviceDocument`      | string  | Documento PDF assinado codificado em **Base64**.                                                                            |

#### Código de Resultado do Serviço

O `serviceResultCode` indica o resultado geral da execução do serviço:

| serviceResultCode | Descrição                                                                              | Código HTTP |
| ----------------- | -------------------------------------------------------------------------------------- | ----------- |
| 0                 | A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente. | 200         |

#### Exemplo de resposta

```json
{
  "serviceTransactionId": "19624424-018c-4e48-b0d6-498c3a497792",
  "serviceResultCode": 0,
  "serviceResultLog": "Executed OK",
  "timestamp": "2025-02-11T11:46:32.190Z",
  "serviceDocument": "JVBERi0xLjUKJbXtrvsK...."
}
```

#### `400` Requisição inválida

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Não autorizado

```json
{
  "message": "Unauthorized"
}
```

#### `403` Acesso negado

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Gateway inválido

```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` Tempo limite do gateway

```json
{
  "message": "Endpoint request timed out"
}
```