Support Hub/Learn & Insights/O SDK do seu fornecedor só funciona no Windows, ainda…
Translated from the English article and reviewed by a person. Read the English original
Article

O SDK do seu fornecedor só funciona no Windows, ainda nesta década de IA?

O SDK do seu fornecedor só funciona no Windows, ainda nesta década de IA?

Se você está lendo isto, sua equipe provavelmente já comentou sobre o problema. Seu hardware biométrico funciona bem. O dispositivo faz exatamente o que deveria fazer. Mas o SDK que o fabricante distribui para se comunicar com ele é uma DLL compilada para Windows, exige um runtime específico do Visual C++, não roda em um contêiner Docker, e seus desenvolvedores usam Mac ou Linux. O dispositivo não é o problema. O problema é o SDK. Este artigo explica exatamente por que isso acontece, por que todas as soluções alternativas que sua equipe tentou acabam falhando e como é a alternativa arquitetural.

 

As reclamações são consistentes em todas as equipes de engenharia

Os detalhes variam, mas o padrão é sempre o mesmo. Uma organização integra hardware biométrico, descobre as restrições do SDK tarde no processo e gasta um tempo considerável de engenharia contornando um problema que não deveria existir. Veja como essas reclamações soam na prática.

O que as equipes de engenharia dizem, sempre
“O SDK só é fornecido como uma DLL do Windows. Todo o nosso backend roda em Linux. Tivemos que criar uma VM Windows dedicada só para executar a integração biométrica.”
“Não conseguimos conteinerizar isso. Docker está descartado. Kubernetes está descartado. Cada implantação é um processo manual em uma máquina que não pode ser substituída sem reinstalar o SDK e obter uma nova licença.”
“Seus desenvolvedores usam Mac ou Linux. Ninguém consegue executar a integração localmente. Os testes exigem acesso remoto à única máquina Windows do escritório que tem o SDK instalado.”
“O SDK exige o Visual C++ Redistributable 2010. O novo desenvolvedor passou três dias preparando o ambiente antes de escrever uma única linha de código de integração.”
“Atualizamos o servidor para o Windows Server 2022 e o SDK parou de funcionar. O fornecedor levou duas semanas para lançar uma versão atualizada e não tivemos dados de presença nesse período.”
“Nosso pipeline de CI/CD não consegue testar a integração biométrica de forma alguma. Todo teste é manual. Cada lançamento da integração exige que alguém se sente fisicamente na máquina Windows e a execute.”

Por que os SDKs biométricos são exclusivos do Windows: o motivo real

É tentador supor que a comunicação com hardware biométrico é tão complexa que exige APIs de sistema específicas do Windows. Não é o caso. O motivo real pelo qual os SDKs biométricos são exclusivos do Windows é bem mais simples e bem mais frustrante: esse é o ambiente para o qual o SDK foi originalmente escrito, e ninguém investiu desde então em mudá-lo.

A maioria dos SDKs de dispositivos biométricos foi escrita em C ou C++ no início dos anos 2000, tendo o Windows como alvo, pois era o sistema operacional dominante para desktops corporativos da época. O resultado da compilação era uma DLL, uma Dynamic Link Library, que é um formato binário específico do Windows. A lógica de comunicação, as funções que abrem uma conexão TCP com o dispositivo, decodificam o formato de pacotes binários e retornam dados estruturados, era compilada nessa DLL e distribuída aos clientes.

Na época, essa era uma decisão razoável. Software corporativo rodava em Windows. Servidores rodavam Windows. Desenvolvedores usavam Windows. O formato DLL era o mecanismo padrão de distribuição de código compilado reutilizável nesse ecossistema. Nada nessa escolha estava errado dentro do seu contexto.

O problema é que o contexto mudou completamente e o SDK não. O Linux se tornou o sistema operacional dominante para servidores. O Mac se tornou a estação de trabalho dominante para desenvolvedores. Contêineres Docker se tornaram a unidade padrão de implantação. A infraestrutura nativa de nuvem substituiu os servidores Windows locais. Mas o SDK biométrico continuou sendo uma DLL do Windows, porque reescrevê-lo para distribuição multiplataforma exige um investimento de engenharia que o fabricante do hardware tem pouco incentivo comercial para fazer.

“O SDK não foi projetado para ser hostil ao Linux ou ao Mac. Ele foi projetado para um mundo em que Linux e Mac não eram onde o software corporativo rodava. Esse mundo não existe mais. O SDK ficou para trás.”

O que o SDK exclusivo do Windows bloqueia em uma stack moderna

As implicações de um SDK exclusivo do Windows se espalham por todas as camadas de uma configuração moderna de desenvolvimento e implantação. Cada bloqueio abaixo representa uma restrição real que as equipes de engenharia enfrentam quando tentam integrar hardware biométrico a uma stack de software atual.

Docker e conteinerização
Contêineres Docker rodam em Linux. Uma DLL do Windows não pode ser carregada dentro de um contêiner Linux. Qualquer serviço que precise chamar o SDK deve rodar em uma máquina Windows dedicada ou em um contêiner Windows, o que é mais pesado, menos portátil e mais caro de executar do que um contêiner Linux padrão.
Servidores de nuvem Linux
AWS, Google Cloud e Azure oferecem máquinas virtuais Linux como opção padrão e mais barata de servidor. Executar uma VM Windows especificamente para hospedar a integração com o SDK biométrico custa mais e adiciona uma sobrecarga operacional que não tem nada a ver com a função biométrica em si.
Ambientes de desenvolvimento em Mac
Os desenvolvedores não conseguem carregar, executar nem testar o SDK em suas máquinas locais. Cada teste da integração exige acesso à única máquina Windows que tem o SDK instalado. Os ciclos locais de feedback de desenvolvimento, um requisito básico da engenharia produtiva, são eliminados para essa parte da stack.
Pipelines de CI/CD
Pipelines de teste automatizados rodam em agentes Linux. Testes unitários, testes de integração e verificações automáticas de implantação não podem incluir nenhum caminho de código que chame o SDK. A integração biométrica fica totalmente fora do processo automatizado de garantia de qualidade.
Funções serverless
AWS Lambda, Google Cloud Functions e Azure Functions rodam em runtimes Linux gerenciados. Uma arquitetura serverless para integração biométrica é impossível com uma DLL do Windows. A função inteira precisaria ser substituída por um processo Windows de longa duração, o que anula o custo e o modelo operacional do serverless.
Orquestração com Kubernetes
O Kubernetes gerencia contêineres em clusters. Um serviço que depende de um SDK do Windows não pode participar da orquestração padrão do Kubernetes sem pools de nós Windows, que são muito mais complexos de configurar e mais caros de executar do que pools de nós Linux padrão.

As soluções alternativas que as equipes criam e por que todas acabam falhando

Diante de um SDK exclusivo do Windows e de uma stack moderna, as equipes de engenharia criam soluções alternativas. Cada uma resolve o problema imediato, mas cria uma nova dependência estrutural que causará outro problema mais adiante.

01
A VM Windows dedicada
Uma máquina virtual Windows é provisionada especificamente para executar o SDK. O serviço de integração biométrica roda nessa VM e expõe uma API interna que o restante da stack consome. Isso cria um ponto único de falha permanente que não pode ser substituído automaticamente se cair, não pode ser escalado horizontalmente e precisa ser atualizado e mantido como uma responsabilidade de infraestrutura separada.
Falha quando: a VM é desativada, atualizada ou migrada e o SDK deixa de funcionar.
02
O wrapper de interoperabilidade COM
Um wrapper fino é escrito em C# que carrega a DLL e a expõe como um objeto COM ou como um serviço HTTP local que outros processos podem chamar. Isso adiciona uma fronteira de linguagem, uma fronteira de processo e uma nova base de código que precisa ser mantida. O desenvolvedor que o escreveu costuma ser a única pessoa que o entende e, eventualmente, deixa a equipe.
Falha quando: o SDK é atualizado e o wrapper quebra, ou o desenvolvedor original deixa a equipe.
03
Wine no Linux
O Wine é uma camada de compatibilidade que permite executar alguns binários do Windows no Linux. Algumas equipes tentam executar a DLL do SDK biométrico sob Wine. Isso funciona de forma intermitente para SDKs simples e falha de maneira imprevisível para SDKs complexos que dependem de chamadas de sistema específicas do Windows. O suporte do fornecedor do SDK para implantações baseadas em Wine é inexistente.
Falha quando: o SDK chama uma API do Windows que o Wine não implementa, o que é comum.
04
Subsistema Windows para Linux
O WSL2 permite que processos Linux rodem no Windows e vice-versa. Algumas equipes instalam o SDK em uma máquina Windows e o expõem por meio de uma ponte WSL2. Essa é uma ferramenta de conveniência para desenvolvedores reaproveitada como abordagem de integração em produção. Ela não foi projetada para cargas de trabalho de produção e introduz instabilidade na fronteira do WSL sob carga sustentada.
Falha quando: atualizações do WSL quebram a ponte ou a carga causa instabilidade na camada de fronteira.
05
Python ctypes ou cffi
A biblioteca ctypes do Python permite chamar funções C de uma DLL compilada diretamente a partir de código Python. Isso pode funcionar no Windows para interfaces de DLL simples. Exige gerenciamento manual de memória, mapeamento cuidadoso de tipos e conhecimento profundo das convenções de chamada da DLL. É frágil, na maioria dos casos não documentado e totalmente não portável para qualquer plataforma que não seja Windows.
Falha quando: a interface da DLL muda em uma atualização, o que vai acontecer, sem nenhuma garantia de versionamento.
O padrão que todas as soluções alternativas têm em comum

Toda solução alternativa aceita a DLL do Windows como uma restrição fixa e constrói em torno dela. Nenhuma elimina a restrição. Todas acrescentam complexidade, ampliam a superfície de manutenção e introduzem novos modos de falha. A solução correta não é criar uma solução alternativa melhor. É eliminar totalmente a dependência da DLL.

Como é a arquitetura alternativa

A DLL do Windows existe porque o fabricante do dispositivo precisava oferecer aos desenvolvedores uma forma de se comunicar com o protocolo binário proprietário do dispositivo sem expor o próprio protocolo. A DLL é a camada de abstração entre o formato binário de transmissão e o código do desenvolvedor.

Essa camada de abstração não precisa ser uma DLL. Pode ser um servidor HTTP que fala JSON. O servidor cuida do protocolo binário de um lado e expõe uma API do outro. Os desenvolvedores chamam a API usando bibliotecas clientes HTTP padrão, que rodam em qualquer plataforma, em qualquer linguagem, dentro de qualquer contêiner, em qualquer pipeline de CI/CD, em qualquer notebook de desenvolvedor, independentemente do sistema operacional.

Abordagem com SDK

DLL do Windows instalada em uma máquina específica. Chamada por meio de FFI ou wrapper específico de linguagem. Vinculada ao sistema operacional e à versão do runtime. Não pode ser conteinerizada. Não pode ser testada em CI. Quebra com atualizações do sistema operacional. Um SDK por marca de dispositivo.

Abordagem com Biometric Gateway

Dois tipos de API, cada um fazendo um trabalho diferente. A Callback API envia eventos em tempo real do dispositivo para o seu servidor com latência zero. A RESTful API aceita comandos do seu servidor para o dispositivo com tempo de execução de aproximadamente 15 segundos. Ambas usam JSON sobre HTTP/HTTPS, com criptografia AES-256 opcional. Qualquer linguagem, qualquer SO, totalmente conteinerizável, testável em qualquer ambiente de CI.

Nenhum dos tipos de API exige que o dispositivo mude. O dispositivo continua falando seu protocolo binário proprietário. O Biometric Gateway fica entre seus dispositivos e sua aplicação, cuidando internamente de toda a tradução de protocolo. Seu Protocol Engine gerencia o processamento seguro de autenticação, o registro de transações de dados, a tradução de protocolo e o cache e a fila offline para quando os dispositivos estiverem temporariamente inacessíveis. Sua Camada de API Padronizada cuida da gestão de identidade, da integração com IA e MCP, do despacho de callbacks, do roteamento de comandos REST e da normalização de dados entre todas as marcas de dispositivos suportadas.

O que muda para a sua equipe de desenvolvimento

Quando o SDK é substituído por uma API, as mudanças práticas no seu fluxo de desenvolvimento são significativas. Não são melhorias incrementais. É a eliminação de categorias inteiras de atrito que sua equipe já aceitou como normal.

Tarefa de desenvolvimento Com SDK do Windows Com API
Configuração do ambiente de desenvolvimento para novos desenvolvedores Horas a dias, VM Windows + instalação do SDK + licença + dependências de runtime Minutos, basta adicionar a URL base da API e o token de autenticação às variáveis de ambiente
Desenvolvimento e testes locais Exige acesso remoto à máquina Windows com o SDK Funciona em qualquer notebook, em qualquer SO, com qualquer ferramenta cliente HTTP
Integração com pipeline de CI/CD Não é possível em agentes Linux padrão Chamadas HTTP padrão, funciona em qualquer ambiente de CI
Implantação em contêineres Exige contêiner Windows ou VM dedicada Qualquer contêiner Linux, de qualquer tamanho, totalmente orquestrável
Adição de uma segunda marca de dispositivo Novo SDK, nova DLL, novo wrapper, nova documentação Mesma superfície das Callback e RESTful APIs, independentemente da marca
Depuração de uma operação com falha Logs de protocolo binário, muitas vezes não documentados Códigos de resposta HTTP padrão e corpos de erro em JSON
Impacto de atualizações do SO ou do runtime Pode quebrar a compatibilidade do SDK, exige atualização do fornecedor Sem impacto no código do cliente

Os dois tipos de API: o que o seu desenvolvedor realmente escreve

Para tornar o contraste concreto, veja como os dois tipos de API funcionam na prática. A RESTful API é chamada pelo seu servidor para enviar um comando ao dispositivo. A Callback API é o caminho inverso: o Gateway chama o seu servidor para enviar um evento em tempo real. Seu desenvolvedor escreve um receptor para uma e um chamador para a outra. Ambas usam JSON sobre HTTP/HTTPS. Nenhuma exige uma DLL, uma máquina Windows ou qualquer instalação de SDK.

Callback API, Requisição, enviada ao seu servidor pelo Gateway
{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}
Callback API, Resposta, seu servidor deve retornar isto ao Gateway
{ "status": "done" }

A chamada à API é feita com qualquer biblioteca HTTP em qualquer linguagem: requests do Python, fetch do Node, net/http do Go, cURL em um script de shell. Ela funciona de forma idêntica em um notebook Mac, em um runner Linux de CI, em um contêiner Docker no Kubernetes e em uma função serverless. O payload da Callback API chega ao endpoint de webhook que o seu servidor expõe, no mesmo formato JSON, independentemente da marca do dispositivo ou do tipo de entrada que gerou o evento. Impressão digital, reconhecimento facial, veia da palma, cartão RFID, PIN, código QR ou código de barras: a estrutura que o seu servidor recebe é sempre a mesma. Sem DLL. Sem dependência de runtime. Sem exigência de Windows. Sem arquivo de licença para gerenciar.

O que isso significa especificamente para a sua equipe

Um desenvolvedor que entrar na sua equipe na próxima semana pode clonar o repositório, adicionar as credenciais do Gateway ao arquivo de ambiente e fazer sua primeira chamada bem-sucedida a um dispositivo biométrico em poucos minutos após se sentar. Para a RESTful API, ele escreve um POST HTTP padrão. Para a Callback API, ele escreve um receptor HTTP padrão. Nenhuma das duas exige uma máquina Windows, um instalador de SDK, uma chave de licença do fornecedor ou qualquer conhecimento de protocolos binários de dispositivos. Eles integram com o Gateway exatamente da mesma forma que integram com qualquer outro serviço JSON da sua stack.

Perguntas frequentes

Substituir o SDK por uma API significa perder alguma funcionalidade do dispositivo?
O Cams Biometrics Gateway expõe 38 operações biométricas nos dois tipos de API. A RESTful API lida com os comandos que o seu servidor envia ao dispositivo, como adicionar usuários, excluir registros, carregar logs e cadastrar biometrias. A Callback API entrega eventos em tempo real do dispositivo para o seu servidor, incluindo registros de ponto por impressão digital, reconhecimento facial, veia da palma, cartão RFID, PIN, código QR e código de barras. Na maioria dos casos, o Gateway expõe mais capacidades do que uma determinada versão do SDK do fabricante, porque trabalha diretamente com o protocolo do dispositivo. Verifique a compatibilidade do seu modelo de dispositivo específico com a equipe de suporte da Cams antes de migrar.
Já construímos um wrapper significativo em torno do SDK. Quanto disso teremos que descartar?
A lógica de negócio do seu wrapper, as regras sobre quais funcionários recebem quais níveis de acesso, o mapeamento entre os IDs do seu HRMS e os IDs de usuário do dispositivo, o tratamento de erros e a lógica de repetição, tudo isso é reutilizável. O que você substitui é a camada que chama as funções da DLL. Em vez de chamar funções do SDK, você faz requisições HTTP. A lógica acima dessa camada permanece a mesma. Na maioria dos casos, a substituição do SDK é uma mudança menor do que parece vista de fora.
Uma API é menos confiável do que uma conexão direta com o SDK?
Não necessariamente. O Gateway mantém uma conexão persistente com o dispositivo e inclui um cache e uma fila offline que armazenam operações quando um dispositivo está temporariamente inacessível. Os eventos não são perdidos durante interrupções de conectividade e são entregues ao seu endpoint de Callback quando a conexão é restabelecida. A confiabilidade da conexão com o dispositivo é determinada pela infraestrutura do Gateway, e não pelo fato de sua aplicação falar com ele via HTTP ou via chamadas de DLL. Um gateway bem operado terá disponibilidade superior à que a maioria das equipes consegue com uma instalação de SDK autogerenciada em uma única VM Windows.
E quanto à latência? O salto de rede adicional gera um atraso significativo?
Para a maioria das operações biométricas, o salto de rede adicional acrescenta apenas alguns milissegundos. Os callbacks de presença são entregues em tempo real, com o gateway enviando para o seu endpoint de webhook, portanto o modelo de latência é semelhante ao de uma conexão direta com o SDK recebendo um evento. Para operações de escrita, como adicionar um usuário, o tempo total de ida e volta é dominado pelo tempo de processamento do próprio dispositivo, que fica entre 1 e 3 segundos, independentemente de como a instrução chegou. O salto HTTP não é o gargalo.
Podemos usar a API a partir do nosso backend Python ou Node.js existente sem nenhuma biblioteca cliente especial?
Sim. A API usa HTTP padrão com corpos JSON. Qualquer biblioteca cliente HTTP, em qualquer linguagem, funciona sem modificações. Você não precisa de um SDK especial, de uma biblioteca cliente publicada pelo fornecedor do gateway nem de nenhum pacote específico de linguagem. Se você consegue fazer uma requisição POST HTTP com um corpo JSON, consegue chamar a API. Essa é toda a superfície de integração do ponto de vista da sua aplicação.

Conclusão: o problema do SDK tem uma solução limpa

Um SDK biométrico exclusivo do Windows não é uma realidade inevitável com a qual sua equipe de engenharia precise conviver para sempre. É consequência de uma decisão de distribuição tomada há duas décadas, em um cenário de infraestrutura diferente. Essa decisão pode ser substituída por um gateway que absorve a complexidade do protocolo binário e expõe o dispositivo por meio de uma API padrão.

Quando essa transição acontecer, a VM Windows dedicada será desativada. O pipeline de CI/CD voltará a incluir a integração biométrica. O novo desenvolvedor configura seu ambiente local em minutos. O contêiner Docker roda sem configuração especial. Os desenvolvedores Mac deixam de acessar remotamente a única máquina do escritório que tem a licença do SDK instalada. Essas não são pequenas melhorias de qualidade de vida. São a eliminação de uma restrição estrutural que vem consumindo o tempo e a paciência da sua equipe de engenharia há anos.

O Cams Biometrics Gateway substitui completamente o SDK do Windows. Ele se conecta aos seus dispositivos biométricos da Cams, ZKTeco, Suprema, Hikvision, Anviz, Morpho/IDEMIA, Virdi, Mantra, Nitgen, Realtime, Biomax, Secugen, eSSL, Matrix e outros, usando seus protocolos nativos, sem necessidade de instalar qualquer SDK em nenhum ponto da sua infraestrutura. Ele expõe 38 operações em dois tipos de API: uma Callback API que envia eventos de dispositivos em tempo real para o seu servidor com latência zero, e uma RESTful API que aceita comandos do seu servidor para o dispositivo. Toda a comunicação é feita em JSON sobre HTTP/HTTPS, com criptografia AES-256 opcional. A integração nativa com MCP permite que Claude, Gemini e ChatGPT chamem operações biométricas diretamente. O cache e a fila offline lidam automaticamente com interrupções de conectividade. O Gateway funciona de forma idêntica, seja sua stack executada em Linux, Mac, Windows, Docker, Kubernetes ou funções serverless. Sem DLL. Sem Visual C++ Redistributable. Sem máquina Windows dedicada. Sem arquivo de licença. Explore a API completa em CamsBiometrics.com para saber mais sobre a migração da sua integração atual com SDK.

 

Was this article helpful?