INTRODUÇÃO

Esta seção detalha tecnicamente o funcionamento da plataforma, explicando as terminologias utilizadas, os processos, validações, eventos e a integração sistêmica. O entendimento de cada etapa é importante para poder extrair o melhor da plataforma tanto em termos de funcionalidades quanto em criar outras aplicações que dependam de assinaturas.

PROCESSO DE ASSINATURAS

A BITSIGN transformou o processo de assinaturas digitais, que é algo complexo, em uma forma muito mais simples de criar, gerenciar e assinar documentos. Todo o processo é orquestrado pelas API's, que recebe o documento a ser assinado, notifica o(s) assinante(s), coleta sua(s) assinatura(s) e informa ao contratante da conclusão.

Este processo foi cuidadosamente desenhado para facilitar para os assinantes durante a assinatura dos documentos, mas também, como uma perspectiva de integração completa, já que entendemos que o sucesso da utilização de qualquer sistema parceiro, está muito associado à forma como a integração é desenvolvida. Para auxiliar no entendimento, iniciamos a documentação com detalhes operacionais, para que seja possível se familiarizar com os elementos que compõem o processo, suas atribuições e utilidade dentro do ecossistema de assinaturas da BITSIGN. Uma vez que esses termos estejam claros, sequenciamos com toda a parte técnica e detalhamento de nossas API's.

Hierarquia

Esta seção, que é uma das mais importantes, resume a estrutura dos elementos que compõem o processo de assinaturas, o aninhamento, relação quantitativa e suas principais características. É importante entender o que representa cada um deles e suas relações entre si, já que a partir deste momento, será assumido que se tenha este conhecimento formado.

                                                    
    Aplicação 1
    └── Lotes
        ├── Lote 1
        │   └── Documentos
        │       ├── Documento 1
        │       │   ├── Assinaturas
        │       │   │   ├── Assinatura 1
        │       │   │   │   └── Assinantes
        │       │   │   │       ├── Assinante 1
        │       │   │   │       ├── Assinante 2
        │       │   │   │       ├── Assinante 3
        │       │   │   │       └── Assinante N
        │       │   │   ├── Assinatura 2
        │       │   │   │   └── Assinantes
        │       │   │   │       └── Assinante 1
        │       │   │   └── Assinatura N
        │       │   ├── Documento 2
        │       │   │   └── Assinaturas
        │       │   │       └── Assinatura 1
        │       │   │           └── Assinantes
        │       │   │               └── Assinante 1
        │       │   └── Documento N
        │       ├── Notificações
        │       │   └── ...
        │       ├── Observadores
        │       │   └── ...
        │       └── Anexos
        │           └── ...
        ├── Lote 2
        │   └── ...
        └── Lote N
                                                    

Status

Todos os elementos descritos acima (lote, documento, assinatura e assinante), possuem um atributo que é essencial para processo de assinaturas: o Status. É através da análise deste campo que a BITSIGN determina se uma assinatura, documento ou lote está concluído (assinado ou rejeitado). Para conhecer as opções disponíveis e quando elas são utilizadas, leia atentamente o quadro abaixo:

Fluxo

Através da imagem abaixo é possível ter uma visão panorâmica do processo em execução, mesclando tudo o que vimos até então com alguns detalhes técnicos para o melhor entendimento de como ocorre o fluxo entre os atores envolvidos no processo. A seguir, há uma descrição de cada um dos passos exibidos na imagem, com informações de mais "baixo nível" que incluem detalhes técnicos importantes para a implementação e integração por parte do contratante.

• PASSO 1: O processo se inicia com o contratante postando para a API o pacote com o manifesto de assinaturas (arquivo XML ou JSON) e os respectivos arquivos para serem assinados. Este pacote nada mais é que um arquivo compactado com todos estes arquivos dentro dele.
  • Validações Realizadas (Requisição será rejeitada)
    • Existência do Manifesto: se o arquivo que detalha as assinaturas está presente dentro do pacote;
    • Schema do XML: se o arquivo de manifesto for um XML, avalia está em conformidade com a estrutura esperada;
    • Regras de Domínio: alguma falha ocorre no momento da construção dos objetos de domínio: CPF/CNPJ inválido, algum campo que é obrigatório e não foi informado, etc.;
    • Contratante Divergente: se o contratante informado no arquivo de manifesto divergir daquele informado no cabeçalho da requisição;
    • Arquivo não Localizado: algum dos arquivos mencionados no manifesto não foi encontrado fisicamente no pacote e também não havia opção para download do mesmo.
• PASSO 2: Uma vez que o pacote é aceito, a BITSIGN gerará internamente todos os artefatos necessários para controlar o processo de assinaturas. Esta etapa consiste no armazenamento das informações, que, por sua vez, irá gerar os identificadores para o lote, documentos e assinaturas mencionadas no pacote.
  • Identificadores: é de responsabilidade do contratante armazenar os identificadores gerados. É a partir deles que será possível a interação com outras API's.
  • Processamento Assíncrono: Como o processamento pode levar alguns minutos para materializar o lote e seus documentos, a BITSIGN processa o pacote de forma assíncrona, isso quer dizer que ao submetê-lo, a API retornará o código 202 - Accepted com o id do lote recém gerado; a partir daí, opte por uma das opções a seguir para determinar se o mesmo foi processado com sucesso ou se gerou alguma falha.
    • Polling: Este método permite consultar, periodicamente, se o lote já foi ou não processado. É necessário que se armazene o id do lote, retornado logo após o envio, para realizar a consulta. Esta consulta retorna o lote serializado, e para determinar o resultado do processamento, consulte a propriedade Status, que poderá ser: EmProcessamento, Pendente ou Falha.
    • Callbacks: Tão logo o lote for processado, o contratante será notificado do resultado. Isso evitará desperdiçar recursos para ficar constantemente realizando a consulta. O detalhamento dos callbacks e os eventos gerados são mencionados abaixo.
• PASSO 3: O contratante pode optar por notificar o assinante de que há um novo documento disponível para assinatura. Para isso, haverá um atributo no manifesto chamado Notificar, que indica se a BITSIGN deverá ou não enviar um e-mail ao assinante. Para visualizar um exemplo do e-mail que é enviado, consulte o manual de assinaturas na seção de ajuda.
  • Observadores: Caso haja observadores associados ao lote, eles também serão notificados neste mesmo momento de que há novos documentos disponíveis para assinatura.
• PASSO 4: O assinante, através do aplicativo assinador, irá realizar a assinatura (ou rejeição) dos documentos. Uma vez que o assinante concluir as assinaturas, ele sincronizará com a BITSIGN, que orquestra o processo de assinaturas, e faz a atualização da cadeia de status dos respectivos lotes.
  • Expiração: Quando um lote é criado, é necessário informar a data de expiração do mesmo para evitar que ele fique eternamente disponível para assinatura. Essa data, quando atingida, marcará o lote e as assinaturas como Expirado, não ficando mais disponível para assinatura. O contratante é notificado da expiração através de um callback.
• PASSO 5: Este passo tem a finalidade de analisar e validar as assinaturas realizadas pelos assinantes, executando todas as regras necessárias para garantir que as mesmas estão de acordo com as regras impostas pela ICP-Brasil. Se alguma inconsistência ocorrer neste momento, o assinante será notificado imediatamente e a assinatura não será aceita pela plataforma.
• PASSO 6: Caso os callbacks estejam habilitados, o sistema da BITSIGN notificará o contratante de que o assinante, documento e lote foram assinados ou rejeitados.
• PASSO 7: Uma vez que todos os documentos do lote forem assinados, o sistema gera o pacote de retorno, incluindo nele, além do arquivo manifesto, os documentos originais, os documentos assinados (que possuem validade jurídica) e os manifestos de assinaturas. Como é um processo que pode demorar alguns minutos, ele é executado de forma autônoma e periódica.
• PASSO 8: Assim que o pacote for gerado com sucesso, com os callbacks habilitados, o contratante será notificado de que o mesmo está pronto para ser realizado o download.
• PASSO 9: Por fim, se o contratante desejar, assim que ele for notificado de que o pacote está gerado, pode realizar o download do mesmo informando o identificador de lote. Caso ele acesse este recurso antes do lote assinado ou quando ele ainda não tiver sido gerado, a requisição será rejeitada pelo serviço.

Observadores

A plataforma define o conceito de observadores, que como o próprio nome sugere, é uma relação de endereços de e-mails que serão notificados quando um novo lote de documentos for cadastrado. Eles receberão um link que redirecionará para a tela de acompanhamento ao vivo das assinaturas. Os observadores somente visualizam as assinaturas e não interferem de nenhuma forma no processo.

Os observadores podem ser "pontuais", ou seja, informados durante a criação do lote, ou, se preferir, há a possibilidade de cadastrar observadores "globais" e que serão adicionados aos lotes sempre que eles forem adicionados. Durante a adição do lote, a plataforma mesclará os observadores pontuais com os globais.

Anexos

Os anexos nada mais são que arquivos que podem ser adicionados ao lote para instruir, complementar ou justificar as assinaturas que estão sendo solicitadas. Estes documentos são destinados e ficam disponíveis para todos os assinantes envolvidos no processo, que podem utilizar este documento para esclarecer alguma dúvida antes de efetivamente assinar o documento.

Para utilizar este recurso, é necessário informar os anexos no manifesto e inseri-los no pacote que é enviado para a geração do lote. Os arquivos que eventualmente estiverem no pacote, mas não mencionados no manifesto, serão desprezados; já se estiver mencionado no manifesto mas não localizado no pacote, a requisição será rejeitada.

Atualmente, os formatos de arquivos suportados para anexos são: *.doc, *.docx, *.xls, *.xlsx, *.pdf, *.png, *.jpg, *.xml e *.txt.

Procurações e Representações

Poderá haver cenários onde uma entidade (pessoa física ou jurídica) constitui um procurador para representá-la, concedendo poderes para que esta outra entidade possa exercer em seu nome. De forma semelhante, temos situações em que um assinante é o representante legal de uma pessoa jurídica.

Nestes casos, quem assina o documento é sempre o outorgado/representante, porém, a BITSIGN disponibiliza durante a criação do documento, um atributo chamado EntidadeVinculada para que se possa informar os dados (nome, documento e e-mail) da entidade associada, especificando inclusive o tipo de vínculo (outorgante ou representado). Com isso, logo após a assinatura do outorgado/representante, aparecerá o nome da entidade outorgante/representado para que possa ficar visível que a assinatura está legalmente amparada em uma procuração ou algum outro documento que caracterize o vínculo.

Coleta Ordenada

Por padrão, todos os assinantes podem assinar os documentos do lote sem uma sequência específica. Isso quer dizer que a BITSIGN não controlará a ordem das assinaturas, ficando um determinado assinante livre para assinar antes ou depois de outro. Apesar de disso dar mais flexibilidade e agilidade ao processo de assinaturas, pode haver cenários onde se deseja controlar a ordem/sequência em que as assinaturas sejam realizadas, e para isso, os contratantes precisam informar durante a inclusão do novo lote a ordem em que deseja que a coleta de assinaturas seja feita.

A coleta ordenada é controlada através de um atributo chamado Ordem que é definido no Perfil de Assinatura; através dele você define a posição em que aquele perfil de assinatura deverá ser coletado, e caso um assinante abaixo dele tente realizar a assinatura, a BITSIGN irá rejeitar até que os perfis que antecedem sejam completamente assinados. E com isso, a cada assinatura realizada a BITSIGN reavalia a ordem e disponibiliza os perfis seguintes para assinatura. Por fim, se houverem perfis de assinaturas que podem ser assinados paralelamente, basta definir o número de ordem igual para todos eles.

Diretórios Virtuais

Os lotes estão fisicamente e unicamente associados às aplicações. Se há a necessidade de segregar virtualmente os lotes, a plataforma oferece ao contratante um recurso para estruturá-los de uma forma semelhante quando lidamos com diretórios e arquivos de um computador. A cada nova inclusão de lote de documentos, é possível especificar o diretório virtual onde ele deverá ser acomodado.

Uma vez que esta informação, que não é obrigatória, seja definida, será possível apresentar de uma forma hierárquica os lotes e, consequentemente, realizar a busca de acordo com o local onde eles estão, virtualmente, armazenados. Para aqueles que desejarem utilizar este recurso, não é necessária fazer o cadastro prévio da estrutura; a plataforma é capaz de agrupar os diretórios informados e estruturá-los hierarquicamente.

Ao enviar o lote, informe o diretório através do atributo Diretorio, separando os diretórios pela barra ("/"). Através da tabela abaixo é possível visualizar à esquerda alguns exemplos de lotes atribuídos à diversos diretórios; já à direta temos a hierarquia gerada através destas informações enviadas.

INTEGRAÇÃO ENTRE SISTEMAS

Protocolo

A integração fornecida pela BITSIGN é baseada no protocolo HTTPS, fornecendo um conjunto vasto de API's que permite ao contratante, não somente enviar os documentos para coletar as assinaturas, mas também monitorar e controlar todo o andamento deste processo. Este protocolo é amplamente utilizado nas integrações entre sistemas, pois ele é baseado em formato texto e de simples utilização, já que qualquer linguagem de programação atualmente possui recursos para o consumo e interação com estes tipos de serviços.

O protocolo HTTP define códigos de retorno, conhecidos como status, que indicam o resultado do processamento da requisição. A API da BITSIGN faz uso destes códigos, e abaixo estão uma breve descrição de quando e do porquê eles ocorrem:

Ambientes

Para facilitar o desenvolvimento por parte dos contratantes (e outros integradores), a BITSIGN fornece um ambiente de SANDBOX para que se possa testar o sistema consumidor durante o desenvolvimento, sem que isso afete o ambiente de produção, gerando cobranças indevidas para documentos que não tenham qualquer valor real.

Sistemicamente falando, o ambiente de SANDBOX é um "espelho" do ambiente de PRODUÇÃO, com exceção de que as assinaturas realizadas não são efetivamente válidas. Por fim, quando o sistema estiver devidamente desenvolvido, o integrador deverá modificar o acesso e começar a apontar para o ambiente de PRODUÇÃO.

A seguir temos as URLs de cada um dos ambientes, além disso, também disponibilizamos os endereços de IPs onde cada um destes serviços estão hospedados, para que, se houver alguma política de firewall, você conseguir abrir uma exceção e permitir que as interações (requisições e respostas) trafeguem sem qualquer tipo de restrição.

Autenticação

Autenticação é o processo de identificação do contratante para o serviço. Sem que essa identificação seja apresentada, todos os serviços rejeitarão as requisições, informando que o cliente está proibido de acessar tal recurso.

Na BITSIGN a autenticação deve ser realizada apresentando dois códigos: o código do contratante e a chave de integração. Ambos os códigos são gerados no momento da contratação do plano, e assim que o cadastro for confirmado, o código e a chave estarão disponíveis na área restrita do contratante. Ambas as informações devem ser informadas para toda e qualquer requisição que seja realizada ao serviço. Você deve informar estas chaves através do header Authorization com o scheme Basic, onde o código do contratante deve ser o Username e a chave de integração o Password, separados pelo caractere ":" e codificado em Base64, assim como é mostrado abaixo:

API's

As API's estão divididas em grandes categorias, que estão sumarizadas abaixo:

• Anexos: Documentos anexados ao lote que complementam, instruem ou justificam as assinaturas.
• Aplicações: Configurações que guiam o processo de assinaturas, configurações operacionais e integração.
• Buscador: Buscador avançado de recursos (lotes, documentos, etc.).
• Carimbo do Tempo: Gerador de carimbos do tempo para assinaturas e documentos digitais.
• Certificados: Análise, emissão e manipulação de certificados.
• Contratantes: Informações cadastrais e configurações do processo operacional das assinaturas.
• Documentos: Download dos documentos enviados, assinados e manifestos de assinaturas.
• Dumps: Repositório de requisições geradas em ambiente de SANDBOX.
• Financeiro: Detalhamento dos planos contratados, fechamentos e faturas do contratante.
• Lotes: Envio e gestão dos lotes de documentos para assinatura.
• Notificações: Informações e manipulação de notificações e callbacks.
• Uploads: Armazenamento de arquivos para posterior assinatura.
• Utilitarios: Funcionalidades periféricas para documentos e assinaturas.

Há uma seção totalmente dedicada para a documentação técnica necessária para guiar o desenvolvimento da aplicação consumidora. Esta seção inclui todos os detalhes das API's, incluindo: headers de autenticação, endereço de acesso, parâmetros necessários, objetos de retorno (com seus respectivos schemas) e códigos de erros que eventualmente possam ocorrer.

API's

Endpoints, Estrutura e Schemas.

Clique no botão abaixo para acessar a documentação das API's disponíveis para consumo.

OpenAPI

---

Versão	Descrição	Data da Publicação
v1	Versão Inicial da API	01/05/2021	Versão em Uso

Pacotes

Por pacote se compreende ser todo o conteúdo que trafega entre o contratante e a BITSIGN. Este pacote pode se referir ao conteúdo enviado da contratante para a BITSIGN com o lote para ser gerado e coletado as assinaturas, bem como o pacote que é gerado pela BITSIGN quando todos os documentos do lote forem devidamente assinados.

A estrutura deste pacote consiste em um arquivo chamado de manifesto, chamado de Manifesto.xml (ou Manifesto.json), o qual relaciona todos os documentos que deverão ser assinados. Os arquivos mencionados no manifesto poderão estar embutidos no próprio pacote ou indicado, através da propriedade Download, em uma URL para que a BITSIGN possa procurar pelo arquivo em um endereço HTTP[S] (através do método GET). Se optar por embutir os arquivos no próprio pacote, é importante garantir que o tamanho do mesmo não ultrapasse 20MB, caso contrário, a requisição será rejeitada.

Além de relacionar os arquivos a serem assinados, este o manifesto define o padrão e a política de assinatura, os perfis de assinatura (descrição e quantidade mínima) e, por fim, os assinantes, que além do nome, CPF (ou CNPJ) e e-mail, deverá também informar a obrigatoriedade dele no processo e se deve ser ou não notificado (por e-mail) de que um novo documento está disponível para assinatura. O manifesto também contemplará outras informações adicionais ao processo, tais como: observadores e anexos.

Abaixo temos dois exemplos deste documento, onde o primeiro deles é como ele deve ser formatado para envio e geração do lote para assinaturas, e o segundo, como a BITSIGN devolve quando todas as assinaturas são concluídas.

<Lote ModeloDeAssinatura="D"
	  Tags="processo:456"
	  Diretorio="formalizacao/contratacoes"
	  QtdeDeDocumentos="1">
	<Aplicacao>
		<Contratante Id="aefff7fe-43b8-4eee-9828-531ea6c4ca2d">
			<Entidade Nome="White House S/A"
					  Documento="16338212000113"
					  Email="contact@whitehouse.com" />
		</Contratante>
	</Aplicacao>
	<Entidade Nome="White House S/A"
			  Documento="16338212000113" />
	<Documentos>
		<Documento Descricao="Contrato de Locação"
				   Tipo="Contrato"
				   NomeDoArquivo="ContratoDeLocacao.pdf"
				   FormatoDoArquivo="PDF"
				   TamanhoDoArquivo="52472"
				   PadraoDeAssinatura="CAdES"
				   PoliticaDeAssinatura="PA_AD_RB_v2_3"
				   CarimboDoTempo="false"
				   Tags="contratoId:123">
			<Assinaturas>
				<Assinatura Perfil="Locador"
							QtdeMinima="1"
							Ordem="1">
					<Assinantes>
						<Assinante Obrigatorio="false"
								   Notificar="true"
								   Autenticacao="Certificado">
							<Entidade Nome="Jack Bauer"
									  Documento="57863748070"
									  Email="jack.bauer@ctu.com"
									  Telefone="(19) 91111-2222"
									  Idioma="en"/>
							<Mensagem>Assinar o mais breve possível.</Mensagem>
						</Assinante>
						<Assinante Obrigatorio="false"
								   Notificar="true"
								   Autenticacao="Certificado">
							<Entidade Nome="Nina Myers"
									  Documento="88488048025"
									  Email="nina.myers@ctu.com"
									  Telefone="(19) 93333-4444"
									  Idioma="en"/>
							<Mensagem>Assinar o mais breve possível.</Mensagem>
						</Assinante>
					</Assinantes>
				</Assinatura>
				<Assinatura Perfil="Locatário"
							QtdeMinima="1"
							Orderm="2">
					<Assinantes>
						<Assinante Obrigatorio="true"
								   Notificar="true"
								   Autenticacao="Certificado">
							<Entidade Nome="Joe Biden"
									  Documento="94478520097"
									  Email="potus@whitehouse.com"
									  Idioma="en"/>
							<Mensagem>Assinar o mais breve possível.</Mensagem>
						</Assinante>
					</Assinantes>
				</Assinatura>
			</Assinaturas>
		</Documento>
	</Documentos>
	<Observadores>
		<Observador Email="monitor@whitehouse.com" />
	</Observadores>
	<Anexos>
		<Anexo NomeDoArquivo="Planta.png"
			   FormatoDoArquivo="PNG"
			   Descricao="Visão geral do imóvel." />
	</Anexos>
</Lote>

<Lote Id="d6ec639c-52a8-4feb-bef0-5c1f71cbdb5d"
	  ModeloDeAssinatura="D"
	  Data="2021-02-11T12:15:08.974-03:00"
	  Tags="processo:456"
	  Diretorio="formalizacao/contratacoes"
	  QtdeDeDocumentos="1"
	  Status="Pendente"
	  DataDoStatus="2021-02-11T12:15:08.965-03:00"
	  UrlAoVivo="https://bitsign.com.br/aovivo?id=d6ec639c-52a8-4feb-bef0-5c1f71cbdb5d">
	<Aplicacao Id="94b2eec8-5e2e-4014-98d8-668023a8a172">
		<Contratante Id="985e0702-e94a-4954-b7a8-1f28c73c8122">
			<Entidade Id="aefff7fe-43b8-4eee-9828-531ea6c4ca2d"
					  Nome="White House S/A"
					  Documento="16338212000113"
					  Email="contact@whitehouse.com" />
		</Contratante>
	</Aplicacao>
	<Entidade Id="aefff7fe-43b8-4eee-9828-531ea6c4ca2d"
			  Nome="White House S/A"
			  Documento="16338212000113"
			  Email="contact@whitehouse.com" />
	<Documentos>
		<Documento Id="1490f513-1185-4eac-9d58-90a2dd010fd7"
				   Data="2021-02-11T12:15:08.989-03:00"
				   Descricao="Contrato de Locação"
				   Tipo="Contrato"
				   NomeDoArquivo="ContratoDeLocacao.pdf"
				   FormatoDoArquivo="PDF"
				   TamanhoDoArquivo="52472"
				   PadraoDeAssinatura="CAdES"
				   PoliticaDeAssinatura="PA_AD_RB_v2_3"
				   CarimboDoTempo="false"
				   Tags="contratoId:123"
				   Status="Pendente"
				   DataDoStatus="2021-02-11T12:15:08.981-03:00"
				   NomeDoArquivoAssinado="ContratoDeLocacao.pdf.p7s"
				   NomeDoArquivoDeManifesto="ContratoDeLocacao-Manifesto.pdf"
				   NomeDoArquivoOriginalComManifesto="ContratoDeLocacao-Original-Manifesto.pdf"
				   UrlDoManifesto="https://bitsign.com.br/visualizador?id=1490f513-1185-4eac-9d58-90a2dd010fd7">
			<Hash>(SHA1) - CBEAD3F95553FB1BF650E394C3DE2BB1E2D00EEB</Hash>
			<Assinaturas>
				<Assinatura Id="7e64e29d-2e23-4501-bd72-07a0045a8a99"
							Perfil="Locador"
							QtdeMinima="1"
							Ordem="1"
							Status="Pendente"
							DataDoStatus="2021-02-11T12:15:08.998-03:00">
					<Assinantes>
						<Assinante Status="Pendente"
								   DataDoStatus="2021-02-11T12:15:09.009-03:00"
								   Obrigatorio="false"
								   Notificar="true">
							<Entidade Id="45513cbd-d4f1-44d3-8080-8b29af2364bf"
									  Nome="Jack Bauer"
									  Documento="57863748070"
									  Email="jack.bauer@ctu.com" />
						</Assinante>
						<Assinante Status="Pendente"
								   DataDoStatus="2021-02-11T12:15:09.019-03:00"
								   Obrigatorio="false"
								   Notificar="true">
							<Entidade Id="729315d9-5c76-4afd-bcba-a6dd0cf899dc"
									  Nome="Nina Myers"
									  Documento="88488048025"
									  Email="nina.myers@ctu.com" />
						</Assinante>
					</Assinantes>
				</Assinatura>
				<Assinatura Id="bed8e5f0-7c20-48d7-93ee-4468a00d9270"
							Perfil="Locatário"
							QtdeMinima="1"
							Ordem="2"
							Status="Pendente"
							DataDoStatus="2021-02-11T12:15:09.027-03:00">
					<Assinantes>
						<Assinante Status="Pendente"
								   DataDoStatus="2021-02-11T12:15:09.035-03:00"
								   Obrigatorio="true"
								   Notificar="true">
							<Entidade Id="add7fb96-826c-49f4-afcf-feffc5a72214"
									  Nome="Joe Biden"
									  Documento="94478520097"
									  Email="potus@whitehouse.com" />
						</Assinante>
					</Assinantes>
				</Assinatura>
			</Assinaturas>
		</Documento>
	</Documentos>
</Lote>

{
  "Aplicacao": {
    "Contratante": {
      "Entidade": {
        "Nome": "White House - USA",
        "Documento": "95038850000195",
        "Email": "contact@whitehouse.com"
      },
      "Id": "aefff7fe-43b8-4eee-9828-531ea6c4ca2d"
    }
  },
  "Entidade": {
    "Nome": "White House - USA",
    "Documento": "14175773000113",
    "Email": "contact@whitehouse.com"
  },
  "DataDeExpiracao": "2021-10-20T19:31:24.1426672-03:00",
  "Tags": "processo=456",
  "ModeloDeAssinatura": "D",
  "Diretorio": "formalizacao/contratacoes",
  "QtdeDeDocumentos": 1,
  "Documentos": [
    {
      "Descricao": "Contrato de Locação",
      "Tipo": "Contrato",
      "NomeDoArquivo": "ContratoDeLocacao.pdf",
      "FormatoDoArquivo": "PDF",
      "Download": {
        "Url": "http://www.site.com.br/documentos/ContratoDeLocacao.pdf",
        "Headers": null
      },
      "CarimboDoTempo": false,
      "PadraoDeAssinatura": "CAdES",
      "PoliticaDeAssinatura": "PA_AD_RB_v2_3",
      "Tags": "contratoId=123",
      "Assinaturas": [
        {
          "Perfil": "Locador",
          "QtdeMinima": 1,
          "Ordem": 0,
          "Assinantes": [
            {
              "Entidade": {
                "Nome": "Jack Bauer",
                "Documento": "57863748070",
                "Email": "jack.bauer@ctu.com",
                "Idioma":  "eu"
              },
              "Obrigatorio": true,
              "Notificar": true,
              "Autenticacao": "Certificado"
            }
          ]
        }
      ]
    }
  ],
  "Observadores": null,
  "Anexos": null
}

Como se vê o exemplo do manifesto de retorno, será possível encontrar dentro do pacote, além do arquivo original (atributo NomeDoArquivo), o arquivo assinado (atributo NomeDoArquivoAssinado), o manifesto de assinaturas (atributo NomeDoArquivoDeManifesto) e o arquivo original com o manifesto adicionado (atributo NomeDoArquivoOriginalComManifesto). Os arquivos gerados e colocados dentro do pacote respeitarão a relação de documentos que são especificados no parâmetro documentosDoPacote.

Tags

As tags são recursos que agregam informações aos lotes e aos documentos e que não interferem no processo de assinaturas. As tags são informações que só tem significado para os contratantes, e são úteis para incluir identificadores internos e com isso, facilitar a busca pelo elemento em sua base de dados.

Elas só podem ser informadas no momento do envio do lote. A partir daí, sempre que for solicitada o detalhamento do lote (através da API), as tags serão incluídas aos respectivos recursos (lotes ou documentos). Da mesma forma, quando houver um callback relacionado à algum evento de lote ou documento, as tags também serão encaminhadas.

Segundo o schema, as tags tem um limite de 1.000 caracteres. Trata-se de um campo livre para incluir qualquer informação necessária. Se houver a necessidade de informar múltiplos dados, aconselha-se a utilizar uma combinação de chave e valor, separado por ponto-e-vírgula (;), como por exemplo: Id=1234;Contexto=Locação.

Rastreio da Requisição

Para fins de auditoria e, principalmente, de depuração, a aplicação consumidora poderá, opcionalmente, adicionar um header nas requisições para identificá-la. Quando estiver presente, esta informação será armazenada juntamente com os logs internos que são gerados, e futuramente, poderá ser utilizado quando houver a necessidade de realizar algum diagnóstico.

Para utilizar este recurso, inclua um header chamado BS-Tracking em todas as requisições enviadas ao serviço. É um campo livre, não obrigatório, onde poderá definir qualquer informação que identifique unicamente a requisição. É importante que se optar por utilizar, mantenha armazenado este identificador para, futuramente, poder correlacionar com os logs internos da BITSIGN.

Por fim, quando este código estiver presente na requisição, a BITSIGN o devolverá, também, através do mesmo header na resposta; com isso, a aplicação consumidora poderá realizar alguma consistência sobre ele, como correlacionar as mensagens, armazenamento de logs, etc.

Configurações

Existem diversas configurações que coordenam o processo de assinaturas e de integração com a BITSIGN. Essas configurações podem ser alteradas à qualquer momento, acessando uma API exclusiva para realizar esta alteração. É importante dizer que estas alterações são aplicadas de forma imediata, mas serão somente consideradas a partir das próximas assinaturas realizadas, ou seja, tudo o que foi feito até a alteração, respeitarão as configurações anteriores.

A tabela a seguir relaciona cada um destes parâmetros e detalha a sua utilidade e onde cada um é aplicado. Apesar de haver uma configuração padrão para cada um destes parâmetros, é de inteira responsabilidade do contratante definir quais parâmetros melhor se aplicam à sua necessidade. Todas as configurações podem ser customizadas de acordo com cada aplicação que é criada, permitindo o agrupamento de características a fim de otimizar e agilizar o processo de assinaturas.

Configuração	Descrição
urlDeCallback	O processo de assinaturas gera diversos eventos que foram mapeados, e que podem ser enviados para o contratante para que ele possa recepcionar e, consequentemente, informar seus usuários do andamento do processo de assinatura. Esta configuração permitirá você a indicar um endereço HTTP(S) para que a BITSIGN envie uma notificação do que ocorreu. Importante: Antes de aceitar a URL informada, a BITSIGN realiza uma espécie de ping (através do método HEAD) para confirmar a existência do endereço e que o mesmo esteja acessível. Enquanto esta requisição não retornar um status 200 - OK, o mesmo não será aceito. Os headersDeCallback informados são aplicados à requisição e o content-type é configurado de acordo com o que se define na propriedade formatoDeCallback.
headersDeCallback	Sempre que a BITSIGN envia uma notificação para o contratante, ela poderá incluir no cabeçalho (headers) da requisição informações para que a aplicação cliente possa identificá-la e, eventualmente, autenticá-la. As informações são sempre uma combinação de chave e valor, separadas pelo caractere ":" (dois pontos). Para informar múltiplos parâmetros, basta separá-los por ponto-e-vírgula (;): X-ServiceName:Assinador;X-ServiceKey:123456
janelasDeCallback	Se houver alguma restrição de dia ou hora, você pode especificar as janelas disponíveis para a realização do envio dos callbacks. A ausência destas janelas indicará para a BITSIGN que ela pode enviar a notificação tão logo o evento ocorrer.
formatoDeCallback	A notificação que é devolvida para a aplicação cliente tem um objeto pré-definido e que pode ser serializado em um dos seguintes formatos: JSON ou XML. A configuração padrão é: JSON.
formatoDoManifesto	Indica em qual formato deverá ser serializado o arquivo de manifesto ao gerar o pacote contendo os documentos assinados. Os formatos suportados são: JSON ou XML. A configuração padrão é: XML.
ipsAutorizados	Relação que permite especificar os IPs que estarão autorizados à acessar os serviços. Por padrão, não há qualquer restrição, sendo todas as requisições aceitas. Para restringir, informe os IPs autorizados, e se precisar especificar múltiplos, basta separá-los por ponto-e-vírgula (;). Se o IP for definido e a requisição não for oriunda deste local, a mesma será abortada com um erro 401 (Unauthorized).
eventosReportados	A BITSIGN gera uma porção de eventos que podem ser reportados para a aplicação cliente (através da urlDeCallback). Estes eventos são gerados a partir de diversos estágios do processo de assinaturas, fechamento financeiro, entre outros. Abaixo estão relacionados os eventos que são gerados e podem ser recepcionados pelo cliente: Assinante: Ocorre quando um assinante realiza a assinatura ou rejeita um documento. Assinatura: Ocorre quando todos os assinantes da assinatura se manifestam (assinando ou rejeitando). Documento: Ocorre quado todas as assinaturas envolvidas nos documentos são encerradas. Lote: Ocorre quando todos os documentos do lote têm sua(s) assinatura(s) concluída(s). Pacote: Ocorre quando é concluído o processo de geração do pacote de documentos do lote. Financeiro: Ocorre quando o fechamento mensal é concluído e apurado o gasto realizado para pagamento pelo contratante. Para receber múltiplos eventos, basta separá-los por ponto-e-vírgula (;): Assinante;Lote;Pacote. A configuração padrão é: Financeiro;Pacote;Lote;Documento.
documentosDoPacote	Quando o lote de documentos é concluído e suas assinaturas realizadas, você pode guiar como o pacote com os documentos digiais é gerado. Você pode optar por incluir no pacote, os seguintes arquivos: Original: Inclui o documento original que foi enviado para assinatura. Assinado: Inclui o documento assinado. Este é o documento oficial que armazena todos os artefatos criptográficos que garante a autenticidade e integridade. Manifesto: Relatório (em PDF) que exibe os detalhes das assinaturas e assinantes do documento. Original + Manifesto: Adiciona uma página ao documento original contendo o relatório com o manifesto de assinaturas. Para receber múltiplos documentos, basta separá-los por ponto-e-vírgula (;): Assinado;Original + Manifesto. A configuração padrão é: Assinado;Original + Manifesto.
documentosPermitidos	Esta opção permite especificar quais tipos de documentos serão suportados pela respectiva aplicação. Quando nenhum deles é especificado, todos os documentos são suportados. Atualmente, as opções disponíveis são: Aditivo Balanço Carta de Cessão Cédula de Crédito Bancário Cédula de Produtor Rural Conhecimento de Transporte Declaração Endividamento Ficha Cadastral Letra de Câmbio Nota Fiscal Procuração Receituário Rescisão Termo de Adesão Termo de Confidencialidade Apólice Boletim Carta de Circularização Cédula de Crédito Imobiliário Certificado Contrato Diploma Exame Fonte de Dados Manifesto Nota Promissória Prontuário Recibo Termo de Abertura de Conta Termo de Cessão Termo de Garantia Autorização Carta de Anuência Cédula de Crédito à Exportação Cédula de Crédito Rural Confissão de Dívida Debênture Duplicata Faturamento Laudo Técnico Nota de Crédito à Exportação Nota Promissória Rural Proposta Registro de Ponto Termo de Aceite Termo de Conduta Termo de Titularidade Para receber múltiplos documentos, basta separá-los por ponto-e-vírgula (;): Duplicata;Termo de Cessão.
posicaoDoCarimbo	Indica o local onde será colocado e exibido o carimbo com detalhes da assinatura no documento original. Neste carimbo temos o hash do documento original e uma URL que direciona para o portal da BITSIGN para validação do documento e de suas assinaturas. Topo: Carimbo será colocado no topo do documento. Esquerda: Carimbo será colocado na margem esquerda do documento. Direita: Carimbo será colocado na margem direita do documento. Rodapé: Carimbo será colocado no rodapé do documento. Importante: os carimbos consideram que o tamanho/formato dos documentos sejam A4. A configuração padrão é: Rodapé.
margensDoCarimbo	Margens (em pontos) para posicionamento do carimbo da assinatura no documento original. Será respeitada a distância mínima definida nesta propriedade ao incluir os dados do carimbo (URL e hash). A configuração padrão é: 0,0.
rejeicoesPadroes	Mensagens predefinidas com os possíveis motivos de rejeição, e que serão apresentadas ao assinante quando ele rejeitar a assinatura. Além da facilidade, isso auxiliará o contratante na tomada de decisões ou na geração de estatísticas, pois a mensagem de rejeição será entregue através dos callbacks, colocada no atributo Complemento. Para múltiplos motivos, basta separá-los por ponto-e-vírgula (;): Em desacordo com os valores.;Fora do horário permitido..
acompanhamentoAoVivo	Indica se o lote poderá ter ou não o acompanhamento ao vivo do andamento das assinaturas de todos os documentos envolvidos no mesmo. Ao submeter o lote, a BITSIGN irá disponibilizar um link público, para quem tiver acesso à ele, possa visualizar o andamento das assinaturas. A BITSIGN também gera um link (âncora) para cada documento, simplesmente sufixando o nome do arquivo no link gerado para o lote, o que permitirá posicionar a rolagem da página exatamente no local onde está o documento. Clique aqui para ver um exemplo do acompanhamento ao vivo. A configuração padrão é: true.
periodoParaLembrete	Para evitar cair no esquecimento dos assinantes, a BITSIGN pode lembrá-los que há documentos pendentes de assinaturas. Periodicamente fazemos a análise, e se houver documentos que ainda não foram concluídos, notificamos os assinantes para que regularizem (assinando ou rejeitando). As notificações são recorrentes, mas respeitarão o prazo determinado neste parâmetro, que pode ser: Diário: Envio diário de notificações (1 dia). Semanal: Envio semanal de notificações (7 dias). Quinzenal: Envio quinzenal de notificações (15 dias). Mensal: Envio mensal de notificações (30 dias). A configuração padrão é: Semanal.
aliasDoRemetente	Através desta opção é possível customizar o alias do remetente dos e-mails que são gerados e enviados pela Plataforma. O endereço de e-mail será sempre o mesmo; o que esta configuração faz é apenas definir um nome amigável que é visualizado pelos leitores de e-mails. O valor informado neste campo será combinado com o nome da Plataforma, ficando da seguinte forma: BITFIN Tecnologia (Via BITSIGN) <no-reply@bitsign.com.br>

Callbacks

O processo de notificação do contratante é chamado de Callbacks. Com eles, o contratante pode, opcionalmente, fornecer uma URL de acesso para que a BITSIGN possa notificá-lo sempre que algum evento relevante do processo ocorrer. Isso permitirá ao contratante um controle muito mais refinado do processo de assinaturas, podendo, por exemplo, guiar o andamento de algum processo ou esteira interna que dependa das assinaturas destes documentos.

Os callbacks são enviados para o cliente através do método POST do protocolo HTTP, onde em seu corpo, teremos o objeto callback serializado em formato JSON ou XML. Para entendimento e familiarização, temos abaixo o objeto de callback serializado em JSON. Apesar de autoexplicativo, apenas é necessária uma consideração sobre o atributo Id: quando o evento é referente ao Assinante, o Id será o número do documento da entidade assinante (CPF/CNPJ), caso contrário, será retornado o identificador da assinatura, do documento ou do lote.

{
  "Evento": "Assinante",
  "Id": "12345678900",
  "Status": "Rejeitado",
  "Data": "2024-11-21T03:23:53.491643-03:00",
  "Complemento": {
    "Observacoes": "Em desacordo com os valores."
  },
  "Tags": "contratoId=7362",
  "AplicacaoId": "1661666c-8048-4175-a1ea-06775744caa0"
}

Combinado com a URL, também é disponibilizada uma opção que permite configurar os eventos que devem ser reportados. Isso evitará que sejam encaminhados eventos que talvez não sejam úteis para o contratante. Abaixo estão detalhados os eventos, o quando e o por que eles ocorrem:

Serviço de Dumps

Templates

Quando há um grande volume de documentos para assinatura, poderá ser extremamente oneroso a geração, o envio e o processamento por parte da BITSIGN. Isso obrigará a ter que lidar com problemas de performance, largura de banda e limitadores de tráfego, entre outras coisas. Em geral, grandes volumes de documentos são gerados e partir de uma lista de dados, que são submetidos, linha à linha, para o relatório que exibe as informações, gera o documento (PDF, muitas vezes) e o submete para assinatura dos envolvidos.

A BITSIGN definiu um conceito de templates, em que os contratantes podem submeter um conjunto de dados para extração e geração do documento, evitando assim trafegar dezenas ou milhares de arquivos. A sua utilização é simples: basta informar dentro do manifesto o arquivo que representa o conjunto de dados, suas características (perfis de assinaturas, assinantes, política, carimbo do tempo, etc.) e o nome do modelo através da propriedade Template; quando a BITSIGN receber um lote com um documento associado à um template, identificará que há uma "expansão" e processará o arquivo, gerando e configurando os documentos de acordo com os dados informados nele. Caso você tenha necessidade de um template customizado, entre em contato. Atualmente, a BITSIGN oferece, gratuitamente e publicamente, os templates abaixo:

Buscador de Recursos

Entre o conjunto de API's que a BITSIGN oferece para interagir com o processo de assinaturas, existe também uma em especial que permite buscar por recursos (lotes, documentos, assinaturas, notificações, etc.) que foram enviados ou gerados pela plataforma. A finalidade desta API é permitir a realização de uma busca mais explícita e detalhada para toda a base histórica das informações que trafegaram de alguma forma pela plataforma.

Chamada de Buscador, este serviço recebe um conjunto de parâmetros que são utilizados para filtrar os recursos. Esses parâmetros são representados pela classe ParametrosDeBusca e seus valores são utilizados para filtrar a busca por um determinado recurso. O resultado é uma relação dos recursos solicitados e filtrados, porém são otimizados para não sobrecarregar a comunicação; isso quer dizer que terá informações suficientes para que, se necessário, utilize os serviços dos respectivos recursos para extrair maiores informações.

Esse serviço concederá acesso às aplicações para que elas possam ter acesso e exibir toda a base de dados de documentos digitais do contratante, sem a necessidade de se criar e/ou manter esses dados localmente. Se desejar criar uma espécie de dashboard diretamente em seu sistema para exibir ao(s) usuário(s) as assinaturas pendentes, utilize este serviço.

Bibliotecas

Status dos Serviços

A BITSIGN oferece um endpoint que permite monitorar a saúde dos serviços que são oferecidos e que são consumidos pela plataforma, e que todos contribuem para atender o processo de assinaturas digitais. O acesso se dá através deste link e retorna um conteúdo em formato JSON, qual pode também integrar e monitorar sistemicamente o status destes serviços. Opcionalmente, também existe um painel que permite o acompanhamento de uma forma mais amigável.

Badges de Status

Se estiver trabalhando com uma aplicação Web, você poderá utilizar os badges que a BITSIGN oferece com o status atual do lote. Isso permitirá você incorporar em sua aplicação para exibir aos usuários a situação em que se encontra o lote de documentos enviados para assinatura, sem a necessidade de manter dentro em sua base de dados o status e garantir que ele esteja sempre atualizado.

Você pode embutir isso em sua página HTML através de um <iframe/>, onde no atributo src você aponta para a URL da BITSIGN informando o identificador (através da querystring id) do lote que deseja exibir o status. A BITSIGN retornará uma página HTML com apenas o bagde e as informações referentes ao lote solicitado. A seguir vemos o código HTML com a URL de acesso correspondente para que você possa embutir em suas aplicações; e mais abaixo, temos os badges de exemplo:

<iframe 
    src="https://sandbox.bitsign.com.br/aovivo/badge?id=60852917-cc9e-4303-b40d-f52f848ab20f" 
    style="width: 100%" 
    frameborder="0"></iframe>

PARCEIROS

A BITSIGN possui parceria com algumas instituições para viabilizar o processo de assinaturas digitais. Em geral, estas parcerias visam exclusivamente atender demandas customizadas destes parceiros que não estão contempladas no modelo tradicional.

Esta seção relaciona as parcerias existentes e documenta detalhadamente os ajustes necessários que os contratantes devem realizar em suas aplicações/integrações para que seja possível o envio dos documentos e a realização das assinaturas.

Singulare

A BITSIGN está homologada e consegue realizar assinaturas digitais em contratos, termos de cessão e duplicatas de operações que são negociadas através de fundos FIDCs hospedados na Singulare. Esta integração entre BITSIGN e Singulare permite com que as consultoras e gestoras utilizem a BITSIGN como certificadora oficial de suas operações.

O funcionamento correto desta integração exige uma colaboração do contratante em fazer os ajustes sistêmicos para que a respectiva operação em análise pela Singulare seja devidamente associada aos documentos que deverão ser assinados (termos de cessão e as duplicatas). Abaixo temos os itens que devem ser analisados e devidamente implantados para o correto funcionamento:

• Contratação de um dos planos disponíveis;
• Adição da aplicação predefinida chamada Singulare;
  • Em Entidades Vinculadas cadastrar os fundos FIDCs operados por este contratante.
• Dentro do pacote deverá conter:
  • Arquivo de Manifesto;
    • A associação entre os documentos para a assinatura e a Singulare se dará com a inclusão de duas tags no lote a ser enviado:
      • cnpjdofundo: número do CNPJ do fundo que foi previamente cadastrado nas Entidades Vinculadas da aplicação da Singulare;
      • termodecessao: corresponderá ao mesmo número informado no cabeçalho do arquivo CNAB enviado para a Singulare nas posições 111 a 117 (com 7 caracteres).
  • PDF com o Termo de Cessão;
  • Arquivo CSV com a relação de Duplicatas, de acordo com o template BITSIGN.Duplicata.
    • Deverá conter exatamente os mesmos títulos do CNAB enviado para a Singulare.

MODELOS DE ASSINATURA

Os modelos de assinaturas estão divididas em duas opções: digital e eletrônica, e de forma resumida, a característica de cada uma é exibida nos quadrantes abaixo:

Todo lote deve, obrigatoriamente, indicar qual modelo de assinatura deseja que seja aplicado a todos os seus documentos, ou seja, não é permitido que dentro de um lote haja documentos para assinatura digital e eletrônica simultaneamente. Todo lote possui uma propriedade chamada ModeloDeAssinatura que deverá ser configurada com uma das seguintes opções:

• D: para Assinatura Digital;
• E: para Assinatura Eletrônica.

Identificação do Assinante

A identificação do assinante é um processo que tenta garantir que a pessoa é quem diz ser; a escolha do modelo de assinatura (Digital ou Eletrônico) vai determinar qual o tipo de identificação dos assinantes envolvidos no documento.

Quando optar pelo modelo Digital haverá a obrigatoriedade do assinante apresentar um certificado digital válido, que pode estar subordinado à ICP-Brasil ou a alguma cadeia privada. Em geral, como os certificados possuem os dados do respectivo proprietário (CPF/CNPJ), ele somente poderá assinar documentos que estão endereçados a sua entidade, constante neste certificado.

Já quando o modelo escolhido for o Eletrônico, para os assinantes se identificarem, terão que digitar seus dados pessoais (nome, CPF/CNPJ e data de nascimento/fundação) para confirmar e avançar no processo de assinatura. Se os dados confirmados forem válidos, então um token será gerado e enviado que o assinante possa informá-lo e concluir a assinatura dos documentos pendentes. Os dados cadastrais dos assinantes deverão ser informados durante o envio do documento para assinatura e serão armazenados para posterior validação, que ocorrerá no momento da assinatura.

Após a confirmação dos dados cadastrais, um token é gerado e enviado para o e-mail cadastrado do assinante. Este token nada mais é que um código alfanumérico que é gerado e deverá ser informado durante o processo para concluir com sucesso a assinatura do(s) documento(s).

PADRÕES DE ASSINATURA DIGITAL

Padrão CAdES

Este é um dos padrões mais utilizados atualmente, e um dos seus principais objetivos e permitir a assinatura digital em qualquer tipo de arquivo. Como não importa o formato do arquivo a ser assinado, este padrão produz um novo arquivo, com extensão P7S, que além de conter as assinaturas e seus artefatos, inclui o arquivo original que foi assinado. Este é o modelo "anexado" de assinatura; há a possibilidade também de ter a assinatura "desanexada", onde o arquivo P7S somente irá conter as assinaturas, sem seu conteúdo original.

Apesar de extremamente flexível, o arquivo produzido por este padrão (P7S) é de difícil visualização das assinaturas, e para dificultar, o arquivo original não tem qualquer evidência que uma assinatura digital foi realizada. Isso exigirá um software ou serviço para extrair e exibir as assinaturas. Felizmente, a BITSIGN oferece um visualizador gratuito de assinaturas digitais, mesmo para aqueles arquivos que não foram assinados pela plataforma.

Padrão PAdES

O padrão PAdES (PDF Advanced Electronic Signatures) fornece uma especificação para assinar e incorporar os artefatos das assinaturas digitais na estrutura de um arquivo PDF. Uma de suas princiais funcionalidades é permitir a visualização eletrônica da mesma forma que a impressa. Isso quer dizer que, ao contrário do padrão CAdES, podemos estampar os dados da assinatura no interior do documento PDF, posicionando a assinatura no mesmo local onde se assinaria fisicamente o documento, o que facilita a visualização por qualquer pessoa sem a necessidade de ferramentas ou leitores específicos.

A BITSIGN suporta esse padrão de assinatura nativamente em sua plataforma, e compete ao contratante especificar este padrão no momento do envio dos documentos, utilizando o atributo Padrao do elemento Documento. O único parâmetro adicional necessário para o padrão PAdES é a posição em que a assinatura será estampada no interior do documento PDF, que pode ser utilizada a propriedade Assinante.Posicao ou Assinatura.Posicoes; são nestas propriedades que se informa o número da página e as coordenadas (X e Y) onde deverá ser estampado o carimbo das assinaturas a medida em que os assinantes as realizam. Abaixo estão algumas considerações sobre este padrão:

• Somente arquivos PDFs são suportados;
• Selo da Assinatura
  • Assinatura.Posicoes: utilize esta propriedade para especificar as regiões de assinantes onde elas deverão ser estampadas a medida em que elas são realizadas;
  • Assinante.Posicao: quando há a necessidade de especificar o local onde a assinatura deverá ser estampada, recorra a esta posição para atribuir o local exato daquele assinante;
  • Importante: Se ambas as posições forem omitidas, não será estampado o selo da assinatura no documento, ficando a mesma invisível; se ambas forem definidas, prevalece a do nível mais alto, que é a propriedade Assinatura.Posicoes.
• Pelo fato do padrão de assinatura ser uma característica do documento, um lote pode ser composto de documentos em qualquer um destes padrões;
• O eixo X é o horizontal, enquanto o Y é o vertical. O ponto de referência dos eixos é rodapé/esquerda e não topo/esquerda;
• Como há necessidade de saber antecipadamente o local onde as assinaturas serão desenhadas, este tipo de documento não suporta assinaturas opcionais;
• Se o nome do assinante ultrapassar 40 caracteres, os nomes intermediários serão abreviados;
• As dimensões do selo da assinatura gerado pela BITSIGN é 210pt de largura por 50pt de altura.

Padrão XAdES

Da mesma forma que o PAdES está para arquivos PDF, o padrão XAdES é exclusivo para assinatura de arquivos XML. Isso utilizará os recursos nativos da própria estrutura XML para acomodar os novos elementos que serão produzidos pelas assinaturas digitais (XML-DSig). Em geral, arquivos XML são comumente utilizados em integrações entre sistemas, que utilizam a assinatura digital para garantir a integridade da mensagem e garantir que o assinante seja, de fato, quem ele diz ser.

Um cenário bastante comum onde este padrão de assinaturas é aplicado, é durante a emissão de notas fiscais junto às Secretarias de Fazenda dos Estados (SEFAZ), que obrigam os emitentes das notas fiscais e assinar digitalmente as notas com seus respectivos certificados (e-CNPJ). Algumas prefeituras utilizam a mesma técnica para assinar arquivos XML para a emissão de notas fiscais (de serviço). Outros serviços que circundam o processo fiscal do governo também utilizam massivamente esta técnica, tais como: conhecimento de transporte, cartas de correção, manifesto do destinatário, etc.

Entre os estilos de assinatura de arquivos XML, podemos destacar duas categorias: Enveloped e Enveloping. A primeira delas, Enveloped, a assinatura é incluída como um subelemento do elemento que está sendo assinado; já com a opçãoEnveloping, ao contrário, o elemento assinado é envolvido pela assinatura. A escolha entre um destes estilos vai depender de como o destinatário da mensagem assinada exige. Para exemplificar, de acordo com o Manual do Contribuinte, a SEFAZ exige que a assinatura utilize o estilo Enveloped para os documentos fiscais.

Além do estilo, é necessário também especificar qual elemento que será assinado. Como estes dois parâmetros são exigidos para realizar a assinatura, é necessário especificar estas informações através da propriedade Posicao, que está disponível para cada assinante do documento. Para especificar o formato, utilize a propriedade Estilo; já o nome do elemento a ser assinado, deverá ser informado através da propriedade Tag.

Políticas Suportadas

Atualmente a BITSIGN oferece assinaturas digitais em padrão CAdES (CMS Advanced Electronic Signatures) e PAdES (PDF Advanced Electronic Signatures) e XAdES (XML Advanced Electronic Signatures), podendo estar asssociadas (ou não) as regras impostas pelas políticas da ICP-Brasil. As seguintes políticas são suportadas:

FINANCEIRO E COBRANÇA

Planos Contratados

O plano contratado define, basicamente, a escala de documentos/assinaturas que estão contempladas para pagamento do respectivo valor. Qualquer documento/assinatura excedente, a quantidade que excede a faixa, será multiplicada pelo valor unitário excedente que também é informado durante a contratação do plano. A API fornece recursos para listar todos os planos contratados, seus respectivos status, o progresso do consumo de armazenamento e todas as demais características de cada um deles.

Caso o plano atual vigente não esteja de acordo com as necessidades atuais da empresa, você poderá optar por contratar um novo plano que melhor se encaixa a nova realidade de sua empresa. Para isso, basta passar novamente pelo processo de contratação e contratar um novo plano. Uma vez que este novo plano seja efetivado, o consumo do plano anterior será migrado para o novo, inativando o plano antigo.

Fechamentos

O fechamento é apuração mensal que é realizada pela BITSIGN e ocorre todo primeiro dia do mês, que sumariza toda a quantidade de lotes, documentos e assinaturas que foram realizadas no decorrer do mês. O valor é totalizado pelo contratante, independentemente de quantas aplicações estejam cadastradas. De qualquer forma, o demonstrativo irá detalhar e quantificar o consumo por aplicação para que o contratante possa diferenciar.

Uma vez que esta apuração é concluída, uma notificação é enviada via e-mail para a contratante, exibindo o resumo de todas as atividades que foram realizadas e seus respectivos valores. Anexado ao e-mail, também teremos os dados para proceder com o pagamento e dados referente à nota fiscal de serviços. Opcionalmente, você pode optar por também receber esta notificação através de callbacks; para isso, basta incluir a opção Financeiro no parâmetro eventosReportados. Com o Id do fechamento em mãos, você pode também acessar todos os detalhes dele através da API da categoria Financeiro.

A BITSIGN oferece uma visualização agrupada por centro de custo de todos os lotes assinados. Para ter esta visualização, apenas é necessário incluir uma tag chamada BSCentroDeCusto, definindo o nome desejado que o identifique para que, durante a apuração mensal, seja incluída a sumarização por cada um destes centros de custo.

Pagamentos

Os fechamentos determinam o valor à ser pago à BITSIGN pelos contratantes. O fechamento é realizado todo primeiro dia mês, e a data de vencimento é definida para todo dia 8 e será cobrado através de boleto bancário. Os pagamentos não realizados, depois do vencimento, a BITSIGN notifica, também via e-mail, de que há pendências financeiras ainda em aberto. Depois de 10 dias sem o devido pagamento, a BITSIGN se reserva ao direito de bloquear o serviço para o envio de novos lotes de documentos até que o pagamento seja devidamente realizado. Quando isso ocorrer, algumas API's passarão a retornar o código 402 - Payment Required.

VISUALIZADOR DE DOCUMENTOS

Documentos que são assinados digitalmente através do padrão CAdES, não são fáceis de visualizar quem são os assinantes e as características das assinaturas. Para isso, a BITSIGN oferece em seu site, um visualizador que permite qualquer pessoa de posse de um documento, submeter para análise, extração e validação das assinaturas.

Este visualizador é capaz de analisar documentos P7S, PDF e XML, sendo assinados no padrão CAdES, PAdES ou XAdES. É importante dizer que este visualizador não está restrito à documentos que são assinados também por esta plataforma, ou seja, ele é capaz de analisar documentos que são assinados por qualquer outro portal de assinaturas digitais.

Por fim, este visualizador também é capaz de receber o código de verificação do documento assinado por esta plataforma, e exibir todos os detalhes dos assinantes que foram coletadas durante o processo de assinaturas. Isso permitirá à qualquer pessoa, que conheça este código, consultar e analisar a autenticidade e integridade das assinaturas que compõem o documento.

CADEIAS DE CERTIFICAÇÃO

ICP-Brasil

A ICP-Brasil é o órgão governamental que, define, rege e padroniza todas as políticas de assinaturas digitais. Ela também é responsável por garantir a estrutura (raiz e intermediários) de certificação à qual todos os certificados deverão estar subordinados. Essa hierarquia garante com que os certificados utilizados para assinatura sejam emitidos por Autoridades Certificadoras (ACs) que estejam devidamente homologadas pela ICP-Brasil.

Honrar todas as políticas e as regras impostas pela ICP-Brasil, garantirá com que os documentos assinados com estes certificados digitais, estejam de acordo com a Medida Provisória 2.200-2/2001. Por padrão, todos os documentos assinados pela BITSIGN seguem a padronização para garantir a validade jurídica implícita gerada por assinaturas com certificados digitais emitidos por alguma das Autoridades Certificadoras homologadas.

Opcionalmente, você poderá baixar toda a cadeia de certificação vigente que é disponibilizada pela ICP-Brasil através desde endereço. Baixe e instale no computador que fará uso dos certificados, para que o sistema operacional reconheça e seja capaz de construir e validar toda a hierarquia até sua raiz.

Cadeias Privadas

Além de suporte a assinaturas no padrão ICP-Brasil, a BITSIGN oferece aos clientes da plataforma a possibilidade da criação de cadeias privadas de certificação, que permite a customização de aplicações, serviços e funcionalidades para confiarem nesta cadeia customizada. Entre suas utilizações, podemos citar: realização de assinaturas digitais (desde que a validade seja acordada entre as partes), autenticação de usuários ou para a proteção de mensagens que são trocadas entre aplicações.

Para sua utilização, basta a criar a Unidade Organizacional (OU) e emitir os certificados que estarão subordinados a ela. A BITSIGN se encarrega de gerar a cadeia privada para instalação nos computadores/aplicações e faz a gestão das revogações, emitindo e atualizando as listas (CRL's). Para fins de automação, a emissão e revogação dos certificados podem ser realizadas através das API's.

Certificados para Testes

Para sucesso nos testes em ambiente de SANDBOX, obviamente, é necessário também que se realize as assinaturas. Para isso, é necessário ter um certificado digital válido. Mas quando estamos em ambiente de desenvolvimento, nem sempre temos acesso aos certificados reais para fazer os testes.

A BITSIGN entende que esta etapa dos testes é essencial para o sucesso da implementação, e para tornar estes testes mais ágeis sem depender de certificados reais, é disponibilizado uma opção para a geração de certificados que simulam os certificados emitidos pela ICP-Brasil, mas sem qualquer validade jurídica, e que são úteis exclusivamente se utilizados pelo ambiente de SANDBOX da BITSIGN.

Clique no botão a seguir para preencher o formulário, e informe os dados cadastrais para geração do certificado de testes. Ao concluir, a plataforma irá gerar um arquivo com extensão PFX, qual você poderá incluir no repositório de certificados do Windows e utilizá-lo para assinar os documentos enviados para a BITSIGN no ambiente SANDBOX.

Se desejar fazer uso deste certificado em alguma aplicação ou instalá-lo no sistema operacional, você deverá baixar a cadeia de certificação (privada) para garantir que o mesmo seja considerado um certificado confiável. Clique aqui e baixe o pacote com todos os certificados necessários para isso.

SUPORTE

Caso esta documentação não tenha sido suficiente para esclarecer suas dúvidas ou houve alguma dificuldade em realizar a integração, entre em contato através deste formulário ou via WhatsApp através do telefone (19) 9.9901-1065, para, muito brevemente, entrarmos em contato para tentar esclarecer e sanar suas dúvidas. Utilize este mesmo canal se desejar nos enviar alguma crítica ou sugestão.