> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-es/kilo-center/kilo-mioty-service-center/integrations/api-reference.md).

# Referencia de la API

Referencia de la API gRPC de KiloCenter — definiciones de Protocol Buffer para estaciones base y endpoints, con portal en línea.

KiloCenter proporciona una API gRPC para integrarse con la plataforma o ampliarla. Todas las definiciones de la API son Protocol Buffers alojados en el repositorio en `KC-Core/api/proto/`.

### Referencia interactiva de la API

Hay disponible una referencia navegable de la API con todos los endpoints RPC en:

<https://servicecenter-api.kiloiot.io/>

### Resumen de gRPC

gRPC es un framework RPC de alto rendimiento que usa Protocol Buffers para la serialización y HTTP/2 para el transporte. Para más información, consulte [grpc.io](https://grpc.io/).

La API de KiloCenter se define en tres archivos proto:

| Archivo            | Descripción                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `kilocenter.proto` | Servicio unificado compatible con versiones anteriores (los 117 RPCs)                                              |
| `core.proto`       | Mensajes del dominio central (endpoints, estaciones base, mensajes, downlinks, eventos, certificados, planos base) |
| `identity.proto`   | Mensajes del dominio de identidad (usuarios, organizaciones, claves API, autenticación)                            |

### Generación de clientes

**Go (usando buf — predeterminado del proyecto):**

```bash
cd KC-Core/api/proto && buf generate
```

Salida: `KC-Core/api/gen/` (solo stubs de Go — `buf.gen.yaml` configura los complementos de Go).

**Otros lenguajes (usando protoc):**

```bash
# Ejemplo en Python
python -m grpc_tools.protoc \\
  -I KC-Core/api/proto \\
  --python_out=./gen --grpc_python_out=./gen \\
  KC-Core/api/proto/kilocenter.proto \\
  KC-Core/api/proto/core.proto \\
  KC-Core/api/proto/identity.proto
```

`buf.gen.yaml` solo genera stubs de Go. Para otros lenguajes, use protoc o añada complementos de buf. Consulte [grpc.io/docs/languages](https://grpc.io/docs/languages/) para guías específicas de cada lenguaje.

### Autenticación

#### Community Edition

Community Edition se ejecuta con la autenticación deshabilitada (`KILOCENTER_AUTH_ENABLED=false`). No se requieren encabezados para ningún RPC — todos los métodos son accesibles directamente.

```bash
# No se necesitan encabezados de autenticación
grpcurl -plaintext -d '{}' \\
  localhost:9090 kilocenter.api.v1.KiloCenterService/GetSystemStatus
```

#### Edición Enterprise

Cuando la autenticación está habilitada (`KILOCENTER_AUTH_ENABLED=true`), se aplican tres encabezados de metadatos:

| Encabezado          | Requerido para                                                     | Valor                                     |
| ------------------- | ------------------------------------------------------------------ | ----------------------------------------- |
| `authorization`     | Todos los RPC no públicos                                          | `Bearer <JWT_TOKEN>` o `Bearer <API_KEY>` |
| `x-organization-id` | Todos los RPC no exentos                                           | UUID de la organización objetivo          |
| `x-user-id`         | RPCs llamados sin JWT (modo de autenticación solo con encabezados) | UUID del usuario que actúa                |

**Métodos públicos** (no se requieren encabezados): `Iniciar sesión`, `RefreshTokens`, `GetAuthSettings`, `ExchangeOIDC`, `ExchangeOAuth2`, `GetReleaseInfo`, `RegisterAccount` Fuente: `KC-Core/pkg/grpc/public_methods.go`

**Métodos exentos de organización** (se requiere autenticación, sin encabezado de organización): `GetSystemStatus`, `GetProfile`, `Cerrar sesión`, `ChangePassword`, CRUD de Usuario/Org/Membresía (el contexto de la organización se resuelve a partir de los campos de la solicitud) Fuente: `KC-Core/pkg/grpc/public_methods.go` → `OrgExemptMethods`

Los tokens de API se crean a través de KC-Web o del `CreateApiKey` RPC.

### Referencia de la API por dominio

#### Endpoints (7)

`CreateEndPoint`, `GetEndPoint`, `UpdateEndPoint`, `DeleteEndPoint`, `ListEndPoints`, `AttachEndPoint`, `DetachEndPoint`

#### Estaciones base (7)

`CreateBaseStation`, `GetBaseStation`, `UpdateBaseStation`, `DeleteBaseStation`, `ListBaseStations`, `GetBaseStationStats`, `UpdateBaseStationEui`

#### Mensajes (11)

`GetMessage`, `ListMessages`, `StreamMessages`, `ListBaseStationMessages`, `GetBaseStationMessage`, `GetBaseStationMessageStats`, `SearchBaseStationMessages`, `ExportBaseStationMessages`, `StreamBaseStationMessages`, `ListEndpointMessages`, `ListBaseStationActivity`

#### Downlinks (4)

`SendDownlink`, `RevokeDownlink`, `ListDownlinkQueue`, `GetDownlinkResults`

#### Transmisión UL (1)

`SendULTransmit`

#### Control de estación base (2)

`RequestBaseStationStatus`, `InitiatePing`

#### Estado DL RX (3)

`GetDLRXStatus`, `QueryDLRXStatus`, `GetDLRXStatusQueries`

#### Sistema (3)

`GetSystemStatus`, `GetStatistics`, `GetReleaseInfo`

#### Claves API (4)

`CreateApiKey`, `GetApiKey`, `DeleteApiKey`, `ListApiKeys`

#### Integraciones (5)

`CreateIntegration`, `GetIntegration`, `UpdateIntegration`, `DeleteIntegration`, `ListIntegrations`

#### Analítica (3)

`GetAnalyticsOverview`, `GetActivityAnalytics`, `GetSignalQualityAnalytics`

#### Eventos y alertas (8)

`ListEvents`, `ListBaseStationEvents`, `ListEndPointEvents`, `StreamEvents`, `StreamBaseStationEvents`, `StreamEndPointEvents`, `ListAlerts`, `GetAlertSummary`

#### Monitoreo SCACI (6)

`ListScaciSessions`, `GetScaciSession`, `GetScaciStatistics`, `ListScaciErrors`, `ListScaciQueues`, `GetScaciStatus`

#### Certificados (6)

`GenerateCertificate`, `DownloadCertificate`, `DownloadBaseStationCertificate`, `GenerateServerCertificates`, `RenewServerCertificates`, `GetServerCertificateStatus`

#### Fabricantes (5)

`CreateManufacturer`, `GetManufacturer`, `UpdateManufacturer`, `DeleteManufacturer`, `ListManufacturers`

#### Modelos de dispositivos (5)

`CreateDeviceModel`, `GetDeviceModel`, `UpdateDeviceModel`, `DeleteDeviceModel`, `ListDeviceModels`

#### Planos base (8)

`CreateBlueprint`, `GetBlueprint`, `UpdateBlueprint`, `DeleteBlueprint`, `ListBlueprints`, `SetDefaultBlueprint`, `SubmitBlueprintToRegistry`, `CreateDeviceModelWithBlueprint`

#### Utilidades de planos base (1)

`DecodePreview`

#### Estadísticas de endpoints (2)

`GetEndPointStats`, `GetEndPointOperations`

#### Autenticación y sesión (8) — Enterprise

`Iniciar sesión`, `RefreshTokens`, `GetProfile`, `GetAuthSettings`, `Cerrar sesión`, `ChangePassword`, `ExchangeOIDC`, `ExchangeOAuth2`

#### Registro de autoservicio (1) — Enterprise

`RegisterAccount`

#### Usuarios (6) — Enterprise

`CreateUser`, `GetUser`, `UpdateUser`, `DeleteUser`, `ListUsers`, `UpdateUserPassword`

#### Organizaciones (5) — Enterprise

`CreateOrganization`, `GetOrganization`, `UpdateOrganization`, `DeleteOrganization`, `ListOrganizations`

#### Membresías de organización (6) — Enterprise

`AddOrganizationUser`, `GetOrganizationUser`, `UpdateOrganizationUser`, `RemoveOrganizationUser`, `ListOrganizationUsers`, `ListUserOrganizations`

### RPCs de streaming

Cinco RPCs usan streaming del lado del servidor para entregar datos en tiempo real:

| RPC                         | Caso de uso                           |
| --------------------------- | ------------------------------------- |
| `StreamMessages`            | Mensajes uplink en tiempo real        |
| `StreamBaseStationMessages` | Flujo de mensajes de la estación base |
| `StreamEvents`              | Notificaciones de eventos del sistema |
| `StreamBaseStationEvents`   | Flujo de eventos de la estación base  |
| `StreamEndPointEvents`      | Flujo de eventos del endpoint         |

```typescript
const stream = client.streamMessages(request, metadata);
stream.on('data', (message) => { /* manejar mensaje */ });
stream.on('error', (err) => { /* manejar error */ });
stream.on('end', () => { /* stream cerrado */ });
```

### Paginación

Todos `List*` los RPC admiten paginación basada en desplazamiento mediante `page_size` y `page_token` campos.

**RPC de lista estándar:** 20 por defecto, 100 máximo **Listas de gran volumen** (endpoints, estaciones base, downlinks): 100 por defecto, 1000 máximo

Fuente: `KC-Core/pkg/grpc/pagination.go`

```protobuf
message ListEndPointsRequest {
  int32 page_size = 1;    // 20 por defecto, 100 máximo
  string page_token = 2;  // De ListEndPointsResponse.next_page_token anterior
}
```

### Manejo de errores

Todos los errores usan códigos de estado gRPC con tokens de error legibles por máquina de `KC-Core/pkg/grpc/errors_catalog.go`.

| Código gRPC               | Equiv. HTTP | Causas comunes                              |
| ------------------------- | ----------- | ------------------------------------------- |
| `INVALID_ARGUMENT` (3)    | 400         | Solicitud mal formada, fallos de validación |
| `NOT_FOUND` (5)           | 404         | El recurso no existe                        |
| `ALREADY_EXISTS` (6)      | 409         | Recurso duplicado                           |
| `PERMISSION_DENIED` (7)   | 403         | Fallo de autorización                       |
| `UNAUTHENTICATED` (16)    | 401         | Token faltante o inválido                   |
| `FAILED_PRECONDITION` (9) | 400         | Fallo basado en estado                      |
| `INTERNAL` (13)           | 500         | Error del servidor                          |

Para el modelo completo de errores y los rangos de tokens de error, consulte docs/api.md.

### Consola de la API

La reflexión gRPC está habilitada en KC-Gateway. Herramientas compatibles:

```bash
# grpcui — UI web interactiva
grpcui -plaintext localhost:9090

# grpcurl — cliente de línea de comandos
grpcurl -plaintext localhost:9090 list

# Postman — use la pestaña gRPC con reflexión del servidor
# BloomRPC — cliente gRPC de escritorio
```

### Lecturas adicionales

* Referencia completa de la API — contratos de solicitud/respuesta y rangos de tokens de error
* Archivos fuente proto — definiciones canónicas de la API
* Primeros pasos con gRPC — verifique la conectividad y descubra métodos


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kiloiot.io/kilo-docs-es/kilo-center/kilo-mioty-service-center/integrations/api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.