# Assinatura de documento(s)

Todas as assinaturas são processadas no modo assíncrono, ao iniciar-se o processo de assinatura é gerado um TCN (Token de controle da transação), o TCN deve ser utilizado para identificar a transação nos momentos de checagem de status e recuperação de assinatura/documento assinado.

O Fluxo de assinatura pode ser dividido em 4 etapas:

1. Criação de transação
2. Upload de documento (O upload pode ser feito através do TCN obtido na primeira etapa + o ID do documento, podendo ser enviado no modo batch/lote ou documento por documento)
3. Consulta de transação (Detalha o estado atual da transação, como: Status do upload, Status da assinatura etc)
4. Download de documento/assinatura (O download do documento também deve ser feito através do TCN obtido na primeira etapa + o ID do documento, sendo necessário realizar o download de cada documento individualmente)

A etapa 1 é a única obrigatória, dependendo da modalidade de integração escolhida não será necessário a utilização das etapas 2, 3 e 4.

Caso  na etapa 1 seja definido que os documentos à serem assinados serão referenciados (caminho local), as etapas 2 e 4 não são mais necessárias.

Caso na etapa 1 seja definido um endpoint de callback o cliente será notificado quando a transação for finalizada, ou seja, não é necessário ficar consumindo periodicamente o serviço da etapa 3 para obter o estado da transação.<br>

### Criação de transação - Iniciar processo de assinatura

O serviço de criação de transação deve ser utilizado para iniciar o processo de assinatura de forma assíncrona.

Tipos de assinatura e política:&#x20;

* CMS ou CAdES: Suporta assinatura de qualquer tipo de arquivo. O arquivo será considerado como uma sequência de bytes sem interpretação/validação de conteúdo. Podendo ser do tipo attached (onde o conteúdo assinado é envelopado dentro da assinatura) ou do tipo detached (onde o conteúdo não é envelopado, e sempre que for necessário realizar a validação da assinatura precisa-se dos dois arquivos)&#x20;
* PDFSignature ou PAdES: Suporta somente a assinatura de documentos do tipo PDF válidos, podendo haver restrição com a versão do documento PDF caso a flag "auto\_fix\_document" não tenha sido enviada como ativa.\
  A assinatura é inserida dentro do próprio PDF, sendo assim, o PDF assinado é uma nova versão do PDF original (com a modificação da assinatura, mas com toda a rastreabilidade e histórico das versões antigas)

<mark style="color:green;">`POST`</mark> <https://cess.lab.vaultid.com.br/signature-service>

#### Headers

| Name          | Type   | Description                                                   |
| ------------- | ------ | ------------------------------------------------------------- |
| Authorization | string | Basic, Bearer ou VCSchema (Veja "Autenticação e Autorização") |
| Content-Type  | string | application/json                                              |
| Accept        | string | application/json                                              |

#### Request Body

{% tabs %}
{% tab title="200 " %}

```
curl --location 'https://cess.lab.vaultid.com.br/signature-service' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'VCSchemaCfg: returnAccessToken=true;lifetime=2592000;autoRevoke=false' \
--header 'Authorization: Basic OTk0NTE5NDgxMDQ6NjRwNDNz' \
--data '{
	"certificate_alias": "",
	"type": "PDFSignature",
	"hash_algorithm": "SHA256",
	"auto_fix_document": true,
	"signature_settings": [{
		"id": "default",
		"contact": "123456789",
		"location": "GoianiaGO",
		"reason": "Aprovação de documento",
		"visible_signature": true,
		"visible_sign_x": 0,
		"visible_sign_y": 790,
		"visible_sign_width": 230,
		"visible_sign_height": 50,
		"visible_sign_page": 1
	}],
	"documents_source": "UPLOAD_REFERENCE"
}'
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `http://cess.local/signature-service`

#### Request Body

{% tabs %}
{% tab title="201 " %}

```
{
    "tcn": "3d7a7ab3-4a3f-a0c8-74a1-6b02ae251f74",
    "certificate_alias": "CERTIFICADO TESTE:99451948104"
}
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `http://cess.local/signature-service`

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | oVG7h6uzPzZc |
| Content-Type  | string | Kxv8jSWHPkUA |
| Accept        | string | XBnbGNvpREaF |

#### Request Body

| Name                   | Type      | Description  |
| ---------------------- | --------- | ------------ |
| certificate\_alias     | string    | FmnFVXRAkwLw |
| documents\_destination | string    | PAyUo1XD1Z7W |
| mode                   | string    | D5EALe0qiH9Z |
| type                   | string    | Q4eR0Xjbvz8h |
| notification\_callback | string    | 1SxMMVPeLnui |
| policy                 | string    | UoHGlj5co3Bu |
| hash\_algorithm        | string    | ohy2VTH0TPWq |
| signature\_settings    | object    | 3ypseJzkORSy |
| auto\_fix\_document    | boolean   | oXJ8bibIMEnn |
| tsa\_server\_id        | string    | QLkBiUjwMKhp |
| tsa\_hash\_algorithm   | string    | kIrxGt2JMQsW |
| documents\_source      | string    | DxyAPiYGBgDO |
| documents              | string    | 6HkmaEBxuC7P |
| signer\_company        | signature | jQa6RIm201uI |
| return\_signature      | boolean   | ZRQTUyb61cOs |

<mark style="color:green;">`POST`</mark> `http://cess.local/signature-service`

#### Request Body

| Name                | Type   | Description  |
| ------------------- | ------ | ------------ |
| signature\_settings | object | KA4YlXrmkrbj |

Para mais informações de como utilizar o CESS com AWS S3, acesse [Integração S3](https://docs.vaultid.com.br/workspace/cess/api/integracao-s3)

Para mais informações de como utilizar o CESS com Google Cloud Platform Storage, acesse [Integração GCP Storage](https://docs.vaultid.com.br/workspace/cess/api/integracao-gcp-storage)

<mark style="color:green;">`POST`</mark> [`http://cess.local/signature-service`](https://cess.lab.vaultid.com.br/signature-service)

#### Request Body

| Name                   | Type   | Description |
| ---------------------- | ------ | ----------- |
| documents\_destination | string |             |

{% tabs %}
{% tab title="AWS\_S3 " %}

```
curl --location 'https://cess.lab.vaultid.com.br/signature-service' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer b13cd9deead82be176b7841a8116f6ffbabff6e4488' \
--data '{
	"certificate_alias": "",
	"type": "CMS-attached",
	"hash_algorithm": "SHA256",
	"tsa_hash_algorithm": "SHA256",
	"documents_source": "AWS_S3",
    "checksum_algorithm": "SHA256",
	"mode": "sync",
    "documents": [
        {
            "id": "0",
            "data": "nome_objeto_no_gcp_storage.pdf"
        }
    ]
}'
```

{% endtab %}

{% tab title="GCP\_STORAGE" %}

```
curl --location 'https://cess.lab.vaultid.com.br/signature-service' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer b13cd9deead82be176b7841a8116f6ffbabff6e4488' \
--data '{
	"certificate_alias": "",
	"type": "CMS-attached",
	"hash_algorithm": "SHA256",
	"tsa_hash_algorithm": "SHA256",
	"documents_source": "GCP_STORAGE",
    "checksum_algorithm": "SHA256",
	"mode": "sync",
    "documents": [
        {
            "id": "0",
            "data": "nome_objeto_no_gcp_storage.pdf"
        }
    ]
}'
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `http://cess.local/signature-service`

#### Request Body

| Name                   | Type   | Description  |
| ---------------------- | ------ | ------------ |
| documents\_destination | string | cWDzv7RzN4GX |

### Upload do documento

Sempre que a origem dos documentos (documents\_source) de uma transação for indicada como “UPLOAD\_REFERENCE” será necessário realizar o upload dos documentos por esse serviço.

Os uploads podem ser feito no modo “batch” (lote, vários documentos em uma única requisição de upload) ou “simple”, que é o envio de documento por documento.

É necessário sinalizar através do parâmetro “eot” (end of transaction) que o upload do lote chegou ao fim. Caso seja uma assinatura “simple” de um único documento, basta enviar a flag na própria requisição do documento.&#x20;

Caso haja mais de uma configuração de assinatura na transação, o parâmetro “signature\_setting” deve ser populado com o ID da da configuração escolhida.

<mark style="color:green;">`POST`</mark> <https://cess.lab.vaultid.com.br>`/file-transfer/<tcn>/<eot, continue or empty>/<signature_setting>`

#### Headers

| Name         | Type   | Description         |
| ------------ | ------ | ------------------- |
| Content-Type | string | multipart/form-data |
| Accept       | string | application/json    |

#### Request Body

| Name         | Type   | Description     |
| ------------ | ------ | --------------- |
| document     | string | Documento único |
| document\[0] | string | Document 0      |
| document\[1] | string | Document 1      |
| document\[n] | string | Document n      |

{% tabs %}
{% tab title="201" %}

```
{
    "tcn": "201cd48c-9991-1b23-eac7-b5ab9fa8f385",
    "eot": true,
    "executed_mode": "batch"
}
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `http://cess.local/file-transfer/<tcn>/<eot, continue or empty>/<signature_setting>`

#### Headers

| Name         | Type   | Description  |
| ------------ | ------ | ------------ |
| Content-Type | string | ITxjqLT3c9T0 |
| Accept       | string | YXA2bqvYTf9w |

#### Request Body

| Name         | Type   | Description  |
| ------------ | ------ | ------------ |
| document     | string | XyhpyCkn7txL |
| document\[0] | string | yPUlx0pzlwHz |
| document\[1] | string | tWgp0Q5RIqDO |
| document\[n] | string | tnbdSqKTxThQ |

### Consulta de transação - Verificar status do processo de assinatura

O serviço de consulta de transação deve ser utilizado quando não for informado um endpoint de callback (notificação) ou em possíveis falhas de notificação.

<mark style="color:blue;">`GET`</mark> <https://cess.lab.vaultid.com.br/signature-service>`/<tcn>`

#### Headers

{% tabs %}
{% tab title="201 " %}

```
{
    "tcn": "201cd48c-9991-1b23-eac7-b5ab9fa8f385",
    "certificate_alias": "CERTIFICADO TESTE:12345678900",
    "type": "PDFSignature",
    "hash_algorithm": "SHA256",
    "checksum_algorithm": "SHA1",
    "status": 200,
    "visible_signature": true,
    "tsa": false,
    "eot": true,
    "documents_destination": null,
    "documents_source": "UPLOAD_REFERENCE",
    "documents": [
        {
            "id": 0,
            "original_file_name": "Nome_Arquivo.pdf",
            "mediatype": "application/pdf",
            "status": "SIGNED",
            "lifetime": 86372,
            "result": "https://cess.lab.vaultid.com.br/file-transfer/201cd48c-9991-1b23-eac7-b5ab9fa8f385/0",
            "checksum": "2bb5292b25e540903b088b1343b43de47952ba69"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://cess.local/signature-service/<tcn>`

#### Headers

| Name         | Type   | Description  |
| ------------ | ------ | ------------ |
| Content-Type | string | WgA0plySedeg |
| Accept       | string | 0w3lrdgH2M8d |

Estrutura da resposta:

| .                  | .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tcn                | Token de controle da transação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| certificate\_alias | Identifica qual foi o certificado utilizado para realizar a assinatura                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| type               | Tipo de assinatura                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| hash\_algorithm    | Algoritmo de hash utilizado na assinatura                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| tsa                | Indica se foi utilizado alguma política que utilizou uma carimbadora do tempo                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| documents\_source  | <p>Indica origem dos documentos, valores possíveis:</p><ul><li>DATA\_URL</li><li>FILE\_PATH</li><li>UPLOAD\_REFERENCE </li><li>AWS\_S3</li><li>GCP\_STORAGE</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| documents          | <p>Lista de documentos/assinaturas na transação, <br></p><ul><li><p>id ( Identificador do documento na </p><p>transação) </p></li><li><p>status ( Status da assinatura, </p><p>valores possíveis: SIGNED, WAITING ou ERROR )</p></li><li><p>result ( Link/Path para cópia/download do</p><p>documento/assinatura )</p></li><li>destination\_file\_name (apenas quando utilizado destination\_source = AWS\_S3 ou GCP\_STORAGE)</li><li><p>lifetime ( Tempo de vida em segundos, </p><p>indica quanto tempo os documentos</p><p>assinados continuarão disponíveis</p><p>para cópia/download. )</p></li></ul> |

### Download de documento/assinatura

Quando houver resposta de uma transação via notificação ou serviço de “consulta de transação” com a sinalização que o documento já foi assinado, esse serviço automaticamente torna-se disponível para o TCN/Document ID recebido.

<mark style="color:blue;">`GET`</mark> <https://cess.lab.vaultid.com.br>`/file-transfer/<tcn>/<document id>`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
bytes do documento/assinatura
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://cess.local/file-transfer/<tcn>/<document id>`

#### Path Parameters

| Name | Type   | Description  |
| ---- | ------ | ------------ |
|      | string | phK1hwab10Qw |