> 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-pessoas.md).

# Gestão de Pessoas

Guia de endpoints para grupos e pessoas. Traz base URL, exemplos JSON/curl, filtros e paginação, adição de pessoas, exclusão em lote, reenvio de falhas e eventos de acesso.

## Como usar:

* Substitua variáveis `{{host}}`, `{{loginToken}}`, `{{newPersonId}}` pelos valores reais do seu ambiente ou utilize variáveis que tenham esses valores.
* Copie e cole os blocos por endpoint e mantenha a estrutura “Tópico / Fonte / Resposta / Exemplo”.
* Adicione/oculte campos de corpo (JSON) conforme a necessidade do seu caso, mantendo o padrão do projeto.

***

## Convenções & Autenticação

* Base URL: `http://{{host}}/obms/api/v1.1`
* Autenticação: header `X-Subject-Token: {{loginToken}}` (obtenha o token no seu fluxo de login do projeto)
* Idioma (opcional): `Accept-Language: en`
* Content-Type: `application/json;charset=UTF-8`
* Códigos de resultado (padrão): `code: 1000` indica sucesso

{% hint style="info" %}
Dica: Centralize `{{loginToken}}` em um collection variable no Postman para reutilização automática em todos os requests ou utilize um script em seu projeto para manter o ticket.
{% endhint %}

***

## 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 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 |

***

### Adicionar Grupo de Pessoas

**Tópico:** Cria um novo agrupamento (unidade/organização) para vincular pessoas.

* **Método**: `POST /acs/person-group`
* Headers:
  * `X-Subject-Token: <token>`
  * `Content-Type: application/json;charset=UTF-8`

Parâmetros (Body JSON):

| Campo         | Tipo           | Obrigatório | Descrição                      |
| ------------- | -------------- | ----------- | ------------------------------ |
| parentOrgCode | string         | SIM         | Código do grupo pai (ex.: 001) |
| orgName       | string         | Não         | Nome do grupo                  |
| remark        | string         | Não         | Observação/comentário          |
| roleIds       | array\[string] | Não         | IDs de papéis associados       |
| sourceType    | string         | Não         | Tipo de origem ("1" padrão)    |
| sourceId      | string         | Não         | ID de origem                   |
| associateId   | string         | Não         | ID associado                   |

**Body (exemplo):**

```json
{
  "parentOrgCode": "001",
  "orgName": "test",
  "remark": "Apenas Teste",
  "roleIds": ["1", "2"],
  "sourceType": "1",
  "sourceId": "",
  "associateId": ""
}
```

**Exemplo (curl):**

```bash
curl -X POST "http://{{host}}/obms/api/v1.1/acs/person-group" \
 -H "X-Subject-Token: {{LoginToken}}" \
 -H "Content-Type: application/json;charset=UTF-8" \
 -d '{ "parentOrgCode": "001", "orgName": "test", "remark": "Apenas Teste", "roleIds": ["1","2"], "sourceType": "1", "sourceId": "", "associateId": "" }'
```

{% hint style="info" %}
Verifique se o servidor utiliza HTTPS. Se sim, altere a URL para `https://` e adicione `-k` ao final do comando para ignorar verificação do certificado (apenas em ambientes de teste).
{% endhint %}

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": { "orgCode": "001004" } }
```

***

### Atualizar o Grupo de Pessoas

**Tópico**: Atualiza metadados do grupo (nome, papéis, observações).

* **Método**: `PUT /acs/person-group/{orgCode}`
* Path Params: `orgCode` (ID do grupo)
* Headers: `X-Subject-Token`, `Content-Type`

**Body (exemplo mínimo):**

```json
{
  "orgName": "Engineering",
  "remark": "updated",
  "roleIds": ["1"],
  "sourceType": "1",
  "sourceId": "",
  "associateId": ""
}
```

**Exemplo (curl):**

```bash
curl -X PUT "http://{{host}}/obms/api/v1.1/acs/person-group/001004" \
 -H "X-Subject-Token: {{LoginToken}}" \
 -H "Content-Type: application/json;charset=UTF-8" \
 -d '{ "orgName": "Engineering", "remark": "updated", "roleIds": ["1"], "sourceType": "1", "sourceId": "", "associateId": "" }'
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success" }
```

***

### Excluir Grupo de Pessoas Específico

**Tópico**: Remove um grupo; use `mode=2` com cautela para remoção forçada.

* **Método**: `DELETE /acs/person-group/{orgCode}?mode=1`
* Query: `mode` (`1` = normal; `2` = força)
* Headers: `X-Subject-Token`

**Exemplo (curl):**

```bash
curl -X DELETE "http://{{host}}/obms/api/v1.1/acs/person-group/001004?mode=1" \
  -H "X-Subject-Token: {{loginToken}}"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success" }
```

***

### Listar Grupos de Pessoas

**Tópico**: Retorna todos os grupos disponíveis para associação de pessoas.

* **Método**: `GET /acs/person-group/list`
* Headers: `X-Subject-Token`

**Exemplo (curl):**

```bash
curl -X GET "http://{{host}}/obms/api/v1.1/acs/person-group/list" \
 -H "X-Subject-Token:{{Logintoken}}"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": [{ "orgCode": "001", "orgName": "Root" }] }
```

***

### Adicionar Pessoa

**Tópico**: Cria uma pessoa com dados básicos e opcionais de identificação. Suporta foto em Base64.

* **Método**: `POST /acs/person`
* Headers: `X-Subject-Token`, `Content-Type`

Campos principais:

| Campo                 | Tipo           | Obrigatório | Onde          | Descrição                    |
| --------------------- | -------------- | ----------- | ------------- | ---------------------------- |
| baseInfo.personId     | string         | SIM         | baseInfo      | ID único da pessoa           |
| baseInfo.firstName    | string         | SIM         | baseInfo      | Nome                         |
| baseInfo.gender       | string         | –           | baseInfo      | Código do gênero (ex.: "2")  |
| baseInfo.orgCode      | string         | SIM         | baseInfo      | Código do grupo principal    |
| baseInfo.orgCodes     | array\[string] | –           | baseInfo      | Lista de grupos              |
| baseInfo.tel          | string         | –           | baseInfo      | Telefone                     |
| baseInfo.facePictures | array\[string] | –           | baseInfo      | Imagens em Base64            |
| extensionInfo.idType  | string         | –           | extensionInfo | Tipo de documento (ex.: "6") |
| extensionInfo.idNo    | string         | –           | extensionInfo | Número do documento          |

**Body (exemplo):**

```json
{
  "baseInfo": {
    "personId": "{{newPersonId}}",
    "lastName": "",
    "firstName": "Mary Joanne",
    "gender": "0",
    "orgCode": "001",
    "orgCodes": [
      "001"
    ],
    "email": "",
    "tel": "",
    "remark": "",
    "source": "0",
    "facePictures": []
  },
  "extensionInfo": {
    "nickName": "",
    "address": "",
    "idType": "6",
    "idNo": "",
    "nationalityId": "9999",
    "birthday": "",
    "companyName": "",
    "department": "",
    "position": ""
  },
  "userDefineFields": [],
  "residentInfo": {
    "houseHolder": "0",
    "sipId": "",
    "vdpUser": "0"
  },
  "authenticationInfo": {
    "combinationPassword": "",
    "cards": [],
    "fingerprints": [],
    "startTime": "1703606400",
    "endTime": "2019311999"
  },
  "accessInfo": {
    "accessType": "0",
    "guestUseTimes": "200",
    "passageRuleIds": []
  },
  "faceComparisonInfo": {
    "enableFaceComparisonGroup": "0",
    "faceComparisonGroupId": ""
  },
  "entranceInfo": {
    "enableEntranceGroup": "0",
    "enableParkingSpace": "0",
    "parkingSpaceNum": "0",
    "vehicles": []
  }
}
```

**Exemplo (curl):**

```bash
curl -X POST "http://{{host}}/obms/api/v1.1/acs/person" \
  -H "X-Subject-Token: {{loginToken}}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{
{
  "baseInfo": {
    "personId": "16251244",
    "lastName": "",
    "firstName": "Mary Joanne",
    "gender": "0",
    "orgCode": "001",
    "orgCodes": [
      "001"
    ],
    "email": "",
    "tel": "",
    "remark": "",
    "source": "0",
    "facePictures": []
  },
  "extensionInfo": {
    "nickName": "",
    "address": "",
    "idType": "6",
    "idNo": "",
    "nationalityId": "9999",
    "birthday": "",
    "companyName": "",
    "department": "",
    "position": ""
  },
  "userDefineFields": [],
  "residentInfo": {
    "houseHolder": "0",
    "sipId": "",
    "vdpUser": "0"
  },
  "authenticationInfo": {
    "combinationPassword": "",
    "cards": [],
    "fingerprints": [],
    "startTime": "1703606400",
    "endTime": "2019311999"
  },
  "accessInfo": {
    "accessType": "0",
    "guestUseTimes": "200",
    "passageRuleIds": []
  },
  "faceComparisonInfo": {
    "enableFaceComparisonGroup": "0",
    "faceComparisonGroupId": ""
  },
  "entranceInfo": {
    "enableEntranceGroup": "0",
    "enableParkingSpace": "0",
    "parkingSpaceNum": "0",
    "vehicles": []
  }
}
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": "null"
```

***

### Atualizar o Cadastro de Uma Pessoa

**Tópico**: Atualiza dados cadastrais, janelas de validade e regras de acesso.

* **Método**: `PUT /acs/person/{personId}`
* Path Params: `personId`
* Headers: `X-Subject-Token`, `Content-Type`

**Body (exemplo enxuto):**

```json
{
  "baseInfo": {
    "personId": "00021088",
    "firstName": "ChenJing11",
    "orgCode": "001",
    "orgCodes": ["001"],
    "email": "user@example.com",
    "tel": "15350228989"
  },
  "authenticationInfo": {
    "startTime": "1726675200",
    "endTime":   "2042294399"
  },
  "accessInfo": {
    "accessType": "0",
    "guestUseTimes": "200",
    "passageRuleIds": []
  }
}
```

**Exemplo (curl):**

```bash
curl -X PUT "http://{{host}}/obms/api/v1.1/acs/person/00021088" \
  -H "X-Subject-Token: {{loginToken}}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{ "baseInfo": {"personId": "00021088", "firstName": "Mery Joanne", "orgCode": "001", "orgCodes": ["001"], "email": "user@example.com", "tel": "15350228989"}, "authenticationInfo": {"startTime": "1726675200", "endTime": "2042294399"}, "accessInfo": {"accessType": "0", "guestUseTimes": "200", "passageRuleIds": []} }'
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success" }
```

***

### Obter as Informações do Cadastro de Uma Pessoa

**Tópico**: Recupera o cadastro completo da pessoa por `personId`.

* **Método**: `GET /acs/person/{personId}`
* Headers: `X-Subject-Token`

**Exemplo (curl):**

```bash
curl -X GET "http://{{Host}}/obms/api/v1.1/acs/person/77421973" \
 -H "X-Subject-Token: {{LoginToken}}"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": { "personId": "77421973", "firstName": "Jack" } }
```

***

### Pesquisa Por Filtro de Pessoas (Página de Pesquisa)

**Tópico**: Lista com filtros e paginação. Use `page` (1-based) e `pageSize`.

* **Método**: `GET /acs/person/page`
* Query (exemplo): `page=1&pageSize=20&orgCode=001&containChild=0&personId=&cardNo=&personName=`

**Exemplo (curl):**

```bash
curl -G "http://{{host}}/obms/api/v1.1/acs/person/page" \
 -H "X-Subject-Token: {{LoginToken}}" \
 --data-urlencode "page=1" \
 --data-urlencode "pageSize=20" \
 --data-urlencode "orgCode=001" \
 --data-urlencode "containChild=0"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": { "total": 1, "list": [{"personId":"77421973"}] } }
```

***

### Pesquisa Rápida de Pessoas Cadastradas

**Tópico**: Versão otimizada para listagem; retorna apenas campos essenciais.

* **Método**: `GET /acs/person/summary/page`
* Query (exemplo): `faceIssueResult=&deviceCode=&page=1&accessTypes=&keyword=&orgCode=001&channelId=&pageSize=20&faceComparisonGroupId=`

**Exemplo (curl):**

```bash
curl -G "http://{{host}}/obms/api/v1.1/acs/person/summary/page" \
  -H "X-Subject-Token: {{loginToken}}" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=20" \
  --data-urlencode "orgCode=001"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": { "total": 1, "list": [{"personId":"77421973","firstName":"Jack"}] } }
```

***

### Excluir Pessoas em Lote

**Tópico**: Remove múltiplas pessoas por ID; use `mode` para controle da remoção.

* **Método**: `POST /acs/person/delete/batch`
* Headers: `X-Subject-Token`, `Content-Type`

**Body (JSON):**

```json
{ "personIds": ["00021088"], "mode": "1" }
```

**Exemplo (curl):**

```bash
curl -X POST "http://{{Host}}/obms/api/v1.1/acs/person/delete/batch" \
 -H "X-Subject-Token: {{LoginToken}}" \
 -H "Content-Type: application/json;charset=UTF-8" \
 -d '{"personIds":[21088],"mode":"1"}'
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success" }
```

***

### Obter Informações de Falha de Envio

**Tópico**: Identifica registros de pessoas que falharam ao serem propagados para dispositivos/serviços.

* **Método**: `GET /acs/person/authorize/failure/list`
* Query: `personIds=<ids separados por vírgula>&dataType=0`
* Headers: `X-Subject-Token`

**Exemplo (curl):**

```bash
curl -G "http://{{host}}/obms/api/v1.1/acs/person/authorize/failure/list" \
  -H "X-Subject-Token: {{loginToken}}" \
  --data-urlencode "personIds=91665028" \
  --data-urlencode "dataType=0"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": [{ "personId": "91665028", "reason": "timeout" }] }
```

***

### Reenvio dos Cadastros Com Falha

**Tópico**: Reprocessa o envio para casos listados em "Obter informações de falha de envio".

* **Método**: `POST /acs/person/authorize/failure/reissue`
* Headers: `X-Subject-Token`, `Content-Type`

**Body (JSON):**

```json
{ "personIds": ["91665028"], "dataType": "0" }
```

**Exemplo (curl):**

```bash
curl -X POST "https://{{Host}}/obms/api/v1.1/acs/person/authorize/failure/reissue" \
 -H "X-Subject-Token: {{LoginToken}}" \
 -H "Content-Type: application/json;charset=UTF-8" \
 -d '{"personIds":[91665028],"dataType":0}'
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success" }
```

***

### Obter os Eventos de Controle de Acesso Por Página

**Tópico**: Consulta eventos por intervalo temporal e retorna páginas com checkpoint (split) para paginação consistente.

* **Método**: `POST /acs/access/record/fetch/page`
* Headers: `X-Subject-Token`, `Content-Type`

**Body (JSON – exemplo):**

```json
{
  "page": 5,
  "pageSize": 20,
  "areaCodes": [],
  "startTime": "1702915200",
  "endTime": "1703001599",
  "eventLevels": ["1","2","3"],
  "orgCode": "",
  "pointId": "",
  "pointTypes": [],
  "currentPage": 2,
  "splitId": "32781022",
  "splitTime": "1702965112",
  "pointName": "",
  "personId": "",
  "personName": ""
}
```

**Exemplo (curl):**

```bash
curl -X POST "http://{{Host}}/obms/api/v1.1/acs/access/record/fetch/page" \
 -H "X-Subject-Token: {{LoginToken}}" \
 -H "Content-Type: application/json;charset=UTF-8" \
 -d '{"page":1,"pageSize":20,"startTime":1610928000,"endTime":1611014400}'
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": { "total": 20, "list": [ { "id": "2024071200000000006" } ] } }
```

***

### Obter o Histórico de Eventos de Controle de Acesso

**Tópico**: Retorna informações completas de um evento de controle de acesso.

* **Método**: `GET /acs/access/record/{id}`
* Path Params: `id`
* Headers: `X-Subject-Token`

**Exemplo (curl):**

```bash
curl -X GET "http://{{host}}/obms/api/v1.1/acs/access/record/2024071200000000006" \
  -H "X-Subject-Token: {{loginToken}}"
```

**Resposta (modelo – sucesso):**

```json
{ "code": 1000, "msg": "success", "data": { "id": "2024071200000000006", "eventLevel": "1" } }
```

***

### Fluxos sugeridos

{% stepper %}
{% step %}

#### Fluxo A — Cadastro completo

* Criar grupo.
* Criar pessoa vinculando `orgCode`.
* Validar com Listar pessoas.
* Consultar exceções e, se houver, Reenviar.
  {% endstep %}

{% step %}

#### Fluxo B — Auditoria de acessos

* Listar eventos com intervalo de tempo.
* Abrir detalhe para investigação.
* Ajustar cadastros se necessário.
  {% endstep %}
  {% endstepper %}

***

### Troubleshooting (checklist rápido)

* 401/403: confirme `X-Subject-Token` e o escopo/permissão.
* 415: verifique `Content-Type`.
* 400: valide campos obrigatórios; envie JSON válido.
* Paginação: mantenha `page` e `pageSize` consistentes; em eventos, preserve `splitId`/`splitTime` quando fornecidos.
* Base64: garanta que a imagem não excede limites definidos pelo seu ambiente.

***

Notas Finais:

* Este é um modelo com respostas exemplificadas.
* Ajuste mensagens, campos e exemplos de acordo com o comportamento real do seu ambiente e com a documentaçã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-pessoas.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.