«E o trator, por acaso, não está em garantia?» — A história de uma integração com o FЦИИТ
Uma análise detalhada de uma integração bancária com o FЦИИТ, explorando desafios técnicos e operacionais. O artigo aborda desde a automação de processos até a resolução de problemas com dados e segurança, oferecendo um guia prático para analistas de sistemas.
MundiX News·01 de maio de 2026·12 min de leitura·👁 1 views
«E o trator, por acaso, não está em garantia?» — Era com essa pergunta que geralmente começava o dia de trabalho dos funcionários do departamento de garantia de bens em nosso banco. Por trás dela, havia uma rotina monótona que costumava consumir a maior parte do tempo: abrir o Registro de Notificações de Garantia de Bens Móveis, inserir os dados do cliente, esperar o resultado, analisar, tomar uma decisão — e assim por diante para cada um.
A verificação de um mutuário leva no máximo cinco minutos, mas quando cem solicitações chegam em uma hora, o modo manual se transforma em um gargalo.
Assim, em 2024, nos deparamos com a tarefa de automatizar o download de dados sobre garantias de bens móveis do registro, cujo operador é a Câmara Notarial Federal. Eu atuei como analista de sistemas do sistema responsável pela interação do banco com serviços externos — acabei no lugar mais interessante: entre o banco e o mundo exterior. Neste artigo, contarei como tornamos o banco amigo do FЦИИТ, com quais dificuldades nos deparamos e o que aconteceu com isso.
O material será útil para analistas de sistemas e de negócios que estão apenas começando a projetar integrações com sistemas externos.
Contexto de Negócios
Os principais heróis desta história são os funcionários do departamento de garantia de bens. São eles que abrem o registro todos os dias, inserem dados e esperam o resultado. São eles que realizam um trabalho colossal no modo manual.
Antes da integração com a API do FЦИИТ, o processo era baseado no controle documental. O banco recebia documentos para verificar a existência de ônus em favor do banco e a ausência de ônus de terceiros, cuja verificação era realizada no Sistema de Informação Unificado do notariado por meio do site https://www.reestr-zalogov.ru.
Nosso objetivo era automatizar o controle documental para que o sistema realizasse uma verificação automática da existência no Sistema de Informação Unificado do notariado de notificações sobre a ocorrência de garantia sobre bens móveis em favor do banco e todas as notificações sobre alterações na garantia sob o contrato em consideração, bem como a busca de informações sobre o objeto da garantia em todas as outras notificações sobre a garantia, incluindo notificações sobre alterações/exclusão de informações.
Como projetamos isso
FЦИИТ (Fundo «Centro de Inovação e Tecnologias da Informação») é uma estrutura que, em uma base comercial, fornece aos bancos acesso aos dados do Registro de Notificações de Garantia de Bens Móveis. Em resumo: com base em um contrato, eles fornecem acesso a um banco de dados com informações sobre garantias, e nós temos a oportunidade de não ir ao site manualmente, mas de obter os dados automaticamente.
O FЦИИТ fornece acesso aos dados por meio de um recurso FTP dedicado, no qual carrega diariamente um arquivo com dados sobre garantias. O arquivo contém deltas com alterações na garantia ou novas garantias do dia anterior.
Para a transferência de dados do lado do banco, um serviço de transporte foi desenvolvido. O banco se conecta ao recurso por FTP em um determinado momento e baixa 5 arquivos (Notificação de Garantia, Informações sobre Garantia, Informações sobre o Mutuário, Informações sobre o Credor, Informações sobre o Gerente de Garantia) no formato txt, combinados em um único arquivo compactado no formato ZIP. Se olharmos na seção do banco de dados, cada arquivo é uma tabela separada, todos os 5 arquivos estão interconectados e, no total, formam um contrato de garantia. Mas o acesso não é apenas «aqui está seu login e senha». Tudo o que está relacionado à transferência de dados entre o banco e o mundo exterior deve ser criptografado. Para acessar o recurso dedicado, um canal criptografado de transferência de dados é usado. A criptografia da troca de informações é implementada por meio de um provedor de criptografia por meio do protocolo IPSec usando algoritmos de criptografia GOST (o mesmo que é obrigatório para órgãos governamentais).
A conexão é organizada por meio do Coordinator — um gateway que garante a interação segura entre o banco e o recurso externo. Nosso sistema atua como iniciador, por meio do Coordinator nos conectamos ao recurso FTP do ЦИИТ e baixamos os dados. Definimos uma programação para que o download chegasse imediatamente após o arquivo aparecer no servidor. Para obter acesso ao recurso FЦИИТ, transmitimos previamente os endereços IP dos quais a conexão será iniciada. Eles foram incluídos nas listas brancas, abrindo assim o acesso para nós — sem isso, as solicitações seriam simplesmente cortadas na entrada.
Onde encontramos os obstáculos
Um pouco de informações sobre como as garantias são organizadas.
Cada garantia tem seu próprio tipo:
notificação sobre a ocorrência de garantia (tipo 1)
notificação sobre alteração de garantia (tipo 2)
notificação sobre exclusão de garantia (tipo 3)
Na verdade, existem muito mais tipos, mas só precisávamos desses.
A primeira notificação de garantia será sobre a ocorrência, e as subsequentes — sobre alteração ou exclusão. Cada alteração deve ser sobreposta à anterior para que a estrutura correta do contrato de garantia seja preservada.
Ao criar uma notificação com o tipo «sobre a ocorrência de garantia», o número de registro da notificação terá a forma: 2020-004-888888-130. Quando alterações são feitas na garantia, o tipo de notificação muda de «sobre a ocorrência de garantia» para «sobre a alteração da garantia» e o número de registro da notificação já terá a forma: 2020-004-888888-130/1 (após a barra, o número de alterações que a garantia sofreu), uma entrada adicional aparecerá no campo, onde o número da notificação pai é inserido — o número da notificação que foi atribuído ao criar a notificação: 2020-004-888888-130.
Como mencionado anteriormente, as informações sobre uma garantia estão em cinco arquivos txt diferentes, que também precisam ser interconectados para obter um contrato de garantia com um número de registro de notificação. Ao alterar um Contrato de Garantia existente pelo número da notificação pai, todas as entradas são pesquisadas, então essas entradas são classificadas por data de registro da notificação, obtemos os objetos de garantia e participantes da transação relacionados a ela. Em seguida, a nova notificação é salva e todos os participantes e objetos de garantia são «reescritos» por chaves estrangeiras para a nova notificação (um novo número de registro é formado). Se objetos de garantia ou informações sobre participantes da transação foram transferidos com a notificação, eles são comparados com as entradas existentes no banco de dados. Caso não sejam equivalentes, as novas informações substituem as antigas. Se um novo objeto de garantia for transferido, ele será adicionado ao banco de dados. Acontece algo como uma palmeira — o histórico de notificações é preservado e o mais recente possui todas as informações atuais.
Se, no download diário do FЦИИТ, uma notificação com o tipo «sobre a exclusão da garantia» chegar, definimos o status «Inativo». Depois disso, a notificação e os objetos de garantia não devem entrar na seleção.
Parece lógico. Mas, na prática, tudo acabou sendo mais complicado.
Parte 1. Não há base de teste
Sim, você não deve contar com uma base de teste. Para testes do lado do FЦИИТ, recebemos vários arquivos zip com dados de clientes. Mas havia uma nuance: esses arquivos continham um delta por dia — apenas alterações nas garantias que ocorreram em dias aleatórios. Não tínhamos a cadeia completa que a garantia passou com todas as suas alterações.
O que fizemos: preparamos nossa própria base, colocamos os dados lá, ajustamos para os cenários necessários. Formamos nossos próprios deltas, que também carregamos separadamente para verificar como a gravação no banco de dados ocorre.
Parte 2. Não um ZIP, mas milhares
«O carregamento inicial de dados é fornecido pela obtenção do primeiro arquivo arquivado, que contém todas as informações incluídas no Registro de Garantias, no momento da formação do arquivo correspondente» - entendemos esse requisito como o download seria único: um arquivo ZIP, dentro do qual 5 arquivos txt. Somente quando recebemos os arquivos «prod», percebemos como estávamos errados.
No download, havia milhares de ZIPs, a partir de 2014, cada um dos quais continha seus próprios 5 arquivos txt. Não nos deram «todo o download para o dia atual», mas um monte de deltas, que ainda precisavam ser desmontados e aplicar cada delta à garantia na ordem correta.
A lógica de atualização da garantia já estava escrita. Mas a escala era diferente. Tivemos que dividir o carregamento em partes em modo semi-manual e carregar em turnos. Desde 2014, os contratos de garantia sofreram muitas alterações, os nomes dos campos foram alterados, o formato de preenchimento, alguns campos foram divididos em vários diferentes ao longo do tempo, etc., então também tivemos que descobrir qual campo corresponde a qual no momento atual e onde colocar quais dados.
Não vou contar quanto tempo gastamos nisso, quantos erros desvendamos e quantas alterações fizemos na lógica do serviço. Direi apenas que esta foi a parte mais longa do projeto, embora parecesse que já estávamos na reta final.
Parte 3. Não há regras para preencher campos
É bom testar seus dados ideais, mas quando começamos a transferir dados para nosso banco de dados, descobriu-se que não havia regras para preencher os campos. Por exemplo, no campo «Série e número do documento de identidade», pode haver não apenas a série e o número, mas também vários símbolos, letras, espaços extras, hífens. Em um lugar, o passaporte é escrito como «45 12 345678», em outro — «série: 4512 número: 345678», em um terceiro — «4512-345678».
A dificuldade residia no fato de que planejamos pesquisar clientes no banco de dados com base em dados de passaporte ou TIN/OGRN. Porque pode haver vários contratos de garantia para um cliente, e você precisava ver exatamente todos os seus bens garantidos, e não apenas informações sobre um contrato específico.
Saímos dessa situação da seguinte forma: realizamos uma análise de um grande número de registros para identificar as opções para preencher os campos, fizemos uma limpeza adicional de símbolos e letras desnecessários, trouxemos tudo para um formato unificado. Agora, antes de procurar um cliente, normalizamos seus dados de passaporte: removemos espaços, hífens, sinais extras, trazemos para um formato unificado.
Parte 4. Como entender o que realmente mudou
Tentarei explicar com um exemplo. O mutuário tinha uma garantia, na qual estavam listados um pato, um urso e um veado. Hoje, o mutuário decidiu garantir um trator (adicionado) e remover o urso da garantia (excluído). Logicamente, amanhã no delta devemos receber um registro de que, para esta garantia, agora há: pato, veado e trator, mas não. No registro haverá: trator e urso. Vou explicar: o delta será do tipo «sobre a alteração da garantia, mas não indica qual objeto de garantia foi removido, qual foi alterado e qual foi adicionado, nisso consistia a dificuldade.
Ou seja, no delta, todos os objetos de garantia que participaram da alteração chegam sem indicar o que foi feito com eles: adicionado ou removido. Sem ter uma base completa que possa ser analisada, foi difícil descobrir como atualizar corretamente a garantia para que apenas os objetos atuais permanecessem no banco de dados.
Verificamos cada objeto de garantia (OG) que chegou na notificação de alteração com os registros que já temos em nosso banco de dados.
Se o OG não estiver no banco de dados — então este é um novo objeto, adicionamos. Se o OG estiver no banco de dados — então ele foi removido da garantia, ou uma alteração foi feita nele (por exemplo, uma alteração em seu status ou alteração em sua descrição pode ter sido feita). Se nenhuma alteração for detectada no banco de dados, a garantia é removida — removemos, se houver alterações — atualizamos os campos correspondentes e o OG não é removido.
Soa lógico, mas configurar essa lógica levou várias semanas. Analisamos caso a caso, encontramos erros, refinamos as regras. E só depois de fazer isso em milhares de registros reais, pudemos dizer: «tudo, agora funciona».
Resultado
O que obtivemos:
O tempo de processamento de uma garantia foi reduzido de vários minutos (entrada manual, espera, análise) para segundos (solicitação automática, recebimento da resposta). Em cargas de pico, isso é especialmente perceptível.
Os dados do FЦИИТ chegam todos os dias, o sistema os pega, processa e atualiza o banco de dados. Ninguém se esquece de clicar no botão, não sai de férias, não se distrai com outras tarefas.
Paramos de perder tempo com verificações manuais, excluímos o fator humano (erros de entrada, garantias perdidas), reduzimos o risco de perder ônus.
Com o aumento do fluxo de solicitações, não precisamos contratar dezenas de novos funcionários. O sistema lidará sozinho, apenas processando mais solicitações.
Lista de verificação para um analista
Se você estiver projetando uma integração com um sistema externo (por exemplo, com o FЦИИТ), talvez minha lista de verificação pessoal, formada com base em nossas dificuldades e erros, seja útil.
Projetando:
Especifique o formato de download. Um ZIP ou milhares? Quantos arquivos dentro? Qual é a estrutura? Com que frequência é atualizado?
Descubra sobre o contorno de teste. Existe? Se não — como testar? É possível obter arquivos de teste para depuração?
Pergunte sobre os regulamentos. Existem prazos rígidos para download? O que acontecerá se não tivermos tempo para obter os dados?
Avalie o volume. Quantos registros no primeiro download? Quantos haverá no delta diário? Isso é importante para avaliar o desempenho.
Dados:
Especifique as regras para preencher os campos. Se não houver — coloque a limpeza e a normalização de dados. Dados de passaporte, TIN, OGRN — tudo isso pode vir em formatos diferentes. Contamos com a lógica, mas o que parecia óbvio para nós não era óbvio para todos os outros, então tivemos que refazer.
Entenda a lógica das mudanças. Como a garantia é identificada? Como saber que esta é uma nova notificação, e não uma alteração da antiga? Como rastrear a cadeia de mudanças?
Coloque flexibilidade no parser. Se o formato mudar, o sistema não deve falhar. Registre o erro, envie uma notificação, mas não pare.
Rede e acessos:
Concorde com os endereços IP com antecedência. Transmita-os ao sistema externo antes de iniciar os testes. Verifique se todos os endereços foram inseridos.
Verifique os firewalls. Quais portas estão abertas? Modo FTP ativo ou passivo? Isso pode ser diferente nos contornos de teste e produção.
Especifique sobre a criptografia. Qual protocolo (IPSec, TLS)? Quais algoritmos? Você precisa de um provedor de criptografia?
Testando:
Crie seu próprio banco de dados de teste. Se o ambiente de teste externo for limitado, implante o seu. Preencha-o com diferentes cenários: garantia limpa, alterações, exclusões, dados errados.
Teste com dados reais. Não se limite a arquivos ideais do fornecedor. Pegue registros reais e veja como o sistema os processará.
Teste cargas de pico. O que acontecerá se um download grande chegar? O sistema terá tempo para processar tudo antes do próximo download?
Suporte:
Coloque o monitoramento. Prazos de certificados, disponibilidade de FTP, erros de análise — tudo isso deve ser rastreado automaticamente.
Documente tudo. Esquemas, configurações, lógica de atualização — para que em seis meses você mesmo possa se lembrar do porquê fez exatamente isso.
Conclusão
A integração com o FЦИИТ foi uma experiência interessante para mim: tanto em termos de dados quanto em termos de lógica e infraestrutura.
Ao enfrentar esses projetos, você percebe que a integração não é apenas API e JSON. É também rede, e certificados, e criptografia, e a capacidade de negociar com o serviço de segurança, e a capacidade de entender milhares de arquivos, quando a base de teste é apenas sua cabeça e alguns arquivos zip.
Se você está projetando sua primeira integração com agências governamentais agora — não tenha medo. Haverá obstáculos, mas toda vez que você pisar neles, você adquire uma experiência incomparável.
🛡️⚡
Pare de pesquisar. Comece a hackear.
O MundiX é seu copiloto de pentest com IA: comandos exatos, análise de outputs e próximo passo na kill chain — em segundos.
Sem cartão para começar · Planos a partir de R$49/mês
«E o trator, por acaso, não está em garantia?» — Era com essa pergunta que geralmente começava o dia de trabalho dos funcionários do departamento de garantia de bens em nosso banco. Por trás dela, havia uma rotina monótona que costumava consumir a maior parte do tempo: abrir o Registro de Notificações de Garantia de Bens Móveis, inserir os dados do cliente, esperar o resultado, analisar, tomar uma decisão — e assim por diante para cada um.
A verificação de um mutuário leva no máximo cinco minutos, mas quando cem solicitações chegam em uma hora, o modo manual se transforma em um gargalo.
Assim, em 2024, nos deparamos com a tarefa de automatizar o download de dados sobre garantias de bens móveis do registro, cujo operador é a Câmara Notarial Federal. Eu atuei como analista de sistemas do sistema responsável pela interação do banco com serviços externos — acabei no lugar mais interessante: entre o banco e o mundo exterior. Neste artigo, contarei como tornamos o banco amigo do FЦИИТ, com quais dificuldades nos deparamos e o que aconteceu com isso.
O material será útil para analistas de sistemas e de negócios que estão apenas começando a projetar integrações com sistemas externos.
Contexto de Negócios
Os principais heróis desta história são os funcionários do departamento de garantia de bens. São eles que abrem o registro todos os dias, inserem dados e esperam o resultado. São eles que realizam um trabalho colossal no modo manual.
Antes da integração com a API do FЦИИТ, o processo era baseado no controle documental. O banco recebia documentos para verificar a existência de ônus em favor do banco e a ausência de ônus de terceiros, cuja verificação era realizada no Sistema de Informação Unificado do notariado por meio do site https://www.reestr-zalogov.ru.
Nosso objetivo era automatizar o controle documental para que o sistema realizasse uma verificação automática da existência no Sistema de Informação Unificado do notariado de notificações sobre a ocorrência de garantia sobre bens móveis em favor do banco e todas as notificações sobre alterações na garantia sob o contrato em consideração, bem como a busca de informações sobre o objeto da garantia em todas as outras notificações sobre a garantia, incluindo notificações sobre alterações/exclusão de informações.
Como projetamos isso
FЦИИТ (Fundo «Centro de Inovação e Tecnologias da Informação») é uma estrutura que, em uma base comercial, fornece aos bancos acesso aos dados do Registro de Notificações de Garantia de Bens Móveis. Em resumo: com base em um contrato, eles fornecem acesso a um banco de dados com informações sobre garantias, e nós temos a oportunidade de não ir ao site manualmente, mas de obter os dados automaticamente.
O FЦИИТ fornece acesso aos dados por meio de um recurso FTP dedicado, no qual carrega diariamente um arquivo com dados sobre garantias. O arquivo contém deltas com alterações na garantia ou novas garantias do dia anterior.
Para a transferência de dados do lado do banco, um serviço de transporte foi desenvolvido. O banco se conecta ao recurso por FTP em um determinado momento e baixa 5 arquivos (Notificação de Garantia, Informações sobre Garantia, Informações sobre o Mutuário, Informações sobre o Credor, Informações sobre o Gerente de Garantia) no formato txt, combinados em um único arquivo compactado no formato ZIP. Se olharmos na seção do banco de dados, cada arquivo é uma tabela separada, todos os 5 arquivos estão interconectados e, no total, formam um contrato de garantia. Mas o acesso não é apenas «aqui está seu login e senha». Tudo o que está relacionado à transferência de dados entre o banco e o mundo exterior deve ser criptografado. Para acessar o recurso dedicado, um canal criptografado de transferência de dados é usado. A criptografia da troca de informações é implementada por meio de um provedor de criptografia por meio do protocolo IPSec usando algoritmos de criptografia GOST (o mesmo que é obrigatório para órgãos governamentais).
A conexão é organizada por meio do Coordinator — um gateway que garante a interação segura entre o banco e o recurso externo. Nosso sistema atua como iniciador, por meio do Coordinator nos conectamos ao recurso FTP do ЦИИТ e baixamos os dados. Definimos uma programação para que o download chegasse imediatamente após o arquivo aparecer no servidor. Para obter acesso ao recurso FЦИИТ, transmitimos previamente os endereços IP dos quais a conexão será iniciada. Eles foram incluídos nas listas brancas, abrindo assim o acesso para nós — sem isso, as solicitações seriam simplesmente cortadas na entrada.
Onde encontramos os obstáculos
Um pouco de informações sobre como as garantias são organizadas.
Cada garantia tem seu próprio tipo:
notificação sobre a ocorrência de garantia (tipo 1)
notificação sobre alteração de garantia (tipo 2)
notificação sobre exclusão de garantia (tipo 3)
Na verdade, existem muito mais tipos, mas só precisávamos desses.
A primeira notificação de garantia será sobre a ocorrência, e as subsequentes — sobre alteração ou exclusão. Cada alteração deve ser sobreposta à anterior para que a estrutura correta do contrato de garantia seja preservada.
Ao criar uma notificação com o tipo «sobre a ocorrência de garantia», o número de registro da notificação terá a forma: 2020-004-888888-130. Quando alterações são feitas na garantia, o tipo de notificação muda de «sobre a ocorrência de garantia» para «sobre a alteração da garantia» e o número de registro da notificação já terá a forma: 2020-004-888888-130/1 (após a barra, o número de alterações que a garantia sofreu), uma entrada adicional aparecerá no campo, onde o número da notificação pai é inserido — o número da notificação que foi atribuído ao criar a notificação: 2020-004-888888-130.
Como mencionado anteriormente, as informações sobre uma garantia estão em cinco arquivos txt diferentes, que também precisam ser interconectados para obter um contrato de garantia com um número de registro de notificação. Ao alterar um Contrato de Garantia existente pelo número da notificação pai, todas as entradas são pesquisadas, então essas entradas são classificadas por data de registro da notificação, obtemos os objetos de garantia e participantes da transação relacionados a ela. Em seguida, a nova notificação é salva e todos os participantes e objetos de garantia são «reescritos» por chaves estrangeiras para a nova notificação (um novo número de registro é formado). Se objetos de garantia ou informações sobre participantes da transação foram transferidos com a notificação, eles são comparados com as entradas existentes no banco de dados. Caso não sejam equivalentes, as novas informações substituem as antigas. Se um novo objeto de garantia for transferido, ele será adicionado ao banco de dados. Acontece algo como uma palmeira — o histórico de notificações é preservado e o mais recente possui todas as informações atuais.
Se, no download diário do FЦИИТ, uma notificação com o tipo «sobre a exclusão da garantia» chegar, definimos o status «Inativo». Depois disso, a notificação e os objetos de garantia não devem entrar na seleção.
Parece lógico. Mas, na prática, tudo acabou sendo mais complicado.
Parte 1. Não há base de teste
Sim, você não deve contar com uma base de teste. Para testes do lado do FЦИИТ, recebemos vários arquivos zip com dados de clientes. Mas havia uma nuance: esses arquivos continham um delta por dia — apenas alterações nas garantias que ocorreram em dias aleatórios. Não tínhamos a cadeia completa que a garantia passou com todas as suas alterações.
O que fizemos: preparamos nossa própria base, colocamos os dados lá, ajustamos para os cenários necessários. Formamos nossos próprios deltas, que também carregamos separadamente para verificar como a gravação no banco de dados ocorre.
Parte 2. Não um ZIP, mas milhares
«O carregamento inicial de dados é fornecido pela obtenção do primeiro arquivo arquivado, que contém todas as informações incluídas no Registro de Garantias, no momento da formação do arquivo correspondente» - entendemos esse requisito como o download seria único: um arquivo ZIP, dentro do qual 5 arquivos txt. Somente quando recebemos os arquivos «prod», percebemos como estávamos errados.
No download, havia milhares de ZIPs, a partir de 2014, cada um dos quais continha seus próprios 5 arquivos txt. Não nos deram «todo o download para o dia atual», mas um monte de deltas, que ainda precisavam ser desmontados e aplicar cada delta à garantia na ordem correta.
A lógica de atualização da garantia já estava escrita. Mas a escala era diferente. Tivemos que dividir o carregamento em partes em modo semi-manual e carregar em turnos. Desde 2014, os contratos de garantia sofreram muitas alterações, os nomes dos campos foram alterados, o formato de preenchimento, alguns campos foram divididos em vários diferentes ao longo do tempo, etc., então também tivemos que descobrir qual campo corresponde a qual no momento atual e onde colocar quais dados.
Não vou contar quanto tempo gastamos nisso, quantos erros desvendamos e quantas alterações fizemos na lógica do serviço. Direi apenas que esta foi a parte mais longa do projeto, embora parecesse que já estávamos na reta final.
Parte 3. Não há regras para preencher campos
É bom testar seus dados ideais, mas quando começamos a transferir dados para nosso banco de dados, descobriu-se que não havia regras para preencher os campos. Por exemplo, no campo «Série e número do documento de identidade», pode haver não apenas a série e o número, mas também vários símbolos, letras, espaços extras, hífens. Em um lugar, o passaporte é escrito como «45 12 345678», em outro — «série: 4512 número: 345678», em um terceiro — «4512-345678».
A dificuldade residia no fato de que planejamos pesquisar clientes no banco de dados com base em dados de passaporte ou TIN/OGRN. Porque pode haver vários contratos de garantia para um cliente, e você precisava ver exatamente todos os seus bens garantidos, e não apenas informações sobre um contrato específico.
Saímos dessa situação da seguinte forma: realizamos uma análise de um grande número de registros para identificar as opções para preencher os campos, fizemos uma limpeza adicional de símbolos e letras desnecessários, trouxemos tudo para um formato unificado. Agora, antes de procurar um cliente, normalizamos seus dados de passaporte: removemos espaços, hífens, sinais extras, trazemos para um formato unificado.
Parte 4. Como entender o que realmente mudou
Tentarei explicar com um exemplo. O mutuário tinha uma garantia, na qual estavam listados um pato, um urso e um veado. Hoje, o mutuário decidiu garantir um trator (adicionado) e remover o urso da garantia (excluído). Logicamente, amanhã no delta devemos receber um registro de que, para esta garantia, agora há: pato, veado e trator, mas não. No registro haverá: trator e urso. Vou explicar: o delta será do tipo «sobre a alteração da garantia, mas não indica qual objeto de garantia foi removido, qual foi alterado e qual foi adicionado, nisso consistia a dificuldade.
Ou seja, no delta, todos os objetos de garantia que participaram da alteração chegam sem indicar o que foi feito com eles: adicionado ou removido. Sem ter uma base completa que possa ser analisada, foi difícil descobrir como atualizar corretamente a garantia para que apenas os objetos atuais permanecessem no banco de dados.
Verificamos cada objeto de garantia (OG) que chegou na notificação de alteração com os registros que já temos em nosso banco de dados.
Se o OG não estiver no banco de dados — então este é um novo objeto, adicionamos. Se o OG estiver no banco de dados — então ele foi removido da garantia, ou uma alteração foi feita nele (por exemplo, uma alteração em seu status ou alteração em sua descrição pode ter sido feita). Se nenhuma alteração for detectada no banco de dados, a garantia é removida — removemos, se houver alterações — atualizamos os campos correspondentes e o OG não é removido.
Soa lógico, mas configurar essa lógica levou várias semanas. Analisamos caso a caso, encontramos erros, refinamos as regras. E só depois de fazer isso em milhares de registros reais, pudemos dizer: «tudo, agora funciona».
Resultado
O que obtivemos:
O tempo de processamento de uma garantia foi reduzido de vários minutos (entrada manual, espera, análise) para segundos (solicitação automática, recebimento da resposta). Em cargas de pico, isso é especialmente perceptível.
Os dados do FЦИИТ chegam todos os dias, o sistema os pega, processa e atualiza o banco de dados. Ninguém se esquece de clicar no botão, não sai de férias, não se distrai com outras tarefas.
Paramos de perder tempo com verificações manuais, excluímos o fator humano (erros de entrada, garantias perdidas), reduzimos o risco de perder ônus.
Com o aumento do fluxo de solicitações, não precisamos contratar dezenas de novos funcionários. O sistema lidará sozinho, apenas processando mais solicitações.
Lista de verificação para um analista
Se você estiver projetando uma integração com um sistema externo (por exemplo, com o FЦИИТ), talvez minha lista de verificação pessoal, formada com base em nossas dificuldades e erros, seja útil.
Projetando:
Especifique o formato de download. Um ZIP ou milhares? Quantos arquivos dentro? Qual é a estrutura? Com que frequência é atualizado?
Descubra sobre o contorno de teste. Existe? Se não — como testar? É possível obter arquivos de teste para depuração?
Pergunte sobre os regulamentos. Existem prazos rígidos para download? O que acontecerá se não tivermos tempo para obter os dados?
Avalie o volume. Quantos registros no primeiro download? Quantos haverá no delta diário? Isso é importante para avaliar o desempenho.
Dados:
Especifique as regras para preencher os campos. Se não houver — coloque a limpeza e a normalização de dados. Dados de passaporte, TIN, OGRN — tudo isso pode vir em formatos diferentes. Contamos com a lógica, mas o que parecia óbvio para nós não era óbvio para todos os outros, então tivemos que refazer.
Entenda a lógica das mudanças. Como a garantia é identificada? Como saber que esta é uma nova notificação, e não uma alteração da antiga? Como rastrear a cadeia de mudanças?
Coloque flexibilidade no parser. Se o formato mudar, o sistema não deve falhar. Registre o erro, envie uma notificação, mas não pare.
Rede e acessos:
Concorde com os endereços IP com antecedência. Transmita-os ao sistema externo antes de iniciar os testes. Verifique se todos os endereços foram inseridos.
Verifique os firewalls. Quais portas estão abertas? Modo FTP ativo ou passivo? Isso pode ser diferente nos contornos de teste e produção.
Especifique sobre a criptografia. Qual protocolo (IPSec, TLS)? Quais algoritmos? Você precisa de um provedor de criptografia?
Testando:
Crie seu próprio banco de dados de teste. Se o ambiente de teste externo for limitado, implante o seu. Preencha-o com diferentes cenários: garantia limpa, alterações, exclusões, dados errados.
Teste com dados reais. Não se limite a arquivos ideais do fornecedor. Pegue registros reais e veja como o sistema os processará.
Teste cargas de pico. O que acontecerá se um download grande chegar? O sistema terá tempo para processar tudo antes do próximo download?
Suporte:
Coloque o monitoramento. Prazos de certificados, disponibilidade de FTP, erros de análise — tudo isso deve ser rastreado automaticamente.
Documente tudo. Esquemas, configurações, lógica de atualização — para que em seis meses você mesmo possa se lembrar do porquê fez exatamente isso.
Conclusão
A integração com o FЦИИТ foi uma experiência interessante para mim: tanto em termos de dados quanto em termos de lógica e infraestrutura.
Ao enfrentar esses projetos, você percebe que a integração não é apenas API e JSON. É também rede, e certificados, e criptografia, e a capacidade de negociar com o serviço de segurança, e a capacidade de entender milhares de arquivos, quando a base de teste é apenas sua cabeça e alguns arquivos zip.
Se você está projetando sua primeira integração com agências governamentais agora — não tenha medo. Haverá obstáculos, mas toda vez que você pisar neles, você adquire uma experiência incomparável.
📤 Compartilhar & Baixar
🧰 Ferramentas recomendadas
Divulgação: alguns links são patrocinados. Podemos receber comissão se você comprar — sem custo extra para você. Só indicamos o que faz sentido para a comunidade.
