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

Name
Type
Description

certificate_alias

string

Identifica qual certificado será utilizado para realizar assinatura.

documents_destination

string

- AWS_S3 (o arquivo assinado será salvo no bucket S3) - GCP_STORAGE (o arquivo assinado será salvo no bucket Google Cloud Platform Storage)

mode

string

Modo de operação - sync - async

type

string

Tipo de assinatura - CMS-attached - CMS-detached - PDFSignature - CAdEs-attached - CAdEs-detached - PAdEs - XAdES

notification_callback

string

URL de callback para notificação, o sistema irá notificar quando o processo de assinatura for finalizado, será feito uma requisição HTTP(s) - POST na URL informada, na chamada será concatenado o código transação no final da url informada neste parâmetro. URL informada: http://endpointx.com?tcn= URL que será feita a requisição HTTP: http://endpointx.com?tcn=tcn_aqui_123456

policy

string

Políticas por tipo de assinatura - CMS: - Default ( Assinatura padrão CMS ) - TSA ( Assinatura padrão CMS incluindo assinatura da carimbadora do tempo ) - PDFSignature: - Default ( Assinatura padrão PDF - Adobe ) - TSA ( Assinatura padrão de PDF - Adobe incluindo assinatura da carimbadora do tempo ) - CAdEs/PAdEs: - AD_RB ( ICP Brasil ) - AD_RT ( ICP Brasil ) - XAdES: - AD_RB - AD_RT - AD_RC - AD_RA

hash_algorithm

string

Algoritmo de hash que será utilizado na assinatura (SHA1,SHA256, SHA384 ou SHA512)

signature_settings

object

Parâmetros adicionais de configuração de assinatura, devem ser enviados para configuração de assinatura visível (PDFSignature/PAdES) - id ( Identificador da configuração de assinatura ) - contact ( Contato do assinante ) - location ( Localização da assinatura, Ex: Washington-DC ) - reason ( Motivo da assinatura ) -visible_signature (true or false, desabilita a assinatura visível) - visible_sign_page ( Página onde será inserido a assinatura visível. Envie "1" para a primeira página, "-1" para última e "*" para todas) - visible_sign_x ( Coordenada X na página onde será inserido a assinatura visível ) - visible_sign_y ( Coordenada Y na página onde será inserido a assinatura visível ) - visible_sign_width ( Largura da imagem da assinatura visível ) - visible_sign_height ( Altura da imagem da assinatura visível ) - visible_sign_scale ( Escala (%) da imagem da assinatura visível ) - visible_sign_img ( Bytes de uma imagem PNG no formato DATA URI com a assinatura do usuário - RFC 2397 ) - extraInfo (Array para adicionar metadados no PDF, útil para prescrição médica. Contendo as chaves name e value. Exemplo: "extraInfo": [{ "name": "2.16.1.12.1.2", "value": "Atestado Médico" }] )

-prepare_fields Array onde pode ser inserido vários dados no PDF, como textos, imagens e QRCodes; este campo é utilizado em conjunto com o campo "prepare_fields_value".

Exemplo de como adicionar um campo de texto:

{

"name": "my_first_field",

"type": "text",

"value": "",

"option_multiline": false, "option_read_only": true, "border_color": "WHITE", "border_style": "WHITE", "border_width": 1,

"x": 320,

"y": 810,

"height": 40,

"width": 200,

"page": 1

}

Exemplo de como adicionar um campo de imagem/QRCode no PDF:

{

"name": "my_second_field",

"type": "image",

"value": "data:image/png;base64,BASE64",

"x": 505,

"y": 760,

"height": 80,

"width": 100,

"page": 2

}

Caso deseje que o mesmo campo, com as mesmas configurações seja adicionado em todas as páginas, basta indicar no número da página um asterisco ("*"), da seguinte forma:

"page": "*"

-prepare_fields_value (Array para adicionar valores aos formulários do PDF. Contendo as chaves name, type e value. Exemplo: "prepare_fields_value": [ { "name": "03_Cidade Local de Atendimento", "type": "text", "value": "Goiania" }] ) Parâmetros adicionais para configuração de assinatura devem ser enviados para assinatura padrão XAdES - tag_name (Nome da tag a ser assinada) - tag_id (Id da tag a ser assinada)

auto_fix_document

boolean

Habilita autocorreção do documento caso disponível

tsa_server_id

string

Identificador da carimbadora do tempo

tsa_hash_algorithm

string

Algoritmo de hash que será utilizado na assinatura do carimbo do tempo (SHA1,SHA256, SHA384 ou SHA512)

documents_source

string

Origem dos documentos: - DATA_URL ( Arquivo encodado na URL - https://tools.ietf.org/html/rfc2397 ) - FILE_PATH ( Caminho do arquivo dentro do container ) - UPLOAD_REFERENCE ( O conteúdo do arquivo deverá ser enviado posteriormente via API ) - AWS_S3 (nome do objeto no bucket do S3) - GCP_STORAGE (nome do objeto no bucket do GCP) - HASH (o hash deverá ser em hexadecimal - enviado na chave data de documents)

documents

string

Caso o documents_source seja do tipo DATA_URL ou FILE_PATH esse parâmetro deve ser enviado. Lista de especificação de documento(s) a ser(em) assinado(s), caso seja enviado mais de um item na lista, automaticamente a requisição será reconhecida como transação de assinatura em lote. - id ( Identificador do documento na transação ) - data ( Conteúdo compatível com especificado no data source ) - destination_file_name (Caso esteja utilizando documents_destination com valor AWS_S3 ou GCP_STORAGE, poderá ser definido o nome do objeto. Se o nome não for definido, será criado um identificar aleatório com a seguinte lei de formação: ano/mês/dia/timestamp_númeroAleatório8dígitos

signer_company

signature

CNPJ do assinador no caso de assinante PJ

return_signature

boolean

Retorna a assinatura no corpo da resposta da requisição

{
    "tcn": "123AAAAAAAAAAAAAAAAAAABBBBBBBBBB9999",
    "certificate_alias": "AAAAAAA...AAAAAAAAAAAA",
    "signature": "AAAAAAAAAAAAAAAAAA....AAAAAAA",
    "detail": {
        "code": "0000",
        "status": "",
        "message": ""
    }
}

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

Request Body

Name
Type
Description

signature_settings

object

Parâmetros adicionais de configuração de assinatura, devem ser enviados para configuração de assinatura visível (PDFSignature/PAdES)

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

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

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

Name
Type
Description

Content-Type

string

application/json

Accept

string

application/json

{
    "tcn": "123AAAAAAAAAAAAAAAAAAABBBBBBBBBB9999",
    "certificate_alias": "PAULO FILIPE...AAAAAAAAAAAA",
    "type": "CMS-attached",
    "hash_algorithm": "SHA256",
    "tsa": false,
    "documents_source": "UPLOAD_REFERENCE",
    "documents": [{
            "id": "Signature request ID 1",
            "status": "SIGNED",
            "result": "https://x.com/download/da39a3ee5e6b4b0d3255bfef95601890afd80709/Signature request ID 1",
            "lifetime": 120
        },
        {
            "id": "Signature request ID 2",
            "status": "WAITING"
        }
    ],
    "detail": {
        "code": 0000,
        "status": "",
        "message": ""
    }
}

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

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 assinatura

Last updated

Was this helpful?