--- title: "Assinar PDF/PAdES utilizando Certificado em nuvem" method: POST path: "/fw/v1/pdf/kms/lote/assinaturas" tags: ["Assinador PDF"] --- # Assinar PDF/PAdES utilizando Certificado em nuvem `POST /fw/v1/pdf/kms/lote/assinaturas` ## Request - Base URL: `https://cloud-hom.bry.com.br` - URL: `https://cloud-hom.bry.com.br/fw/v1/pdf/kms/lote/assinaturas` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Headers - `kms_type` 'BRYKMS' | 'GOVBR' | 'DINAMO' | 'HSMPKCS1' | 'PSC', required ## Request body `multipart/form-data` - object - `documento[0]` string, binary, required: Documento no formato PDF que será assinado. Para lotes, basta incrementar o valor do índice, por ex: documento[0], documento[1] - `dados_assinatura` DadosAssinaturaKms, required: Identificação do signatário e configurações básicas da assinatura (algoritmo de hash e perfil). Deve ser informado no formato JSON. - `kms_data` union: Credenciais de acesso ao certificado em nuvem. - object: Credenciais de acesso ao certificado digital armazenado no BRyKMS. Um dos valores entre 'pin' e 'token' deve ser enviado. - `pin` string: Senha definida pelo titular do certificado armazenado no BRyKMS para autorizar o acesso a chave.

Valor deve estar codificado em Base64.

- `token` string: Token de pré-autorização de acesso a chave no BRyKMS. Este token deve ser gerado em um passo anterior através da [API Certificado em Nuvem](https://api-assinatura.bry.com.br/api-certificado-em-nuvem) e permite o acesso a chave durante um determinado tempo ou quantidade de vezes.

Valor deve estar codificado em formato Hexadecimal.

- `uuid_cert` string: UUID do certificado cadastrado no BRyKMS. O UUID pode ser obtido via API ou na interface do BRyKMS, na tela de gerenciamento de um certificado. - `user` string: CPF do titular do certificado no BRy KMS. Pode ser utilizado para filtrar o certificado no compartimento vinculado uma conta Pessoa Jurídica. Caso seja uma conta de Pessoa Física, irá filtrar pelo certificado mais atual. - `cloud_token` string: Define o token de identificação do certificado cadastrado no BRyKMS. - object: Credenciais de acesso ao certificado armazenado em HSM Dinamo. Um dos valores entre 'user' e 'token' deve ser enviado. - `uuid_cert` string, required: Identificador do certificado que será utilizado para assinatura. - `uuid_pkey` string, required: Identificador da chave privada que será utilizada para assinatura. - `user` string: Usuário que irá acessar o HSM. - `pin` string: Senha de acesso do usuário às chaves armazenadas em HSM.

Valor deve estar codificado em Base64.

- `otp` string: Valor do OTP que será utilizado para acessar o HSM. - `token` string: Token de acesso às chaves armazenadas em HSM.

Valor deve estar codificado em Base64.

- object: Credenciais de acesso ao certificado armazenado no GOVBR. - `token` string, required: Token de acesso a [API de Assinatura Digital Avançada](https://www.gov.br/conecta/catalogo/apis/assinatura-digital-avancada). - object: Credenciais de acesso ao certificado armazenado em HSM Dinamo, no HUB-Signer auxiliar configurado. Disponível atualmente apenas para o endpoint de assinatura PDF. Um dos valores entre 'user' e 'token' deve ser enviado. - `uuid_cert` string, required: Identificador do certificado que será utilizado para assinatura. - `uuid_pkey` string, required: Identificador da chave privada que será utilizada para assinatura. - `user` string: Usuário que irá acessar o HSM. - `pin` string: Senha de acesso do usuário às chaves armazenadas em HSM. Valor deve estar codificado em Base64. - `otp` string: Valor do OTP que será utilizado para acessar o HSM. - `token` string: Token de acesso às chaves armazenadas em HSM. Valor deve estar codificado em Base64. - object: Credenciais de acesso ao certificado armazenado em serviço PSC. - `uuid_cert` string: Identificador do certificado que será utilizado para assinatura. - `url` string, required: Url de acesso ao serviço PSC que será utilizado. - `token` string, required: Token de acesso ao serviço PSC. O token deve estar configurado de acordo com o número de assinaturas que serão realizadas. - `perfil` string, required: Perfil da assinatura que será gerada. [Valores disponíveis: BASIC, TIMESTAMP, COMPLETE, ADRB, ADRT, ADRV, ADRC, ADRA, ETSI_B, ETSI_T, ETSI_LT e ETSI_LTA]. Aceita também os valores legados em português para os perfis de assinatura CMS básica. - `algoritmoHash` string, required: Algoritmo de hash que será utilizado para gerar a assinatura. [Valores disponíveis: SHA1, SHA256 e SHA512]. - `razao` string: Campo opcional para informar a razão para geração da assinatura. - `contato` string: Campo opcional para informar o contato do signatário na geração da assinatura. - `local` string: Campo opcional para informar o local onde a assinatura está sendo gerada. - `tipoRestricao` 'NENHUMA_RESTRICAO' | 'PERMITIR_COMENTARIOS_E_PREENCHIMENTO_FORMULARIOS' | 'PERMITIR_SOMENTE_PREENCHIMENTO_FORMULARIOS' | 'DESABILITAR_QUALQUER_ALTERACAO': Campo opcional para informar o tipo de restrição que será associado ao documento. - `tipoRetorno` string: Tipo de retorno da resposta [Valores disponíveis: LINK e BASE64]. Caso LINK, o arquivo será excluído da cache após o download. - `restructure` boolean: Define se será bloqueada a assinatura de arquivos PDF cuja tabela de estrutura de objetos esteja desestruturada. - `configuracao_imagem` ConfiguracaoImagem[]: Configuração dos parâmetros de posição, dimensão e visualização da imagem. Deve ser informado no formato JSON. Obs: Para configurações específicas para cada documento, é necessário adicionar entradas 'configuracao_imagem' tantas vezes quanto forem necessárias. - `altura` string, required: Altura (em mm) da imagem que será inserida. - `largura` string, required: Largura (em mm) da imagem que será inserida. - `coordenadaX` string: Define o deslocamento horizontal (em mm) da imagem em relação a posição definida no parâmetro "posicao", sendo o valor default o canto inferior esquerdo da página. Valores positivos deslocam a imagem para a direita e para cima, enquanto negativos para a esquerda e para baixo. - `coordenadaY` string: Define o deslocamento vertical (em mm) da imagem em relação a posição definida no parâmetro "posicao", sendo o valor default o canto inferior esquerdo da página. Valores positivos deslocam a imagem para a direita e para cima, enquanto negativos para a esquerda e para baixo. - `posicao` string: Define a origem 0,0 do campo em relação aos quatro cantos da página. [Valores disponíveis: INFERIOR_DIREITO, INFERIOR_ESQUERDO, SUPERIOR_DIREITO e SUPERIOR_ESQUERDO]. - `pagina` string: Define a(s) página(s) na qual a imagem será adicionada. [Valores disponíveis: PRIMEIRA, ULTIMA e TODAS]. A opção TODAS não pode ser utilizada em documentos já assinados. - `numeroPagina` string: Define o índice da página na qual a imagem será adicionada. A contagem do índice de páginas inicia em 1. - `campoAssinatura` string: Define o nome do campo (preexistente ou não) no documento onde a assinatura será visível. - `posicaoBorda` string: Define que a imagem será posicionada centralizada em uma das bordas da página. [Valores disponíveis: BORDA_DIREITA, BORDA_ESQUERDA, BORDA_INFERIOR e BORDA_SUPERIOR]. - `rotacaoImagemBorda` string: Define a rotação da imagem para os casos de página em modo paisagem ou imagem de assinatura posicionada na borda.[Valores disponíveis: ANTI_HORARIO_90_GRAUS e HORARIO_90_GRAUS]. - `imagemInvertida` string: Booleano que inverte a posição da imagem e do texto. O comportamento padrão é que a imagem (quando não for imagem de fundo) ficam do lado esquerdo da imagem da assinatura, enquanto o texto fica do lado direito. Definindo esta opção como true, a imagem ou nome do signatário ficarão do lado direito e o texto do lado esquerdo. - `proporcaoImagem` string: Inteiro que define a proporção de espaço que a imagem ocupará em relação ao texto da assinatura. O valor padrão é 50, que indica que a imagem ocupará metade do espaço e o texto a outra metade. Valores menores que 50 indicam que a imagem ocupará uma parte menor do retângulo da assinatura, enquanto valores maiores farão com que ela ocupe um espaço maior no retângulo. - `marker` string: Texto que será procurado no documento para obter sua coordenada X e Y. A procura é case sensitive, ou seja, letras maiúsculas e minúsculas fazem diferença. O texto informado deve ser exatamente igual ao que está no PDF. Deve ser utilizado um marcador único. Caso existam várias marcações iguais no documento, será utilizada as coordenadas da primeira ocorrência. As coordenadas encontradas serão utilizadas para configuração automática da imagem. - `offset` string: Offset que será utilizado para deslocar a posição na coordenada y caso um marker seja utilizado. Valores positivos deslocam para cima e valores negativos deslocam para baixo. - `ignorarMargens` string: Booleano que define se as coordenadas X e Y poderão ser configuradas fora das margens da página do documento PDF. - `configuracao_texto` ConfiguracaoTexto[]: Configuração do texto que será inserido na assinatura. Deve ser informado no formato JSON. A posição do texto é definida pelo parâmetro 'configuracao_imagem'. Obs: Para configurações específicas para cada documento, é necessário adicionar entradas 'configuracao_texto' tantas vezes quanto forem necessárias. - `texto` string: Define o texto que será incluído no campo da assinatura. - `incluirCN` boolean: Define se o campo CN do certificado do signatário será incluído no texto da assinatura. - `incluirCPF` boolean: Define se o campo CPF do certificado do signatário será incluído no texto da assinatura. - `incluirEmail` boolean: Define se o campo Email do certificado do signatário será incluído no texto da assinatura. - `rotacaoTexto` string: Define a rotação do texto. [Valores disponíveis: ANTI_HORARIO_90_GRAUS e HORARIO_90_GRAUS]. - `fonte` string: Define a fonte do texto. [Valores disponíveis: COURIER, HELVETICA, TIMES_NEW_ROMAN]. - `tamanhoFonte` string: Define o tamanho da fonte do texto. O valor padrão é 10. - `posicaoBorda` string: Define que o texto será posicionado centralizado em uma das bordas da página. [Valores disponíveis: BORDA_DIREITA, BORDA_ESQUERDA, BORDA_INFERIOR e BORDA_SUPERIOR]. - `largura` string: Define a largura do retângulo onde o texto será inserido, em milímetros, para o caso de ter sido selecionada alguma das bordas da página para ancorar o texto (posicaoBorda). As quebras de linhas acontecerão automaticamente quando a palavra ultrapassar a largura do retângulo. O valor padrão é 127mm (360 pontos PDF - metade de uma folha A4), caso este parâmetro esteja ausente. - `altura` string: Define a altura do retângulo onde o texto será inserido, em milímetros, para o caso de ter sido selecionada alguma das bordas da página para ancorar o texto (posicaoBorda). O valor padrão é tamanhoFonte x número de linhas cálculado pela aplicação, caso este parâmetro esteja ausente. - `metadados` Metadados[]: Lista dos pares de nome e valor dos metadados a serem adicionados no arquivo a ser assinado. É possível adicionar tantos quanto se deseje. Para enviar uma configuracao específica por documento do lote, basta repetir este parâmetro. Deve ser informado no formato JSON. - `2.16.76.1.4.2.2.2` string: Valor do metadado a ser adicionado - `2.16.76.1.4.2.2.3` string: Valor do metadado a ser adicionado - `nome_metadado1` string: Valor do metadado a ser adicionado - `nome_metadado2` integer: Valor do metadado a ser adicionado - `configuracao_anotacao[0]` ConfiguracaoAnotacao[]: Lista das configurações que definem os parâmetros de posição, dimensão e visualização de uma anotação. Deve ser informado no formato JSON. Para cada documento que se deseja adicionar anotações, é necessário enviar configurações específicas de acordo com o índice do documento, por ex: configuracao_anotacao[0], configuracao_anotacao[1]. Para adicionar múltiplas anotações a um mesmo documento é necessário adicionar entradas 'configuracao_anotacao[i]' tantas vezes quanto forem necessárias. - `altura` string, required: Altura (em mm) da anotação que será inserida. - `largura` string, required: Largura (em mm) da anotação que será inserida. - `coordenadaX` string: Define o deslocamento horizontal (em mm) da anotação em relação à posição definida no parâmetro "posicao". - `coordenadaY` string: Define o deslocamento vertical (em mm) da anotação em relação à posição definida no parâmetro "posicao". - `posicao` string: Define a origem 0,0 do campo em relação aos quatro cantos da página. - `pagina` string: Define a(s) página(s) em que a anotação será adicionada. - `numeroPagina` string: Define o índice da página na qual a anotação será adicionada. - `posicaoBorda` string: Define que a anotação será posicionada centralizada em uma das bordas da página. - `marker` string: Texto que será procurado para inserção da anotação. - `offset` string: Offset que será utilizado para deslocar a posição na coordenada y. - `nomeAnotacao` string: Define o nome que será atribuído à anotação. - `autor` string: Define o nome do autor da anotação. - `descricao` string: Define a descrição associada à anotação. - `tipo` 'IMAGEM' | 'TEXTO' | 'QRCODE', required: Define o tipo de anotação que será inserida. - `ignorarMargens` string: Define se as coordenadas X e Y poderão ser configuradas fora das margens da página. - `valor` union, required: Define o valor associado a um determinado tipo de anotação. - ConfiguracaoTexto - `texto` string: Define o texto que será incluído no campo da assinatura. - `incluirCN` boolean: Define se o campo CN do certificado do signatário será incluído no texto da assinatura. - `incluirCPF` boolean: Define se o campo CPF do certificado do signatário será incluído no texto da assinatura. - `incluirEmail` boolean: Define se o campo Email do certificado do signatário será incluído no texto da assinatura. - `rotacaoTexto` string: Define a rotação do texto. [Valores disponíveis: ANTI_HORARIO_90_GRAUS e HORARIO_90_GRAUS]. - `fonte` string: Define a fonte do texto. [Valores disponíveis: COURIER, HELVETICA, TIMES_NEW_ROMAN]. - `tamanhoFonte` string: Define o tamanho da fonte do texto. O valor padrão é 10. - `posicaoBorda` string: Define que o texto será posicionado centralizado em uma das bordas da página. [Valores disponíveis: BORDA_DIREITA, BORDA_ESQUERDA, BORDA_INFERIOR e BORDA_SUPERIOR]. - `largura` string: Define a largura do retângulo onde o texto será inserido, em milímetros, para o caso de ter sido selecionada alguma das bordas da página para ancorar o texto (posicaoBorda). As quebras de linhas acontecerão automaticamente quando a palavra ultrapassar a largura do retângulo. O valor padrão é 127mm (360 pontos PDF - metade de uma folha A4), caso este parâmetro esteja ausente. - `altura` string: Define a altura do retângulo onde o texto será inserido, em milímetros, para o caso de ter sido selecionada alguma das bordas da página para ancorar o texto (posicaoBorda). O valor padrão é tamanhoFonte x número de linhas cálculado pela aplicação, caso este parâmetro esteja ausente. - object - `nome` string, required: Define o nome da imagem multipart que será utilizada na anotação. - ConfiguracaoQrcode - `dimensao` integer, required: Qualidade (em pixels) da imagem QRCode. - `texto` string, required: Texto do QRCode. - `tipoImagem` string: Formato da imagem QRCode. - `margem` integer: Tamanho da margem que será adicionada ao QRCode. - `padraoCodificacao` string: Padrão de codificação que será utilizado no texto do QRCode. Exemplos: UTF-8, UTF-16, ISO-8859-1, US-ASCII. - `padraoMascara` integer: Número do padrão de máscara que será utilizado para codificar o QRCode. [Valores disponíveis: [0-7]] - `versao` integer: Versão do QRCode que será utilizada. Quanto maior o número da versão, mais dados podem ser armazenados. [Versões disponíveis: [1-40]]. - `compacto` boolean: Define se será gerado QRCode no modo compacto. - `nivelErro` 'L7' | 'M15' | 'Q25' | 'H30': Define o nível de erro que será utilizado no QRCode. O valor inteiro representa a porcentagem dos dados que podem ser perdidos. [Valores disponíveis: L7, M15, Q25 ou H30] - `imagem[0]` string, binary: Imagem que será inserida no campo de assinatura. Atualmente os formatos suportados são JPEG, PNG e BMP. Obs: Para imagens específicas para cada documento, é necessário adicionar entradas 'imagem[i]' para cada documento do lote. - `imagemFundo[0]` string, binary: Imagem que será inserida ao fundo do campo de assinatura. Atualmente os formatos suportados são JPEG, PNG e BMP. Obs: Para imagens de Fundo específicas para cada documento, é necessário adicionar entradas 'imagemFundo[i]' para cada documento do lote. - `imagemAnotacao[0]` string, binary: Imagem que será inserida na anotacao. O nome do parâmetro deve corresponder ao campo "valor/nome" de uma anotação com "tipo" igual a IMAGEM. É possível utilizar a mesma imagem para diferentes anotações. Atualmente os formatos suportados são JPEG, PNG e BMP. - `oidPolitica` string: Quando enviado, este parâmetro define o OID da política de assinatura a ser usada com perfil de assinatura selecionado. - `es_data` EsData[]: Lista das configurações de evidências que serão adicionadas a uma coleção de assinaturas eletrônicas para emissão de relatório. Deve ser informado no formato JSON. É necessário definir um valor de 'es_data' pra cada documento do lote, adicionando entradas 'es_data' de acordo com o número de documentos. - `event` string: UUID de referência para uma coleção de assinaturas em um documento. Refere-se ao evento no qual a assinatura atual será incluída. Caso não informado, será criada uma nova coleção de assinaturas. O UUID do evento relacionado a um documento com índice i é retornado como um header com chave event-i. - `evidence` object: Evidências que serão adicionadas à coleção de assinaturas eletrônicas. Para mais informações sobre os possíveis valores, acesse a [API Assinatura Eletrônica](https://api-assinatura.bry.com.br/api-assinatura-eletronica). - `nome_parametro` string: Valor relacionado ao parâmetro. - `configuracao_qrcode` ConfiguracaoQrcode[]: Configuração da imagem QRCode que será inserida. Deve ser informado no formato JSON. A posição do QRCode é definida pelo parâmetro 'configuracao_imagem'. Não pode ser utilizado em conjunto com o parâmetro 'imagem'. Obs: Para configurações específicas para cada documento, é necessário adicionar entradas 'configuracao_qrcode' tantas vezes quanto forem necessárias. - `dimensao` integer, required: Qualidade (em pixels) da imagem QRCode. - `texto` string, required: Texto do QRCode. - `tipoImagem` string: Formato da imagem QRCode. - `margem` integer: Tamanho da margem que será adicionada ao QRCode. - `padraoCodificacao` string: Padrão de codificação que será utilizado no texto do QRCode. Exemplos: UTF-8, UTF-16, ISO-8859-1, US-ASCII. - `padraoMascara` integer: Número do padrão de máscara que será utilizado para codificar o QRCode. [Valores disponíveis: [0-7]] - `versao` integer: Versão do QRCode que será utilizada. Quanto maior o número da versão, mais dados podem ser armazenados. [Versões disponíveis: [1-40]]. - `compacto` boolean: Define se será gerado QRCode no modo compacto. - `nivelErro` 'L7' | 'M15' | 'Q25' | 'H30': Define o nível de erro que será utilizado no QRCode. O valor inteiro representa a porcentagem dos dados que podem ser perdidos. [Valores disponíveis: L7, M15, Q25 ou H30] - `senhasDecifragem` string: Array de strings com as senhas para decifragem dos documentos enviados no lote. Deve haver uma senha para cada documento do lote remetido, que será usada na decifragem do documento no respectivo índice do lote de documentos. Exemplo: ['1234','4321'] - `senhasCifragem` string: Array de strings com as senhas para cifragem dos documentos enviados no lote. Deve haver uma senha para cada documento do lote remetido, que será usada na cifragem do documento no respectivo índice do lote de documentos. Exemplo: ['1234','4321'] ## Response `200` - union - DocumentoLinkSemNonce - `identificador` string: Identificador da requisição - `quantidadeAssinaturas` integer: Numero de documentos da requisição - `documentos` object[] - `hash` string: Hash do documento - `nomeArquivo` string: Nome do documento - `links` object[] - `rel` string - `href` string: Link para recuperar documento assinado - string[] ## Other responses - `400`: Resposta de erro da aplicação - `default`: Para mais detalhes sobre as Respostas: [link para as respostas de erro](/openapi/assinadoresPdf.html) ou [no formato properties](/openapi/assinadoresPdfErrors.properties) --- [API](https://skmtc.dev/bry/apis/bry-easy-sign-api-rest.md) - [All operations](https://skmtc.dev/bry/apis/bry-easy-sign-api-rest/llms.txt) - [OpenAPI document](https://skmtc.dev/bry/apis/bry-easy-sign-api-rest/revisions/c87e026e87ac?raw)