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 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

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

POST http://cess.local/signature-service

Request Body

201

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

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

Para mais informações de como utilizar o CESS com Google Cloud Platform Storage, acesse Integração GCP Storage

POST http://cess.local/signature-service

Request Body

Name	Type	Description
documents_destination	string

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"
        }
    ]
}'

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"
        }
    ]
}'

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 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

201

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

POST 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.

GET https://cess.lab.vaultid.com.br/signature-service/<tcn>

Headers

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

GET 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	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 https://cess.lab.vaultid.com.br/file-transfer/<tcn>/<document id>

Path Parameters

Name	Type	Description
	string

200

bytes do documento/assinatura

GET http://cess.local/file-transfer/<tcn>/<document id>

Path Parameters

Name	Type	Description
	string	phK1hwab10Qw