Integração com ATS via API: avaliações dentro do seu processo

Permite que o seu ATS, portal de carreiras ou sistema interno de recrutamento dispare avaliações e receba os resultados sem que o recrutador saia da tela dele. Na prática: quando uma candidatura avança de etapa no ATS, o sistema chama a Coodesh, o candidato recebe o convite, responde a avaliação na Coodesh, e o resultado volta para o card da candidatura com nota, detalhamento por questão, link do relatório e resumo de integridade. O recrutador deixa de exportar planilha, copiar link de convite e conferir duas telas. A lógica do processo continua no ATS; a Coodesh cuida só da avaliação.

São três chamadas e um webhook. Primeiro, o seu sistema lista as avaliações disponíveis na área de trabalho, para que o recrutador escolha qual enviar. Segundo, cria uma tentativa para o candidato, informando nome, e-mail, identificadores do candidato e da vaga no seu sistema, a URL para onde o candidato volta ao terminar e a URL do seu webhook; a resposta traz o identificador da tentativa e o link para o candidato iniciar. Terceiro, a cada mudança de estado da tentativa, a Coodesh chama o seu webhook com os dados daquele estado. Se precisar, o seu sistema também consulta o resultado de uma tentativa a qualquer momento pelo identificador. A documentação completa, com exemplos de requisição e resposta, está em coodesh.com/docs.

A integração da Coodesh é feita por API aberta, o que significa que qualquer ATS ou sistema próprio pode se conectar com os mesmos três endpoints, sem depender de um conector específico. Isso vale para plataformas de mercado e para o sistema interno que a sua empresa construiu. Para saber se o seu ATS já tem uma conexão configurada por outro cliente ou pelo fornecedor, ou para alinhar uma implementação conjunta com o time do seu ATS, fale com o time da Coodesh; a maior parte das integrações leva poucos dias porque o contrato da API é pequeno e estável.

A autenticação é por chave de integração, enviada no header de cada requisição. A chave é gerada dentro da plataforma, por área de trabalho, e só dá acesso às avaliações e tentativas daquela área. É o modelo adequado para integração servidor a servidor: não há login de usuário envolvido, a chave fica guardada no seu backend, e pode ser revogada e gerada de novo a qualquer momento sem afetar usuários. A recomendação é uma chave por sistema integrado, nunca compartilhada entre ambientes, e rotação sempre que alguém com acesso sair do time.

A pontuação geral, o tipo de pontuação, as datas de convite, início e término, o detalhamento por teste, um link do relatório completo na Coodesh e um texto pronto em linguagem natural com o resumo do desempenho, pensado para ser colado em um comentário ou card do ATS. Vem também um resumo de integridade: quantidade de dispositivos e localizações, saídas de aba e de tela cheia, eventos de copiar e colar, navegador e sistema operacional, e a categoria de severidade da tentativa. Isso permite que o recrutador priorize a revisão sem abrir a Coodesh, e que o detalhe completo esteja a um clique.

A Coodesh chama a URL de webhook informada na criação da tentativa a cada mudança de estado: iniciado, quando o candidato começa; expirado, quando o prazo termina sem conclusão; e finalizado, quando o resultado está disponível. O webhook de finalizado traz o resultado completo, então o seu sistema não precisa fazer uma segunda chamada. Como boa prática, trate o webhook como sinal e não como única fonte: responda rápido, processe de forma assíncrona, e mantenha a consulta de resultado por identificador como reconciliação para o caso de o seu endpoint estar indisponível no momento do envio.

O candidato faz a avaliação na Coodesh, com a mesma experiência de qualquer outro candidato: navegador, celular quando o formato permite, recursos de integridade conforme a configuração da avaliação. O convite pode ir pelo e-mail padrão da Coodesh ou, se o seu ATS já se comunica com o candidato, você desativa o e-mail na criação da tentativa e entrega o link por onde preferir. Ao terminar, o candidato é redirecionado para a URL que o seu sistema informou, voltando para o portal de carreiras ou para a página de confirmação da empresa.

Crie uma avaliação curta de teste na sua área de trabalho, gere uma chave de integração e use o próprio fluxo com um e-mail da sua equipe: liste as avaliações, crie uma tentativa com o e-mail desativado, abra o link, responda e observe os webhooks chegarem em cada estado. Como tentativas de teste consomem resultado como qualquer outra, alinhe com o time da Coodesh o volume de testes durante a implementação. A documentação traz exemplos de requisição e resposta para cada endpoint e os códigos de erro esperados. Doc: https://coodesh.com/docs

Entre alguns dias e duas semanas, dependendo mais do seu ATS do que da Coodesh. O contrato da API tem três endpoints e um webhook, então o trabalho do lado da Coodesh é pequeno. O tempo vai para o mapeamento no seu sistema: em que etapa disparar, onde gravar o resultado, como exibir o link do relatório e o que fazer com a categoria de integridade. Um desenvolvedor backend com experiência em APIs REST e webhooks resolve. Se o seu ATS é de terceiro, o caminho costuma ser o time de integrações do fornecedor com suporte da Coodesh.

O seu sistema envia para a Coodesh nome, e-mail e identificadores internos do candidato e da vaga; a Coodesh devolve resultado, relatório e resumo de integridade. A sua empresa é a controladora e a Coodesh, a operadora, o que deve estar refletido no acordo de tratamento de dados. Dois cuidados de implementação: o link do relatório que vem no resultado dá acesso ao relatório sem login, então trate-o como dado sensível no seu sistema, com acesso restrito ao time de recrutamento; e os identificadores que você envia devem ser os do seu sistema, não CPF ou documento, porque a API não precisa deles para funcionar.