Portal do Desenvolvedor

Dossiê — geração assíncrona do Dossiê de pessoa física via API

Solicite o Dossiê de um CPF, acompanhe o andamento por webhook e baixe o PDF gerado, sem precisar acessar o painel.

A URL base é https://api.assertivasolucoes.com.br e os endpoints do produto usam o caminho /dossie. Todas as chamadas exigem um token OAuth2 no cabeçalho Authorization: Bearer.

Como funciona

Fluxo de integração

A geração do Dossiê é assíncrona. A solicitação retorna na hora um protocol e o PDF é baixado depois, quando estiver pronto.

Solicitar

POST /dossie/pf responde com um protocol e o status 11 - Em Fila.

Aguardar

Informe webhookUrl para ser avisado quando o dossiê terminar, com sucesso ou com falha.

Baixar o PDF

GET /dossie/download/{protocolo} retorna o PDF do dossiê.

O que dá para fazer

Endpoints

Funcionalidade	Método	Endpoint
Gerar token de acesso	`POST`	`/oauth2/v3/token`
Solicitar Dossiê PF	`POST`	`/dossie/pf`
Baixar o PDF do Dossiê	`GET`	`/dossie/download/{protocolo}`

Tipos de consulta

O parâmetro tipoConsulta define a versão do Dossiê gerada. Seu usuário precisa ter permissão para a versão solicitada, caso contrário a API retorna 403.

tipoConsulta	Descrição
`PRO`	Dossiê completo (valor padrão quando o parâmetro não é informado).
`LITE`	Dossiê simplificado.

Módulos adicionais

Todo dossiê inclui automaticamente os módulos básicos do tipoConsulta. O parâmetro idsModulosAdicionais serve apenas para pedir consultas adicionais, que são opcionais.

ID	Módulo adicional	tipoConsulta
`2`	Bens Veiculares	`PRO`

Para incluir a consulta de veículos no Dossiê PRO, envie "idsModulosAdicionais": [2].
Sem o parâmetro (ou com lista vazia), o dossiê é gerado só com os módulos básicos.
Não informe o ID dos módulos básicos: eles são sempre incluídos.
O Dossiê LITE não possui módulos adicionais.

Acompanhamento

Status da consulta

O idStatus retornado na solicitação indica a situação da consulta no momento em que ela foi criada. Quando a consulta é aceita, o retorno é 11 - Em Fila.

A API pode responder 200 e, ainda assim, informar no idStatus que a consulta não pôde ser realizada (por exemplo, sem saldo ou documento bloqueado). Sempre verifique o idStatus antes de aguardar o webhook ou tentar baixar o PDF.

idStatus	Descrição
`1`	Informações não encontradas
`2`	Sem saldo
`3`	Documento não encontrado
`4`	Bloqueado por LGPD
`5`	Erro interno do sistema
`6`	Consultando
`7`	Impossível devido à situação do documento
`8`	Documento inválido
`9`	Finalizado com sucesso
`10`	Impossível devido à idade do titular
`11`	Em Fila
`12`	Consulta duplicada

Notificações por webhook

Com webhookUrl informada, a Assertiva envia um POST para a sua URL conforme o processamento avança. O campo status da notificação pode ser:

status	Significado	Final?
`CONSULTING`	PDF parcial gerado, mas ainda há módulos em consulta (ex.: veículos). Nova notificação virá ao concluir.	Não
`SUCCESS`	Dossiê concluído, PDF final disponível com todos os módulos.	Sim
`PARTIAL_SUCCESS`	Dossiê concluído, mas módulos adicionais não puderam ser consultados (ver `modulosAdicionaisComErro`).	Sim
`FAILURE`	Não foi possível gerar o dossiê. O motivo vem em `errorMessage`.	Sim

Dossiê sem módulos adicionais recebe uma única notificação. No Dossiê PRO com módulos adicionais, o mesmo protocolo recebe CONSULTING e depois a notificação final. Trate o dossiê como concluído somente em SUCCESS ou PARTIAL_SUCCESS.

Conformidade

Finalidade de uso (LGPD)

A solicitação exige o parâmetro idFinalidade. Para o Dossiê, o valor aceito é:

`idFinalidade`	Finalidade	Descrição
`2`	Ciclo de crédito	Uso no ciclo de proteção ao crédito, incluindo cobrança, verificação da situação financeira e correta identificação.

O valor informado deve corresponder à finalidade real do tratamento dos dados.

Respostas

Códigos HTTP

Código	Significado	Tratamento recomendado
`200`	Solicitação recebida ou PDF retornado.	Na solicitação, verifique o `idStatus` antes de aguardar o resultado.
`400`	Requisição inválida (CPF, finalidade ou `webhookUrl`).	Corrigir o campo indicado na `message`.
`401`	Falha na autenticação.	Verificar o token e gerar um novo se necessário.
`403`	Usuário sem permissão para a operação ou para o tipo de consulta.	Confirmar as permissões da aplicação e do produto.
`404`	No download: protocolo inválido, dossiê não encontrado, ainda não concluído ou expurgado.	Conferir o protocolo e baixar somente após a notificação final.
`500`	Erro de servidor.	Repetir com retentativas controladas; acionar o suporte se persistir.

Segurança

Proteção de dados

O Dossiê contém dados pessoais. Proteja CPF, o PDF e os tokens, use HTTPS, não registre dados completos em logs e não coloque credenciais ou dados sensíveis na webhookUrl. A notificação não traz o arquivo: confirme o protocolo consultando o download com o seu token antes de processar o resultado.

Próximos passos

Continue a integração

Autenticação

Gere o token de acesso — pré-requisito de todas as chamadas.

Primeira requisição

Solicite seu primeiro Dossiê, passo a passo.

Casos de uso

Use webhook, módulos adicionais e trate os status em fluxos reais.