Para integrar tu ATS o producto con las evaluaciones de Coodesh, usa la API REST con una clave de integración de tu área de trabajo. Con ella, tu sistema lista las evaluaciones publicadas, invita a las personas a responderlas y recibe los resultados.

Entornos y enlaces

Recurso	Dirección
Documentación oficial de la API	https://coodesh.com/docs
Producción	https://api.coodesh.com
Asistentes de IA (MCP)	Cómo conectar tu asistente de IA (MCP)

Autenticación

Envía la clave de integración en todas las solicitudes, en los encabezados siguientes:

Encabezado	Valor
X-API-KEY	<tu clave de integración>
Content-Type	application/json

Flujo de la integración

Tu sistema consulta las evaluaciones disponibles (GET /assessments/ats).
Para cada persona, tu sistema crea un intento (POST /assessments/ats/attempts) y recibe el enlace de la evaluación.
Coodesh envía la invitación por correo electrónico. Si envías disable_email: true, la invitación no se envía y tu sistema entrega el enlace a la persona.
La persona responde la evaluación.
En cada cambio de estado, Coodesh llama al webhook_url informado. El resultado también se puede consultar en cualquier momento.

Endpoints

Las rutas siguientes son relativas a https://api.coodesh.com.

Listar evaluaciones

GET /assessments/ats

Lista las evaluaciones publicadas en el área de trabajo de la clave, de la más reciente a la más antigua. Parámetros opcionales:

search: texto para buscar evaluaciones.
offset: cuántos elementos omitir. Por defecto: 0.
limit: elementos por página. Por defecto: 20; máximo: 2000.

Respuesta

{
  "offset": 0,
  "total": 1,
  "limit": 20,
  "payload": [
    {
      "assessment_id": "6707e51d867d313ecdd5f456",
      "name": "Desenvolvimento Backend",
      "description": "Avaliar lógica de programação e arquitetura",
      "default_locale": "pt",
      "duration": 5,
      "duration_unit": "hour",
      "subaccount_ids": [],
      "assess_team": false,
      "questions": [
        {
          "name": "Teste básico de lógica",
          "description": "Crie uma classe que implemente os métodos abaixo...",
          "type": "freecoding",
          "type_formatted": "Programação livre",
          "level": "beginner",
          "level_formatted": "Iniciante",
          "duration": 30,
          "duration_unit": "minute"
        },
        {
          "name": "Infraestrutura multiusuário e multitenant",
          "description": "Desenhe e explique uma arquitetura...",
          "type": "whiteboard",
          "type_formatted": "Quadro branco",
          "level": "advanced",
          "level_formatted": "Avançado",
          "duration": 5,
          "duration_unit": "hour"
        }
      ]
    }
  ]
}

Crear un intento

POST /assessments/ats/attempts

Crea un intento de la evaluación elegida para una persona y devuelve el enlace para responderla. El idioma y el plazo siguen la configuración de la evaluación.

Campo	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la persona
`email`	string	Sí	Correo electrónico de la persona
`user_id`	string	Sí	Identificador de la persona en tu sistema
`assessment_id`	string	Sí	Evaluación, según el listado
`company_id`	string	Sí	Identificador de la empresa en tu sistema
`job_id`	string	Sí	Identificador de la vacante en tu sistema
`callback_url`	URL	Sí	Dirección de retorno en tu sistema, como la página de la candidatura
`webhook_url`	URL	No	Dirección que recibe los cambios de estado
`disable_email`	boolean	No	Si es true, Coodesh no envía la invitación ni el correo de resultado a la persona. Por defecto: false

Si la evaluación tiene una dirección de retorno configurada en Coodesh, esta prevalece sobre la enviada. Si ya existe una invitación aún no iniciada para la misma persona y evaluación, la API reutiliza ese intento.

Solicitud

{
  "name": "Ana Silva",
  "email": "ana.silva@exemplo.com",
  "user_id": "b12002e0-afc4-11ee-ac51-1fb9ace11428",
  "company_id": "d5cf6e60-f2f5-11e7-9747-838fbc80281c",
  "job_id": "54046020-aec4-11ee-a01d-174ac5115722",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "callback_url": "https://empresa.seuats.com/candidaturas/123",
  "webhook_url": "https://api.seuats.com/webhooks/coodesh",
  "disable_email": true
}

Respuesta

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "attempt_url": "https://coodesh.com/pt/assessments/{token}"
}

Obtener un resultado

GET /assessments/ats/attempts/{attemptId}

Devuelve el estado y el resultado de un intento a partir del attempt_id. En results, cada elemento corresponde a una pregunta de la evaluación.

Respuesta

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "finished",
  "status_formatted": "Finalizado",
  "description": "Este é o resultado da sua avaliação Desenvolvimento Backend",
  "score": 62,
  "score_type": "percentage",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "finished": "2026-09-26T18:50:25.575Z",
  "invite_link": "https://coodesh.com/pt/assessments/{token}",
  "public_link": "https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}",
  "result_talent_link": "https://coodesh.com/pt/assessments/results/66df68adc308c0ef4ee945f7",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com",
  "proctoring": {
    "devices": 1,
    "locations": 2,
    "fullscreen_exits": 0,
    "tab_exits": 3,
    "copy_paste_count": 0,
    "devtools_open_count": 0,
    "last_location": "BR",
    "last_device_type": "desktop",
    "last_browser": "Chrome",
    "last_os": "macOS",
    "severity_category": "none",
    "severity_category_formatted": "Nenhuma"
  },
  "results": [
    {
      "score": 80,
      "score_type": "percentage",
      "title": "Teste básico de lógica",
      "description": "Programação livre",
      "date": "2026-09-26"
    },
    {
      "score": 44,
      "score_type": "percentage",
      "title": "Infraestrutura multiusuário e multitenant",
      "description": "Quadro branco",
      "date": "2026-09-26"
    }
  ],
  "company_result_string": "Ana Silva obteve 62% de aproveitamento na avaliação Desenvolvimento Backend.\nTestes:\n80% - Teste básico de lógica - Programação livre\n44% - Infraestrutura multiusuário e multitenant - Quadro branco\nAtividades suspeitas: Nenhuma\nEnviada em: 15:47 26 set, 2026 GMT-03:00\nFinalizado em: 15:50 26 set, 2026 GMT-03:00\nRelatório: https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}"
}

Webhook

Si informas el webhook_url al crear el intento, Coodesh envía un POST con un JSON a esa dirección cada vez que cambia el estado del intento:

Iniciado (started): la persona comenzó la evaluación y aún no la terminó.
Expirado (expired): el plazo terminó sin que la persona concluyera la evaluación.
Finalizado (finished): la persona concluyó la evaluación y el resultado está disponible.
Bloqueado (blocked): la persona concluyó la evaluación, pero el resultado está bloqueado por falta de créditos en el área de trabajo.

Los eventos finalizados y bloqueados traen la nota, los enlaces y el resumen de integridad. Para ver la nota de cada pregunta, consulta el resultado con GET /assessments/ats/attempts/{attemptId}.

Iniciado (started)

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "started",
  "status_formatted": "Iniciado",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com"
}

Expirado (expired)

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "expired",
  "status_formatted": "Expirado",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "expired": "2026-09-27T18:47:50.183Z",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com"
}

Finalizado (finished)

{
  "attempt_id": "66df68adc308c0ef4ee945f7",
  "assessment_id": "6707e51d867d313ecdd5f456",
  "title": "Desenvolvimento Backend",
  "status": "finished",
  "status_formatted": "Finalizado",
  "created": "2026-09-26T18:47:50.183Z",
  "invited": "2026-09-26T18:47:50.183Z",
  "started": "2026-09-26T18:48:02.179Z",
  "updated": "2026-09-26T18:51:09.457Z",
  "provider_name": "Coodesh",
  "provider_link": "https://coodesh.com",
  "description": "Este é o resultado da sua avaliação Desenvolvimento Backend",
  "score": 62,
  "score_type": "percentage",
  "finished": "2026-09-26T18:50:25.575Z",
  "public_link": "https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}",
  "result_talent_link": "https://coodesh.com/pt/assessments/results/66df68adc308c0ef4ee945f7",
  "proctoring": {
    "devices": 1,
    "locations": 2,
    "fullscreen_exits": 0,
    "tab_exits": 3,
    "copy_paste_count": 0,
    "devtools_open_count": 0,
    "last_location": "BR",
    "last_device_type": "desktop",
    "last_browser": "Chrome",
    "last_os": "macOS",
    "severity_category": "none",
    "severity_category_formatted": "Nenhuma"
  },
  "results": [
    {
      "score": 62,
      "title": "Desenvolvimento Backend",
      "score_type": "percentage",
      "date": "2026-09-26"
    }
  ],
  "company_result_string": "Ana Silva obteve 62% de aproveitamento na avaliação Desenvolvimento Backend.\nTestes:\n80% - Teste básico de lógica - Programação livre\n44% - Infraestrutura multiusuário e multitenant - Quadro branco\nAtividades suspeitas: Nenhuma\nEnviada em: 15:47 26 set, 2026 GMT-03:00\nFinalizado em: 15:50 26 set, 2026 GMT-03:00\nRelatório: https://coodesh.com/pt/share/assessments/66df68adc308c0ef4ee945f7?accessToken={token}"
}

Límite de solicitudes

Existe un límite de solicitudes por segundo, por clave y por área de trabajo. Al recibir el código 429, espera los segundos indicados en el encabezado Retry-After-short (límite por clave) o Retry-After-long (límite por área de trabajo) y repite la llamada.

Códigos de error

Código	Significado
400 - Bad Request	Datos inválidos o fuera del estándar, o evaluación e intento no encontrados en el área de trabajo de la clave.
401 - Unauthorized	Clave de integración ausente o inválida.
403 - Forbidden	La clave no tiene acceso al recurso solicitado.
429 - Too Many Requests	Límite de solicitudes alcanzado.
500 - Internal Server Error	Error inesperado en el servidor. Si persiste, escribe a help@coodesh.com.

Quiero integrar mi producto con Coodesh vía API

Entornos y enlaces

Autenticación

Flujo de la integración

Endpoints

Listar evaluaciones

Respuesta

Crear un intento

Solicitud

Respuesta

Obtener un resultado

Respuesta

Webhook

Iniciado (started)

Expirado (expired)

Finalizado (finished)

Límite de solicitudes

Códigos de error