API Gateway Resumen

El esCHAMPREPAPI Gateway el punto de entrada público para las integraciones de plataformas compatibles. Valida las credenciales, comprueba los ámbitos y el acceso al servicio, aplica los controles de uso vigentes y redirige las solicitudes aceptadas al CHAMPREPservicio correspondiente.

URL base

https://api.champrep.com/v1

Las rutas públicas seleccionadas se versionan en /v1. Utilice la URL HTTPS completa en las aplicaciones de servidor y utilice la configuración del entorno en lugar de dispersar la URL base por todo el código.

Primera solicitud autenticada

Cree una clave con ámbito en API Claves, y a continuación pásela como una credencial de portador:

curl --fail-with-body \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Accept: application/json" \
  https://api.champrep.com/v1/auth/whoami

Nunca incluya una clave real en el control de código fuente, en un paquete de navegador, en un binario móvil, en un mensaje de asistencia técnica ni en la documentación. Utilice un gestor de secretos del lado del servidor para las integraciones implementadas.

Convenciones de solicitud

• Envíe y acepte JSON, salvo que un punto final describa explícitamente otro tipo de medio.
• Utilice marcas de tiempo ISO 8601 con una zona horaria explícita para los valores de fecha y hora.
• Codifique mediante URL los valores de la ruta y de la consulta.
• Mantenga la credencial «bearer» en el Authorization encabezado.
• Trate los identificadores como cadenas opacas; no deduzca su formato ni los construya localmente.
• Utilice las rutas seleccionadas /v1 las rutas en el Referencia de puntos finales del servicio.

Official SDKspuede utilizar rutas compatibles con Gateway mientras un servicio se está migrando a una versión seleccionada /v1 . Esa capa de compatibilidad está destinada aSDK; las nuevas integraciones directas no deben copiar rutas privadas del backend procedentes del tráfico del navegador o de componentes internosSDK.

Sobres de respuesta

Las respuestas generadas con éxito por la pasarela tienen este formato:

{
  "success": true,
  "data": {}
}

Los errores de la pasarela adoptan esta forma:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A safe explanation of the error.",
    "status": 400
  }
}

Algunas respuestas de servicios con proxy conservan su envoltura de datos específica del servicio. Compruebe siempre primero el estado HTTP y, a continuación, lea success, data, o error cuando esté disponible. Consulte errores, límites y reintentos para una gestión de errores portátil.

Flujo de autenticación y autorización

Cada solicitud de servicio se evalúa en el siguiente orden:

1. La pasarela valida la claveAPI y cualquier restricción de IP configurada.
2. Se ha marcado la ventana de uso actual de Gateway.
3. API Gateway se comprueba en función del plan y el perfil activos.
4. Se ha comprobado el acceso al servicio de destino.
5. El ámbito de la clave se compara con la ruta y el método HTTP.
6. El servicio de destino aplica sus propias comprobaciones de rol, organización, recurso y cuota.

A 403 puede indicar, por lo tanto, que la clave es válida, pero que el ámbito activo, el rol, el acceso al servicio, el plan, la política de la organización o el permiso de acceso a los recursos no permiten la operación.

Control de versiones

El primer segmento de la URL corresponde a la versiónAPI principal. Dentro de una misma versión principal pueden aparecer campos de respuesta adicionales y nuevos puntos finales. Las integraciones deben ignorar los campos desconocidos y no deben basarse en campos no documentados ni en su orden de aparición.

Utilice GET /v1/version para obtener información sobre la versión pública de Gateway. Planifique las migraciones a una futura versión principal de forma explícita, en lugar de reescribir /v1 en tiempo de ejecución.

Próximos pasos

• Cree una clave con privilegios mínimos.
• Elija una ruta de servicio.
• Gestione los límites y los errores.
• Utilice webhooks en lugar de consultas frecuentes.
• ¿Prefiere los flujos de trabajo en terminal? Instale el CHAMPREPCLI.