--- title: "Iniciar uma requisição de assinatura" method: POST path: "/api/service/sign/v1/signatures" tags: ["Envelope"] --- # Iniciar uma requisição de assinatura `POST /api/service/sign/v1/signatures` Realiza uma requisição de envio de um ou mais documentos para assinatura, conforme parâmetros e gera links de acesso a página de assinatura para cada assinante listado. ## Request body - object - `name` string, required — Determina o nome que será atribuído ao envio e exibido para o assinante no momento da assinatura. - `clientName` string, required — Determina o nome que será atribuído ao criador do envio e exibido para o assinante no momento da assinatura. - `expiration` number — Determina a duração da requisição de envio de assinaturas gerada em segundos. Mínimo: 86400 (1 dia). Default: 604800 (7 dias) - `signatureOrder` 'ORDERED' | 'UNORDERED' | 'GROUPED' — Determina se existirá uma ordem pré-definida para os assinantes. ORDERED - criador do envelope define a ordem das assinaturas; UNORDERED - sem ordem pré-definida entre as assinaturas; GROUPED - criador do envelope define a ordem dos grupos que podem realizar as assinaturas; - `language` 'pt-br' | 'en-us' | 'es-cl' — Linguagem padrão do envelope. Define a linguagem para os signatários que não a definirem. - `sendNotifications` boolean — Define se as mensagens de notificação definidas para os signatários serão enviadas na criação do envelope. Deprecated: para não enviar as notificações configuradas na inicialização deve ser utilizado o parâmetro 'startAsDraft' e iniciar o envelope pela página de configuração - `startAsDraft` boolean — Define se o envelope será iniciado no estado de 'DRAFT'. Caso esteja verdadeiro, as notificações dos signatários não serão enviadas, sendo necessário iniciar o envelope após finalizar as alterações. Para inicializar o envelope, acesse a página de configuração do envelope. - `keepDocument` boolean — Define se os documentos assinados serão mantidos após a expiração do envelope. Caso esteja verdadeiro, os documentos não serão removidos automaticamente após a expiração do envelope - `linkMark` LinkMark — Marcas de referência adicionadas aos documentos - `id` object — Marca de referência do identificador de cada documento. Não é possível adicionar em documentos já assinados. Caso o documento original esteja assinado, o comportamento do id é definido pelo parâmetro `required`. - `required` boolean, required — Define se a presença da marca é requerida para todos os documentos. 'false': a marca não será adicionada a documentos que já possuam assinaturas. 'true': a requisição irá falhar caso algum documento possua assinaturas. - `creator` Creator — Informações do criador do envelope - `nonce` string — Valor nonce do criador do envelope - `name` string — Nome do criador do envelope - `email` string, email — Email do criador do envelope - `signersData` Signer[], required - `signerNonce` string — Valor nonce único para identificação do assinante. Caso não seja enviado, seu valor será igual ao identificador único gerado para o assinante. - `name` string, required — Nome do assinante dentro do envio a ser gerado. - `email` string — E-mail do assinante dentro do envio a ser gerado. - `phone` string — Telefone do assinante dentro do envio a ser gerado. Deve estar no formato E.164. - `personal_identifier` string — Identificador pessoal único do assinante. - `personal_identifier_type` string — Tipo da identificação enviada em 'personal_identifier'. - `language` 'pt-br' | 'en-us' | 'es-cl' — Linguagem que será utilizada como padrão na comunicação com signatário para página de assinatura, e-mail e/ou sms. Caso não informada, utiliza a linguagem do envelope. - `positioningMode` 'CREATOR' | 'PRESET' | 'SIGNEE' — Modo de aposição da rúbrica visível. CREATOR - A definição da imagem e posição de assinatura são configuradas pelo criador do envelope, no momento de criação, não sendo possível sua alteração por parte do assinante. PRESET - A definição da imagem de assinatura fica a cargo do assinante. A posição em que cada imagem é inserida deve ser configurada no momento de criação do envelope. SIGNEE - A definição da imagem de assinatura e sua posição fica a cargo do assinante. - `signInBatch` boolean — Permite que este envelope seja assinado em lote pelo signatário, caso haja outros envelopes pendentes - `groupNonce` string — Grupo ao qual este signatário pertence. Caso esteja vazio, o signatário não será adicionado a nenhum grupo. - `purpose` string — Papel do signatário dentro do envelope. Caso esteja vazio, não será adicionado nenhum papel ao signatário. - `authenticationOptions` string[] — Objeto JSON Array, com todos os tipos de evidências que devem ser coletadas na tela de assinatura pelo signatário. GEOLOCATION - Define se utilizará as coordenadas geográficas do signatário. IP - Define se utilizará endereço ip do signatário. OTP_PHONE - Define se a confirmação OTP será enviada ao telefone do signatário por SMS. Caso verdadeiro, o número de telefone do signatário deve ser informado. OTP_EMAIL - Define se a confirmação OTP será enviada ao email do signatário. Caso verdadeiro, o email do signatário deve ser informado. OTP_WHATSAPP - Define se a confirmação OTP será enviada ao telefone do signatário por WhatsApp. Caso verdadeiro, o número de telefone do signatário deve ser informado. SELFIE - Define se será tirada Foto do usuário no momento da assinatura. DRIVER_LICENSE - Define se será solicitado foto ou PDF da carteira de motorista do usuário no momento da assinatura. Se definido também o parâmetro SELFIE, será realizada a verificação de similaridade entre a foto do usuário e do documento. Caso formato PDF e definição do parâmtro SELFIE, será aceito exclusivamente o documento emitido pelo aplicativo Carteira Digital de Trânsito. DATAVALID - Define se a Foto do usuário será validada na base do governo. Caso verdadeiro, o CPF do signatário deve ser informado pelo parâmetro 'personal_identifier', utilizando `CPF` como `personal_identifier_type`. Adiciona nível de segurança `SELFIE`. É possível definir o nível mínimo de similaridade aceito utilizando o parâmetro `biometricOptions` de cada signatário. LIVENESS - Define se será verificado vivacidade do signatário. Adiciona nível de segurança SELFIE. É possível definir os valores mínimos de vivacidade aceitos utilizando o parâmetro biometricOptions de cada signatário. PERSONAL_IDENTIFIER - Define se será solicitado a confirmação do 'personal_identifier' do signatário na tela de assinaturas. A confirmação será realizada utilizando apenas os caracteres alpha-numéricos do campo (ex: os valores 12345632151 e 123.456.321-51 serão considerados iguais). VIEW_DOCUMENTS - Define se o signatário deverá visualizar todas as páginas dos documentos antes de seguir com a assinatura - `signatureConfig` SignatureConfig — Configurações de assinatura para determinado assinante. Define o modo de assinatura (SIMPLE, ADVANCED, QUALIFIED) e as propriedades deste modo. - `mode` 'SIMPLE' | 'ADVANCED' | 'QUALIFIED', required — Modalidade da assinatura deste assinante dentro da requisição de envio a ser gerado. SIMPLE - Assinatura eletrônica com coleta de evidências; ADVANCED - Assinatura eletrônica com coleta de evidências e certificado digital; QUALIFIED - Assinatura eletrônica com coleta de evidências e certificado digital ICP-Brasil. - `hashAlgorithm` string — Algoritmo de hash para este assinante dentro do envio a ser gerado. Disponível somente para modos ADVANCED e QUALIFIED. - `profile` string — Perfil de assinatura deste assinante dentro do envio a ser gerado. Disponível somente para modos ADVANCED e QUALIFIED. Valores disponíveis ['BASIC', 'TIMESTAMP', 'COMPLETE', 'ADRB', 'ADRT', 'ADRC', 'ETSI_B', 'ETSI_T', 'ETSI_LT'] - `typeMessaging` string[] — Canal de retorno do link de acesso a tela de assinaturas para cada assinante. LINK - Retorno das informações na(s) resposta(s) da API. EMAIL - Envia o link de acesso para o email do signatário. WHATSAPP - Envia o link de acesso para o whatsapp do signatário. - `typeReport` string[] — Tipo de mensagem de finalização que será enviada para o signatário. REPORT - Envia o(s) relatório(s) de validação dos documentos. DOCUMENT - Envia o(s) documento(s) assinados. REPORT_UNIFIED - Envia o(s) relatório(s) unificado(s) do processo de assinatura. - `typeReportNotify` string[] — Modo de como a mensagem de finalização será enviada para o signatário. Caso não definido na requisição, será utilizado o tipo EMAIL. EMAIL - Envia a(s) mensagem(ns) para o email do signatário. Caso os documentos sejam muito grandes, envia um link para download. SMS - Envia um link de acesso a(s) mensagem(ns) para o telefone do signatário através de um SMS - `biometricOptions` BiometricOptions — Configurações de biometria para assinatura. - `similarity` number — Grau de similaridade entre foto do assinante e documento de identificação. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.75. Somente utilizado quando ambas autenticações SELFIE e DRIVER_LICENSE são enviadas. - `datavalid` number — Grau de similaridade entre foto do assinante e base do governo. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.75. - `livenessCaptureProbability` number — Probabilidade de captura da imagem ter sido feita com uma câmera real e sem manipulação. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.5. - `livenessCaptureScore` number — Nota referente a captura da imagem utilizada. O valor mínimo permitido é 0.5. - `livenessFaceProbability` number — Probabilidade de ser uma pessoa ao vivo na frente da câmera. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.5. - `metadata` object — Metadados do assinante que serão adicionados aos documentos assinados. Disponível somente para assinaturas em modos ADVANCED e QUALIFIED. Deve ser informado no formato JSON, contendo os metadados no formato chave-valor. - `documents` Document[], required - `type` 'PDF' | 'CMS' | 'XML' — Formato detectado do documento. - `name` string — Nome do documento. - `size` integer — Tamanho do documento em bytes. - `hash` Hash — Resumo criptográfico (hash) - `value` string — Valor do hash codificado em hexadecimal. - `algorithm` string — Algoritmo utilizado para o cálculo do hash. - `images` Image[] - `image` string, required — Imagem a ser utilizada por um ou mais assinantes, como rúbrica visível da assinatura a ser gerada, a ser aposta no documento. - `imageNonce` string, required — Nonce da imagem - Este nonce deve ser referenciado em signaturePositions para cada uma das assinaturas cujo assinante deseje usar a imagem contida neste objeto JSON. - `groups` object[] - `groupNonce` string — Nonce do grupo, referenciado pelos signatários ## Response `201` Retorno das informações completas de um envio para Assinatura - object - `uuid` string — Request_id criado para o envio - `name` string — Nome atribuído ao envio e exibido para o assinante - `clientName` string — Nome atribuído ao criador do envio e exibido para o assinante - `accessPassword` string — Senha de acesso ao(s) relatório(s) de assinaturas, criada para o envio - `language` 'pt-br' | 'en-us' | 'es-cl' — Linguagem padrão do envelope. Define a linguagem para os signatários que não a definirem. - `status` 'DRAFT' | 'CREATED' | 'ONGOING' | 'FINISHED' | 'EXPIRED' | 'DELETED' — Status atual deste envio. CREATED - Envio de assinatura foi gerado; ONGOING - Assinaturas do envio foram inicializadas; FINISHED - Todas as assinaturas definidas no envio foram realizadas; EXPIRED - Tempo de expiração do envio chegou ao fim sem que todas as assinaturas tenham sido realizadas; DELETED - Envio foi deletado sem que todas as assinaturas tenham sido realizadas; DRAFT - Envelope está em estado de rascunho, signatários ainda não podem realizar assinaturas; - `signatureOrder` 'UNORDERED' | 'ORDERED' | 'GROUPED' — Modo de ordenação das assinaturas deste envio - `expiration` string — Unix timestamp de expiração do envio - `creation` string — Unix timestamp de criação do envio - `deletion` string — Unix timestamp de deleção do envio, caso envio tenha sido deletado - `keepDocument` boolean — Define se os documentos assinados serão mantidos após a expiração do envelope - `linkMark` LinkMark — Marcas de referência adicionadas aos documentos - `id` object — Marca de referência do identificador de cada documento. Não é possível adicionar em documentos já assinados. Caso o documento original esteja assinado, o comportamento do id é definido pelo parâmetro `required`. - `required` boolean, required — Define se a presença da marca é requerida para todos os documentos. 'false': a marca não será adicionada a documentos que já possuam assinaturas. 'true': a requisição irá falhar caso algum documento possua assinaturas. - `creator` Creator — Informações do criador do envelope - `nonce` string — Valor nonce do criador do envelope - `name` string — Nome do criador do envelope - `email` string, email — Email do criador do envelope - `signers` SignerResponse[] - `signerNonce` string — Valor nonce do assinante, definido pelo usuário ou gerado pelo backend - `signerUuid` string — Valor UUID do assinante, gerado pelo backend - `name` string — Nome do assinante - `email` string — E-mail do assinante dentro do envio a ser gerado. - `phone` string — Telefone do assinante dentro do envio a ser gerado. - `personal_identifier` string — Identificador pessoal único do assinante. - `personal_identifier_type` string — Tipo da identificação enviada em 'personal_identifier'. - `language` 'pt-br' | 'en-us' | 'es-cl' — Linguagem que será utilizada como padrão na comunicação com signatário para página de assinatura, e-mail e/ou sms. Caso não informada, utiliza a linguagem do envelope. - `positioningMode` 'CREATOR' | 'PRESET' | 'SIGNEE' — Modo de aposição da rúbrica visível. CREATOR - Posição e imagem definidas apenas pelo criador das assinaturas. PRESET - Posição e imagem iniciais definidas pelo criador das assinaturas com possibilidade da definição da imagem de assinaura pelo assinante. SIGNEE - Posição e imagem iniciais definidas pelo criador das assinaturas com possibilidade da definição da posição e imagem de assinatura pelo assinante. - `signInBatch` boolean — Permite que este envelope seja assinado em lote pelo signatário, caso haja outros envelopes pendentes - `canSign` boolean — Se assinante pode assinar o envio - `status` 'PENDING' | 'SIGNED' | 'REFUSED' — Status da assinatura deste assinante. PENDING - Assinatura ainda não foi realizada; SIGNED - Assinatura realizada; REFUSED - Assinatura recusada. - `groupNonce` string — Grupo ao qual este signatário pertence. Valor não é retornado caso signatário não pertença a nehum grupo. - `evidenceDate` string — Unix timestamp da assinatura do assinante, caso assinatura tenha sido realizada - `purpose` string — Papel do signatário dentro do envelope - `signatureConfig` object — Configurações da assinatura deste assinante - `mode` string - `hashAlgorithm` string - `profile` string - `signatureOrder` integer - `authentications` string[] — Objeto JSON Array, com todos os tipos de evidências que devem ser coletadas na tela de assinatura pelo signatário. GEOLOCATION - Define se utilizará as coordenadas geográficas do signatário. IP - Define se utilizará endereço ip do signatário. OTP_PHONE - Define se a confirmação OTP será enviada ao telefone do signatário por SMS. Caso verdadeiro, o número de telefone do signatário deve ser informado. OTP_EMAIL - Define se a confirmação OTP será enviada ao email do signatário. Caso verdadeiro, o email do signatário deve ser informado. OTP_WHATSAPP - Define se a confirmação OTP será enviada ao telefone do signatário por WhatsApp. Caso verdadeiro, o número de telefone do signatário deve ser informado. SELFIE - Define se será tirada Foto do usuário no momento da assinatura. DRIVER_LICENSE - Define se será solicitado foto ou PDF da carteira de motorista do usuário no momento da assinatura. Se definido também o parâmetro SELFIE, será realizada a verificação de similaridade entre a foto do usuário e do documento. Caso formato PDF e definição do parâmtro SELFIE, será aceito exclusivamente o documento emitido pelo aplicativo Carteira Digital de Trânsito. DATAVALID - Define se a Foto do usuário será validada na base do governo. Caso verdadeiro, o CPF do signatário deve ser informado pelo parâmetro 'personal_identifier', utilizando `CPF` como `personal_identifier_type`. Adiciona nível de segurança `SELFIE`. É possível definir o nível mínimo de similaridade aceito utilizando o parâmetro `biometricOptions` de cada signatário. LIVENESS - Define se será verificado vivacidade do signatário. Adiciona nível de segurança SELFIE. É possível definir os valores mínimos de vivacidade aceitos utilizando o parâmetro biometricOptions de cada signatário. PERSONAL_IDENTIFIER - Define se será solicitado a confirmação do 'personal_identifier' do signatário na tela de assinaturas. A confirmação será realizada utilizando apenas os caracteres alpha-numéricos do campo (ex: os valores 12345632151 e 123.456.321-51 serão considerados iguais). VIEW_DOCUMENTS - Define se o signatário deverá visualizar todas as páginas dos documentos antes de seguir com a assinatura - `link` object — Link para acesso a página de assinatura - `href` string - `iframe` object — Link para acesso a página de assinatura utilizando IFrame - `href` string - `typeMessaging` string[] — Canal de retorno do link de acesso a tela de assinaturas para cada assinante. LINK - Retorno das informações na(s) resposta(s) da API. EMAIL - Envia o link de acesso para o email do signatário. WHATSAPP - Envia o link de acesso para o whatsapp do signatário. - `typeReport` string[] — Tipo de mensagem de finalização que será enviada para o signatário. REPORT - Envia o(s) relatório(s) de validação dos documentos. DOCUMENT - Envia o(s) documento(s) assinados. REPORT_UNIFIED - Envia o(s) relatório(s) unificado(s) do processo de assinatura. - `typeReportNotify` string[] — Modo de como a mensagem de finalização será enviada para o signatário. Caso não definido na requisição, será utilizado o tipo EMAIL. EMAIL - Envia a(s) mensagem(ns) para o email do signatário. Caso os documentos sejam muito grandes, envia um link para download. SMS - Envia um link de acesso a(s) mensagem(ns) para o telefone do signatário através de um SMS - `biometricOptions` BiometricOptions — Configurações de biometria para assinatura. - `similarity` number — Grau de similaridade entre foto do assinante e documento de identificação. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.75. Somente utilizado quando ambas autenticações SELFIE e DRIVER_LICENSE são enviadas. - `datavalid` number — Grau de similaridade entre foto do assinante e base do governo. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.75. - `livenessCaptureProbability` number — Probabilidade de captura da imagem ter sido feita com uma câmera real e sem manipulação. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.5. - `livenessCaptureScore` number — Nota referente a captura da imagem utilizada. O valor mínimo permitido é 0.5. - `livenessFaceProbability` number — Probabilidade de ser uma pessoa ao vivo na frente da câmera. Porcentagem deve ser enviada como valores entre 0 e 1. O valor mínimo permitido é 0.5. - `metadata` object — Metadados do assinante que serão adicionados aos documentos assinados. - `documents` DocumentResponse[] - `documentNonce` string — Valor nonce do documento, definido pelo usuário ou gerado pelo backend - `documentUuid` string — Valor UUID do documento, gerado pelo backend - `name` string — Nome do documento - `status` 'AVAILABLE' | 'DELETED' — Status atual do documento. AVAILABLE - Documento está disponível; DELETED - Documento foi removido e não está mais disponível. - `deletion` string — Unix timestamp de deleção do documento, caso ele tenha sido removido. - `currentDocumentSize` number — Tamanho (em bytes) do documento contendo as assinaturas já realizadas. - `currentDocumentLink` object — Link de acesso com autenticação ao documento contendo as assinaturas já realizadas - `href` string - `originalDocumentLink` object — Link de acesso com autenticação ao documento original - `href` string - `groups` object[] - `groupNonce` string — Nonce do grupo - `groupOrder` number — Ordem definida para o grupo ## Other responses - `4XX` — Retorno de erro da aplicação - `5XX` — Retorno de erro da aplicação --- [API](https://skmtc.net/bry/apis/bry-easy-sign-api-rest.md) · [All operations](https://skmtc.net/bry/apis/bry-easy-sign-api-rest/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bry/bry-easy-sign-api-rest/revisions/c87e026e87ac/schema)