Integraciones, API y transferencias a proveedores de Dashboard

Conecta cada flujo de operadores en la capa que le corresponde. Dashboard presenta controles y transporta el contexto autenticado del proyecto; la API de Ordering.co valida solicitudes y aplica sus efectos en los datos; los plugins y proveedores externos completan las operaciones que dependen de ellos. Mantén separadas estas responsabilidades al diseñar o resolver problemas de una integración.

Usa API Reference como contrato

Usa la API Reference canónica para consultar autenticación, métodos HTTP, rutas, parámetros, esquemas y comportamiento documentado de las respuestas. Empieza con el contrato público de autenticación y luego selecciona la operación responsable del recurso que necesitas.

No copies esquemas de endpoints del código fuente de Dashboard ni de ejemplos históricos para usarlos en una integración. El cliente muestra cómo se usan solicitudes, pero no define el contrato público; un checkout local tampoco demuestra qué código sirve un entorno determinado. API Reference publicada sigue siendo la fuente de autoridad para los contratos públicos del servidor.

Antes de hacer una solicitud autorizada, confirma el identificador del proyecto, el idioma, el entorno, el método de autenticación, la operación y el esquema de respuesta documentados para esa operación. Trata las claves de API y los datos bearer como secretos; nunca los guardes en archivos del repositorio, configuración visible en el navegador, URL, capturas de pantalla, tickets ni chats.

Matriz de transferencias

Límite	Responsabilidad de Dashboard	Responsabilidad de la API de Ordering.co	Responsabilidad del proveedor u operador
Sesión y proyecto	Recopilar los datos de inicio de sesión admitidos, mantener el estado de sesión mediante el cliente compartido y seleccionar el contexto de proyecto configurado.	Autenticar la solicitud, resolver el proyecto y autorizar cada recurso y acción.	El operador protege las credenciales e inicia sesión en el entorno previsto.
Configuración remota	Cargar y presentar valores admitidos y disponibilidad de funciones.	Devolver la configuración permitida para el proyecto y la persona solicitante.	La persona responsable del proyecto aprueba los valores y la configuración del proveedor.
Plugins y complementos	Detectar controles compatibles y dirigir al operador al flujo de configuración.	Devolver el estado de plugins y configuración, y aceptar cambios autorizados.	El plugin o proveedor define requisitos previos, credenciales, límites y aceptación final.
POS y canales de venta	Presentar integraciones aptas y el estado de conexión por negocio.	Autorizar el acceso al negocio y guardar los cambios admitidos de integración.	El proveedor controla el acceso a la cuenta, el catálogo, los pedidos y los fallos externos.
Servicios de entrega	Presentar servicios configurados y asignaciones a negocios.	Validar y guardar las relaciones de servicio admitidas.	El proveedor de entrega controla la cobertura, cotización, aceptación y ejecución de la entrega.
Pagos y Stripe Connect	Presentar superficies configuradas de estado y configuración sin gestionar directamente material secreto de pago.	Aplicar los requisitos del lado del servidor y guardar referencias o ajustes de cuenta admitidos.	Stripe o el proveedor de pago seleccionado controla la incorporación, verificación, autorización, liquidación y disputas.
Mapas, notificaciones, tiempo real, analítica y soporte	Inicializar el comportamiento del navegador solo cuando se cumplan las condiciones de configuración y sesión.	Autorizar las lecturas o escrituras relacionadas y devolver configuración del ámbito del proyecto.	El navegador, el sistema operativo o el proveedor controla el consentimiento, la entrega, la conectividad y el procesamiento.

Tareas habituales de API

Los ejemplos anteriores asociados a esta guía abarcan consultas de pedidos y negocios, búsquedas de catálogo, flujos de carrito y pedido, y actualizaciones de productos. Usa la operación correspondiente de API Reference actual para cada tarea; no reutilices rutas de endpoint, ID de proyecto ni cargas capturadas.

Consulta pedidos deliberadamente

Una consulta de pedidos puede filtrarse por campos como estado, intervalo de fechas o correo del cliente cuando la operación de API seleccionada documente esos filtros. Los datos de pedidos pueden incluir información del cliente, pagos, entrega y operaciones, así que solicita solo los campos y registros necesarios para el propósito aprobado.

Consulta negocios y contexto de catálogo

Usa la operación documentada de negocio para obtener solo los campos que necesita la integración. Los ejemplos históricos seleccionaban campos como ID externo, estado habilitado, slug, precio de entrega, tiempo de entrega, tiempo de recogida, reseñas y categorías; la compatibilidad de campos y la autorización pueden variar según la operación y el entorno.

Para categorías y productos, usa la operación de API Reference que documenta la relación admitida entre negocio, categoría y producto. No deduzcas un esquema de respuesta a partir de una captura de pantalla ni de un contenedor genérico.

Trata los pedidos y las actualizaciones como efectos

Crear un carrito, realizar un pedido, actualizar un precio y actualizar el inventario o la cantidad pueden provocar cambios de estado distintos. Usa la operación publicada en cada paso, valida el esquema de solicitud requerido, autoriza el flujo y vuelve a leer el recurso afectado solo cuando el flujo y el modelo de permisos lo permitan.

Los ejemplos del cliente de API pueden mostrar datos confidenciales. No uses credenciales, identificadores ni registros reales en ejemplos compartidos. Una respuesta de la interfaz no confirma que un cambio de pedido, carrito, precio o inventario se haya completado.

Reglas de configuración y plugins

• Considera el archivo de configuración del repositorio y cualquier anulación en tiempo de ejecución como entradas propias del entorno. No reemplaces parcialmente ajustes anidados de API o socket sin validar el resultado combinado completo.
• Mantén alineados la identidad del proyecto, la API base, la versión de API, el idioma, el límite de socket y los identificadores de la aplicación. Que una configuración sea sintácticamente válida no demuestra compatibilidad ni conectividad.
• Trata los indicadores de funciones, registros de plugins, estado de complementos y configuración del cliente solo como señales de disponibilidad. No otorgan permisos, demuestran derechos comerciales ni garantizan que el proveedor esté listo.
• Mantén los secretos del proveedor en un almacén de secretos del lado del servidor aprobado. Las variables expuestas al navegador y la configuración incluida en el paquete son públicas para quien pueda cargar la aplicación.
• No reconstruyas callbacks de OAuth, tokens de pago, firmas de proveedor ni credenciales de integración a partir del estado de la interfaz, URL, registros o capturas de pantalla.

Límites de permisos

Dashboard registra rutas protegidas para varios niveles técnicos de usuario y aplica comprobaciones adicionales de solo lectura en el cliente. Estas comprobaciones mejoran la navegación, pero no constituyen una taxonomía pública completa de roles ni deben ser la fuente de autorización de una integración.

Para cada solicitud:

1. Autentícate conforme al contrato de API publicado.
2. Envía la solicitud al proyecto y entorno previstos.
3. Deja que la API autorice a la persona, el recurso y la acción.
4. Trata las respuestas 401 y 403 como decisiones del servidor; no las eludas exponiendo una ruta oculta.
5. Después de una mutación autorizada, vuelve a leer el recurso afectado cuando el flujo requiera confirmación.

Nunca trates un parámetro de ruta, identificador de negocio o plugin ni callback de proveedor como token de capacidad. Reduce al mínimo los identificadores en los registros; nunca registres tokens bearer, claves de API, material de pago ni credenciales de proveedor.

Gestión de fallos

Observación	Límite responsable	Respuesta segura
El control no aparece	Configuración del cliente, función, plugin o compuerta de ruta	Confirma el proyecto previsto y la configuración aprobada. No fuerces la ruta.
Se abre la ruta, pero se deniegan los datos	Autorización de la API de Ordering.co	Conserva el resultado del servidor y verifica el ámbito actual de la persona y el recurso.
Ordering.co acepta los datos, pero falla el proveedor	Transferencia al proveedor	Mantén separados los resultados de Ordering.co y del proveedor; sigue el contrato de reintento o recuperación del proveedor.
Se detienen el tiempo real o las notificaciones mientras funcionan las lecturas de API	Socket, navegador, sistema operativo o proveedor de notificaciones	Diagnostica por separado la conexión, los permisos y el estado del proveedor, sin confundirlos con el acceso HTTP normal.
La configuración solo funciona en un entorno	Límite de configuración o despliegue	Compara claves de configuración saneadas y revisiones de origen; no copies secretos ni supongas que los entornos son equivalentes.

Relacionado: Guía de ingeniería de Dashboard · Documentación de producto de Dashboard