Documentación · Guía de integración

Credenciales de la API externa

Este documento explica cómo manejar de forma segura las credenciales de la API externa utilizadas por el plugin ADP Car Market Hub. Cubre de dónde provienen normalmente las credenciales, qué no debe publicarse nunca, cómo coordinar los valores con los proveedores que las emiten y cómo compartir información para soporte sin exponer secretos.

Está escrito para cualquier administrador, integrador o socio que maneje valores de credenciales en nombre de un concesionario.

Cuándo usar este documento

Use este documento cuando esté:

Recibiendo credenciales de un proveedor por primera vez y necesite saber cómo almacenarlas y transmitirlas de forma segura.
Coordinando la rotación de credenciales entre el concesionario, el proveedor de la API y el sitio de WordPress.
Preparando una solicitud de soporte, una captura de pantalla o una exportación y necesite saber qué censurar.
Auditando cómo se almacenan las credenciales en una instalación de WordPress.

Descripción general

El plugin puede almacenar credenciales para varias integraciones independientes. El conjunto exacto depende de qué características estén activadas, pero los ejemplos típicos incluyen:

API de AutoScout24 – el Client ID de OAuth, el Client Secret y el/los Seller ID(s) utilizados por el importador. Consulte Configuración de la API de AutoScout24.
AI Assistant – utiliza la configuración gestionada de Google Gemini en ADP Car Market Hub. La clave de API de Gemini gestionada es provista por AD Promotion en AS24CI\Ai_Config después de la instalación; no es necesario introducir ningún proveedor de IA, modelo o clave de API en el backend de WordPress, y no se almacena ninguna clave de IA como opción de WordPress.
Token de cron – un token generado aleatoriamente que se utiliza para autenticar el endpoint REST de cron del plugin cuando un cron de servidor externo activa las importaciones. Consulte Configuración del cron del servidor.
Secreto de webhook – un secreto compartido que se utiliza para firmar las cargas útiles de los webhooks salientes con HMAC-SHA256. Consulte Integración de webhooks.

Todos estos valores se almacenan como opciones de WordPress en el sitio que ejecuta el plugin. Nunca se incluyen con el propio plugin y siempre deben ser proporcionados por el cliente o por su socio de integración.

De dónde provienen normalmente los valores

Credencial	Emitida por	Notas
Client ID / Client Secret de AutoScout24	AutoScout24 o el socio de integración que provee el acceso a la API para el concesionario.	AD Promotion no emite estos datos. El inicio de sesión del sitio web del concesionario no es una credencial de API.
Seller ID(s) de AutoScout24	AutoScout24 o el socio de integración.	El Seller ID es un identificador de cuenta estable, no el nombre visible del concesionario.
URL base de la API	AutoScout24 o el socio de integración.	Determina con qué entorno se comunica el plugin. No hay un host codificado de forma fija dentro del plugin.
AI Assistant (Gemini gestionado)	Provisto por AD Promotion como parte de la configuración de IA gestionada.	Se almacena como una constante de PHP en `AS24CI\Ai_Config`, no en `wp_options`, y nunca se expone en el backend de WordPress. El cliente no introduce ningún proveedor de IA, modelo ni clave de API.
Token de cron	Generado automáticamente por el plugin y visible en la pestaña Importación y límites.	Cualquiera que conozca el token puede activar una importación. Trátelo como un secreto.
Secreto de webhook	Definido por el concesionario o el operador del sistema receptor; se copia en el plugin y en el receptor.	Opcional. Sin él, no se generan las firmas de las cargas útiles.

Si un valor es desconocido, no lo invente. Solicítelo a la parte propietaria del sistema correspondiente.

Lo que no debe publicarse

Los siguientes valores nunca deben aparecer en ninguna ubicación pública (repositorios públicos de Git, comentarios públicos en tickets, capturas de pantalla incrustadas en material de marketing, publicaciones de blog, asistentes de IA sin garantías de confidencialidad, canales de chat públicos o documentos compartidos accesibles fuera del concesionario o la agencia):

El Client Secret de AutoScout24 y cualquier otro secreto de OAuth.
El token de cron del plugin (cualquiera con el token puede activar importaciones).
El secreto de webhook.
URLs de solicitud completas que ya incluyan un parámetro de consulta ?token=....
Copias de seguridad de la base de datos, exportaciones de wp_options o exportaciones de diagnóstico completas del plugin sin censura previa.
Nombres de host internos, endpoints privados o URLs no públicas que formen parte de la integración.
Datos personales de leads, personal del concesionario o clientes.

El Client ID de AutoScout24, el Seller ID y la URL base de la API no son técnicamente secretos en el mismo sentido que un Client Secret, pero identifican la cuenta del concesionario y, aun así, deben tratarse como confidenciales y compartirse únicamente con personas que legítimamente los necesiten.

Reglas de manejo seguro

Use un canal seguro. Reciba y envíe credenciales a través de un gestor de contraseñas, un mensaje cifrado de extremo a extremo o una herramienta segura de transferencia de archivos. El correo electrónico normal y el chat sin cifrar no son aceptables.
Limite quién los conoce. Solo las personas que realmente configuran u operan la integración necesitan los valores. Retire el acceso cuando las personas dejen el proyecto.
Mantenga una copia maestra fuera de WordPress. El gestor de contraseñas central del concesionario es la fuente de verdad. La instalación de WordPress es solo un consumidor de las credenciales.
Rote después de una exposición. Si una credencial se filtra, solicite una rotación a la parte emisora de inmediato, luego actualice el valor en el plugin y vuelva a ejecutar la Prueba de conexión. Para el token de cron, regenérelo desde la pestaña Importación y límites. Para el secreto de webhook, cámbielo tanto en el plugin como en el sistema receptor.
Rote cuando cambie el acceso. Cuando una persona que manejaba credenciales ya no necesite acceso (por ejemplo, un empleado deja el concesionario o la agencia), rote las credenciales afectadas. Eliminar su cuenta de WordPress no invalida los valores que haya podido copiar anteriormente.
No guarde credenciales en el control de versiones. Nunca suba credenciales a Git, a un tema, a un mu-plugin o a cualquier otro archivo que termine en el control de código fuente.
Tenga en cuenta el tipo de campo. El plugin muestra el Client Secret de AutoScout24 como un campo de entrada de contraseña que intencionadamente no se rellena previamente con el valor existente cuando se vuelve a cargar la página. Vuelva a introducir el valor solo cuando realmente desee cambiarlo. El token de cron también se muestra con un control de Mostrar / Ocultar; déjelo oculto al compartir capturas de pantalla.

Coordinación de credenciales con proveedores de integración

Para cualquier integración, siga este patrón de coordinación:

Solicite el acceso a través del concesionario. El concesionario es el titular de la cuenta. El aprovisionamiento normalmente requiere una solicitud del concesionario, incluso cuando una agencia o socio se encarga del trabajo técnico.
Acuerden el entorno. Confirme con el proveedor para qué URL base de la API son válidas las credenciales. Mezclar valores de diferentes entornos es la causa más común de fallos de autenticación.
Confirme el alcance de la autorización. Para AutoScout24, confirme que el par Client ID / Client Secret está autorizado para cada Seller ID que deba importarse. Los concesionarios con múltiples vendedores a menudo requieren una autorización explícita por vendedor.
Reciba los valores de forma segura. Consulte las Reglas de manejo seguro anteriores.
Configure y pruebe en el sitio de WordPress. Utilice la Configuración de Credenciales de la API y la Prueba de conexión antes de activar las importaciones automáticas.
Documente quién es el propietario de cada elemento. Registre, en la documentación interna del concesionario, quién es el contacto en el proveedor de la API, quién emitió los valores y cuándo, y dónde se almacena la copia maestra de las credenciales.
Planifique la rotación. Acuerde un proceso para rotar las credenciales, tanto de forma periódica como bajo demanda (después de una filtración, tras cambios de personal, después de un incidente grave).

Para el AI Assistant, la configuración gestionada de Google Gemini en AS24CI\Ai_Config es la fuente de verdad. El cliente no configura, almacena ni rota una clave de API del proveedor de IA en el backend de WordPress; AD Promotion se encarga del aprovisionamiento gestionado de Gemini.

Compartir información para soporte sin filtrar secretos

Cuando necesite compartir información de configuración o de registro con AD Promotion o con otro contacto de soporte:

Utilice la información de soporte descrita en la Lista de comprobación de información de soporte.
Censure los secretos antes de compartirlos. Como mínimo, reemplace el Client Secret de AutoScout24, el token de cron y el secreto de webhook por [REDACTED].
Para las URLs que incluyan un parámetro de consulta ?token=..., reemplace el token por [REDACTED] antes de pegar la URL en un ticket.
Recorte o difumine las secciones relevantes de cualquier captura de pantalla que pudiera revelar secretos.
El directorio de logs del plugin en wp-content/uploads/as24ci-logs/ no escribe el Client Secret en texto plano, pero puede incluir URLs y metadatos de las solicitudes. Trate el directorio de logs como confidencial y revise los extractos antes de compartirlos.

Almacenamiento en el sitio de WordPress

Credenciales se almacenan como opciones estándar de WordPress. Pueden ser leídas por cualquier código con acceso a la base de datos en el mismo sitio (otros plugins, temas, mu-plugins, procesos a nivel de servidor).
Por lo tanto, las copias de seguridad de la base de datos, las exportaciones de wp_options y las instantáneas completas del servidor contienen las credenciales. Aplique las mismas protecciones que para cualquier otra copia de seguridad que contenga secretos.
El plugin no transmite credenciales a AD Promotion ni a ningún tercero que no sea el proveedor de la API al que están destinadas las credenciales. Las credenciales de AutoScout24 se envían únicamente a la URL base de la API configurada. Las solicitudes de IA van al endpoint gestionado de Google Gemini configurado por AD Promotion en AS24CI\Ai_Config.
Para obtener detalles sobre lo que el plugin almacena en la base de datos, consulte la Descripción general del almacenamiento de datos y la Referencia de base de datos y almacenamiento.

Notas operativas

Credenciales por entorno. Utilice credenciales distintas por entorno (producción, staging, local). No apunte un sitio de staging de WordPress a credenciales de producción de AutoScout24 a menos que lo haya acordado explícitamente con el concesionario; de lo contrario, la actividad de staging puede alterar las analíticas, activar correos de leads o generar llamadas de webhook no deseadas.
Migración entre entornos. Cuando copie una base de datos de producción a staging (o viceversa), revise cada campo de credencial en el sitio de destino. Consulte la Migración de Staging a Live.
Desinstalación. Cuando se desinstala el plugin con la opción Eliminar datos al desinstalar activada, las opciones almacenadas (incluidas las credenciales) se eliminan de la base de datos. Si la opción está desactivada, las credenciales permanecen en la base de datos después de la desinstalación. Consulte el Comportamiento de desinstalación y limpieza.
Verifique el comportamiento en la versión actual. Las etiquetas específicas de la interfaz de usuario, los valores predeterminados y las claves de almacenamiento exactas pueden cambiar entre versiones. Verifique este comportamiento en la versión actual del plugin antes de publicar instrucciones dirigidas al cliente.

Resolución de problemas

Síntoma	Causa probable	Qué comprobar
La autenticación falla inmediatamente después de un cambio de credenciales.	Un token de acceso preexistente todavía está almacenado en caché.	Limpie la caché de tokens desde Car Market Hub → Herramientas y vuelva a ejecutar la Prueba de conexión.
La autenticación falla aunque los valores "parecen correctos".	Espacios en blanco invisibles, comillas tipográficas o un carácter intercambiado (`0` frente a `O`, `1` frente a `l`).	Pegue cada valor en un editor de texto plano primero, elimine los espacios en blanco de los extremos y luego péguelo en el campo.
El plugin informa de que no hay credenciales configuradas.	Se introdujeron los valores pero no se envió el formulario, o un plugin de seguridad eliminó la solicitud.	Vuelva a abrir la pestaña de ajustes correspondiente y confirme que los valores se han guardado. Desactive temporalmente los plugins de seguridad si interfieren con el envío de formularios de administración.
El endpoint de cron devuelve un error 403.	El token de cron en la URL no coincide con el token almacenado, o el token ha sido regenerado.	Copie la URL del activador REST actual desde la pestaña Importación y límites en la tarea cron de su servidor. Consulte Configuración de Cron del Servidor.
El receptor de webhooks rechaza los payloads con una firma no válida.	El secreto del webhook en el plugin y en el receptor ya no coinciden.	Vuelva a copiar el secreto en ambos extremos y reenvíe un evento de prueba. Consulte Integración de Webhooks.
Una credencial parece haberse filtrado en un registro o en un ticket.	La ocultación de datos fue incompleta.	Rote la credencial inmediatamente con la parte emisora, luego actualice el plugin y vuelva a probar.