> 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-pt/kilo-center/kilo-mioty-service-center/integrations/api-reference.md).

# Referência da API

Referência da API gRPC do KiloCenter — definições Protocol Buffer para estações base, endpoints, com portal online.

O KiloCenter fornece uma API gRPC para integrar com ou estender a plataforma. Todas as definições da API são Protocol Buffers alojados no repositório em `KC-Core/api/proto/`.

### Referência Interativa da API

Uma referência de API navegável com todos os endpoints RPC está disponível em:

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

### Visão Geral do gRPC

gRPC é uma estrutura RPC de alto desempenho que usa Protocol Buffers para serialização e HTTP/2 para transporte. Para contexto, veja [grpc.io](https://grpc.io/).

A API do KiloCenter está definida em três ficheiros proto:

| Ficheiro           | Descrição                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `kilocenter.proto` | Serviço unificado compatível com versões anteriores (todos os 117 RPCs)                                            |
| `core.proto`       | Mensagens do domínio principal (endpoints, estações base, mensagens, downlinks, eventos, certificados, blueprints) |
| `identity.proto`   | Mensagens do domínio de identidade (utilizadores, organizações, chaves API, autenticação)                          |

### Geração de Cliente

**Go (usando buf — predefinição do projeto):**

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

Saída: `KC-Core/api/gen/` (apenas stubs Go — `buf.gen.yaml` configura plugins Go).

**Outras linguagens (usando protoc):**

```bash
# Exemplo em 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` gera apenas stubs Go. Para outras linguagens, use protoc ou adicione plugins buf. Veja [grpc.io/docs/languages](https://grpc.io/docs/languages/) para guias específicos por linguagem.

### Autenticação

#### Edição Comunitária

A Community Edition é executada com autenticação desativada (`KILOCENTER_AUTH_ENABLED=false`). Nenhum cabeçalho é necessário para qualquer RPC — todos os métodos estão acessíveis diretamente.

```bash
# Não são necessários cabeçalhos de autenticação
grpcurl -plaintext -d '{}' \
  localhost:9090 kilocenter.api.v1.KiloCenterService/GetSystemStatus
```

#### Edição Enterprise

Quando a autenticação está ativada (`KILOCENTER_AUTH_ENABLED=true`), aplicam-se três cabeçalhos de metadados:

| Cabeçalho           | Necessário Para                                                   | Valor                                      |
| ------------------- | ----------------------------------------------------------------- | ------------------------------------------ |
| `authorization`     | Todos os RPCs não públicos                                        | `Bearer <JWT_TOKEN>` ou `Bearer <API_KEY>` |
| `x-organization-id` | Todos os RPCs não isentos                                         | UUID da organização de destino             |
| `x-user-id`         | RPCs chamados sem JWT (modo de autenticação apenas por cabeçalho) | UUID do utilizador em ação                 |

**Métodos públicos** (não são necessários cabeçalhos): `Login`, `RefreshTokens`, `GetAuthSettings`, `ExchangeOIDC`, `ExchangeOAuth2`, `GetReleaseInfo`, `RegisterAccount` Origem: `KC-Core/pkg/grpc/public_methods.go`

**Métodos isentos de organização** (autenticação obrigatória, sem cabeçalho de organização): `GetSystemStatus`, `GetProfile`, `Logout`, `ChangePassword`, CRUD de Utilizador/Organização/Filiação (contexto da organização resolvido a partir dos campos do pedido) Origem: `KC-Core/pkg/grpc/public_methods.go` → `OrgExemptMethods`

Os tokens API são criados através do KC-Web ou do `CreateApiKey` RPC.

### Referência da API por Domínio

#### Endpoints (7)

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

#### Estações Base (7)

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

#### Mensagens (11)

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

#### Downlinks (4)

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

#### Transmissão UL (1)

`SendULTransmit`

#### Controlo da Estação Base (2)

`RequestBaseStationStatus`, `InitiatePing`

#### Estado DL RX (3)

`GetDLRXStatus`, `QueryDLRXStatus`, `GetDLRXStatusQueries`

#### Sistema (3)

`GetSystemStatus`, `GetStatistics`, `GetReleaseInfo`

#### Chaves API (4)

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

#### Integrações (5)

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

#### Análises (3)

`GetAnalyticsOverview`, `GetActivityAnalytics`, `GetSignalQualityAnalytics`

#### Eventos e Alertas (8)

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

#### Monitorização 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 Dispositivo (5)

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

#### Blueprints (8)

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

#### Utilitários de Blueprint (1)

`DecodePreview`

#### Estatísticas do EndPoint (2)

`GetEndPointStats`, `GetEndPointOperations`

#### Autenticação e Sessão (8) — Enterprise

`Login`, `RefreshTokens`, `GetProfile`, `GetAuthSettings`, `Logout`, `ChangePassword`, `ExchangeOIDC`, `ExchangeOAuth2`

#### Registo Self-Service (1) — Enterprise

`RegisterAccount`

#### Utilizadores (6) — Enterprise

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

#### Organizações (5) — Enterprise

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

#### Filiações de Organização (6) — Enterprise

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

### RPCs de Streaming

Cinco RPCs usam streaming do lado do servidor para fornecer dados em tempo real:

| RPC                         | Caso de Uso                        |
| --------------------------- | ---------------------------------- |
| `StreamMessages`            | Mensagens uplink em tempo real     |
| `StreamBaseStationMessages` | Feed de mensagens da estação base  |
| `StreamEvents`              | Notificações de eventos do sistema |
| `StreamBaseStationEvents`   | Feed de eventos da estação base    |
| `StreamEndPointEvents`      | Feed de eventos do endpoint        |

```typescript
const stream = client.streamMessages(request, metadata);
stream.on('data', (message) => { /* tratar mensagem */ });
stream.on('error', (err) => { /* tratar erro */ });
stream.on('end', () => { /* stream fechado */ });
```

### Paginação

Todos `List*` os RPCs suportam paginação baseada em offset através de `page_size` e `page_token` campos.

**RPCs de listagem padrão:** predefinição 20, máximo 100 **Listas de alto volume** (endpoints, estações base, downlinks): predefinição 100, máximo 1000

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

```protobuf
message ListEndPointsRequest {
  int32 page_size = 1;    // Predefinição 20, máximo 100
  string page_token = 2;  // Da ListEndPointsResponse.next_page_token anterior
}
```

### Tratamento de Erros

Todos os erros usam códigos de estado gRPC com tokens de erro legíveis por máquina de `KC-Core/pkg/grpc/errors_catalog.go`.

| Código gRPC               | Equiv. HTTP | Causas Comuns                          |
| ------------------------- | ----------- | -------------------------------------- |
| `INVALID_ARGUMENT` (3)    | 400         | Pedido malformado, falhas de validação |
| `NOT_FOUND` (5)           | 404         | O recurso não existe                   |
| `ALREADY_EXISTS` (6)      | 409         | Recurso duplicado                      |
| `PERMISSION_DENIED` (7)   | 403         | Falha de autorização                   |
| `UNAUTHENTICATED` (16)    | 401         | Token em falta ou inválido             |
| `FAILED_PRECONDITION` (9) | 400         | Falha baseada no estado                |
| `INTERNAL` (13)           | 500         | Erro do servidor                       |

Para o modelo completo de erros e os intervalos de tokens de erro, veja docs/api.md.

### Console da API

A reflexão gRPC está ativada no KC-Gateway. Ferramentas compatíveis:

```bash
# grpcui — interface web interativa
grpcui -plaintext localhost:9090

# grpcurl — cliente de linha de comando
grpcurl -plaintext localhost:9090 list

# Postman — use o separador gRPC com reflexão do servidor
# BloomRPC — cliente gRPC para desktop
```

### Leitura Adicional

* Referência completa da API — contratos de pedido/resposta e intervalos de tokens de erro
* Ficheiros fonte Proto — definições canónicas da API
* Primeiros Passos com gRPC — verifique a conectividade e 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-pt/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.