Prácticas recomendadas

Usa estos patrones para que las integraciones de socios sean predecibles, observables y seguras para las instalaciones.

Identifica las instalaciones de forma coherente

Elige el método de vinculación configurado para tu cuenta de socio y úsalo de forma coherente:

• Direct Link: usa el facility_id del Performance Hub que devuelve el endpoint de instalaciones.
• Linking Identifier: usa tu propio identificador de ubicación, como un ID de sucursal, un código de ubicación o un número de tienda.

No envíes ambos identificadores en la misma solicitud. El Performance Hub resuelve las solicitudes con el método de vinculación configurado para tu cuenta de socio.

Consulta Métodos de vinculación de socios para obtener instrucciones de configuración.

Escribe por lotes con cuidado

La Partner API acepta cuerpos de solicitud JSON y está diseñada para flujos de sincronización por lotes, donde así se documenta. Mantén los lotes acotados y reintentables.

Pautas predeterminadas:

• Usa hasta 1000 elementos por solicitud por lotes para un rendimiento óptimo.
• Mantén las cargas útiles por debajo de 10MB.
• No superes 5 solicitudes por segundo por endpoint.

Los límites de frecuencia se pueden ajustar y tu administrador de cuenta de socio del Performance Hub puede configurarlos caso por caso. Si prevés importaciones de gran volumen, tráfico de lanzamiento o cargas retroactivas de informes, acuerda el rendimiento necesario antes de la ventana de cambio.

Si necesitas sincronizar un conjunto de datos grande, divídelo en fragmentos deterministas y registra el ID de cada fragmento en tu sistema. Así es más fácil analizar los reintentos fallidos.

Reintenta de forma segura

Usa el retroceso exponencial para los errores transitorios, como 429, 500, 502, 503 y 504.

Evita los bucles de reintento rápidos. Un buen punto de partida es:

1. Reintentar después de 1 segundo.
2. Reintentar después de 2 segundos.
3. Reintentar después de 4 segundos.
4. Detenerse y emitir una alerta si la operación sigue fallando.

En los errores de validación, como 400 o 422, corrige la solicitud antes de reintentar.

Usa la idempotencia donde se admita

El endpoint de desbloqueo del controlador de puertas y portones admite una idempotency_key opcional. Si reutilizas la misma clave para el mismo socio, la misma instalación y la misma puerta, se devuelve el resultado existente cuando hay uno disponible.

Usa una clave estable para la acción que se realiza, por ejemplo, un ID de registro de entrada o un ID de evento de acceso de tu sistema.

No supongas que todos los endpoints de escritura admiten la idempotencia, a menos que esté documentado para ese endpoint.

Mantén limpios los datos de origen

Envía valores estables y normalizados siempre que sea posible:

• Usa ID coherentes de miembros, planes, instalaciones y registros de entrada de tu sistema de origen.
• Usa marcas de tiempo ISO 8601 para las fechas y horas.
• Envía los números de teléfono en formato internacional, si están disponibles.
• Envía las monedas con los campos documentados para cada endpoint.
• Evita sobrecargar los campos de texto libre con datos que corresponden a campos estructurados.

Diseña para sincronizaciones incrementales y completas

La mayoría de las integraciones de socios necesitan ambas:

• Sincronizaciones incrementales para los cambios del día a día.
• Sincronizaciones completas de conciliación para corregir eventos perdidos, importaciones históricas o desviaciones de datos.

Tu integración debe poder reenviar el estado actual de un miembro, un plan de membresía o una instantánea de informe sin depender de que una solicitud anterior se haya completado correctamente.

Publica las Access Time Windows de forma segura

Trata el valor access_time_windows de cada miembro como una instantánea completa con revisiones independientes:

• Coordina una única secuencia de access_time_windows_revision monótonamente creciente entre los procesos incrementales y los de conciliación.
• Reintenta una entrega incierta o transitoria con la misma revisión y la misma carga útil normalizada.
• Omite access_time_windows cuando no lo estés actualizando.
• Envía [] solo después de que una consulta correcta a la fuente autorizada demuestre que no queda ninguna ventana. Nunca conviertas un tiempo de espera agotado, un resultado parcial o un error de análisis de la fuente en una revocación.
• Mantén estables external_id y scope_key, y certifica cada asignación de ámbito antes de pasar a producción.
• Supervisa la antigüedad de la fuente con respecto a la política de actualización acordada para esa integración.

Consulta la guía oficial para productores de Access Time Windows para conocer las instantáneas completas, las zonas horarias, el horario de verano, la cancelación y los vectores de prueba.

Trata el control de acceso como algo crítico para la seguridad

En los desbloqueos de controladores de puertas y portones:

• Tu sistema debe decidir si la persona puede entrar antes de llamar al Performance Hub.
• El Performance Hub devuelve 200 solo después de que el controlador del sitio confirma que el relé se desbloqueó físicamente.
• La mayoría de las confirmaciones se completan en 3-5 segundos.
• Un tiempo de espera agotado es un desbloqueo fallido explícito, no un éxito en segundo plano.
• Reintenta solo según tus propias reglas de acceso y seguridad.

Registra siempre el event_id y el command_id que devuelve el endpoint de desbloqueo.

Supervisa tu integración

Usa los registros de solicitudes de la Partner Console durante el desarrollo y el lanzamiento. En producción, mantén también tus propios registros con:

• Marca de tiempo de la solicitud.
• Endpoint.
• ID del registro de origen.
• Identificador de instalación.
• Código de estado HTTP.
• Cuerpo de la respuesta o mensaje de error del Performance Hub.

Estos campos agilizan mucho el soporte y la conciliación cuando un cliente pregunta qué ocurrió.