> 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/gestao-de-faces.md).

# Gestão de faces

Guia de endpoints de Faces: repositórios/grupos de comparação, emissão/ativação em dispositivos, buscas por imagem e por características, e download de snapshots.

### Como usar:

* Substitua variáveis `{{host}}`, `{{loginToken}}` e IDs de exemplo.
* Mantenha a estrutura “Tópico / Fonte / Resposta / Exemplo (curl/Python)”.
* Use Unix epoch (segundos) para campos de tempo (`startTime`, `endTime`, etc.).

***

### Convenções (sem login)

* Base URL principal: `http://{{host}}/obms/api/v1.0` (alguns endpoints usam `v1.1` – ver seção de histórico).
* Header: `X-Subject-Token: {{loginToken}}`
* Content-Type: `application/json;charset=UTF-8` (quando houver body)
* Padrão de sucesso: `code == 1000` no corpo JSON.

***

### Erros comuns (modelo)

| Situação               | Sintoma                | Como resolver                             |
| ---------------------- | ---------------------- | ----------------------------------------- |
| Token ausente/expirado | `401` / `code != 1000` | Refaça login e atualize `X-Subject-Token` |
| Content-Type incorreto | `415`                  | Use `application/json;charset=UTF-8`      |
| Validação de campos    | `400`                  | Revise a seção **Parâmetros** do endpoint |

***

### Adicionar um grupo de comparação facial

**Tópico**: Cria um novo grupo de comparação facial (repositório de faces), permitindo o cadastro de conjuntos de pessoas para uso em reconhecimento e análises faciais.

* Método: `POST /brms/api/v1.1/face/repository`
* Headers: `X-Subject-Token`

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/brms/api/v1.1/face/repository' 
--header 'X-Subject-Token: EC581D562F8C42CC86eff7bf17a0c48c' 
--header 'Content-Type: application/json' 
--data '{
    "repositoryName": "face_test",
    "color": "5",
    "memo": "test",
    "roleIds": [
        "1",
        "2"
    ],
    "source": ""
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": {
        "id": "3"
    }
}
```

### Atualizar um grupo de comparação facial

**Tópico**: Atualiza as informações de um grupo de comparação facial existente, como nome, cor, descrição e perfis associados.

* Método: `PUT /brms/api/v1.1/face/repository/{repositoryId}`
* Headers: `X-Subject-Token, Content-Type: application/json`
* Path Params: `repositoryId` — ID do grupo de comparação facial

Exemplo (curl):

```powershell
curl --location --request PUT 'http://{{Host}}/brms/api/v1.1/face/repository/2' 
--header 'X-Subject-Token: 17136559C3284BFD97bae4e002c9978f' 
--header 'Content-Type: application/json' 
--data '{
    "color": "6",
    "repositoryName": "face001",
    "memo": "face detection",
    "roleIds": [
        "1",
        "2"
    ],
    "source": ""
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Excluir um grupo de comparação de faces

**Tópico**: Exclui permanentemente um grupo de comparação facial existente e todas as suas configurações associadas.

* Método: `DELETE /brms/api/v1.1/face/repository/{repositoryId}`
* Headers: `X-Subject-Token, Content-Type: application/json`
* Path Params: `repositoryId` — ID do grupo de comparação facial

Exemplo (curl):

```powershell
curl --location --request DELETE 'http://{{Host}}/brms/api/v1.1/face/repository/2' 
--header 'X-Subject-Token: 0556FD9DE2DC48A4944738c3755c0e86' 
--data ''
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Obter a lista de faces em páginas

**Tópico**: Retorna a lista de grupos de comparação facial (repositórios de faces) de forma paginada, permitindo pesquisa e ordenação dos resultados.

* Método: `GET /brms/api/v1.1/face/application/control/repository/page`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/brms/api/v1.1/face/application/control/repository/page?orderType=0&orderDirection=0&keyword=&page=1&pageSize=20' 
--header 'X-Subject-Token: ABD42C99196748D7b46c59522d3f614b' 
--data ''
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": {
        "totalCount": "2",
        "pageData": [
            {
                "repositoryId": "3",
                "repositoryName": "face_test",
                "color": "5",
                "colorName": "Navy",
                "memo": "test",
                "createTime": "1767807349",
                "updateTime": "1767807349",
                "facePersonCount": "0",
                "isFailed": "0",
                "thumbnail": null,
                "channelInfos": []
            },
            {
                "repositoryId": "1",
                "repositoryName": "Teste Grupo Armação",
                "color": "8",
                "colorName": null,
                "memo": "123",
                "createTime": "1765915080",
                "updateTime": "1765915080",
                "facePersonCount": "1",
                "isFailed": "0",
                "thumbnail": null,
                "channelInfos": [
                    {
                        "cameraType": "1",
                        "channelName": "VIP Intelbras",
                        "channelId": "1000000$1$0$0"
                    }
                ]
            }
        ]
    }
}
```

### Emitir banco de dados facial

**Tópico**: Distribui um grupo de comparação facial para dispositivos e canais específicos.

* Método: `POST /brms/api/v1.1/face/application/issue/repository/{repositoryId}`
* Headers: `X-Subject-Token, Content-Type: application/json`
* Path Params: `repositoryId` — ID do grupo de comparação facial

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/brms/api/v1.1/face/application/issue/repository/1' 
--header 'X-Subject-Token: 2E3305FC2A704FB18f5b884c1d706664' 
--header 'Content-Type: application/json' 
--data '{
    "operateType": "1",
    "deviceCodes": [
        "1000051"
    ],
    "channelIds": [
        "1000051&1&0&0"
    ]
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Cancelar edição do banco de dados de faces

**Tópico**: Cancela a edição de um grupo de comparação facial.

* Método: `POST /brms/api/v1.1/face/application/issue/repository/{repositoryId}/cancel`
* Headers: `X-Subject-Token, Content-Type: application/json`
* Path Params: `repositoryId` — ID do grupo de comparação facial

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/brms/api/v1.1/face/application/issue/repository/1/cancel' 
--header 'X-Subject-Token: 3C30DF08E00F40309b23d559ba05f109' 
--header 'Content-Type: application/json' 
--data '{
    "deviceCodes": [
        "1000051"
    ],
    "channelIds": [
        "1000043&1&0&0"
    ]
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Ativar o Banco de Dados de faces

**Tópico**: Ativa um grupo de comparação facial, enviando suas configurações para os dispositivos e canais definidos.

* Método: `POST /brms/api/v1.1/face/application/control/repository/{repositoryId}`
* Headers: `X-Subject-Token, Content-Type: application/json`
* Path Params: `repositoryId` — ID do grupo de comparação facial

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/brms/api/v1.1/face/application/control/repository/1' 
--header 'X-Subject-Token: 1909F412662D4DD8a6e82787b849ac4e' 
--header 'Content-Type: application/json' 
--data '{
    "channels": [
        {
            "channelId": "1000051&1&0&0",
            "similarity": "80"
        }
    ]
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Cancelar Ativação do Banco de Dados de Reconhecimento Facial

**Tópico**: Cancela a ativação de um grupo de comparação facial, interrompendo o envio e a aplicação de suas configurações aos dispositivos e canais especificados.

* Método: `POST /brms/api/v1.1/face/application/control/repository/{repositoryId}/cancel`
* Headers: `X-Subject-Token, Content-Type: application/json`
* Path Params: `repositoryId` — ID do grupo de comparação facial

Exemplo (curl):

```powershell
curl --location 'http://{[Host}}/brms/api/v1.1/face/application/control/repository/1/cancel' 
--header 'X-Subject-Token: 5F0D263AA21A4D449eb4187aa84447bb' 
--header 'Content-Type: application/json' 
--data '{
    "channelIds": [
        "1000043&1&0&0"
    ]
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": {
        "failedChannels": []
    }
}
```

### Iniciar Busca Assíncrona em Registros de Snapshot Faciais por Imagem

**Tópico**: Inicia uma busca assíncrona nos registros de snapshot faciais a partir de uma imagem fornecida, permitindo localizar ocorrências semelhantes dentro de um intervalo de tempo e canais específicos.

* Método: `POST /brms/api/v1.1/face/detection/record/search-by-picture/start`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/brms/api/v1.1/face/detection/record/search-by-picture/start' 
--header 'X-Subject-Token: 1AE5CB098D4A4105aa3ec814debba532' 
--header 'Content-Type: application/json' 
--data '{
    "beginTime": "1609257600",
    "endTime": "1609343999",
    "similarity": "92",
    "channelIds": [
        "1000000$1$0$0",
        "1000000$1$0$1",
        "1000000$1$0$6",
        "1000000$1$0$7"
    ],
    "faceImageData": "iVBORw0KGgoAAAANSUhEU...TeHTY5gAAAABJRU5ErkJggg=="
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Interromper Busca Assíncrona de Capturas Faciais via Pesquisa Reversa de Imagem

**Tópico**: Interrompe uma busca assíncrona de capturas faciais previamente iniciada por meio de pesquisa reversa de imagem.

* Método: `POST /brms/api/v1.1/face/detection/record/search-by-picture/stop`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'https://{{Host}}/brms/api/v1.1/face/detection/record/search-by-picture/stop' 
--header 'X-Subject-Token: 6B787332E6E647DDa7b320878c1d6423' 
--header 'Content-Type: application/json' 
--header 'Cookie: Path=/' 
--data '{
    "session": "2acd14e7290048d88611101e779543fb"
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Pesquisar registros de reconhecimento facial nas páginas com base em características.

**Tópico**: Consulta, de forma paginada, os registros de reconhecimento facial com base em características biométricas, permitindo filtrar ocorrências por pessoa, intervalo de tempo e canais específicos.

* Método: `POST /iams/api/v1.1/face/recognition/record/search-by-feature/page`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/iams/api/v1.1/face/recognition/record/search-by-feature/page' 
--header 'X-Subject-Token: 84EA5F78E9BE404Ea3a7e2ac3f02508a' 
--header 'Content-Type: application/json' 
--data '{
    "channelIds": [
        "1000014$1$0$0"
    ],
    "beginTime": "1689523200",
    "endTime": "1689609599",
    "personId": "34870903",
    "page": "1",
    "pageSize": "20",
    "currentPage": "1",
    "splitTime": "",
    "splitId": ""
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": {
        "totalCount": "0",
        "pageData": []
    }
}
```

### Pesquisar por imagem (Baixar imagem)

**Tópico**: Realiza o download de imagens associadas a registros de detecção ou reconhecimento facial, utilizando a sessão e as URLs retornadas em consultas anteriores.

* Método: `POST /brms/api/v1.1/face/detection/record/device/picture/download`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'https://{{Host}}/brms/api/v1.1/face/detection/record/device/picture/download' 
--header 'X-Subject-Token: 3D07B58937154DE7a77792eec9c1cc57' 
--header 'Content-Type: application/json' 
--header 'Cookie: Path=/' 
--data '{
    "session": "2acd14e7290048d88611101e779543fb",
    "deviceCode": "1000001",
    "urls": [
        {
            "id": "2",
            "type": "1",
            "url": "/picid/2789283.jpg"
        }
    ]
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": null
}
```

### Pesquisar Registros de Captura Facial por Características com Paginação

**Tópico**: Consulta, de forma paginada, os registros de captura facial com base em características biométricas e atributos físicos.

* Método: `POST /iams/api/v1.1/face/detection/record/search-by-feature/page`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/iams/api/v1.1/face/detection/record/search-by-feature/page' 
--header 'X-Subject-Token: 3D07B58937154DE7a77792eec9c1cc57' 
--header 'Content-Type: application/json' 
--data '{
    "channelIds": [
        "1000000$1$0$0"
    ],
    "recordSource": "0",
    "taskIds": [
        "1"
    ],
    "beginTime": "1614219854",
    "endTime": "1614637411",
    "beginAge": "12",
    "endAge": "50",
    "gender": "",
    "page": "1",
    "pageSize": "20",
    "currentPage": "1",
    "orderType": "1",
    "orderDirection": "1",
    "splitTime": "",
    "splitId": "",
    "glasses": "",
    "mask": "",
    "beard": "",
    "recordType": "1"
}'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": {
        "totalCount": "0",
        "pageData": []
    }
}
```

### Pesquisar Registros de Reconhecimento Facial por Características (Paginado)

**Tópico**: Consulta, de forma paginada, os registros de reconhecimento facial com base em características biométricas.

* Método: `POST /iams/api/v1.1/face/recognition/record/search-by-feature/page`
* Headers: `X-Subject-Token, Content-Type: application/json`

Exemplo (curl):

```powershell
curl --location 'http://{{Host}}/iams/api/v1.1/face/recognition/record/search-by-feature/page' 
--header 'X-Subject-Token: 58ADB1D174B44CE0a6a1800b6e4f117c' 
--header 'Content-Type: application/json' 
--data '{
    "channelIds": [
        "1000000$1$0$0"
    ],
    "beginTime": "1614219854",
    "endTime": "1614637411",
    "personId": "",
    "page": "2",
    "pageSize": "20",
    "currentPage": "1",
    "splitTime": "1617297162",
    "splitId": "2021040220000400001"
}
'
```

Resposta (modelo – sucesso):

```json
{
    "code": 1000,
    "desc": "Success",
    "data": {
        "totalCount": "0",
        "pageData": []
    }
}
```

***

Notas finais:

* Todos os endpoints seguem o padrão de resposta com `code == 1000` para sucesso.
* Utilize sempre `{{Host}}` e `{{loginToken}}` conforme o ambiente.
* Campos de tempo devem ser informados em **Unix epoch (segundos)**.
* Alguns serviços utilizam `brms` e outros `iams`; verifique a API correta antes da integração.
* Mantenha o header `Content-Type: application/json;charset=UTF-8` sempre que houver corpo na requisiçã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/gestao-de-faces.md?ask=<question>&goal=<user_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.