TalentApproved

3 Chamadas de API para Entregar Pontuações de Avaliação ATS para RH e Engenharia

3 Chamadas de API para Entregar Pontuações de Avaliação ATS para RH e Engenharia

Prefira uma API de avaliação nativa quando o seu sistema de rastreamento de candidatos oferecer uma. Quando isso não for possível, recorra a uma integração de sistema de registro ou a uma API de Avaliação unificada. De qualquer forma, planeje três ações principais: listar os pacotes de testes disponíveis, acionar uma avaliação para um candidato e sincronizar os resultados de volta por meio de webhooks. Recursos mais avançados ou o acesso à integração em si podem estar disponíveis apenas em um plano pago ou de parceiro.

Resumo:

  • As APIs de avaliação nativas proporcionam a melhor experiência para o recrutador, permitindo filtrar e classificar candidatos com base em pontuações estruturadas dentro do ATS.
  • Quando não há API de avaliação disponível, as integrações de fallback anexam resultados como notas ou arquivos, o que limita a capacidade de filtrar ou ordenar os resultados dos candidatos.
  • A sequência de integração recomendada envolve listar pacotes, acionar avaliações e capturar resultados via webhooks, com foco na identificação segura e no tratamento adequado dos códigos de resposta.
  • Os empregadores devem validar e documentar as ferramentas de avaliação quanto à equidade e conformidade legal antes da implantação, garantindo que os resultados sejam armazenados com uma trilha de auditoria e que o consentimento seja registrado.
  • Testar a integração minuciosamente em um ambiente de homologação e monitorar o sucesso dos webhooks ajuda a prevenir erros e resultados órfãos no pipeline de contratação em produção.
Talent Approved
Avalie Competências Além do Currículo
O Talent Approved ajuda os empregadores a criar avaliações de competências personalizadas, analisar resultados estruturados e tomar decisões de contratação mais embasadas.
Conheça o Talent Approved

Índice

APIs nativas, integrações de fallback e APIs de Avaliação unificadas

Três padrões de integração cobrem quase todas as stacks de contratação, e cada um deles muda o que os seus recrutadores visualizam dentro do ATS.

Uma API de avaliação nativa é a opção mais limpa. Ela expõe pacotes de testes, pedidos e resultados estruturados diretamente no registro do ATS, o que significa que os recrutadores podem filtrar e classificar candidatos por pontuação da mesma forma que filtram por etapa ou origem. A documentação para desenvolvedores do Ashby descreve isso como o formato padrão: listar pacotes, iniciar uma avaliação e registrar os resultados de volta por meio de um webhook.

Quando o ATS não possui endpoints dedicados para avaliação, as equipes recorrem a ouvintes de mudança de etapa e anexam os resultados como notas, links ou uploads de arquivos. Isso garante uma cobertura básica, mas elimina a pontuação estruturada, fazendo com que os recrutadores percam a capacidade de ordenar ou filtrar por resultado dentro do ATS, de acordo com o guia de integração da Kombo.

Uma API de Avaliação unificada fica entre as duas opções. Ela padroniza pacotes, webhooks de pedidos e o registro de resultados de volta em diversas plataformas de ATS ao mesmo tempo, de modo que um fornecedor integra uma vez e alcança dezenas de sistemas, em vez de construir e manter um conector separado para cada um, conforme descrito na visão geral da API de Avaliação Unificada.

  • API nativa: melhor experiência para o recrutador, vinculada a um único ATS.
  • Integração de fallback: maior cobertura, pontuação mais fraca dentro do ATS.
  • API unificada: menor manutenção a longo prazo para fornecedores que atendem a múltiplos ATSs.

Construindo a integração: um checklist passo a passo

Antes de escrever qualquer código, confirme se o ATS realmente expõe uma API de avaliação e obtenha a documentação para desenvolvedores. Muitas plataformas publicam apenas endpoints gerais de candidatos ou candidaturas, e tratar esses endpoints como endpoints de avaliação é um erro comum no início do processo.

  1. Mapeie os identificadores primeiro. Use o ID da candidatura ou o UUID do candidato em cada chamada para que os resultados sejam vinculados ao registro correto, em vez de se tornarem órfãos — uma armadilha destacada nas orientações de integração da JobCannon.
  2. Escolha um padrão de autenticação. A maioria das plataformas utiliza chaves de API, chaves de parceiro ou OAuth, e cada uma exige seu próprio armazenamento seguro e política de rotação.
  3. Siga a sequência padrão de chamadas. Liste os pacotes com assessment.list, acione o teste com assessment.start e, em seguida, aguarde um webhook que é disparado ao término e registre o resultado de volta.
  4. Trate os códigos de resposta documentados. A referência da API Ashby para assessment.start lista 200, 409 e 422 como respostas típicas, e a sua integração precisa de um comportamento definido para cada uma delas.
  5. Defina o payload de resultado. Planeje para pontuações gerais, subpontuações, timestamps, anexos e quaisquer atributos personalizados nos quais sua equipe queira filtrar posteriormente.
  6. Planeje para limites de taxa. Solicite aumentos de cota antes dos períodos de contratação em grande volume para que uma sequência de convites a candidatos não acione erros 429 no meio de uma campanha.

Dica profissional: Armazene o ID da candidatura junto a cada payload de saída e de entrada, mesmo nos logs, para que um webhook com falha seja facilmente rastreado até um candidato específico.

Os empregadores, e não os fornecedores, carregam o peso legal dos testes de emprego. As orientações da EEOC sobre testes de emprego e procedimentos de seleção deixam claro que as ferramentas de seleção devem ser validadas e relacionadas ao cargo, e que os empregadores permanecem responsáveis pelo impacto desproporcional mesmo quando um terceiro desenvolveu o teste. Solicite a documentação de validação de qualquer fornecedor de avaliação antes de integrar a ferramenta dele a um pipeline de contratação em produção. Nosso próprio artigo sobre as diretrizes de testes da EEOC aborda os requisitos da UGESP com mais detalhes.

  • Solicite documentação de validação e de impacto adverso de qualquer fornecedor de avaliação antes de entrar em produção.
  • Armazene os resultados das avaliações com uma trilha de auditoria clara e um período de retenção definido, e não por tempo indeterminado.
  • Pergunte aos fornecedores como eles registram o consentimento para monitoramento por proctoring ou câmera, e se se aplica uma avaliação de impacto à proteção de dados.
  • Documente sua revisão de validação, realize uma verificação-piloto de equidade nos primeiros resultados e mantenha essa evidência arquivada.

Nosso guia prático de testes de impacto adverso explica como realizar essa análise-piloto e o que corrigir quando os números apresentarem desequilíbrio.

Escolhendo entre integração nativa, API unificada e desenvolvimento personalizado

Antes de comprometer tempo de engenharia, percorra um checklist rápido com os responsáveis de RH e engenharia juntos.

  • Confirme quais funcionalidades o ATS suporta nativamente versus quais exigem uma solução alternativa.
  • Pergunte a qualquer fornecedor de avaliação se ele já suporta o seu ATS e se o processo de integração como parceiro envolve uma taxa ou exigência de assinatura, pois algumas plataformas restringem módulos de integração a planos superiores, conforme a comparação de plataformas de avaliação da Coderbyte.
  • Verifique se o registro de resultados inclui pontuações estruturadas, e não apenas um link ou anexo, para que os recrutadores possam filtrar por resultado.
  • Defina antecipadamente as expectativas de confiabilidade e reenvio dos webhooks, e determine quem é responsável pelo monitoramento em ambos os lados.
  • Confirme se o fornecedor pode fornecer documentação de validação, controles anti-trapaça e um acordo de processamento de dados.

Dica profissional: Solicite um ambiente sandbox antes de assinar qualquer coisa. Um fornecedor que não consegue demonstrar o disparo de um webhook de teste de ponta a ponta não está pronto para o seu pipeline em produção.

Testando a integração de ponta a ponta e identificando falhas antecipadamente

Um ambiente de homologação deve simular o ciclo de vida completo antes que qualquer candidato real o utilize: crie um pedido de teste, acione o webhook manualmente e confirme se o resultado é renderizado corretamente na interface do ATS — e não apenas em um registro de banco de dados.

  1. Execute testes de homologação que cubram a listagem de pacotes, a criação de pedidos e o registro de resultados de volta com dados de amostra realistas.
  2. Monitore as taxas de sucesso dos webhooks e as tendências de erros, e crie um relatório de reconciliação que identifique resultados órfãos antes que se acumulem.
  3. Use IDs de correlação em cada requisição para que um chamado de suporte possa ser rastreado em ambos os sistemas em minutos, e não horas.
  4. Implemente lógica de reenvio idempotente para que um webhook reenviado nunca crie um resultado duplicado, e mantenha um script de reprocessamento pronto para quaisquer eventos perdidos.
  5. Escreva um guia operacional resumido indicando quem será alertado em caso de falha de webhook e como reexecutar com segurança um pedido travado.

Como o Talent Approved se encaixa em uma integração com ATS

A plataforma do Talent Approved inclui um recurso que gera avaliações específicas para cada função a partir de descrições de cargos ou listas de competências, além de monitoramento anti-trapaça e resumos gerados por IA que aceleram a análise. No lado da integração, o Talent Approved segue o mesmo ciclo de vida de listagem, acionamento e registro de resultados descrito acima, e o mapeamento do ID da candidatura ou do UUID do candidato em cada chamada garante que os resultados sejam corretamente vinculados ao registro do ATS correspondente. O modelo de preços é por uso, com uma taxa de $5 por candidato concluído, sem necessidade de assinatura. As equipes que implementam a integração também podem consultar nosso guia sobre como as avaliações instantâneas funcionam e nossos recursos de conformidade com a EEOC para obter detalhes sobre implementação e validação.

Como o Talent Approved se encaixa em uma integração com ATS — diagrama de visão geral

O que as equipes de RH erram sobre integração com ATS

O que as equipes de RH erram sobre integração com ATS — diagrama de visão geral

A maioria das equipes trata todas as APIs de ATS da mesma forma e depois se surpreende quando a sua "integração de avaliação" acaba sendo um ouvinte de mudança de etapa sem nenhuma pontuação estruturada anexada. A solução não está em mais horas de engenharia. Está em verificar, desde o primeiro dia, se uma API de avaliação real existe.

Comece com um piloto pequeno em uma única vaga aberta antes de mexer em todo o seu pipeline de contratação. Observe duas coisas ao mesmo tempo: se os recrutadores realmente utilizam a filtragem por pontuação e se os primeiros resultados mostram alguma lacuna de equidade entre grupos de candidatos. Quando uma API de avaliação nativa ou uma API unificada comprovada estiver disponível, escolha-a. Tanto a experiência do recrutador quanto a defensabilidade legal dependem de resultados estruturados e filtráveis — e não de uma solução alternativa acoplada a uma API de uso geral.

— Jimmie

Documentação para desenvolvedores e orientações de conformidade que valem a pena salvar

Mantenha sempre à mão a documentação de integração de avaliações do Ashby, a visão geral da API de Avaliação Unificada e as orientações de testes da EEOC. Para suporte de engenharia no lado da integração, empresas como a Ampersand são especializadas em implementação de API e webhook.

Fontes

FAQ

O que significa integração com ATS?

Integração com ATS significa conectar um sistema de rastreamento de candidatos a outra ferramenta, como uma plataforma de avaliação, para que os dados se movam automaticamente entre eles, em vez de serem copiados manualmente. No caso das avaliações especificamente, isso significa listar pacotes de testes, acionar um teste para um candidato e registrar a pontuação de volta no registro do candidato no ATS.

Quais são os principais sistemas ATS?

Não existe uma classificação oficial única das melhores plataformas de ATS, e a escolha certa depende do tamanho da empresa, do volume de contratações e das integrações necessárias. Em vez de indicar fornecedores específicos, as equipes de RH devem avaliar qualquer ATS verificando se ele expõe uma API de avaliação documentada, conforme descrito na documentação para desenvolvedores do Ashby, em vez de se basearem em listas de popularidade geral.

Qual é a diferença entre um ATS e um CRM?

Um ATS gerencia o fluxo de trabalho de contratação para vagas abertas, acompanhando os candidatos desde a candidatura até a oferta. Um CRM de recrutamento, por sua vez, gerencia relacionamentos de longo prazo com candidatos em potencial, incluindo pessoas que não estão ativamente se candidatando — o que é uma função diferente de rastrear candidatos ativos ao longo de um pipeline.

O que significa ATS?

ATS significa applicant tracking system (sistema de rastreamento de candidatos), o software que as equipes de RH utilizam para publicar vagas, coletar candidaturas e conduzir os candidatos pelas etapas de contratação. Quando suporta uma API de avaliação dedicada, ele também pode acionar testes de competências e receber resultados estruturados diretamente no registro do candidato, conforme o ciclo de vida de integração descrito na referência de API do Ashby.