> 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-visitantes.md). # Gestão de Visitantes Guia de endpoints de Visitantes (API Defense IA): listagem/filtros, detalhe, criação/atualização, geração de QR/cartão, histórico e baixa de vencidos, com exemplos curl/Python e convenções. > Endpoints da função **Visitante**. Este arquivo serve apenas como **modelo**, devendo ser adaptado conforme o seu ambiente (ajuste nomes, exemplos e campos necessários). > > Observação: a funcionalidade de **contagem de visitantes não está incluída**. *** ### 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.1/visitors` (alguns endpoints podem utilizar apenas `/obms/api/v1.1/` dependendo da rota) * 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 | *** ### Listar Visitantes Com Filtros e Paginação **Tópico**: Lista visitantes por intervalo e status; ordenação por `direction` e `orderType`. * **Método**: `GET /visitors/visitor/page` * **Headers**: `X-Subject-Token` * Query (exemplo): `direction=1&orderType=0&startTime=1689004800&endTime=1689177600&timeType=-1&page=1&pagesize=20&key=&status=-1` **Exemplo (curl):** ```powershell curl -G "http://{{host}}/obms/api/v1.0/visitors/visitor/page" -H "X-Subject-Token: {{loginToken}}" --data-urlencode "direction=1" --data-urlencode "orderType=0" --data-urlencode "startTime=1689004800" --data-urlencode "endTime=1689177600" --data-urlencode "timeType=-1" --data-urlencode "page=1" --data-urlencode "pagesize=20" --data-urlencode "key=" --data-urlencode "status=-1" ``` {% hint style="info" %} Retire as `{{}}` após inserir o LoginToken {% endhint %} Exemplo (Python): ```python client = DefenseIAClient(host="{{host}}", token="{{loginToken}}") params = { "direction": 1, "orderType": 0, "startTime": 1689004800, "endTime": 1689177600, "timeType": -1, "page": 1, "pagesize": 20, "key": "", "status": -1, } page, _ = client.request("GET", "/visitors/visitor/page", params=params) print(page) ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success", "data": { "total": 1, "list": [{"visitorId": "3"}] } } ``` *** ### Obter Visitante Por ID **Tópico**: Retorna as informações completas de um visitante específico a partir do seu ID. * **Método**: `GET /visitors/visitor/{id}` * **Headers**: `X-Subject-Token` **Exemplo (curl):** ```powershell curl -X GET "http://{{host}}/obms/api/v1.0/visitors/visitor/3" -H "X-Subject-Token: {{loginToken}}" ``` {% hint style="info" %} Verifique se o servidor utiliza HTTPS. Se sim, altere a URL no `curl` para `https://` e adicione `-k` ao final do comando. {% endhint %} > Essa opção pode ser usada em todos os exemplos para ignorar a verificação do certificado SSL (recomendada apenas em ambientes de teste). **Exemplo (Python):** ```python data, _ = client.request("GET", "/visitors/visitor/3") print(data) ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success", "data": { "visitorId": "3", "visitorName": "Lily" } } ``` *** ### Criar Visitante **Tópico**: Cadastra um visitante e (opcionalmente) define credenciais e permissões. #### **Parâmetros (Body JSON — principais)** | Campo | Tipo | Obrig. | Descrição | | -------------------------- | -------------: | :----: | ----------------------------------------- | | status | string | ✳️ | Status do agendamento/visita (ex.: `"1"`) | | visitorName | string | ✳️ | Nome do visitante | | visitedName | string | ✳️ | Pessoa a ser visitada | | visitedEmail | string | – | E‑mail do visitado | | idType | string | – | Tipo de documento (ex.: `"0"`) | | idNum | string | – | Número do documento | | tel | string | – | Telefone | | email | string | – | E‑mail do visitante | | expectArrivalTime | string | – | Chegada esperada (epoch) | | arrivalTime | string | – | Chegada efetiva (epoch) | | expectLeaveTime | string | – | Saída esperada (epoch) | | leaveTime | string | – | Saída efetiva (epoch) | | plateNo | string | – | Placa do veículo | | reason | string | – | Motivo | | remark | string | – | Observações | | authInfo.sipId | string | – | Extensão/interfone | | authInfo.cardNo | string | – | Número de cartão | | authInfo.qrcode | string | – | Dado do QR (gerado/atribuído) | | authInfo.passportCardNo | string | – | Documento do passe | | authInfo.facePictures\[] | array\[b64] | – | Fotos em Base64 | | authInfo.idPicture | string(b64) | – | Foto do documento (Base64) | | rightInfo.acsChannelIds\[] | array\[string] | – | Canais ACS autorizados | | rightInfo.vtoChannelIds\[] | array\[string] | – | Canais de interfone/VTO | | rightInfo.positionIds\[] | array\[string] | – | Perfis/cargos vinculados | | rightInfo.liftChannels\[] | array\[obj] | – | Acesso a elevadores | **Body (exemplo):** ```json { "status": "1", "visitorName": "Lily", "visitorOrgName": "", "visitedName": "Amy", "visitedOrgName": "", "visitedEmail": "test@test.com", "idType": "0", "idNum": "340521199504214011", "tel": "13170055715", "email": "test@qq.com", "expectArrivalTime": "0", "arrivalTime": "1689161208", "expectLeaveTime": "1689168408", "leaveTime": "0", "plateNo": "A987123", "reason": "", "remark": "", "authInfo": { "sipId": "1#1#102", "cardNo": "0C987123", "qrcode": "r0xnZASOmIg=", "passportCardNo": "ACA09EBB", "facePictures": [""], "idPicture": "" }, "rightInfo": { "acsChannelIds": ["1000001$7$0$0"], "vtoChannelIds": ["1000023$7$0$0"], "positionIds": ["1"], "liftChannels": [] } } ``` **Exemplo (curl):** ```powershell curl -X POST "http://{{host}}/obms/api/v1.0/visitors/visitor" -H "X-Subject-Token: {{loginToken}}" -H "Content-Type: application/json;charset=UTF-8" -d '{ "status": "1", "visitorName": "Lily", "visitedName": "Amy", "idType": "0", "idNum": "340521199504214011", "tel": "13170055715", "email": "test@qq.com", "arrivalTime": "1689161208", "expectLeaveTime": "1689168408", "authInfo": {"sipId": "1#1#102", "cardNo": "0C987123", "qrcode": "r0xnZASOmIg=", "passportCardNo": "ACA09EBB", "facePictures": [""]}, "rightInfo": {"acsChannelIds": ["1000001$7$0$0"], "vtoChannelIds": ["1000023$7$0$0"], "positionIds": ["1"], "liftChannels": []} }' ``` **Exemplo (Python):** ```python payload = { "status": "1", "visitorName": "Lily", "visitedName": "Amy", "idType": "0", "idNum": "340521199504214011", "tel": "13170055715", "email": "test@qq.com", "expectArrivalTime": "0", "arrivalTime": "1689161208", "expectLeaveTime": "1689168408", "leaveTime": "0", "plateNo": "A987123", "reason": "", "remark": "", "authInfo": {"sipId": "1#1#102", "cardNo": "0C987123", "qrcode": "r0xnZASOmIg=", "passportCardNo": "ACA09EBB", "facePictures": [""], "idPicture": ""}, "rightInfo": {"acsChannelIds": ["1000001$7$0$0"], "vtoChannelIds": ["1000023$7$0$0"], "positionIds": ["1"], "liftChannels": []} } created, _ = client.request("POST", "/visitors/visitor", json=payload) print(created) ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success", "data": { "visitorId": "123" } } ``` *** ### Atualizar Visitante **Tópico**: Atualiza os dados de um visitante já cadastrado, incluindo informações pessoais, período da visita e permissões de acesso. * **Método**: `PUT /visitors/visitor/{id}` * **Headers**: `X-Subject-Token, Content-Type` * Body: mesmos campos do Add; incluir `visitorId` se requerido. **Exemplo (curl):** ```powershell curl -X PUT "http://{{host}}/obms/api/v1.0/visitors/visitor/3" -H "X-Subject-Token: {{loginToken}}" -H "Content-Type: application/json;charset=UTF-8" -d '{ "visitorId": "1", "status": "1", "visitorName": "Lily", "visitedName": "Amy", "arrivalTime": "1615947987", "expectLeaveTime": "1615955187", "authInfo": {"sipId": "1#1#102", "cardNo": "0C987123", "qrcode": "a+PcZsF7BWo=", "passportCardNo": "AC54FFDA", "facePictures": [], "idPicture": ""}, "rightInfo": {"acsChannelIds": ["1000174$7$0$0"], "vtoChannelIds": ["1000158$7$0$0", "1000158$7$0$1"], "positionIds": ["1"], "liftChannels": [{"channelId": "1000000$50$0$0", "floors": "1,2,3"}]} }' ``` **Exemplo (Python):** ```python update = { "visitorId": "1", "status": "1", "visitorName": "Lily", "visitedName": "Amy", "arrivalTime": "1615947987", "expectLeaveTime": "1615955187", "authInfo": {"sipId": "1#1#102", "cardNo": "0C987123", "qrcode": "a+PcZsF7BWo=", "passportCardNo": "AC54FFDA", "facePictures": [], "idPicture": ""}, "rightInfo": {"acsChannelIds": ["1000174$7$0$0"], "vtoChannelIds": ["1000158$7$0$0", "1000158$7$0$1"], "positionIds": ["1"], "liftChannels": [{"channelId": "1000000$50$0$0", "floors": "1,2,3"}]} } _, raw = client.request("PUT", "/visitors/visitor/3", json=update) print(raw["msg"]) # success ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success" } ``` *** ### Gerar Dados de QR e Número de Cartão **Tópico**: Gera automaticamente um **QR Code** e um **número de cartão** para uso no cadastro ou atualização de visitantes. * **Método**: `GET /visitors/visitor/passport/generate` * **Headers**: `X-Subject-Token` **Exemplo (curl):** ```powershell curl -X GET "http://{{host}}/obms/api/v1.0/visitors/visitor/passport/generate" -H "X-Subject-Token: {{loginToken}}" ``` **Exemplo (Python):** ```python data, _ = client.request("GET", "/visitors/visitor/passport/generate") print(data) # exemplo: {"qrcode": "...", "cardNo": "..."} ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success", "data": { "qrcode": "....", "cardNo": "0C987123" } } ``` *** ### Listar Histórico de Visitas em Páginas **Tópico**: Retorna a lista de histórico de visitas de forma paginada. * Base: `http://{{host}}/obms/api/v1.1` * **Método**: `GET /visitor/history/record/page` * **Headers**: `X-Subject-Token` * Query (exemplo): `cardNo=&idNo=&tel=&visitorName=&page=1&endTime=1615823999&visitedCompany=&startTime=1615737600&status=-1&visitedName=&pageSize=20&email=¤tPage=&splitId=` **Exemplo (curl):** ```powershell curl -G "http://{{host}}/obms/api/v1.1/visitor/history/record/page" -H "X-Subject-Token: {{loginToken}}" --data-urlencode "page=1" --data-urlencode "pageSize=20" --data-urlencode "startTime=1615737600" --data-urlencode "endTime=1615823999" --data-urlencode "status=-1" ``` **Exemplo (Python):** ```python client_v11 = DefenseIAClient(host="{{host}}", token="{{loginToken}}", base_path="/obms/api/v1.1") params = {"page": 1, "pageSize": 20, "startTime": 1615737600, "endTime": 1615823999, "status": -1} page, _ = client_v11.request("GET", "/visitor/history/record/page", params=params) print(page) ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success", "data": { "total": 10, "list": [{"visitorId": "3"}] } } ``` *** ### Dar Baixa em Visitantes Vencidos **Tópico**: Finaliza os registros de visitantes cujo período de autorização já expirou. * **Método**: `POST /visitors/visitor/overdue/clear` * **Headers**: `X-Subject-Token, Content-Type` * Body (JSON): `{ "visitorIds": ["1"] }` **Exemplo (curl):** ```powershell curl -X POST "http://{{host}}/obms/api/v1.0/visitors/visitor/overdue/clear" -H "X-Subject-Token: {{loginToken}}" -H "Content-Type: application/json;charset=UTF-8" -d '{"visitorIds":["1"]}' ``` **Exemplo (Python):** ```python payload = {"visitorIds": ["1"]} _, raw = client.request("POST", "/visitors/visitor/overdue/clear", json=payload) print(raw["msg"]) # success ``` **Resposta (modelo – sucesso):** ```json { "code": 1000, "msg": "success" } ``` *** ### Fluxos sugeridos {% stepper %} {% step %} #### Fluxo A — Agendamento e acesso * Gerar dados de QR/cartão (2.5) se necessário. * Criar visitante (2.3) com `authInfo`/`rightInfo`. * Conferir listagem (2.1) e detalhe (2.2). * Histórico (2.7) para auditoria. {% endstep %} {% step %} #### Fluxo B — Encerramento em massa * Obter página de visitantes (2.1) e/ou histórico (2.7). * Dar baixa nos vencidos (2.8). {% endstep %} {% endstepper %} *** ### Troubleshooting (checklist) * 401/403: valide `X-Subject-Token`. * 400: reveja campos obrigatórios (ex.: `visitorName`, `visitedName`, datas). * Base64: confirme tamanho/formato das imagens em `authInfo.facePictures`/`idPicture`. * Paginação: use `page/pagesize` coerentes; em histórico, preserve `currentPage/splitId` se aplicável. *** Notas finais: * Este é um modelo com payloads de exemplo; ajuste aos seus retornos reais. * Alguns endpoints usam `v1.1` (histórico), os demais `v1.0`. * Mantenha coerência com as práticas do seu ambiente (token já disponível). --- # 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-visitantes.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.