O Assertiva Autentica é uma solução para onboarding, coleta de informações e assinatura de contratos, permitindo centralizar o gerenciamento de solicitações em uma única plataforma.
A solução possibilita criar fluxos personalizados para:
Coleta de dados cadastrais;
Envio e leitura de documentos;
Captura de selfie;
Validação de identidade por biometria facial;
Assinatura de propostas e contratos;
Anexação de documentos;
Acompanhamento de pedidos;
Geração de evidências assinatura;
Notificação de eventos por webhook.
A integração deve ser realizada por uma equipe técnica. Este artigo apresenta os principais conceitos e o fluxo de utilização da API.
1. Visão geral do funcionamento
O processo de integração do Assertiva Autentica é baseado na criação e no acompanhamento de pedidos.
Um pedido pode conter:
Uma ou mais partes envolvidas;
Anexos globais, compartilhados com todos os envolvidos;
Fluxos de coleta;
Documentos;
Campos cadastrais;
Etapas de assinatura;
Validações de identidade.
O fluxo geral é:
Consultar os fluxos disponíveis.
Selecionar o fluxo adequado para a operação.
Obter links temporários para envio de arquivos, quando necessário.
Criar um pedido.
Informar as partes envolvidas.
Enviar o link de acesso para cada parte.
Acompanhar o andamento do pedido.
Aprovar, reprovar, cancelar ou reenviar uma parte, quando necessário.
Obter os resultados após a finalização.
Baixar os documentos e gerar as evidências da operação.
2. Autenticação
O acesso às APIs da Assertiva utiliza credenciais de aplicação:
Client ID;
Secret.
Essas credenciais são utilizadas para gerar um token de acesso OAuth 2.0.
2.1 Endpoint para geração do token
Método: POST
URL:
https://api.assertivasolucoes.com.br/oauth2/v3/token
Configure a requisição utilizando:
Autorização: Basic Auth;
Usuário: Client ID;
Senha: Secret;
Tipo do corpo:
application/x-www-form-urlencoded;Parâmetro:
grant_type=client_credentials.
2.2 Utilização do token
Após gerar o token, envie-o nas requisições da API no cabeçalho:
Authorization: Bearer SEU_TOKEN_DE_ACESSO
O token deve ser armazenado com segurança e não deve ser exposto no código do front-end, em logs ou em repositórios públicos.
Para consultar o procedimento completo de criação das credenciais, acesse o artigo Como gerar credenciais e token de acesso para as APIs da Assertiva.
3. Conceitos principais
3.1 Pedido
O pedido representa uma solicitação de coleta ou assinatura.
Um pedido pode conter:
Uma ou mais partes;
Anexos globais;
Fluxos de coleta;
Dados cadastrais;
Documentos;
Informações necessárias para assinatura.
O pedido deve ser acompanhado até que seja finalizado, cancelado, reprovado ou atinja alguma situação de erro.
3.2 Parte
A parte representa uma pessoa ou empresa envolvida no pedido.
Ela contém os dados necessários para realizar uma coleta ou assinatura, como:
CPF ou CNPJ;
Nome;
Celular;
E-mail;
Perfil de assinatura;
Fluxo de coleta;
Anexos;
Campos cadastrais.
Um mesmo pedido pode possuir uma ou mais partes.
3.3 Perfil de assinatura
O perfil de assinatura define os campos e as informações necessárias para uma parte participar do fluxo.
Entre os dados que podem compor um perfil estão:
CPF;
CNPJ;
Nome;
Celular;
E-mail;
Dados adicionais exigidos pelo processo.
O perfil deve ser escolhido conforme o papel que a pessoa ou empresa desempenha na operação.
3.4 Artefato
Um artefato representa uma etapa ou módulo dentro de um fluxo de coleta.
Exemplos:
Captura de selfie;
Leitura de documento PDF;
Anexação de documentos;
Preenchimento de campos;
Assinatura de proposta;
Validação de identidade.
Os artefatos são configurados de acordo com a necessidade de cada fluxo.
3.5 Fluxo de coleta
O fluxo de coleta define as etapas que deverão ser executadas pela parte.
É possível utilizar fluxos diferentes para finalidades distintas, como:
Coleta de documentos pessoais;
Validação de identidade;
Assinatura de contratos;
Assinatura de propostas;
Coleta de selfie;
Envio de documentos como RG ou CNH.
A aplicação deve consultar os fluxos publicados e liberados antes de criar um pedido.
3.6 Carimbo do tempo
O carimbo do tempo registra informações relacionadas à finalização do fluxo pelo usuário.
Ele funciona como uma evidência da operação e pode conter:
Quem realizou a ação;
Data e hora;
Local;
Endereço IP;
Hash do documento ou da operação.
Essas informações podem ser utilizadas para comprovar a integridade e a realização do processo de assinatura.
4. Controllers da API
A API do Assertiva Autentica é organizada em controllers, cada um responsável por uma área funcional da solução.
Controller | Responsabilidade |
Fluxos | Consulta fluxos de coleta e assinatura publicados e liberados para uso. |
Arquivos | Gerencia uploads e downloads de arquivos relacionados às solicitações. |
Partes | Gerencia os envolvidos, status, links e resultados das partes. |
Gera e disponibiliza o PDF com os dados de uma parte finalizada. | |
Pedidos | Cria, consulta, filtra e gerencia pedidos de coleta ou assinatura. |
Perfis | Consulta os perfis disponíveis e seus campos cadastrais. |
Webhooks | Configura notificações sobre a finalização dos pedidos. |
5. Fluxos
O controller de Fluxos disponibiliza informações sobre os fluxos configurados no sistema.
Por meio dessa funcionalidade, a aplicação pode consultar:
Fluxos publicados;
Fluxos liberados para uso;
Identificadores dos fluxos;
Informações necessárias para criação de pedidos;
Anexos padrão de um fluxo.
Antes de abrir um pedido, a aplicação deve identificar qual fluxo será utilizado e verificar se ele está disponível para a empresa.
5.1 Anexos padrão
Alguns fluxos podem possuir anexos padrão. Esses arquivos podem ser adicionados automaticamente às solicitações criadas com aquele fluxo.
Os anexos padrão são diferentes dos anexos específicos enviados para uma determinada parte.
6. Arquivos
O controller de Arquivos é utilizado para gerenciar documentos associados às solicitações.
Suas principais funções são:
Obter links temporários para upload;
Enviar documentos;
Obter links temporários para download;
Baixar documentos após a finalização do processo;
Acessar arquivos resultantes da coleta ou assinatura.
6.1 Upload de documentos
O fluxo de upload utiliza uma URL temporária.
O processo normalmente segue estas etapas:
Solicitar um link temporário de upload.
Receber a URL e o identificador do arquivo.
Enviar o documento para a URL recebida.
Associar o arquivo ao pedido ou à parte correspondente.
As URLs temporárias devem ser utilizadas dentro do período de validade informado pela API.
6.2 Download de documentos
Após a finalização do pedido ou da parte, a aplicação pode solicitar um link temporário para baixar:
Documentos enviados;
Documentos coletados;
Documentos assinados;
Arquivos de resultado;
Documentos de auditoria, quando disponíveis.
A aplicação deve realizar o download imediatamente após receber a URL temporária.
7. Pedidos
O controller de Pedidos gerencia as solicitações de coleta e assinatura.
Entre as operações disponíveis estão:
Criar um novo pedido;
Listar pedidos;
Filtrar pedidos;
Consultar os detalhes de um pedido;
Consultar o resultado de um pedido finalizado.
7.1 Criar um pedido
Para criar um pedido, a aplicação deve reunir as informações necessárias, como:
Fluxo de coleta;
Partes envolvidas;
Perfil de cada parte;
Dados cadastrais;
Anexos;
Documentos;
Anexos globais.
O pedido deverá ser associado ao fluxo correto e às partes que participarão da operação.
7.2 Consultar pedidos
A consulta de pedidos permite acompanhar:
Identificador do pedido;
Data de criação;
Partes vinculadas;
Status atual;
Fluxo utilizado;
Documentos associados;
Resultado do processo, quando finalizado.
A aplicação deve armazenar o identificador do pedido para realizar as consultas posteriores.
7.3 Filtrar pedidos
Os pedidos podem ser filtrados conforme os critérios disponibilizados pela API, como:
Identificador;
Status;
Período de criação;
Parte envolvida;
Documento;
Tipo de solicitação.
O filtro deve ser utilizado para localizar pedidos específicos ou montar telas de acompanhamento.
8. Partes
O controller de Partes gerencia os envolvidos em um pedido.
As operações relacionadas às partes incluem:
Listar partes de uma solicitação;
Consultar o status de uma parte;
Obter o link de acesso ao fluxo;
Aprovar uma parte;
Reprovar uma parte;
Cancelar uma parte;
Reenviar uma parte;
Consultar o resultado de uma parte finalizada.
8.1 Link de acesso
Cada parte pode receber um link para acessar o fluxo de coleta ou assinatura.
Esse link pode ser encaminhado por canais como:
E-mail;
SMS;
Aplicação própria;
Portal ou sistema integrado.
O link deve ser tratado como informação sensível e não deve ser exposto indevidamente.
8.2 Status da parte
A aplicação deve acompanhar o status da parte antes de executar ações administrativas.
Exemplos de situações que podem ser utilizadas no controle do processo:
Aguardando início;
Em andamento;
Finalizada;
Aprovada;
Reprovada;
Cancelada.
Os valores exatos devem ser tratados conforme o retorno da API e a configuração do fluxo utilizado.
8.3 Aprovar ou reprovar uma parte
Uma parte pode ser aprovada ou reprovada de acordo com as regras do processo.
Antes de realizar essas operações, confirme:
Se a parte está em uma situação que permite a ação;
Se os dados foram analisados;
Se os documentos necessários foram enviados;
Se a justificativa é obrigatória;
Se a operação pode ser revertida.
8.4 Reenviar uma parte
O reenvio pode ser utilizado quando a parte não recebeu o link ou precisa realizar novamente determinada etapa.
Antes do reenvio, verifique:
Se o pedido ainda está ativo;
Se a parte pode receber um novo link;
Se os dados de contato estão atualizados;
Se o fluxo permite o reenvio.
9. Perfis
O controller de Perfis disponibiliza os perfis cadastrados no sistema.
Cada perfil pode indicar:
Nome do perfil;
Identificador;
Campos obrigatórios;
Campos opcionais;
Dados necessários para preenchimento da parte.
A aplicação deve consultar os perfis disponíveis antes de criar o pedido, garantindo que os campos necessários sejam preenchidos corretamente.
10. PDF de uma parte finalizada
O controller de PDF permite gerar ou obter um documento PDF contendo os dados de uma parte que concluiu o processo.
Esse documento pode reunir:
Dados cadastrais;
Informações coletadas;
Evidências do processo;
Informações da assinatura;
Carimbo do tempo;
Dados de auditoria.
O PDF deve ser armazenado em local seguro e com acesso restrito.
11. Webhooks
Os webhooks permitem receber notificações automáticas sobre eventos do processo.
Eles são recomendados para evitar consultas repetitivas à API e permitir que o sistema reaja rapidamente às alterações de status.
11.1 Funcionamento
O fluxo de notificação normalmente ocorre da seguinte forma:
A aplicação configura uma URL de webhook.
O Assertiva Autentica envia uma notificação quando ocorre um evento.
A aplicação recebe a notificação.
O sistema valida e armazena o evento.
A aplicação consulta os detalhes atualizados do pedido ou da parte.
11.2 Boas práticas para webhooks
A URL utilizada deve:
Utilizar HTTPS;
Estar disponível publicamente para o serviço autorizado;
Validar a origem da requisição;
Responder rapidamente;
Armazenar o identificador do evento ou pedido;
Evitar processamentos duplicados;
Implementar mecanismo de retentativa;
Registrar erros sem expor dados sensíveis.
O webhook deve ser utilizado como mecanismo de notificação. Para obter os dados completos e atualizados, a aplicação deve consultar o pedido ou a parte na API.
12. Fluxo recomendado de integração
Etapa 1 — Configurar as credenciais
Crie as credenciais da API no painel da Assertiva e armazene o Client ID e o Secret de forma segura.
Etapa 2 — Gerar o token
Utilize o endpoint OAuth 2.0 para gerar o token de acesso.
Etapa 3 — Consultar os fluxos
Verifique quais fluxos de coleta e assinatura estão publicados e liberados para a empresa.
Etapa 4 — Consultar os perfis
Identifique os perfis disponíveis e os campos obrigatórios para cada parte.
Etapa 5 — Preparar os documentos
Solicite os links temporários de upload e envie os documentos necessários.
Etapa 6 — Criar o pedido
Monte o pedido com:
Fluxo;
Partes;
Perfis;
Dados cadastrais;
Documentos;
Anexos.
Etapa 7 — Enviar os links
Envie o link de acesso de cada parte pelo canal definido no processo.
Etapa 8 — Acompanhar o andamento
Utilize consultas de status ou webhooks para acompanhar o pedido e as partes.
Etapa 9 — Tratar pendências
Quando necessário:
Reenvie o link;
Atualize os dados da parte;
Aprove;
Reprove;
Cancele;
Solicite novos documentos.
Etapa 10 — Obter o resultado
Após a finalização:
Consulte o resultado;
Baixe os documentos;
Gere o PDF da parte;
Armazene as evidências;
Atualize o status no sistema integrado.
13. Dados e segurança
O Assertiva Autentica pode processar dados pessoais, documentos de identificação, imagens e evidências de assinatura. Por isso, a integração deve seguir as políticas de segurança da empresa e os princípios da LGPD.
Recomenda-se:
Utilizar somente a finalidade necessária para o processo;
Restringir o acesso aos dados por perfil;
Criptografar documentos armazenados;
Não registrar documentos ou tokens completos em logs;
Proteger links temporários;
Controlar o prazo de retenção dos arquivos;
Registrar os eventos importantes para auditoria;
Utilizar HTTPS em todas as comunicações;
Validar webhooks e evitar eventos duplicados;
Não compartilhar dados pessoais com sistemas não autorizados.
14. Tratamento de erros
A aplicação deve implementar tratamento para erros de:
Autenticação;
Autorização;
Dados obrigatórios ausentes;
Fluxo inválido ou indisponível;
Documento inválido;
Parte não encontrada;
Pedido inexistente;
Operação não permitida para o status atual;
Timeout;
Indisponibilidade temporária;
Falha no upload ou download.
Para cada erro, registre informações técnicas suficientes para investigação, sem armazenar credenciais, tokens ou dados pessoais desnecessários.
Em situações temporárias, como indisponibilidade ou timeout, utilize retentativas controladas com intervalo progressivo. Evite reenviar operações que possam criar pedidos duplicados.
15. Boas práticas de integração
Armazene os identificadores de pedidos, partes, fluxos e arquivos.
Não crie pedidos duplicados em caso de timeout sem antes verificar o resultado da operação.
Consulte o status antes de aprovar, reprovar ou cancelar uma parte.
Valide os campos obrigatórios antes do envio.
Utilize os perfis e fluxos disponibilizados pela API.
Proteja os links de acesso enviados aos usuários.
Faça o download dos arquivos assim que receber uma URL temporária.
Implemente idempotência no processamento de webhooks.
Mantenha histórico das alterações de status.
Separe documentos de teste e produção.
Evite armazenar documentos além do prazo necessário.
Não exponha dados pessoais em mensagens de erro para usuários finais.
Controle permissões de acesso aos documentos e resultados.
Teste o fluxo completo antes de disponibilizar a integração em produção.
16. Resumo funcional
Necessidade | Recurso |
Consultar fluxos disponíveis | Controller de Fluxos |
Consultar anexos padrão | Controller de Fluxos |
Enviar documentos | Controller de Arquivos |
Baixar documentos finalizados | Controller de Arquivos |
Criar uma solicitação | Controller de Pedidos |
Consultar pedidos | Controller de Pedidos |
Filtrar pedidos | Controller de Pedidos |
Consultar envolvidos | Controller de Partes |
Obter link de acesso | Controller de Partes |
Consultar status da parte | Controller de Partes |
Aprovar ou reprovar parte | Controller de Partes |
Cancelar ou reenviar parte | Controller de Partes |
Consultar perfis e campos | Controller de Perfis |
Gerar PDF de uma parte | Controller de PDF |
Receber notificações | Controller de Webhooks |
17. Documentação e suporte
Para consultar os endpoints, parâmetros, modelos de requisição e respostas, utilize a documentação técnica disponibilizada pela Assertiva.
Em caso de dúvidas ou dificuldades na integração, entre em contato com a Central da Assertiva pelos canais:
0800 878 1179;
(11) 3197-0719;