Saltar al contenido principal

Uso de la Documentación Interactiva

Aprende cómo usar nuestra documentación interactiva basada en OpenAPI en docs.intelliscreen.io para probar y explorar los endpoints de la API.

Comenzando con la Documentación​

Nuestra documentación de API está construida usando especificaciones OpenAPI, proporcionándote una interfaz interactiva para probar endpoints directamente desde tu navegador.

Interfaz de Documentación Interactiva Vista general de la interfaz de documentación interactiva

Métodos de Autenticación​

Tienes dos opciones para autenticarte con la documentación interactiva:

Opción 1: Autenticación Global​

  1. Localiza el ícono de candado en la parte superior derecha de la página de documentación
  2. Haz clic en el ícono de candado para abrir el diálogo de autenticación
  3. Ingresa tu clave API en el campo de autenticación
  4. Haz clic en "Authorize" para autenticar todos los endpoints

Autenticación Global Autorízate con tu clave API

Opción 2: Autenticación de Endpoint Individual​

  1. Navega a cualquier endpoint que quieras probar
  2. Busca el ícono de candado junto al endpoint ubicado en el extremo derecho
  3. Haz clic en el ícono de candado para ese endpoint específico
  4. Ingresa tu clave API para autenticar solo ese endpoint

Autenticación de Endpoint Individual Ícono de candado de autenticación para endpoints individuales

Probando Endpoints​

Una vez autenticado, puedes probar cualquier endpoint siguiendo estos pasos:

Paso 1: Seleccionar un Endpoint​

Navega al endpoint que quieras probar desde la barra lateral de documentación o la página principal.

Paso 2: Pruébalo​

  1. Haz clic en el botón "Try it out" en el endpoint deseado
  2. Esto habilitará los campos de parámetros para edición

Botón Try It Out Ubicación del botón "Try it out" en las páginas de endpoints

Paso 3: Completar la Información Requerida​

  1. Revisa los parámetros requeridos para el endpoint
  2. Completa los campos requeridos con valores apropiados
  3. Opcionalmente completa parámetros opcionales según sea necesario para tu prueba

Paso 4: Ejecutar la Solicitud​

  1. Haz clic en el botón "Execute" para enviar la solicitud
  2. Ve la respuesta en la sección de respuesta de abajo
  3. Analiza los resultados incluyendo código de estado, cuerpo de respuesta y headers

Entendiendo las Respuestas​

La documentación interactiva te muestra:

Información de Respuesta​

  • Código de Estado: Código de estado HTTP (200, 404, 422, etc.)
  • Cuerpo de Respuesta: La respuesta JSON real de la API
  • Headers de Respuesta: Headers devueltos por la API
  • Detalles de Solicitud: La solicitud exacta que fue enviada

Ejemplos de Respuesta​

Cada endpoint incluye ejemplos de respuesta para diferentes escenarios:

  • Respuestas exitosas (códigos de estado 200)
  • Respuestas de error (códigos de estado 400, 404, 422, 500)
  • Diferentes formatos de respuesta basados en el endpoint

Ejemplos de Respuesta Formatos de respuesta de ejemplo mostrados en la documentación

Escenarios Comunes de Prueba​

Probando Endpoints GET​

  1. Auténticate usando tu método preferido
  2. Haz clic en "Try it out" en el endpoint GET
  3. Completa cualquier parámetro de ruta requerido (como candidate_id)
  4. Haz clic en "Execute" para recuperar datos

Probando Endpoints POST​

  1. Auténticate y haz clic en "Try it out"
  2. Completa parámetros requeridos y cuerpo de solicitud
  3. Para subidas de archivos, usa la interfaz de selección de archivos
  4. Haz clic en "Execute" para enviar datos

Probando con Parámetros de Consulta​

  1. Busca parámetros de consulta en la sección de parámetros
  2. Completa parámetros de consulta opcionales como page para paginación
  3. Ejecuta para ver cómo los parámetros afectan la respuesta

Usando la API Fuera de la Interfaz​

Al integrar la API en tus propias aplicaciones (fuera de esta interfaz OpenAPI), necesitarás incluir manualmente tu clave API en los headers de solicitud.

Headers Requeridos​

Cada solicitud API debe incluir estos headers:

X-API-Key: TU_CLAVE_API_AQUI
Content-Type: application/json

Ejemplo cURL​

curl -X GET "https://api.intelliscreen.io/candidates/" \
  -H "X-API-Key: TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json"

Ejemplo JavaScript​

const response = await fetch("https://api.intelliscreen.io/candidates/", {
  method: "GET",
  headers: {
    "X-API-Key": "TU_CLAVE_API_AQUI",
    "Content-Type": "application/json",
  },
});

const data = await response.json();

Ejemplo Python​

import requests

headers = {
    'X-API-Key': 'TU_CLAVE_API_AQUI',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.intelliscreen.io/candidates/', headers=headers)
data = response.json()

Importante: Reemplaza TU_CLAVE_API_AQUI con tu clave API real del panel de tu cuenta.

Consejos para Pruebas Efectivas​

Prueba de Parámetros​

  • Comienza con parámetros requeridos: Siempre completa primero los parámetros requeridos
  • Prueba casos límite: Intenta valores límite y casos extremos
  • Usa datos realistas: Usa correos electrónicos, nombres e IDs de candidatos realistas

Prueba de Errores​

  • Prueba datos inválidos: Intenta IDs inválidos o solicitudes mal formadas
  • Verifica permisos: Prueba endpoints a los que podrías no tener acceso
  • Verifica mensajes de error: Asegúrate de que las respuestas de error sean útiles

Validación de Respuesta​

  • Verifica códigos de estado: Verifica que obtienes los códigos de estado esperados
  • Valida estructura de respuesta: Asegúrate de que la respuesta coincida con el esquema
  • Prueba paginación: Para endpoints paginados, prueba diferentes números de página

Solución de Problemas Comunes​

Problemas de Autenticación​

  • Verifica tu clave API: Asegúrate de que esté copiada correctamente
  • Prueba ambos métodos de autenticación: Si la autenticación global falla, prueba la autenticación de endpoint individual
  • Verifica claves expiradas: Regenera tu clave API si es necesario

Problemas de Parámetros​

  • Requeridos vs opcionales: Asegúrate de que todos los parámetros requeridos estén completados
  • Tipos de datos: Coincide con los tipos de datos esperados (string, integer, etc.)
  • Validación de formato: Sigue cualquier formato especificado para parámetros

Problemas de Red​

  • Verifica tu conexión: Asegúrate de tener una conexión a internet estable
  • Prueba diferentes endpoints: Prueba si el problema es específico del endpoint
  • Limpia caché del navegador: A veces los datos en caché pueden causar problemas