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:

Passo	Descrição
1: /client_token	Chamada para autenticação utilizando as credenciais.

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.

Passo	Descrição
1: acessa a página de login via certificado digital	Acessa a página utilizando seu PSC.
2: solicita a página de login	Faz a solicitação de autenticação.
3: /psc-info	Chamada que busca todos os PSCs compatíveis com o Certillion.

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.

Passo	Descrição
1: informa CPF ou CNPJ	Identificador legal necessário para busca do PSC.
2: solicita lista de PSCs	Solicitação de PSCs atráves do identificador legal.
3: /find-psc-accounts	Chamada que encontra contas de PSC através de um identificador legal.

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.

Passo	Descrição
1: seleciona o PSC	Seleciona o seu PSC.
2: encaminha o PSC escolhido	Envia o PSC selecionado.
3: /authorize (retorna página de autenticação)	Chamada de autorização para o PSC identificar o signatário e o Certillion.
4: exibe página de autenticação	Aplicação exibe página de autenticação.
5: fornece dados de autenticação	Signatário fornece as credencias.
6: /token	Chamada para obter o código de segurança (token).

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.

Passo	Descrição
1: clica em assinar	Signatário seleciona opção de assinar.
2: solicita assinatura	Chama o método que solicita a assinatura do documento.
3: /document (POST)	Chamada que realiza o upload do documento a ser assinado.
4: /signature	Chamada que realiza a assinatura do documento.
5: /document (GET)	Chamada que realiza o download do documento assinado.

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.

Passo	Descrição
1: /document (POST) [opcional]	Faz o upload do documento a ser assinado.
2: /validate	Chamada que verifica qualquer assinatura digital ICP-Brasil.

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.

Passo	Descrição
1: /document (POST)	Chamada que realiza o upload do documento a ser assinado no servidor local do signátario.
2: cálculo hash	Resumo do documento que foi enviado. Cálculo do hash
3: /signature	Chamada que realiza a assinatura do documento no servidor local do signátario.
4: /signature	Chamada que realiza a assinatura do documento no servidor do Certillion.
5: /document (GET)	Chamada que realiza o download do documento assinado no servidor local do signátario.
6: gera documento assinado	Aplicação solicita o documento assinado no servidor local do signatário.

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;

Passo	Descrição
1: seleciona o PSC escolhido	Seleciona o seu PSC.
2: encaminha o PSC escolhido	Envia o PSC selecionado.
3: /authorize (retorna página de autenticação)	Chamada de autorização para o PSC identificar o signatário e o Certillion.
4: exibe página de autenticação	Aplicação exibe página de autenticação.
5: fornece dados de autenticação	Signatário fornece as credencias.
6: /token	Chamada para obter o código de segurança (token).

DOCUMENTAÇÃO

Tutoriais