Bem-vindo ao Banking as a Service do Itaú!
Este documento é um guia para a integração com o Radar de Risco IaaS. Ao completar as configurações necessárias, sua empresa terá acesso ao universo das soluções de avaliação de risco por meio dos nossos serviços. Este material foi construído com o intuito de auxiliar o seu time de desenvolvimento durante a integração com as APIs do produto, evitando erros durante o processo.
Além do manual, no decorrer da integração, é possível contar com o suporte de nossa equipe especializada, que está disponível para esclarecer as suas dúvidas. Para isso, entre em contato com o time de integração ou de atendimento ao cliente parceiro.
Pré-requisitos
Para iniciar a sua jornada de integração com o Radar de Risco IaaS você precisa:
- Ler a documentação Primeiros passos;
- Realizar o setup seguindo as instruções da documentação de Certificado dinâmico e garantir que sejam geradas as credenciais em ambiente produtivo;
- Garantir a autenticação via STS (acesse o item Autenticação na aba informações adicionais da API Radar de Risco).
Dica: Para garantir uma compreensão mais aprofundada das informações de integração presentes nas documentações de API, especialmente no que diz respeito à geração de credenciais e certificados dinâmicos durante a etapa de autenticação, é essencial contar com um profissional técnico na equipe.
Atenção: O time IaaS participará do processo de homologação com o intuito de garantir que tudo funcione corretamente e, posteriormente, prestaremos apoio também no ambiente produtivo.
Boas Práticas para o desenvolvimento com o Radar de Risco IaaS
Antes de começar, é importante se atentar às boas práticas para o melhor desenvolvimento da sua jornada com o Radar de Risco IaaS.
Desenvolvimento Paralelo:
- Por Domínio: Se optar por paralelizar o desenvolvimento, organize as equipes por capacidade: opt-in, restritivo de fraude, farol de crédito, consulta simples, consulta completa e score de pagamentos (a depender do que foi contratado).
- Comunicação: Mantenha uma boa comunicação entre as equipes para garantir que todos os domínios estejam alinhados e que não haja duplicação de esforços.
Estimativas de Desenvolvimento:
- Tempo Estimado: O tempo de integração pode variar a depender da finalidade de uso do serviço e das capacidades contratadas. Em média, o tempo estimado para desenvolver as capacidades do Radar de Risco é de 5 dias;
- Desenvolvimento e Testes Unitários: As estimativas de tempo incluem apenas o desenvolvimento e a realização de testes unitários. Isso garante que o código esteja funcional e livre de erros básicos;
- Homologação Funcional: Após o desenvolvimento de cada capacidade, realize uma homologação funcional, garantindo que todos os cenários de teste sejam executados e retornem os resultados esperados.
Liberação da documentação da API
Após o cliente parceiro demonstrar interesse na contratação do produto, a primeira etapa é liberar a documentação de API, permitindo conhecer melhor a solução e visualizar detalhes de cada endpoint. Para isso, o cliente parceiro é cadastrado no devportal conforme as informações fornecidas pelo Officer.
Após a liberação da documentação da API para um usuário da empresa contratante no devportal, o usuário com o acesso terá o papel de administrador e poderá, de forma independente, liberar a visualização da documentação para outros usuários da empresa, conforme a necessidade.
Vale mencionar que a documentação de API é composta por três abas principais, sendo elas:
Visão geral: Onde estão disponíveis informações mais gerais sobre o produto, como para que serve a API, restrições de uso, tempo de integração, entre outras.
API Reference: Com informações técnicas da documentação, onde estão disponíveis informações detalhadas sobre cada endpoint da API, seus parâmetros e responses. Ademais, também é possível gerar tokens para realizar testes no sandbox, que também está disponível nesta parte da documentação.
Informações adicionais: Seção da documentação que conta com informações aprofundadas sobre a API, tanto as mais voltadas para compreender o funcionamento do produto e suas regras de negócio, quanto detalhes mais técnicos que são importantes para a integração.
Tempo estimado para liberação da documentação: 1 dia.
Informações necessárias:
- Razão social do cliente parceiro;
- CNPJ do cliente parceiro;
- E-mail do usuário principal (que terá acesso à documentação no devportal e poderá liberar o acesso para outras pessoas da empresa);
- Telefone do usuário principal.
1. Autenticação e integração com a API
Para realizar o processo de autenticação, que envolve a geração de credenciais de acesso e do certificado dinâmico, é essencial que o cliente parceiro utilize a API do Radar de Risco. Conforme especificado na seção Informações adicionais da documentação IaaS - API Radar de Risco, há também uma página dedicada no devportal para este assunto: Certificado dinâmico (demais produtos), que oferece instruções detalhadas. Confira a seguir, algumas informações úteis para essa etapa.
Liberação de uso da API
Após o cliente parceiro definir quais recursos da API de Radar de Risco serão contratados e se serão para uso próprio ou para revender, o Officer com o qual o cliente está em contato solicitará a liberação de uso da API para o time de integração do IaaS. Assim, o time de integração conseguirá apoiar o cliente parceiro durante a criação das credenciais de acesso e certificado.
Ambientes de homologação e produção
Para o ambiente de homologação, o cliente parceiro deve aguardar o recebimento do e-mail com as credenciais e certificados necessários junto às devidas orientações de como prosseguir. Para mais informações sobre o ambiente de homologação, acesse o item Informações sobre o ambiente de homologação na aba informações adicionais da documentação IaaS - API Radar de Risco.
Já no caso do ambiente de produção, o cliente parceiro precisa iniciar o processo enviando a chave pública para o time de integração do IaaS, conforme detalhado abaixo.
Criação de chaves pública e privada
O cliente parceiro deverá criar uma chave pública e uma chave privada, conforme as instruções dos Passos 2, 3 e 4 da documentação Certificado dinâmico (demais produtos). Posteriormente, conforme descrito no Passo 5 da documentação citada anteriormente, o cliente deve enviar a chave pública via e-mail para o time de integração do IaaS. Dessa forma, é possível que o time de integração crie as credenciais de uso da API para o cliente.
Observação: A chave privada é confidencial e deve ser armazenada de forma segura pelo cliente parceiro, pois será usada em outro momento.
Geração de credenciais e certificado dinâmico
Após o cliente parceiro enviar a chave pública, o time de integração irá gerar as credenciais de uso da API. Sendo assim, o cliente parceiro deve aguardar receber suas credenciais (client ID, token temporário, válido por 7 dias, e chave de sessão) via e-mail. Para mais detalhes e exemplo de como será o e-mail com as credenciais, acesse o Passo 5 da documentação Certificado dinâmico (demais produtos).
Observação: Caso o token temporário enviado expire, será necessário solicitar a geração de um novo token para o time de integração.
Após receber as credenciais, o cliente parceiro precisa descriptografá-las, conforme as instruções disponíveis no Passo 6 da documentação Certificado dinâmico (demais produtos). Com essa etapa concluída, o cliente pode dar início à geração do certificado dinâmico e, posteriormente, enviá-lo ao STS Itaú para concluir esse processo, como é explicado nos Passos 7 e 8 da documentação referida acima.
Observação: O certificado dinâmico é válido por 365 dias e, caso seja necessário renová-lo, é possível encontrar as instruções de como fazê-lo no item Renovar o certificado dinâmico da documentação Certificado dinâmico (demais produtos).
Autenticação STS
Para a autenticação via STS, que possibilita que o cliente parceiro gere tokens temporários (com validade de até 5 minutos) de forma autônoma para utilizar a API, é necessário que o cliente parceiro já tenha suas credenciais e certificado dinâmico devidamente gerados.
Para mais informações sobre autenticação, acesse o item Autenticação na aba informações adicionais da API Radar de Risco.
2. Opt-in
Para realizar consultas utilizando a solução de Radar de Risco do IaaS, com exceção da API de restritivo de fraude, é importante que o cliente parceiro disponibilize uma opção para o cliente PJ consultante registrar o aceite (opt-in) em relação aos termos de uso do contrato do produto, expressando seu consentimento. Portanto, o primeiro endpoint com o qual você deve se integrar é o POST/ Opt-in da API IaaS - API Radar de Risco.
Observação: É necessário enviar o consentimento do consultante apenas uma vez, sendo isso um requisito para utilizar as APIs de consulta descritas abaixo. No entanto, vale lembrar que o front-end e a experiência de como se dará esse consentimento serão definidos e construídos pelo cliente parceiro.
Testes sugeridos para a implementação da API:
Confira abaixo os testes sugeridos para se integrar com o endpoint de Opt-in do Radar de Risco IaaS:
3. Farol de Crédito (caso contratado)
Caso a funcionalidade farol de crédito tenha sido contratada, é necessário implementar o endpoint POST/ Consultar score de crédito da API IaaS - API Radar de Risco. A partir dessa integração, o cliente parceiro conseguirá consultar e, caso queira, permitir que seus clientes PJ consultem informações sobre o score de crédito (pontuação do score e risco de crédito) de Pessoas Físicas (PF) e Pessoas Jurídicas (PJ).
Observação: Vale lembrar que, para a primeira consulta, é necessário que o consultante envie primeiro o de acordo quanto aos termos de uso do produto (opt-in).
Testes sugeridos para a implementação da API:
Confira abaixo os testes sugeridos para se integrar com a API de liquidação da Conta Vinculada IaaS:
4. Consulta Simples (caso contratada)
Para utilizar a funcionalidade de consulta simples, caso tenha sido contratada, é preciso realizar a implementação do endpoint POST/ Consultar score de crédito e motivos da API IaaS - API Radar de Risco. Com isso, será possível consultar e, caso queira, permitir que seus clientes PJ consultem as informações retornadas no Farol de Crédito (score e risco de crédito de Pessoas Físicas e Jurídicas), além dos motivos para as informações de risco apresentadas.
Observação: Vale lembrar que, para a primeira consulta, é necessário que o consultante envie primeiro o de acordo quanto aos termos de uso do produto (opt-in).
5. Consulta Completa (caso contratada)
Caso contratada, para usar a funcionalidade de consulta completa é preciso implementar o endpoint POST/ Consultar análise completa de crédito da API IaaS - API Radar de Risco. Com isso, tanto o cliente parceiro quanto seu cliente PJ, caso queira oferecer essa solução, poderão consultar informações retornadas na Consulta Simples (score e risco de crédito e motivo para o risco apresentado), tendo como adicional: sugestão se é recomendável fechar negócio ou não, a probabilidade de pagamento, informações cadastrais e contato da pessoa analisada, participação em empresas e recuperações judiciais de falência, renda/faturamento presumido, gasto estimado, dependências financeiras e judiciais, pontualidade de pagamento e relacionamento com o mercado.
Observação: Vale lembrar que, para a primeira consulta, é necessário que o consultante envie primeiro o de acordo quanto aos termos de uso do produto (opt-in).
6. Score de pagamentos (caso contratado)
Caso contratado, a consulta de score de pagamentos permitirá que o cliente parceiro e os seus clientes PJ, caso tenham acesso a essa solução, acessem dados sobre boletos pagos e a receber de uma Pessoa Jurídica, levando em consideração sua proporção de pagamentos e seu histórico de pagamentos e recebimentos em determinado período. Para utilizar essa funcionalidade, é preciso realizar a implementação do endpoint POST/ Score de Pagamentos - Consultar score de Pagamentos da API IaaS - API Radar de Risco.
Observação: Vale lembrar que, para a primeira consulta, é necessário que o consultante envie primeiro o de acordo quanto aos termos de uso do produto (opt-in).