API – Tracks (movimentações)

Visão Geral

O endpoint tracks da API REST do sistema Observa é utilizado para registrar eventos de movimentação de pessoas em locais monitorados por antenas. Cada antena instalada em um ambiente é identificada por um endereço MAC exclusivo, e é responsável por captar sinais de tags (dispositivos ou identificadores) carregadas por pessoas.

Esses eventos indicam se uma pessoa entrou ou saiu de um determinado local, permitindo ao sistema calcular automaticamente o tempo de permanência em cada ambiente. A cada requisição ao endpoint tracks, é possível enviar múltiplos eventos de movimentação, inclusive de diferentes tags, otimizando a integração com sistemas de monitoramento em tempo real.

Autenticação

Este endpoint requer autenticação via Bearer Token. O token deve ser enviado no cabeçalho da requisição HTTP:

Key	Value
Authorization	Bearer <seu_token_de_acesso>
Content-Type	application/json

Token deve ser solicitado à Observa. Entre em contato com o suporte.

URL

Ambiente	Url
Produção	https://dash.observa.app/api/v1
Testing	https://testing.observa.app/api/v1

Detalhes do Endpoint

• URL: /tracks
• Método HTTP: POST
• Autenticação: Obrigatória (Bearer Token)
• Content-Type: application/json

Estrutura da Requisição

A requisição deve conter um corpo JSON com a seguinte estrutura:

{
    "mac_address": "21:52:A4:9B:02:9B",
    "events": [
        {
            "timestamp": "2025-06-21T18:27:05Z",
            "tag": "80689400004022E994DC18"
        },
        {
            "timestamp": "2025-06-21T20:27:05Z",
            "alive": true,
            "tag": "80699500004009C4D40D7A"
        },
        {
            "timestamp": "2025-06-21T19:27:05Z",
            "alive": true,
            "tag": "00471747A06026604E0108"
        }
    ]
}

Campos da Requisição

Campo	Tipo	Obrigatório	Descrição
mac_address	string	Sim	Endereço MAC da antena que captou os eventos. Representa o local físico.
events	array	Sim	Lista de eventos de movimentação detectados. Cada evento representa a leitura de uma tag.

Estrutura de Cada Evento

Campo	Tipo	Obrigatório	Descrição
timestamp	string	Sim	Data e hora em que o evento foi registrado, no formato ISO 8601 (UTC).
tag	string	Sim	Identificador único da tag associada à pessoa.

Lógica de Funcionamento

• Cada antena instalada em um ambiente possui um endereço MAC exclusivo.
• Cada vez que uma tag é identificada no ambiente, a antena armazena internamente o id e o último momento que a tag foi capturada. A cada 5 segundos esses dados devem ser enviados para a API e então esse buffer das tags é eliminado caso o retorno da API seja 200.

Validações

O servidor realiza as seguintes validações antes de processar os dados:

1. Endereço MAC: deve estar no formato válido (XX:XX:XX:XX:XX:XX). Endereços mal formatados são rejeitados.
2. Formato dos eventos: cada item da lista events deve conter todos os campos obrigatórios com valores válidos.
3. Tags: o sistema pode verificar se as tags estão cadastradas ou seguem padrões esperados, de acordo com a configuração interna.

Considerações Finais

O endpoint tracks é essencial para o funcionamento do sistema Observa, possibilitando o rastreamento eficiente da movimentação de pessoas em ambientes físicos. Através da combinação de eventos enviados por antenas com endereços MAC e as leituras de tags, o sistema pode gerar relatórios de presença, calcular tempos de permanência e apoiar processos operacionais e de segurança.

A correta utilização do endpoint, com envio estruturado e autenticação adequada, é fundamental para a integridade e confiabilidade dos dados registrados.