# 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.
### 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: * 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) * 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) `POST` #### 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 %} `POST` `http://cess.local/signature-service` #### Request Body {% tabs %} {% tab title="201 " %} ``` { "tcn": "3d7a7ab3-4a3f-a0c8-74a1-6b02ae251f74", "certificate_alias": "CERTIFICADO TESTE:99451948104" } ``` {% endtab %} {% endtabs %} `POST` `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 | `POST` `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](/workspace/cess/api/integracao-s3.md) Para mais informações de como utilizar o CESS com Google Cloud Platform Storage, acesse [Integração GCP Storage](/workspace/cess/api/integracao-gcp-storage.md) `POST` [`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 %} `POST` `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. 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. `POST` `/file-transfer///` #### 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 %} `POST` `http://cess.local/file-transfer///` #### 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. `GET` `/` #### 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 %} `GET` `http://cess.local/signature-service/` #### 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 |

Indica origem dos documentos, valores possíveis:

  • DATA\_URL
  • FILE\_PATH
  • UPLOAD\_REFERENCE
  • AWS\_S3
  • GCP\_STORAGE
| | documents |

Lista de documentos/assinaturas na transação,

  • id ( Identificador do documento na

    transação)

  • status ( Status da assinatura,

    valores possíveis: SIGNED, WAITING ou ERROR )

  • result ( Link/Path para cópia/download do

    documento/assinatura )

  • destination\_file\_name (apenas quando utilizado destination\_source = AWS\_S3 ou GCP\_STORAGE)

  • lifetime ( Tempo de vida em segundos,

    indica quanto tempo os documentos

    assinados continuarão disponíveis

    para cópia/download. )

| ### 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. `GET` `/file-transfer//` #### Path Parameters | Name | Type | Description | | ---- | ------ | ----------- | | | string | | {% tabs %} {% tab title="200 " %} ``` bytes do documento/assinatura ``` {% endtab %} {% endtabs %} `GET` `http://cess.local/file-transfer//` #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------ | | | string | phK1hwab10Qw | --- # Agent Instructions: 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.vaultid.com.br/workspace/cess/api/assinatura-de-documento-s.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.