> For the complete documentation index, see [llms.txt](https://portal-integracao.intelbras.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://portal-integracao.intelbras.com.br/defense-ia-and-lite/readme/controle-ptz.md).
# Controle PTZ
Guia de endpoints de PTZ para câmeras: lock/arrange, presets, direção e lente (zoom/foco), cruises e posicionamento/área visível, com exemplos curl.
### Como usar:
* Substitua as variáveis `{{host}}`, `{{loginToken}}` e demais identificadores pelos valores reais do ambiente.
* Utilize variáveis globais do seu projeto quando disponíveis para evitar hardcode.
* Ajuste parâmetros de query conforme o cenário (paginação, filtros, IDs).
* Campos JSON opcionais podem ser removidos ou adicionados sem alterar a estrutura base.
* Sempre valide os tipos esperados pelo backend antes de enviar requisições em lote.
***
### Convenções e autenticação
* Códigos de resultado (padrão): `code: 1000` indica sucesso
* Content-Type: `application/json;charset=UTF-8`
* Idioma (opcional): `Accept-Language: en`
* Autenticação: header `X-Subject-Token: {{loginToken}}` (obtenha o token no seu fluxo de login do projeto)
* Base URL: `http://{{host}}/iams/api/v1.1`
***
### Erros comuns (modelo):
| Situação | Sintoma | Como resolver |
| -------------------------- | ----------------------------: | ----------------------------------------- |
| Token ausente/expirado | `401` | Refaça login e atualize `X-Subject-Token` |
| Content-Type incorreto | `415 Unsupported Media Type` | Use `application/json;charset=UTF-8` |
| Campos obrigatórios vazios | `400` / mensagem de validação | Revise a seção **Parâmetros** do endpoint |
***
### Salvar passeios
**Tópico**: Salva ou atualiza a configuração de um **passeio PTZ (cruise)** de uma câmera, definindo pontos, ordem e tempo de permanência.
* Método: `POST` /`brms/api/v1.0/DMS/Cruise/SaveCruise`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Cruise/SaveCruise'
--header 'X-Subject-Token: C117C02E9CF0408Ca45d20c8e8618e7d'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"cruiseId": "1",
"data": "\n\n\t\n\t\t\n\t\n\n",
"channelId": "1000003$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": null
}
```
### Obter passeios
**Tópico**: Consulta os passeios (cruises) configurados em uma câmera PTZ, retornando a lista com IDs e a configuração de cada passeio.
* Método: `POST /brms/api/v1.0/DMS/Cruise/GetCruises`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{[Host}}/brms/api/v1.0/DMS/Cruise/GetCruises'
--header 'X-Subject-Token: C117C02E9CF0408Ca45d20c8e8618e7d'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"channelId": "1000003$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"cruises": [
{
"channelId": "1000003$1$0$1",
"cruiseId": "0",
"data": "\n\n\t\n\t\t\n\t\n"
}
]
}
}
```
### Negociação PTZ
**Tópico**: Realiza a negociação de controle PTZ de uma câmera, permitindo adquirir ou liberar o controle exclusivo do canal. Essa operação é usada para evitar conflitos quando múltiplos usuários tentam controlar o PTZ simultaneamente.
* Método: `POST /brms/api/v1.0/DMS/Ptz/ArrangePtz`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/ArrangePtz'
--header 'X-Subject-Token: C117C02E9CF0408Ca45d20c8e8618e7d'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"extend": "",
"channelId": "1000003$1$0$1",
"lockTime": "0",
"operateType": "1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1",
"lockUser": {
"userName": "system",
"userLevel": "10",
"lowerDomain": null
}
}
}
```
### Obtenha predefinições
**Tópico**: Consulta a lista de **pontos predefinidos (presets)** configurados em uma câmera PTZ, retornando os IDs e informações de cada posição salva.
* Método: `POST /brms/api/v1.0/DMS/Ptz/GetPresetPoints`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/GetPresetPoints'
--header 'X-Subject-Token: C117C02E9CF0408Ca45d20c8e8618e7d'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"channelId": "1000028$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"channelId": "1000028$1$0$1",
"presetPoints": []
}
}
```
### Controle de lente PTZ
**Tópico**: Executa comandos de controle PTZ em uma câmera, permitindo mover a lente, iniciar/parar movimento ou acionar ações específicas.
* Método: `POST /brms/api/v1.0/DMS/Ptz/OperateCamera`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/OperateCamera'
--header 'X-Subject-Token: C117C02E9CF0408Ca45d20c8e8618e7d'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"extend": "",
"direct": "2",
"command": "0",
"channelId": "1000028$1$0$1",
"step": "4",
"operateType": "1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1"
}
}
```
### Controle de direção PTZ
**Tópico**: Executa comandos de direção PTZ em uma câmera, permitindo mover a lente nos eixos horizontal e vertical, iniciar ou interromper o movimento.
* Método: `POST /brms/api/v1.0/DMS/Ptz/OperateDirect`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/OperateDirect'
--header 'X-Subject-Token: E179D23242114367b907d1d28fb08ef5'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"stepY": "4",
"extend": "",
"direct": "8",
"channelId": "1000028$1$0$1",
"stepX": "6",
"command": "1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1"
}
}
```
### Controle de predefinições
**Tópico**: Executa operações relacionadas a **pontos predefinidos (presets)** de uma câmera PTZ.
* Método: `POST /brms/api/v1.0/DMS/Ptz/OperatePresetPoint`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/OperatePresetPoint'
--header 'X-Subject-Token: E179D23242114367b907d1d28fb08ef5'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"presetPointCode": "1",
"endTime": "",
"presetPointName": "ABC",
"channelId": "1000003$1$0$1",
"startTime": "",
"operateType": "1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1",
"lockUser": null
}
}
```
### Obtenha o status do foco elétrico
**Tópico**: Consulta o **estado atual da lente PTZ.**
* Método: `POST /brms/api/v1.0/DMS/Ptz/GetFocusStatus`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/GetFocusStatus'
--header 'X-Subject-Token: E179D23242114367b907d1d28fb08ef5'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/'
--data '{
"data": {
"channelId": "1000003$1$0$1",
"operateType": "2",
"zoom": "",
"focus": "",
"lensType": ""
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1",
"lockUser": null
}
}
```
### Controle de foco elétrico
**Tópico**: Executa **controle da lente elétrica PTZ.**
* Método: `POST /brms/api/v1.0/DMS/Ptz/OperateFocus`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/OperateFocus'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"focus": "0.97",
"channelId": "1000003$1$0$1",
"zoom": "0.05",
"operateType": "0",
"lensType": "1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1",
"lockUser": null
}
}
```
### Posicionamento tridimensional ou posicionamento por radar e domo de velocidade
**Tópico**: Executa **posicionamento tridimensional PTZ**, movendo a câmera para coordenadas espaciais específicas.
* Método: `POST /brms/api/v1.0/DMS/Ptz/SitPosition`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/SitPosition'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"pointZ": "8",
"extend": "1",
"channelId": "1000003$1$0$1",
"pointY": "326",
"pointX": "-1039"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1",
"lockUser": null
}
}
```
### Obtenha as informações de posição PTZ
**Tópico**: Executa **posicionamento tridimensional PTZ**, movendo a câmera para coordenadas espaciais específicas.
* Método: `POST /brms/api/v1.0/DMS/Ptz/GetPosition`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/GetPosition'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"channelId": "1000003$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"channelId": "1000003$1$0$1",
"pointX": "653",
"pointY": "13",
"pointZ": "128"
}
}
```
### Controle de função PTZ
**Tópico**: Executa **posicionamento tridimensional PTZ**, movendo a câmera para coordenadas espaciais específicas.
* Método: `POST /brms/api/v1.0/DMS/Ptz/OperateFunction`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
vcurl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/OperateFunction'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"extend": "",
"target": "0",
"channelId": "1000003$1$0$1",
"command": "0",
"operateType": "25"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"result": "1",
"lockUser": null
}
}
```
### Pesquise as informações da lente
**Tópico**: Consulta as **informações atuais da lente PTZ**, incluindo estado de zoom, foco, posição e capacidades suportadas pela câmera.
* Método: `POST /brms/api/v1.0/DMS/Ptz/GetLensInfo`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/GetLensInfo'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"channelId": "1000003$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"channelId": "1000003$1$0$1",
"zoom": "0.65",
"focus": "0.42",
"iris": "0.30",
"pan": "-120",
"tilt": "45",
"lensStatus": "normal",
"capabilities": {
"zoomSupported": true,
"focusSupported": true,
"irisSupported": true,
"absolutePositionSupported": true
}
}
}
```
### Configurando o alcance visível
**Tópico**: Define o **alcance visível/orientação** da câmera PTZ com base no azimute informado.
* Método: `POST /brms/api/v1.0/DMS/Ptz/SetVisibleArea`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/SetVisibleArea'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"azimuth": "3400",
"channelId": "1000003$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"channelId": "1000003$1$0$1",
"azimuth": "3400",
"result": "1",
"message": "Visible area configured successfully"
}
}
```
### Obtendo alcance visível
**Tópico**: Consulta o **alcance visível/orientação atual** da câmera PTZ, retornando o azimute e informações relacionadas ao campo de visão configurado.
* Método: `POST /brms/api/v1.0/DMS/Ptz/GetVisibleArea`
* Headers: `X-Subject-Token`, `Content-Type`
Exemplo (curl):
```bash
curl --location 'https://{{Host}}/brms/api/v1.0/DMS/Ptz/GetVisibleArea'
--header 'X-Subject-Token: FE28CCCC547F46A39bf2c17cf5b3cfb8'
--header 'Content-Type: application/json'
--header 'Cookie: Path=/; JSESSIONID=291F4548138B8F72B83DAFDE0CF2A3CF'
--data '{
"data": {
"channelId": "1000003$1$0$1"
}
}'
```
Resposta (modelo – sucesso):
```json
{
"code": 1000,
"desc": "Success",
"data": {
"channelId": "1000003$1$0$1",
"azimuth": "3400",
"pan": "-118",
"tilt": "46",
"visibleAreaStatus": "active"
}
}
```
***
Notas Finais:
* Sempre valide o **token (`X-Subject-Token`)** antes de executar operações PTZ para evitar falhas silenciosas de autenticação.
* Padronize o tratamento do **`code` de resposta,** considere qualquer valor diferente de `1000` como erro e registre logs detalhados.
* Evite múltiplos comandos PTZ simultâneos no mesmo canal sem antes realizar a **negociação de controle**.
* Em integrações concorrentes, implemente **controle de lock** para prevenir conflitos entre usuários ou serviços.
* Para operações contínuas (movimento, foco, zoom), implemente **timeouts e cancelamentos**, evitando comandos presos.
* Sempre trate falhas de comunicação como estados recuperáveis, não assuma que a câmera está indisponível sem confirmação.
***
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://portal-integracao.intelbras.com.br/defense-ia-and-lite/readme/controle-ptz.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.