Llamadas a la API de partner - Rhombus Developer Documentation

Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, contáctenos.

Descripción general

Si eres un partner de Rhombus —un proveedor de servicios gestionados (MSP) o un revendedor que opera muchas organizaciones de clientes bajo una sola cuenta de partner—, tu clave de API funciona de forma distinta a la de una organización estándar. Una única clave de partner te permite:

Gestionar tu conjunto de organizaciones cliente con endpoints de partner (/api/partner/...): listar clientes, registrar hardware, consultar licencias y emitir tokens de API.
Acceder a cualquiera de esos clientes y llamar a endpoints a nivel de cliente (cámaras, control de acceso, sensores, usuarios — el resto de la API) como ese cliente, indicando la organización de destino en un solo encabezado de la solicitud.

Esta guía explica los dos tipos de llamadas, el esquema de autenticación de partner y el encabezado x-auth-org que los une, de modo que un único conjunto de credenciales pueda operar en todas las organizaciones que gestionas.

Lo que esta guía no es. Aquí se explica cómo hacer llamadas a la API REST con una clave de API de partner existente. Si necesitas obtener credenciales de partner —el flujo de inicio de sesión OAuth por navegador, detectar isPartner o generar claves de partner de larga duración—, consulta Iniciar sesión con Rhombus, que documenta la ruta OAuth de partner y la generación de claves. Esta guía continúa una vez que ya tienes una clave de partner.

Antes de empezar

Para seguir esta guía necesitas:

Una clave de API de partner (x-auth-apikey) emitida para tu cuenta de partner. Consulta Iniciar sesión con Rhombus → Trabajar con cuentas de partner para saber cómo se generan las claves de partner.
El UUID de la organización cliente sobre la que quieras actuar. No necesitas conocerlo de antemano: la primera llamada de abajo lo devuelve.
Familiaridad con los encabezados de autenticación estándar (x-auth-scheme + x-auth-apikey) que se usan en el resto de la API.

Las URL base son las mismas que para cualquier otra llamada a la API de Rhombus; no hay un host de partner aparte:

URL base	Propósito
`https://api2.rhombussystems.com`	Todos los endpoints de la API, de partner y a nivel de cliente
`https://media.rhombussystems.com`	Medios y streaming (clips, transmisiones en vivo, miniaturas)

Dos tipos de llamadas

Cada solicitud que haces como partner es de uno de dos tipos. La diferencia está en la ruta del endpoint, y en si diriges la llamada a un cliente específico.

	Endpoints de partner	Endpoints a nivel de cliente
Prefijo de ruta	`/api/partner/...`	Todo lo demás (`/api/camera/...`, `/api/accesscontrol/...`, `/api/org/...`, …)
Qué hacen	Gestionar tu cartera de clientes: listar organizaciones, registrar dispositivos, consultar licencias, emitir tokens	Operar dentro de una organización: cámaras, puertas, sensores, usuarios, eventos
Quién puede llamarlos	Solo cuentas de partner	Cualquier cuenta; un partner apunta a un cliente concreto
Esquema de auth	`partner-api-token`	`partner-api-token`
Encabezado `x-auth-org`	No se usa (se ignora)	Obligatorio: indica la organización cliente como la que actuar

La idea clave: los endpoints de partner operan a nivel de partner; los endpoints a nivel de cliente operan dentro de una organización. Un partner accede a un cliente añadiendo el encabezado x-auth-org —explicado más abajo—. No existen “versiones de partner” de los endpoints de cliente; llamas al mismo endpoint /api/camera/... que usaría un cliente, solo que con credenciales de partner y el encabezado x-auth-org.

Autenticarse como partner

Las llamadas de partner usan los mismos dos encabezados que las estándar, con una diferencia: el valor del esquema:

Encabezado	Valor
`x-auth-scheme`	`partner-api-token`
`x-auth-apikey`	Tu clave de API de partner
`Content-Type`	`application/json`

-H "x-auth-scheme: partner-api-token" \
-H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
-H "Content-Type: application/json"

Autenticación por token vs. por certificado. Los partners que usan credenciales de TLS mutuo (basadas en certificado) en lugar de un token usan x-auth-scheme: partner-api con su certificado de cliente. El esquema partner-api-token que se muestra en esta guía es la opción más sencilla, basada en token, y es la recomendada para la mayoría de las integraciones. La autenticación por certificado no es compatible con las conexiones WebSocket.

Trata la clave de API de partner como una llave maestra. Puede alcanzar a todas las organizaciones que gestionas. Guárdala cifrada, nunca la subas al control de versiones y rota o revoca las claves que no uses. Una clave de partner filtrada expone a todos tus clientes, no solo a uno.

Dirigir una llamada a una organización cliente

Para hacer una llamada a nivel de cliente en nombre de un cliente gestionado, añade el encabezado x-auth-org con el UUID de la organización de ese cliente:

Encabezado	Valor
`x-auth-org`	El UUID de la organización cliente de destino (base64 url-safe, ~22 caracteres, p. ej. `AAAAAAAAAAAAAAAAAAAAAA`)

Con este encabezado presente, Rhombus trata la solicitud como si proviniera de dentro de esa organización cliente. El servidor verifica que tu cuenta de partner realmente gestiona la organización de destino antes de atender la llamada; si no es así, la solicitud se rechaza.

x-auth-org no aparece en la especificación OpenAPI. La Referencia de la API autogenerada documenta el cuerpo de cada endpoint y el parámetro x-auth-scheme, pero todavía no describe x-auth-org. El encabezado es totalmente compatible de todas formas: es el mecanismo estándar que usa la CLI de Rhombus para su opción --partner-org y el que usa la API de WebSocket para las conexiones de partner. Añádelo tú mismo en las llamadas a nivel de cliente; no esperes que el panel de “Probar” lo muestre.

Omite x-auth-org en los endpoints /api/partner/...: los endpoints de partner ya operan a nivel de partner y lo ignoran.

Ejemplos

Paso 1: Lista tus organizaciones cliente

Empieza con un endpoint de partner para descubrir las organizaciones que gestionas y sus UUID. POST /api/partner/getClientsV2 devuelve registros de cliente ligeros (nombre + UUID + conteo de dispositivos), ideal para resolver rápidamente el UUID de un cliente antes de actuar sobre él.

curl -X POST https://api2.rhombussystems.com/api/partner/getClientsV2 \
  -H "x-auth-scheme: partner-api-token" \
  -H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Una respuesta lista cada cliente gestionado, incluido el clientOrgUuid que pasarás como x-auth-org:

{
  "clients": [
    {
      "clientOrgName": "Acme Corporation",
      "clientOrgUuid": "aB_cD1eF2gH3iJ4kL5mN",
      "totalCameras": 25,
      "totalLocations": 3
    },
    {
      "clientOrgName": "Beta Industries",
      "clientOrgUuid": "nO_pQ6rS7tU8vW9xY0zZ",
      "totalCameras": 12,
      "totalLocations": 1
    }
  ]
}

Paso 2: Llama a un endpoint a nivel de cliente como un cliente gestionado

Ahora usa un UUID de cliente del Paso 1 en el encabezado x-auth-org para llamar a un endpoint normal a nivel de cliente; aquí, listando las cámaras de un cliente con POST /api/camera/getMinimalCameraStateList. Ten en cuenta que no es un endpoint de partner; es el mismo endpoint de cámaras que usa cualquier organización, dirigido a tu cliente mediante el encabezado.

curl -X POST https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList \
  -H "x-auth-scheme: partner-api-token" \
  -H "x-auth-apikey: YOUR_PARTNER_API_KEY" \
  -H "x-auth-org: aB_cD1eF2gH3iJ4kL5mN" \
  -H "Content-Type: application/json" \
  -d '{}'

Si quitas el encabezado x-auth-org, la misma llamada apuntaría a tu organización de partner en lugar de al cliente, que normalmente no tiene cámaras propias. El encabezado es lo que redirige la llamada hacia el cliente gestionado.

La CLI lo hace por ti

La CLI de Rhombus envuelve el mismo mecanismo tras una opción --partner-org, que acepta un UUID o un nombre de cliente y establece x-auth-org por ti:

# Por UUID
rhombus --partner-org aB_cD1eF2gH3iJ4kL5mN camera get-minimal-camera-state-list

# Por nombre de cliente (la CLI lo resuelve a un UUID con getClientsV2)
rhombus --partner-org "Acme Corporation" camera get-minimal-camera-state-list

Conexiones WebSocket

Las conexiones de partner en tiempo real usan el mismo esquema y organización de destino, pero los pasan como parámetros de consulta en lugar de encabezados. Consulta Autenticación de WebSocket para ver el patrón completo:

wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=partner-api-token&x-auth-org=aB_cD1eF2gH3iJ4kL5mN

Referencia de endpoints de partner

Estos endpoints /api/partner/... operan a nivel de partner y requieren una clave de partner. Todos son POST. Consulta los esquemas completos de solicitud/respuesta en la Referencia de la API.

Propósito	Endpoint	Qué hace
Clientes	`getClients`	Lista todas las organizaciones cliente (info completa)
	`getClientsV2`	Lista clientes con info básica — la forma más rápida de resolver UUID de cliente
	`getClientSummaryInfo`	Resumen de un solo cliente
	`getClientStatusMap`	Estado agregado de dispositivos y ubicaciones de todos los clientes
	`createPartnerClient`	Crea una nueva organización cliente
	`customizeClient`	Personaliza una cuenta de cliente
	`deleteClient`	Elimina una organización cliente
Dispositivos	`getClientDevices`	Dispositivos de un cliente específico
	`getListOfAllClientDevices`	Dispositivos de todos los clientes gestionados
	`getListOfAvailableHardware`	Hardware disponible para registro
	`getClaimKeysForPartnerOrg`	Claves de reclamación de la organización de partner
	`registerCameraToClient`	Registra una cámara en una organización cliente
	`reassignDeviceOrg`	Mueve un dispositivo de una organización cliente a otra
	`customizeClientDevice`	Personaliza un dispositivo de cliente
Licencias	`getLicensesForOrg`	Licencias disponibles para una organización cliente
	`getDeviceLicensesForOrg`	Licencias por dispositivo para una organización cliente
	`updateSendLicenseExpirationEmail`	Activa/desactiva las alertas por correo de vencimiento de licencia
Tokens de API	`getApiTokens`	Lista los tokens de API activos del partner
	`getApiTokenApplications`	Lista las solicitudes de token pendientes
	`revokeApiToken`	Revoca un token de API de partner
Ventas	`registerDeal`	Registra una oportunidad de venta
	`getShipments`	Envíos de un cliente específico

Las claves de API de partner se generan con POST /api/partner/submitApiTokenApplication. Ese endpoint de generación no forma parte de la especificación pública OpenAPI, por lo que no aparecerá en la Referencia de la API; consulta Iniciar sesión con Rhombus → Trabajar con cuentas de partner para saber cómo obtener claves de partner.

Solución de problemas

401 Unauthorized en un endpoint a nivel de cliente

Confirma que tu esquema sea partner-api-token (no api-token) y que x-auth-apikey sea tu clave de partner. Una clave de organización estándar no puede alcanzar otras organizaciones, sin importar qué x-auth-org envíes.

403 Forbidden, o la llamada apunta a la organización equivocada

El valor de x-auth-org debe ser un cliente que tu cuenta de partner realmente gestione. Vuelve a obtener la lista con getClientsV2 y copia el clientOrgUuid exacto: son UUID base64 url-safe (~22 caracteres), así que un valor truncado o recodificado será rechazado o resolverá a la organización equivocada.

Respuesta vacía o inesperada en un endpoint de cliente

Si olvidaste x-auth-org, la llamada se ejecutó contra tu organización de partner (que normalmente no tiene cámaras, puertas ni sensores) y devolvió una lista vacía. Añade el encabezado para dirigir la llamada al cliente.

x-auth-org parece ignorarse en un endpoint /api/partner/

Es lo esperado. Los endpoints de partner operan a nivel de partner e ignoran x-auth-org. Usa el cuerpo de la solicitud del propio endpoint (por ejemplo, el campo orgUuid en registerCameraToClient) para indicar a qué cliente se aplica la acción.

La autenticación de partner falla por WebSocket

Las conexiones WebSocket no admiten la autenticación por certificado (partner-api): genera una clave basada en token y usa partner-api-token. Recuerda también que en WebSocket x-auth-scheme y x-auth-org son parámetros de consulta, no encabezados. Consulta Autenticación de WebSocket.

Próximos pasos

Iniciar sesión con Rhombus

Obtén credenciales de partner y genera claves de partner de larga duración

Autenticación de WebSocket

Abre conexiones de partner en tiempo real dirigidas a una organización cliente

CLI de Rhombus

Usa —partner-org para ejecutar cualquier comando contra un cliente gestionado

Referencia de la API

Explora todos los endpoints de partner y a nivel de cliente

​Descripción general

​Antes de empezar

​Dos tipos de llamadas

​Autenticarse como partner

​Dirigir una llamada a una organización cliente

​Ejemplos

​Paso 1: Lista tus organizaciones cliente

​Paso 2: Llama a un endpoint a nivel de cliente como un cliente gestionado

​La CLI lo hace por ti

​Conexiones WebSocket

​Referencia de endpoints de partner

​Solución de problemas

​Próximos pasos

Iniciar sesión con Rhombus

Autenticación de WebSocket

CLI de Rhombus

Referencia de la API

Descripción general

Antes de empezar

Dos tipos de llamadas

Autenticarse como partner

Dirigir una llamada a una organización cliente

Ejemplos

Paso 1: Lista tus organizaciones cliente

Paso 2: Llama a un endpoint a nivel de cliente como un cliente gestionado

La CLI lo hace por ti

Conexiones WebSocket

Referencia de endpoints de partner

Solución de problemas

Próximos pasos