Casos de uso

Como combinar os controllers do Autentica em fluxos práticos. Os cenários abaixo usam apenas comportamentos descritos na documentação da API.

1. Onboarding com validação de identidade e assinatura

Objetivo: integrar um novo cliente coletando documentos, validando a identidade por biometria e coletando a assinatura de um contrato.

Escolha o fluxo

No controller de Fluxos, selecione um fluxo que combine coleta de documentos, validação de identidade e assinatura. Verifique se está publicado e liberado.

Monte o pedido

Crie o pedido com a parte (o cliente), o perfil adequado e os dados cadastrais exigidos. Anexe documentos via controller de Arquivos, se o fluxo pedir.

Envie o link e acompanhe

Envie o link de acesso à parte e acompanhe o status até finalizada, de preferência por webhook.

Obtenha as evidências

Baixe os documentos assinados e gere o PDF da parte com o carimbo do tempo pelo controller de PDF.

2. Assinatura de contrato com múltiplas partes

Objetivo: coletar a assinatura de mais de uma pessoa ou empresa no mesmo pedido.

Um pedido pode conter uma ou mais partes. Informe cada parte com seu documento (CPF/CNPJ), contato e perfil.
Cada parte recebe seu próprio link de acesso ao fluxo, obtido pelo controller de Partes.
Use anexos globais quando um documento precisar ser compartilhado com todas as partes; use anexos específicos quando for exclusivo de uma parte.

Acompanhe o status de cada parte individualmente — elas podem estar em etapas diferentes do mesmo pedido.

3. Aprovar ou reprovar uma parte

Objetivo: concluir a análise de uma parte de acordo com as regras do processo.

Consulte o status

Confirme que a parte está em uma situação que permite a ação e que os dados e documentos necessários já foram enviados.

Decida

Aprove ou reprove a parte pelo controller de Partes. Verifique se a justificativa é obrigatória e se a operação pode ser revertida.

Sempre consulte o status antes de aprovar, reprovar ou cancelar. Operações não permitidas para o status atual retornam erro.

4. Reenvio de uma parte

Objetivo: reenviar o acesso quando a parte não recebeu o link ou precisa refazer uma etapa.

Antes de reenviar, 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.

5. Notificação por webhook

Objetivo: reagir automaticamente aos eventos do processo, sem ficar consultando a API repetidamente.

Configure a URL

Registre uma URL de webhook pelo controller de Webhooks. Ela deve usar HTTPS e estar disponível publicamente para o serviço autorizado.

Receba o evento

Ao ocorrer um evento, o Autentica notifica sua URL. Valide a origem, responda rapidamente e armazene o identificador do evento ou pedido.

Consulte os detalhes

O webhook é apenas notificação: para os dados completos e atualizados, consulte o pedido ou a parte na API.

Implemente idempotência: evite processar o mesmo evento duas vezes e use retentativas para falhas temporárias.

6. Resultado e evidências de uma operação finalizada

Objetivo: reunir os artefatos finais após a conclusão do pedido.

Solicite links temporários de download pelo controller de Arquivos para os documentos enviados, coletados, assinados e de auditoria.
Gere o PDF da parte finalizada pelo controller de PDF — ele reúne dados cadastrais, informações coletadas, evidências, informações da assinatura, carimbo do tempo e dados de auditoria.
Armazene o PDF e as evidências em local seguro, com acesso restrito e prazo de retenção controlado.

Recomendações

Boas práticas

Guarde os identificadores

Armazene os IDs de pedidos, partes, fluxos e arquivos para as operações e consultas seguintes.

Evite duplicidade

Em caso de timeout, verifique o resultado antes de recriar o pedido. Implemente idempotência nos webhooks.

Consulte antes de agir

Verifique o status da parte antes de aprovar, reprovar, cancelar ou reenviar.

Proteja os dados

Proteja links de acesso, use HTTPS, não exponha dados pessoais em erros e controle o acesso aos documentos e resultados.