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:

Criação de transação
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)
Consulta de transação (Detalha o estado atual da transação, como: Status do upload, Status da assinatura etc)
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

string

application/json

Request Body

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

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

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

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

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

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

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

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

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

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

bytes do documento/assinatura

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

Path Parameters

Name

Type

Description

string

phK1hwab10Qw

PreviousPreparação de documento(s)NextValidação de integridade do documento

Last updated 3 months ago

Was this helpful?