> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.
# Llamadas a la API de partner
> Realiza llamadas a la API de Rhombus como partner: autentícate con una clave de API de partner, gestiona tus organizaciones cliente con endpoints de partner y dirige las llamadas a nivel de cliente a una organización gestionada con el encabezado x-auth-org.
Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, [contáctenos](mailto:support@rhombus.com).
## 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](/es/oauth-authentication), 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](/es/oauth-authentication) 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](/api-reference/overview#authentication) (`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` |
```bash theme={null}
-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](/api-reference/overview) 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](/es/rhombus-cli) para su opción `--partner-org` y el que usa la [API de WebSocket](/es/websocket/authentication) 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.
```bash cURL theme={null}
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 '{}'
```
```python Python theme={null}
import requests
BASE_URL = "https://api2.rhombussystems.com"
headers = {
"x-auth-scheme": "partner-api-token",
"x-auth-apikey": "YOUR_PARTNER_API_KEY",
"Content-Type": "application/json",
}
resp = requests.post(f"{BASE_URL}/api/partner/getClientsV2", headers=headers, json={})
resp.raise_for_status()
for client in resp.json().get("clients", []):
print(client["clientOrgName"], "->", client["clientOrgUuid"])
```
```javascript JavaScript theme={null}
const BASE_URL = "https://api2.rhombussystems.com";
const headers = {
"x-auth-scheme": "partner-api-token",
"x-auth-apikey": "YOUR_PARTNER_API_KEY",
"Content-Type": "application/json",
};
const resp = await fetch(`${BASE_URL}/api/partner/getClientsV2`, {
method: "POST",
headers,
body: JSON.stringify({}),
});
const data = await resp.json();
for (const client of data.clients ?? []) {
console.log(`${client.clientOrgName} -> ${client.clientOrgUuid}`);
}
```
```go Go theme={null}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST",
"https://api2.rhombussystems.com/api/partner/getClientsV2",
bytes.NewBufferString("{}"))
req.Header.Set("x-auth-scheme", "partner-api-token")
req.Header.Set("x-auth-apikey", "YOUR_PARTNER_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var out struct {
Clients []struct {
ClientOrgName string `json:"clientOrgName"`
ClientOrgUUID string `json:"clientOrgUuid"`
} `json:"clients"`
}
json.NewDecoder(resp.Body).Decode(&out)
for _, c := range out.Clients {
fmt.Printf("%s -> %s\n", c.ClientOrgName, c.ClientOrgUUID)
}
}
```
Una respuesta lista cada cliente gestionado, incluido el `clientOrgUuid` que pasarás como `x-auth-org`:
```json theme={null}
{
"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.
```bash cURL theme={null}
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 '{}'
```
```python Python theme={null}
import requests
BASE_URL = "https://api2.rhombussystems.com"
CLIENT_ORG_UUID = "aB_cD1eF2gH3iJ4kL5mN"
headers = {
"x-auth-scheme": "partner-api-token",
"x-auth-apikey": "YOUR_PARTNER_API_KEY",
"x-auth-org": CLIENT_ORG_UUID, # actuar como este cliente gestionado
"Content-Type": "application/json",
}
resp = requests.post(
f"{BASE_URL}/api/camera/getMinimalCameraStateList",
headers=headers,
json={},
)
resp.raise_for_status()
print(resp.json().get("cameraStates", []))
```
```javascript JavaScript theme={null}
const BASE_URL = "https://api2.rhombussystems.com";
const CLIENT_ORG_UUID = "aB_cD1eF2gH3iJ4kL5mN";
const headers = {
"x-auth-scheme": "partner-api-token",
"x-auth-apikey": "YOUR_PARTNER_API_KEY",
"x-auth-org": CLIENT_ORG_UUID, // actuar como este cliente gestionado
"Content-Type": "application/json",
};
const resp = await fetch(`${BASE_URL}/api/camera/getMinimalCameraStateList`, {
method: "POST",
headers,
body: JSON.stringify({}),
});
console.log((await resp.json()).cameraStates);
```
```go Go theme={null}
package main
import (
"bytes"
"net/http"
)
func main() {
clientOrgUUID := "aB_cD1eF2gH3iJ4kL5mN"
req, _ := http.NewRequest("POST",
"https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList",
bytes.NewBufferString("{}"))
req.Header.Set("x-auth-scheme", "partner-api-token")
req.Header.Set("x-auth-apikey", "YOUR_PARTNER_API_KEY")
req.Header.Set("x-auth-org", clientOrgUUID) // actuar como este cliente gestionado
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
// decodificar resp.Body...
}
```
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](/es/rhombus-cli) 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:
```bash theme={null}
# 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](/es/websocket/authentication) para ver el patrón completo:
```text theme={null}
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](/api-reference/overview).
| 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](/es/oauth-authentication) para saber cómo obtener claves de partner.
## Solución de problemas
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.
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.
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.
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.
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](/es/websocket/authentication).
## Próximos pasos
Obtén credenciales de partner y genera claves de partner de larga duración
Abre conexiones de partner en tiempo real dirigidas a una organización cliente
Usa --partner-org para ejecutar cualquier comando contra un cliente gestionado
Explora todos los endpoints de partner y a nivel de cliente