Pré-requisito

Antes de iniciar os testes com a API Certillion são necessários alguns pré-requisitos:

• Obter credenciais de acesso
• Possuir um certificado ICP-Brasil válido para testar sua integração ou solicitar certificado de teste
• Instalar o app Certillion caso o certificado for do tipo A1 (arquivo) ou mídia física A3 (cartão ou token)

As credenciais podem ser obtidas na guia de Contato  solicitando uma conta teste. Ao solicitar a conta teste é necessário enviar as seguintes informações:

• Nome da Empresa
• Nome visível da empresa (que irá aparecer na tela de autenticação para o usuário)
• CNPJ
• Contato técnico: nome, e-mail, telefone

Autenticação do Sistema

Para poder chamar os métodos da API Certillion é necessário primeiro autenticar o sistema que fará as solicitações. Com as credenciais fornecidas (ver Pré-requisitos), faça a autenticação através do método:

Listagem de Certificados Suportados em Nuvem

O Certillion suporta todos os provedores de certificados em nuvem na ICP-Brasil (PSC – Prestadores de Serviço de Confiança). O servidor Certillion fornece e atualiza automaticamente a listagem completa dos identificadores dos PSCs.

O desenvolvedor pode utilizar esta listagem para gerar a interface com seu usuário, para que possam facilmente identificar e utilizar os certificados digitais através do Certillion.

Localização de Certificados

Utilizando a API, também é possível localizar os certificados que o usuário possui em nuvem,  baseando-se no identificador legal que se deseja pesquisar.

Observação: Este método retornará uma listagem cujas entradas é o resultado da busca em cada um dos PSCs. Cada entrada nesta listagem conterá o identificador do PSC e um status indicando se o usuário tem certificado (status=”S”). Caso todas as entradas estejam com o status=”N”, a única possibilidade a oferecer para o usuário é a assinatura utilizando o app Certillion com certificados locais, A1 em arquivo ou A3 em mídia física (cartão ou token).

Autenticação do Usuário (Signatário)

Antes de assinar qualquer documento, o usuário precisa autorizar o acesso ao seu certificado digital.

Você pode conceder a autorização em três modalidades:

• single_signature: Usuário concede a autorização para o sistema executar UMA requisição para assinatura de UM documento.
• multiple_signature: Usuário concede a autorização para o sistema exeutar UMA requisição para um lote de documentos (UM ou mais).
• signature_session: Usuário concede a autorização para o sistema realizar, por um período determinado de tempo, quantas requisições desejar. Cada requisição pode ser para um lote de um ou mais arquivos.

Assinatura de Documentos

Siga os passos descritos no diagrama abaixo para assinar o documento.

Importante! Tratamento Correto de Erros

Caso qualquer um dos 3 métodos acima utilizados na assinatura falhe, repita APENAS a chamada desse método:

• se o 2º método /signature falhar, chame apenas este método, NÃO é necessário fazer upload novamente do arquivo 
• se o 3º método /document (get) falhar, faça apenas outra chamada de download do documento assinado, NÃO é necessário fazer novo upload nem solicitar nova assinatura

Repetir as requisições  processadas corretamente pode gerar cobrança adicional para o sistema que solicita as assinaturas.

Verificação de Assinaturas

O Certillion verifica qualquer assinatura digital ICP-Brasil, mesmo que um sistema externo tenha feito a assinatura. Para isso, use a chamada /validate.

Para verificar os possíveis códigos de retorno do Certillion, consulte a API Online no método Códigos de Status retornados pelas chamadas ao Certillion

Otimização de Sigilo e Desempenho

Como visto no processo de assinatura, você deve enviar o documento para os servidores Certillion para que ele seja assinado ou verificado. Após a assinatura, o documento também deve ser baixado. No Certillion, garantimos o sigilo dos documentos por meio das seguintes práticas:

• não é feito nenhum processamento além do necessário para o tratamento da assinatura digital;
• nenhuma informação contida nos documentos é extraída ou analisada, mesmo de forma anônima;
• o documento é armazenado de forma cifrada nos servidores;
• o documento permanece nos servidores por no mínimo 24 horas e no máximo 48 horas para que seja feito o download após a assinatura, após isso ele é apagado de forma irreversível.

Apesar disso, quando utilizando o servidor Certillion em nuvem, alguns solicitantes podem preferir, no entanto, não ter que enviar documentos para um serviço terceirizado. Através do componente Certillion Agent é possível que o documento seja pré-processado no ambiente do solicitante, evitando a necessidade de upload. Da mesma forma, após concluir a assinatura, o sistema gera o documento assinado localmente. Esta abordagem tem as seguintes vantagens:

• Compliance com possíveis normas da empresa de não externalizar documentos com informações sigilosas ou privativas;
• A assinatura é mais rápida porque não é necessário transmitir os documentos em ambos os sentidos.
• Não é necessário alteração do código de integração, o Certillion Agent é um componente neutro de rede.

Após concluir a integração do seu sistema, solicite a instalação da versão do Certillion Agent em seu ambiente.

Assinador Certillion

Certificados digitais em nuvem dispensam o uso de qualquer aplicativo no ambiente do usuário que irá assinar os documentos. O ambiente do PSC, devidamente credenciado para este fim, processa os certificados digitais de forma segura.

Quando o usuário possui certificados digitais tradicionais (A1 em arquivo e A3 em cartão ou token) é uma falha grave de segurança solicitar que ele forneça o certificado para o seu sistema. Isso pode invalidar a assinatura e gerar responsabilização legal para quem o recebeu.

Para proteger o sistema que solicita a assinatura feita com certificados tradicionais, deve-se solicitar ao usuário que utilize o assinador local Certillion. Este aplicativo garante que você gere a assinatura de forma segura e aderente às normas.

Se você desenvolveu seu sistema com a API Certillion, não precisa alterar o código de integração, pois ele já é compatível com o assinador!

Outras grandes vantagem do assinador Certillion:

• Não é necessário plugins para seu funcionamento em sistemas web;
• Funciona nas principais plataformas: Windows, Mac, Android, iPhone, iPad e Linux;
• Não possui custo adicional, é gratuito inclusive para download;