API - Dispositivos de Controle de Acesso Corporativo

Bem-vindo à documentação da API da linha de acesso da Intelbras. Esta API tem como objetivo fornecer informações e orientações sobre como integrar com os dispositivos de acesso da Intelbras.

Nossos equipamentos de acesso possuem uma interface de comunicação baseada em TCP/IP (Ethernet), tornando a integração simples e independente do sistema operacional e da linguagem de programação utilizados. Neste documento, você encontrará todos os detalhes necessários para utilizar a API e integrar facilmente com nossos dispositivos de acesso.

Dispositivos da Linha Bio-T que suportam a API:

Padrão de Sintaxe Utilizada

A sintaxe da API deve seguir o padrão de URI (RFC 3986 Uniform Resource Identifiers (URI) Generic Syntax).

protocolo: Valor padrão suportado pela API é o "http". Existem exceções apenas em algumas chamadas RTSP que usando o valor "RTSP".

servidor: O servidor é definido por "hostname:porta". O nome do host pode ser o endereço IP ou o nome de domínio de um dispositivo IP. A porta é o número da porta de conexão TCP configurada no dispositivo. Se a porta não for configurada, a porta 80 utilizada.

abs_path: O Request-URI para os recursos é abs_path. O abs_path nesta especificação é na maioria das vezes "/cgi-bin/*.cgi".

query: O campo query é uma string de informações a ser interpretada pelo dispositivo. Consiste em parâmetros relacionados ao recurso sendo requisitado. Deve ser informado seguindo a sintaxe nome=valor. Por exemplo: channel=1 (http://192.168.1.108/cgi-bin/snapshot.cgi?channel=1 (opens in a new tab))

Formato de respostas

O servidor usa os códigos de status HTTP padrão. Com o seguinte código HTTP e significados:

Se o código HTTP for 200, significa que a API foi executada com sucesso e os dados de resposta no corpo HTTP (multipart) pode ser uma multiline key=value de valor ou um objeto JSON ou apenas uma linha com uma palavra "OK"

Alguns dispositivos em suas versões mais recentes, podem retornar no corpo da resposta a requisição alguns códigos de erro verifique a página Códigos de Erros de Requisição

Autenticação

Os dispositivos possuem suporte digest authentication, consulte RFC 2617 (RFC 2617 HTTP Authentication)

A autenticação Digest é um esquema de autenticação baseado em desafio-resposta que permite que um cliente se autentique com um servidor web protegido por senha.

Quando um cliente faz uma solicitação HTTP para um recurso protegido por autenticação Digest, o servidor web responde com um código de status HTTP 401, indicando que o acesso não é permitido sem autenticação. Junto com o código de status 401, o servidor também envia um cabeçalho "WWW-Authenticate" contendo informações sobre a proteção utilizada para a senha, bem como um desafio aleatório.

O cliente responde ao desafio enviando um cabeçalho "Authorization" contendo as credenciais de autenticação criptografadas, juntamente com informações sobre o desafio e outras informações necessárias. O servidor web verifica se as credenciais estão corretas e, se estiverem, retorna um código de status HTTP 200, indicando que o acesso ao recurso foi permitido.

O motivo pelo qual o servidor web envia um código de status HTTP 401 antes de enviar o código de status HTTP 200 é que o cliente precisa ser informado de que a autenticação é necessária antes de enviar as credenciais de autenticação criptografadas. O código de status HTTP 401 é usado para indicar que o acesso ao recurso é negado sem autenticação.

Em resumo, a sequência de códigos de status HTTP 401 seguido por um código de status HTTP 200 é um comportamento padrão na autenticação Digest para permitir que o cliente se autentique com o servidor web protegido por senha

Exemplo de Autenticação:

import requests
 
device_ip = '192.168.1.201'
username = 'admin'
password = 'admin12345'
 
url = "http://{}/cgi-bin/global.cgi?action=getCurrentTime".format(
                                    str(ip)
                                )
digest_auth = requests.auth.HTTPDigestAuth(username, passwd)
rval = requests.get(url, auth=digest_auth, timeout=20, verify=False)

Biblioteca Postman

Recomendamos a execução das chamadas de teste da API utilizando um software client rest como Insomnia (opens in a new tab) ou Postman (opens in a new tab) antes de encapsular em seu software.

Para facilitar a integração foi realizado o mapeamento das principais chamadas na ferramenta Postman, possibilitando importar as chamadas e realizar os testes, disponível através do link: DOWNLOAD POSTMAN COLLECTIONS (opens in a new tab)