> 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/cameras-and-gravadores/integracao-api-cftvip-e-mibo/cameras-e-gravadores/fluxo-de-trafego.md). # Fluxo de Tráfego Integração de fluxo de tráfego: evento TrafficFlowStat e consulta histórica TrafficFlow. ## Dicas & Boas Práticas * Utilize **apenas um tipo de fonte por tarefa** (LocalStream, RemoteStream, VideoFile ou PictureFile) para evitar conflitos de processamento. * Endpoints com **streaming multipart** mantêm conexão persistente, o cliente deve suportar leitura contínua de dados. * Sempre trate o **Heartbeat** para manter sessões vivas e evitar timeout. * Teste regras, filtros e modelagens em **ambiente controlado** antes de produção. * Libere recursos encerrando pesquisas com **stopFind** após uso do token. * Operações assíncronas (multiAppend, reAbstract, groupReAbstract) devem ser acompanhadas por **status/token**. * Verifique **capacidade de armazenamento** antes de importar grandes volumes de imagens. * Padronize timestamps em **UTC** para evitar divergências de busca. * Garanta qualidade/dimensões adequadas das imagens, modelagem falha é frequentemente causada por resolução inválida. *** ### Possíveis Erros | Código HTTP | Descrição | Possível Causa | | ----------- | --------------------- | --------------------------------------- | | 400 | Bad Request | Parâmetro inválido ou formato incorreto | | 401 | Unauthorized | Falha de autenticação | | 403 | Forbidden | Permissão insuficiente | | 404 | Not Found | Endpoint incorreto ou token inválido | | 500 | Internal Server Error | Erro interno do equipamento | *** ### Padrões de Formato de Resposta * Eventos → multipart + key=value * recordFinder → key=value * trafficFlowStat API → JSON *** ### \[Evento] TrafficFlowStat **Tópico:** O evento **TrafficFlowStat** é gerado automaticamente quando o sistema conclui um ciclo de estatística de fluxo de tráfego. #### Ciclo de Vida do Token (Token Lifecycle) A API `trafficFlowStat` utiliza um mecanismo baseado em **token temporário** para controle de paginação e alocação de recursos internos. #### Fluxo 1. `startFind` → Gera um **token** e retorna `totalCount` 2. `doFind` → Consulta dados utilizando o token 3. `stopFind` → Finaliza a pesquisa e libera recursos #### Regras Importantes * O **token é obrigatório** para chamadas `doFind` e `stopFind`. * O token é **válido apenas para a sessão atual**. * Recomenda-se chamar `stopFind` após concluir a paginação. * Caso `stopFind` não seja chamado, o sistema poderá liberar o token automaticamente após timeout interno. * Não reutilizar token antigo para nova pesquisa. * Múltiplos tokens simultâneos podem impactar desempenho do equipamento. *** **Condição de Disparo** O evento é acionado quando: * O período estatístico configurado é concluído * Existe pelo menos um registro de veículo no período * A regra de fluxo está habilitada **Código do evento** `TrafficFlowStat` **Ações do Evento** `Pulse (Evento Periódico)` Observação: normalmente utilizado como evento periódico. ### **Parâmetros do evento**
NomeTipoR/ODescriçãoExemplo
+FlowStatesobject[]RLista de informações de fluxo de tráfego. Cada objeto da lista representa os dados de fluxo de uma faixa (lane).—
++LaneintRNúmero da faixa. A contagem inicia em 0.0
++FlowintRQuantidade de veículos detectados no período estatístico.50
++PeriodintRTempo estatístico do fluxo. Unidade: minuto(s).5
++PeriodByMiliintOTempo estatístico do fluxo em milissegundos. Valor deve estar entre 0 e 59999.655
++DrivingDirectionchar[][]ODireção de circulação. Deve ser um array contendo três strings:1ª: Direção ("Approach" ou "Leave")2ª: Nome da posição de aproximação3ª: Nome da posição de saída["Approach", "XXXCity", "YYYCity"]
#### DrivingDirection (estrutura interna) | Posição | Significado | | ------- | -------------------------- | | 1 | "Approach" ou "Leave" | | 2 | Nome da posição de origem | | 3 | Nome da posição de destino | **Exemplo:** ``` ["Approach", "Centro", "ZonaSul"] ``` **Estrutura do Campo DrivingDirection** O campo `DrivingDirection` é um array composto por **três strings**, com a seguinte estrutura: ``` [ TipoDirecao, Origem, Destino ] ``` **Estrutura** | Posição | Descrição | | --------- | ------------------------------------------ | | 1ª string | Tipo de direção: `"Approach"` ou `"Leave"` | | 2ª string | Nome configurado da posição de aproximação | | 3ª string | Nome configurado da posição de saída | **Valores possíveis** * `"Approach"` → Veículo aproximando-se da referência * `"Leave"` → Veículo afastando-se da referência **Exemplo** ``` ["Approach", "Centro", "ZonaSul"] ``` Neste exemplo: * O veículo está se aproximando * Origem: Centro * Destino: ZonaSul **Exemplo Resposta (Sucesso):** ```powershell -- Content-Type: text/plain Content-Length: xxxx Code=TrafficFlowStat;action=Pulse;index=0;data={ "FlowStates": [ { "Lane": 0, "Flow": 50, "Period": 5, "DrivingDirection": [ "Approach", "XXXCity", "YYYCity"] }, {…}, … ] } -- ``` *** ### Consultar Registros Históricos **Tópicos:** Consulta simples de registros históricos. **Métodos:** `GET /cgi-bin/recordFinder.cgi?action=find` #### Parâmetros do evento
NomeTipoObrigatórioDescrição
namestringRDeve ser "TrafficFlow"
countintOMáximo de registros (padrão 1024)
StartTimestringOInício do período
EndTimestringOFim do período
condition.ChannelintOCanal (inicia em 0)
condition.LaneintOFaixa (inicia em 0)
**Exemplo:** ```http http:///cgi-bin/recordFinder.cgi?action=find&name=TrafficFlow&condition.Channel=0&con dition.Lane=0&StartTime=123456700&EndTime=123456800&count=100 ``` **Resposta**: ```http totalCount=1000 found=100 records[0].RecNo=12345 records[0].CreateTime=123456789 records[0].StaticsticsTime=123456789 records[0].Period=300 records[0].Channel=0 records[0].Lane=0 records[0].Vehicles=250 records[0].AverageSpeed=25.4 … records[1].RecNo=13579 records[1].CreateTime=123456799 records[1].StaticsticsTime=123456799 records[1].Period=300 records[1].Channel=0 records[1].Lane=0 records[1].Vehicles=220 records[1].AverageSpeed=21.8 … ``` ### Estrutura da Resposta Formato: key=value | Campo | Tipo | Descrição | | ---------- | --------- | ------------------ | | totalCount | int | Total encontrado | | found | int | Total retornado | | records | object\[] | Lista de registros | *** ### Iniciar Pesquisa Estatística de Tráfego **Tópico**: Inicia pesquisa de estatística de tráfego. **Métodos:** `POST /cgi-bin/api/trafficFlowStat/startFind` **Exemplo de Requisição** ```json { "condition": { "StartTime": "2026-03-03 00:00:00", "EndTime": "2026-03-03 23:59:59", "Channel": 0, "Lane": 0, "Lanes": [0], "ClassType": 1, "Granularity": "Hour", "PresetID": [1], "Direction": "Both", "Channels": [0,1,2,5] } } ``` ### Parâmetros (JSON) Campo obrigatório: | Campo | Tipo | Descrição | | --------- | -------- | ------------------- | | StartTime | datetime | Início (hora cheia) | | EndTime | datetime | Fim | | Channels | int\[] | Lista de canais | Campos opcionais: * Channel * Lane * Lanes * ClassType (0 = metadata vídeo, 1 = monitoramento rodoviário) * Granularity ("Minute", "Hour", "Day", "Month") * PresetID * Direction ("Both", "LeftToRight", "RightToLeft") **Exemplo Resposta (Sucesso):** ```json { "token": 2342343, "totalCount": 333 } ``` *** ### Obter Estatísticas de Tráfego **Tópico:** Entrega estatísticas de tráfego **Métodos:** `POST /cgi-bin/api/trafficFlowStat/doFind` ### Parâmetros do evento | Campo | Tipo | Descrição | | ----------- | ---- | ----------------------- | | token | uint | Token da pesquisa | | beginNumber | uint | Índice inicial | | count | uint | Quantidade por consulta | **Exemplo Requisição** ```json { "token": 46878, "beginNumber": 0, "count": 24 } ``` **Exemplo Resposta (Sucesso):** ```json { "found": 12, "info": [{ "PresetID" : 1 "DrivingDirection" : ["Approach", "XXXCity", "YYYCity"], "Lane" : 1, "MachineAddress" : "XXX District, YYY Road", "MachineName" : "Device001", "UTC" : 1465389203, "UTCMS" : 123, …… },…{}] } ``` *** ### Encerrar Pesquisa Estatística de Tráfego **Tópico**: Finaliza pesquisa e libera recursos. **Métodos:** `POST /cgi-bin/api/trafficFlowStat/stopFind` ### Parâmetros do Evento | Campo | Tipo | Obrigatório | | ----- | ---- | ----------- | | token | uint | Sim | **Exemplo requisição:** ```json { "token": 46878 } ``` **Exemplo de resposta:** ``` {} ``` *** ### Fluxo Completo de Uso 1. startFind → recebe token 2. doFind → pagina resultados 3. repetir doFind até concluir 4. stopFind → encerra pesquisa *** ### Diferença entre Consulta Simples e Pesquisa Estruturada | Consulta Simples (recordFinder) | Pesquisa Estruturada (trafficFlowStat API) | | ------------------------------- | ------------------------------------------ | | GET | POST | | key=value | JSON | | Busca direta | Busca com token | | Limite fixo | Paginação estruturada | | Mais simples | Mais flexível | *** Notas Finais: * **Separação entre Evento e Consulta Histórica**\ O `TrafficFlowStat` pode ser utilizado de duas formas distintas: * **Evento em tempo real** → Notificação automática ao final de cada período estatístico. * **Consulta histórica** → Recuperação manual de dados através de `recordFinder` ou da API `trafficFlowStat`. * **Escolha do Método de Consulta** * Utilize `recordFinder` para consultas simples e diretas. * Utilize a API `trafficFlowStat (startFind / doFind / stopFind)` para consultas estruturadas, com paginação e filtros avançados. * **Gerenciamento de Token** * Sempre finalize pesquisas utilizando `stopFind`. * Não reutilize tokens antigos. * Evite múltiplas pesquisas simultâneas desnecessárias. * Tokens não encerrados podem consumir recursos do equipamento até expiração automática. * **Formatação e Parsing**\ A API utiliza diferentes formatos de resposta: * Eventos → `multipart` com `key=value` * recordFinder → `key=value` * trafficFlowStat API → `JSON` A aplicação cliente deve implementar tratamento adequado para cada formato. * **Padrão de Tempo** * Campos `UTC`, `StartParking`, `StaticsticsTime` utilizam epoch UTC em segundos. * `UTCMS` representa milissegundos adicionais. * `StartTime` e `EndTime` utilizam formato `"YYYY-MM-DD HH:mm:ss"`.\ Recomenda-se manter todos os dados internamente em UTC. * **DrivingDirection**\ O campo `DrivingDirection` segue a estrutura: ``` [ TipoDirecao, Origem, Destino ] ``` Onde os valores dependem da configuração do equipamento. * **Dependência de Configuração**\ A geração de eventos e dados estatísticos depende de: * Regra de fluxo habilitada * Canal configurado corretamente * Faixa (Lane) ativa * Período estatístico definido * **Variação por Firmware**\ A disponibilidade de parâmetros pode variar conforme: * Modelo do equipamento * Versão do firmware * Licenciamento ativo * **Desempenho e Boas Práticas** * Evitar paginações excessivas com `count` muito elevado. * Controlar reconexões em eventos multipart. * Validar sempre campos retornados antes de processar. * Testar consultas extensas em ambiente controlado antes de uso em produçã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/cameras-and-gravadores/integracao-api-cftvip-e-mibo/cameras-e-gravadores/fluxo-de-trafego.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.