IntegraICP FAQ

IntegraICP

IntegraICP FAQ

Perguntas e respostas sobre integração, autenticação e assinatura digital via API.

Visão Geral & Fluxo

O IntegraICP é capaz de centralizar os prestadores de serviços de confiança (PSCs) do Brasil em uma única API. O fluxo básico consiste em 6 etapas:

  1. Obter as clearances: Inicia a jornada e retorna a lista de provedores disponíveis para o CPF chamado via
    GET /authentications com channelId, secret_data e callback_uri.
  2. Escolha do provedor:
    Selecionar um PSC da lista ou usar autostart=true (por padrão a API selecionará o VidaaS).
  3. Receber o callback:
    A API envia o CredentialId para a sua callback_uri.
  4. Consulta credencial:
    GET /credentials/{credentialId} com o code verifier.
  5. Gerar digest:
    Calcular o SHA256 de cada conteúdo e codificar em Base64 padrão.
  6. Solicitar assinatura:
    POST /signatures com a lista de conteúdos.

Perguntas Frequentes

1. O que é o IntegraICP?
Uma plataforma capaz de centralizar os principais prestadores de serviços de confiança do Brasil em um único produto e expõe APIs para autenticação e assinatura digital com certificados em nuvem. Ela simplifica a integração mantendo um fluxo padronizado.
2. O que é o Channel e para que ele serve?
O Channel funciona como uma chave de acesso (API Key). Ele identifica a aplicação no ecossistema e aparece diretamente nos endpoints. Sem um channel válido, a API retorna erro de canal inválido e não completará as chamadas. Para adquirir um channel, envie um e-mail para contato.
3. O parâmetro subject_key é obrigatório?
Não. O subject_key (normalmente o CPF do proponente, sem formatação, NÃO PODE CONTER PONTOS OU ESPAÇOS) é opcional. Se omitido, a API pode listar todos os provedores registrados no canal, sem focar em um proponente específico.
4. O que é secret_data e por que ele é importante?
O secret_data garante a segurança (PKCE - RFC 7636). Na autenticação, é o code challenge. Nas requisições de credenciais e assinaturas, é o code verifier correspondente. Falhas neste pareamento geram erros de autorização.
5. Para que serve a API de Credentials?
Permite consultar os detalhes do certificado selecionado após a autenticação. Retorna dados como:

credentialId CPF Serial Issuer Validade X.509 encoded
6. O que faz o parâmetro autostart?
Quando autostart=true, a API inicia o processo automaticamente com a primeira opção de clearance disponível e redireciona o usuário, ignorando a etapa de exibição manual de provedores.
7. Existem limites de expiração para a sessão?
Sim. credential_lifetime tem o limite de até 168 horas (o que dá por volta de 7 dias) e clearance_lifetime até 24 horas.
8. Como devo preparar o contentDigest?
O contentDigest deve ser o hash SHA256 do conteúdo original, codificado em Base64. Atenção: não utilize Base64 URL Encoded.
9. Quais políticas de assinatura estão disponíveis atualmente no IntegraICP?
RAW (assina diretamente o hash) e CMS (padrão RFC 5652). Se omitido, utiliza o padrão configurado para o channel.
10. Quais são os erros mais comuns?
  • 400: Problemas de estrutura (Invalid Channel ou digest inválido).
  • 403: Problema de PKCE/secret_data ou credencial expirada.
  • 404: Credencial não encontrada.
11. Como obter o desbloqueio de canais para outros PSCs?
Caso necessite do desbloqueio de canais para outros PSCs, entre em contato com o agente comercial que está lhe atendendo e realize a solicitação.
12. O IntegraICP possui alguma biblioteca ou SDK prontos?
No momento a API não possui. A implementação e o consumo dos endpoints são de inteira responsabilidade do usuário.
13. O IntegraICP possui ambiente de homologação?
O IntegraICP não exige um ambiente de homologação distinto porque não mantém estado de negócio e nem persiste dados sensíveis. Todos os fluxos são efêmeros, isolados por Channel e protegidos por PKCE, permitindo que o mesmo endpoint seja usado com segurança para testes e produção, mudando apenas a configuração do canal.
14. Como eu transformo no final uma hash em um documento válido?
O documento original não é enviado para a API. Em vez disso, a aplicação gera uma hash criptográfica (SHA-256) do conteúdo e envia esse valor para assinatura. O IntegraICP utiliza o certificado digital do usuário para assinar essa hash, retornando uma assinatura criptográfica.

O documento final válido é obtido ao combinar o documento original com a assinatura retornada, permitindo que qualquer verificador confirme a integridade do conteúdo e a autoria da assinatura. Para a montagem estrutural desse documento final, o mercado geralmente utiliza frameworks próprios para esse fim, como iText, PDFBox, dentre outros.