Plataforma de desenvolvedor

Aproveite o que já existe.
Plataforma de Conexão

Duas APIs poderosas — uma API de servidor RESTful para gerenciamento de dispositivos e orquestração de comunicação, e um protocolo CBBP de baixo nível para controle direto de crachás.

Referência da API RESTProtocolo CBBP
OpenAPI 3.0JSON / RESTBluetooth + Wi-FiSuporte a Webhooks
Connection Studio
Explorer
examples
send_command.http
response.json
list_devices.http
webhooks.http
src
docs
send_command.http
response.json
# Send a CBBP command via the server
POST /api/v1/devices/{uuid}/cbbp

{
  "command": "speak",
  "object": {
    "text": "Shift starts in 5 minutes",
    "volume": 85,
    "language": "en-US"
  }
}

# Response
{
  "result": 0,
  "detail": "ok"
}
main
HTTPUTF-8Ln 2, Col 1

API REST

Gerenciamento completo do ciclo de vida do dispositivo — provisionamento, configuração, firmware, comunicações e análises — via HTTPS padrão.

Explore a API REST →

Protocolo CBBP

Protocolo Básico Com Badge — um protocolo de comando JSON para controle direto de dispositivos via Bluetooth (aplicativo), Wi-Fi (proxy de servidor) ou despacho local.

Explore CBBP →

Webhooks

Assine para receber eventos de dispositivos em tempo real — comunicações, alterações de status, atualizações de localização — entregues como payloads HTTP POST em seu endpoint.

Explorar Webhooks →

Early Access: The Connection API is currently available by special request to select partners. Contact us to apply for access.

Pro or Plus plan required: Badges must be on the Pro or Plus plan to be controlled via the API.

Começando

Autenticação

A API de Conexão utiliza autenticação por token Bearer. Todas as requisições devem incluir um token de acesso JWT válido no cabeçalho de Autorização.

Obtenha uma ficha

Envie suas credenciais via POST para o endpoint de autenticação. Você receberá um access_token de curta duração e um refresh_token de longa duração.

Use o token

Inclua o token em todas as solicitações:

Authorization: Bearer <access_token>
POST/api/v1/auth/login
Solicitar
{
  "email": "admin@yourorg.com",
  "password": "••••••••"
}
Resposta 200
{
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcw...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

URL base e versionamento

Todos os endpoints da API são versionados em /api/v1/. A URL base depende da sua implementação.

Para implantações hospedadas na nuvem, use o endpoint regional atribuído à sua organização. Para implantações de servidor locais, use o nome do host do seu servidor.

AmbienteURL base
Nuvem (EUA)https://beta.connection.app/api/v1
No localhttps://<your-server>/api/v1
Tipo de conteúdo
Todos os corpos de requisição e resposta usam application/json. Inclua Content-Type: application/json nas requisições com corpo.

Códigos de erros e status

A API utiliza códigos de status HTTP padrão. As respostas de erro incluem um código legível por máquina e uma mensagem legível por humanos.

StatusSignificado
200Sucesso
201Criado
400Solicitação inválida — parâmetros inválidos
401Não autorizado — token ausente ou expirado
403Proibido — permissões insuficientes
404Não encontrado
500Erro do Servidor Interno
Resposta de erro
{
  "error": {
    "code": "device_not_found",
    "message": "No device with that UUID exists in your organization",
    "status": 404
  }
}
API REST

Visão geral da API REST

A API REST do Connection Server fornece acesso programático completo à sua frota de dispositivos, infraestrutura de comunicações e análises. Ela segue as convenções RESTful com corpos de requisição/resposta em JSON.

Autenticação de API
Usuários
Dispositivos
Canais
Comunicação
Ponte de áudio
Conversas
Contente
Locais
Notificações Push
Armazenar
Operações em massa
Data e hora

Autenticação

Autenticação baseada em token. O login retorna um token que deve ser enviado como Authorization: Token.<token> em todas as solicitações subsequentes.

POST/api/v1/loginAutenticar um usuário e receber um token de autenticação.
POST/api/v1/login-deviceAutenticar um dispositivo por UUID e endereço MAC
POST/api/v1/logoutInvalidar o token de sessão atual

Usuários

Crie e gerencie contas de usuário. O endpoint GET /users/user retorna o usuário autenticado no momento.

GET/api/v1/users/userRecuperar o perfil do usuário atualmente conectado.
POST/api/v1/users/userCriar uma nova conta de usuário
PATCH/api/v1/users/user/{uuid}Atualizar perfil do usuário (ex.: foto de perfil)

Dispositivos

Listar e inspecionar dispositivos, gerenciar associações usuário-dispositivo, ler e gravar configurações e status por dispositivo, manipular firmware e imagens de armazenamento, e receber registros e relatórios de falhas.

GET/api/v1/devices/deviceListe todos os dispositivos
GET/api/v1/devices/device/{uuid}Obtenha informações detalhadas sobre o dispositivo, incluindo firmware e configurações.
PUT/api/v1/devices/association/{uuid}Atualizar a associação entre um usuário e um dispositivo
DELETE/api/v1/devices/association/{uuid}Remover associação usuário-dispositivo e configurações armazenadas
GET/api/v1/devices/device/{device_uuid}/settingsListar as configurações armazenadas para um dispositivo
POST/api/v1/devices/device/{device_uuid}/settingsSalvar configurações específicas do dispositivo
GET/api/v1/devices/device/{device_uuid}/statusObtenha o status do dispositivo (conectividade, bateria, sensores, estado do áudio)
POST/api/v1/devices/device/{device_uuid}/statusPoste o status do dispositivo a partir do dispositivo
GET/api/v1/devices/device/{device_uuid}/contextListar os valores de contexto armazenados para um dispositivo
POST/api/v1/devices/device/{device_uuid}/ingest-contextReceba informações de GPS e Wi-Fi do dispositivo.
GET/api/v1/devices/firmwareListe as versões de firmware compatíveis com uma determinada versão de hardware/software.
GET/api/v1/devices/firmware/{uuid}/{image_type}/fetchObter uma imagem de firmware em partes.
GET/api/v1/devices/languageLista de idiomas e vozes compatíveis com o dispositivo
GET/api/v1/devices/storage_imageBaixe uma imagem de armazenamento de dispositivo personalizada para uma localidade.
POST/api/v1/devices/logReceber um arquivo de registro de um dispositivo
POST/api/v1/devices/crashReceba um despejo de memória (core dump) de um dispositivo.
PATCH/api/v1/devices/crash/{uuid}Atualizar registro de falha

Proxy CBBP

Envie qualquer comando CBBP para um dispositivo através do servidor. O servidor retransmite o comando pela conexão Wi-Fi do dispositivo e retorna a resposta do dispositivo. A resposta de saída também inclui uma mensagem CBBPMessage que o dispositivo executa imediatamente.

POST/api/v1/devices/device/{device_uuid}/cbbpEnviar um comando CBBP para um dispositivo através do servidor.
GET/api/v1/devices/device/{device_uuid}/cbbp/{uuid}Recuperar o estado e a resposta de um comando CBBP enviado anteriormente.

O corpo da solicitação é um envelope de comando CBBP. O objeto CBBPCommand armazenado rastreia o status de entrega: NÃO DEFINIDO → ENVIADO → RECEBIDO ou TEMPO LIMITE EXCEDIDO.

Execute o comando GET /cbbp/ para verificar se o dispositivo recebeu e respondeu ao comando.
Solicitação — mensagem de saída
{
  "outgoingMessage": {
    "command": "WiFiScan"
  }
}
Resposta — Status do comando CBBP
{
  "uuid": "a3f2...",
  "status": "SENT",
  "device": "d7f3a1b2-...",
  "dateSent": "2025-09-15T14:22:01Z",
  "outgoingMessage": { /* echoed */ },
  "incomingMessage": null
}

Canais

Os canais são os elementos básicos da comunicação. Os tipos incluem ChannelPeople, ChannelGroup, ChannelContact, ChannelContactNumber, ChannelExternalNumber, ChannelService e ChannelRecorder.

GET/api/v1/channels/channelListar canais, opcionalmente filtrados por tipo de objeto.
POST/api/v1/channels/channelCrie um canal (ChannelGroup, ChannelContact ou ChannelExternalNumber).
PATCH/api/v1/channels/channel/{uuid}Atualizar um grupo de canais ou um contato de canal
DELETE/api/v1/channels/channel/{uuid}Excluir um canal
DELETE/api/v1/channels/{uuid}Excluir um grupo de canais
DELETE/api/v1/channels/by-type/{channelType}Excluir todos os canais de um determinado tipo (atualmente ChannelContact)
GET/api/v1/channels/associationListar as associações de canais para o usuário atual
POST/api/v1/channels/associationSolicitar associação a um canal
PATCH/api/v1/channels/association/{uuid}Aceitar, recusar ou atualizar as configurações de associação.
DELETE/api/v1/channels/association/{uuid}Remover uma associação com um canal
GET/api/v1/channels/historyObtenha o histórico de acesso ao canal paginado para o usuário atual.
POST/api/v1/channels/historyCriar uma entrada no histórico do canal
GET/api/v1/channels/searchPesquise canais por string de consulta e filtro de tipo opcional.

Comunicação

Inicie e gerencie sessões de comunicação ativas — chamadas de saída, VCP, gravação e streaming de conteúdo. A resposta de chamada de saída inclui uma mensagem CBBPMessage que o dispositivo processa imediatamente.

POST/api/v1/communicate/outgoing-makeInicie um canal de saída para um ChannelPeople, ChannelGroup, ChannelContact ou ChannelContactNumber.
POST/api/v1/communicate/incoming-acceptanceAceitar ou recusar uma solicitação de entrada em um canal
POST/api/v1/communicate/closeFeche o canal de comunicação ativo atual em um dispositivo.
POST/api/v1/communicate/vcp-activateInicie o Protocolo de Comunicação de Voz (VCP) no servidor e no dispositivo.
POST/api/v1/communicate/vcp-deactivateDesative o VCP, retornando a qualquer canal anterior.
POST/api/v1/communicate/recording-activateAtive o modo de gravação no servidor e no dispositivo.
POST/api/v1/communicate/content-startAbra um canal de streaming para conteúdo de áudio.
POST/api/v1/communicate/request-vocalizationGere áudio TTS para o texto fornecido, traduzindo-o opcionalmente.

Ponte de áudio

Acesse gravações de conversas em conferência, incluindo transcrições completas, listas de participantes e resumos gerados por IA. Suporta diversos modelos de resumo (notas de reunião, notas de aula, saúde, etc.) e geração de áudio TTS para os resumos.

GET/api/v1/bridge/conversationsListe todas as conversas da ponte
GET/api/v1/bridge/conversations/{uuid}Obtenha uma conversa detalhada, incluindo transcrição, participantes e resumo.
POST/api/v1/bridge/conversations/{conversation_uuid}/summaryGere um resumo de IA para uma conversa.
POST/api/v1/bridge/conversations/{conversation_uuid}/summary/{summary_uuid}/audioGere áudio para um resumo da conversa.

Conversas

Sessões de conversação com inteligência artificial usando ChatGPT, Gemini ou o mecanismo nativo. Suporta múltiplas personas (Médico, Professor Particular, Mecânico, etc.) e histórico de mensagens paginado.

GET/api/v1/conversations/conversationListe as sessões do gerador de IA, filtráveis por perfil e ferramenta.
POST/api/v1/conversations/conversationCriar uma nova sessão de conversação com IA
GET/api/v1/conversations/conversation/{uuid}Recupere uma sessão de conversa com resumo/atualização de ausência opcional.
DELETE/api/v1/conversations/conversation/{uuid}Excluir sessão de conversa
GET/api/v1/conversations/conversation/{uuid}/messagesListar mensagens em uma conversa
POST/api/v1/conversations/conversation/{uuid}/messagesAdicione uma mensagem de usuário e receba uma resposta de IA.

Contente

Navegue e reproduza conteúdo de áudio em streaming em seus dispositivos. O conteúdo está organizado em uma árvore de categorias; o conteúdo popular pode ser filtrado por cidade, região ou país.

GET/api/v1/content/categoriesObtenha uma árvore de categorias de conteúdo.
GET/api/v1/content/contentListar o conteúdo disponível em uma categoria
GET/api/v1/content/popularListe o conteúdo popular para uma determinada cidade, região ou país.

Locais

Converte coordenadas geográficas em objetos estruturados de cidade, região e país. Utilizado por dispositivos ao receber contexto.

POST/api/v1/location/determineConverter latitude/longitude para cidade, região e país.

Notificações Push

Registre um aplicativo móvel para receber notificações push do FCM. Compatível com iOS, Android e plataformas web.

POST/api/v1/push-notifications/pushRegistre um aplicativo móvel para receber notificações push do FCM (iOS, Android, web)

Armazenar

Faça o download dos arquivos armazenados nos objetos do modelo e execute a remoção do fundo da imagem (retorna o resultado codificado em base64).

GET/api/v1/storage/retrieve/{path}Baixar um arquivo armazenado pelo caminho
POST/api/v1/storage/remove-backgroundRemover o fundo de uma imagem (retorna base64)

Operações em massa

Execute várias operações de API em uma única requisição HTTP. Passe `single_transaction=true` para encapsular todas as operações em uma única transação atômica — uma falha em qualquer item reverte todo o lote.

POST/api/v1/bulkExecute várias operações de API em uma única solicitação, opcionalmente como uma única transação atômica.

Data e hora

Retorna a data e hora atuais do servidor em GMT+0. Não requer autenticação. Usado por dispositivos para sincronizar seus relógios internos.

GET/api/v1/current-datetimeRetorna a data e hora atuais em GMT+0.
Protocolo CBBP

Protocolo Básico de Crachá Com

CBBP é um protocolo de comando JSON leve para interação direta com crachás de conexão. Ele oferece controle total sobre todas as funções de hardware e software do dispositivo.

Formato da mensagem

Cada interação CBBP consiste em uma mensagem de comando enviada ao dispositivo e uma mensagem de resultado retornada pelo dispositivo.

O campo "object" tanto na requisição quanto na resposta contém dados específicos do comando e pode ser omitido quando não for necessário.

A documentação completa do protocolo está disponível para os parceiros registrados. Entre em contato com seu representante comercial da Connection ou fale com developer@connectionbadge.com Para solicitar acesso à referência completa de comandos CBBP, incluindo esquemas completos de solicitação/resposta, códigos de erro e guias de integração.
Mensagem de comando
{
  "command": "command_name",
  "object": {
    // optional command parameters
  }
}
Mensagem de resultado
{
  "result": 0,          // 0 = success, -1 = error
  "detail": "ok",      // human-readable status
  "object": {          // optional response data
    // command-specific fields
  }
}

Transporte

As mensagens CBBP podem ser entregues a um crachá por meio de três protocolos de transporte diferentes, dependendo da sua arquitetura de integração.

Bluetooth (aplicativo)

Envie comandos CBBP diretamente de um aplicativo móvel via BLE. Requer que o dispositivo esteja emparelhado e dentro do alcance.

SDK para dispositivos móveis

Wi-Fi ou Bluetooth via servidor

Encaminhar o CBBP por meio da API REST — POST /devices//cbbp. O servidor encaminha automaticamente a requisição para o dispositivo via Wi-Fi ou Bluetooth, dependendo de como o crachá está conectado. Essa abordagem é mais comum para integrações de backend.

API REST

Despacho interno

Envio de CBBP no dispositivo ou entre processos. Usado pelo firmware do crachá para rotear comandos entre subsistemas internos.

Somente firmware

Comandos de energia

Controle o estado de energia do dispositivo — suspensão, ativação, reinicialização e restauração de fábrica.

PowerRebootReinicie o dispositivo imediatamente.
PowerDeepsleepEntrar no modo de hibernação profunda (baixo consumo de energia).
FactoryResetApague todas as configurações e restaure as configurações de fábrica.

Comandos de Wi-Fi

Configure redes sem fio, procure pontos de acesso (APs), verifique o status da conexão e gerencie as credenciais salvas.

WiFiScanProcure pontos de acesso Wi-Fi disponíveis.
WiFiAPTestTeste a conectividade com um ponto de acesso Wi-Fi específico.
WiFiAPJoinConecte-se a um ponto de acesso Wi-Fi usando as credenciais fornecidas.

Comandos Bluetooth

Controle a publicidade BLE, o emparelhamento e a comunicação entre dispositivos.

BTScanBTProcure por dispositivos Bluetooth clássicos.
BTScanBLEProcure por dispositivos BLE.
DeviceBLEServiceAvailableMarque o serviço BLE como disponível.
DeviceBLEServiceUnavailableMarque o serviço BLE como indisponível.
DeviceBLEActiveAtive o rádio BLE.
DeviceBLEIdleColoque o rádio BLE em estado ocioso.
DeviceBLEAdvChannelAddAdicione um canal à carga útil de publicidade BLE.
DeviceBTScanInicie uma busca por dispositivos Bluetooth.
DeviceBTA2DStartInicie a transmissão de áudio Bluetooth A2DP.
DeviceBTA2DEndFim da transmissão de áudio Bluetooth A2DP.
DeviceBTNativeAssistStartInicie o assistente de voz Bluetooth nativo.
DeviceBTNativeAssistEndEncerre o assistente de voz nativo do Bluetooth.

Comandos de configuração

Ler e gravar a configuração do dispositivo — nome de exibição, fuso horário, idioma e sinalizadores de recursos.

SettingsListGetRecupere todas as configurações como uma lista de pares chave-valor.
SettingsListSetEscreva vários valores de configuração de uma só vez.
SettingsGetObtenha o valor de uma única configuração por meio de uma tecla.
SettingsSetDefina o valor de uma única configuração.
SettingsSendEnviar as configurações atuais para o servidor.
SettingsClearLimpar valores de configuração específicos.
SettingsEraseApagar todas as configurações armazenadas.

Comandos de firmware

Acione atualizações de firmware OTA, verifique o status da atualização e consulte a versão atual do firmware no dispositivo.

FirmwareCheckVerifique se há alguma atualização de firmware disponível.
FirmwareUpdateInicie uma atualização de firmware OTA.
FirmwareValidateValide a integridade de uma imagem de firmware baixada.

Comandos do dispositivo

Ciclo de vida do dispositivo, autenticação, configuração, registro, status e controle de hardware.

NoOpSem operação / manter ativo.
TestTeste básico de conectividade.
DeviceDateTimeObtenha ou defina a data e a hora do dispositivo.
DeviceAuthenticateAutenticar o dispositivo com o servidor.
DeviceConfigureAplique uma carga útil de configuração ao dispositivo.
DevicePostConnectionTasksExecutar tarefas de inicialização pós-conexão.
DeviceStorageLoadCarregar dados do armazenamento interno do dispositivo.
DeviceLoadCustomAudioCarregue arquivos de áudio personalizados no dispositivo.
DeviceCoredumpSendEnvie um arquivo de despejo de memória (core dump) do processo de falha para o servidor.
DeviceAttachConecte o dispositivo a uma sessão do servidor.
DeviceDetachDesconecte o dispositivo da sessão do servidor.
DeviceLogSendEnviar registros do dispositivo para o servidor.
DeviceConnectionTestTeste a conectividade do servidor.
DeviceStatusSendEnviar o status do dispositivo para o servidor.
DeviceStatusGetObtenha o status atual do dispositivo.
DeviceInteractionAcione um evento de interação com o dispositivo.
DeviceSetAPIHostConfigure o host do servidor da API.
DeviceTestMicsExecute um autoteste do microfone.
HardwareI2CCommandEnviar um comando I2C bruto para um periférico de hardware.

Comandos de comunicação

Iniciar chamadas, enviar mensagens, gerenciar sessões de comunicação ativas e controlar a gravação.

CommunicateChannelJoinParticipe de um canal de comunicação.
CommunicateChannelLeaveDeixe um canal de comunicação aberto.
CommunicateChannelChangeMude para outro canal.
CommunicateChannelCloseFeche um canal de comunicação.
CommunicateReceiveIncomingNotificar o dispositivo sobre uma comunicação recebida.
CommunicateRequestOutgoingSolicitar uma comunicação de saída.
CommunicateVCPActivateAtive a sessão do Protocolo de Comunicação de Voz.
CommunicateVCPDeactivateDesative a sessão VCP.
CommunicateRecordingActivateComece a gravar a comunicação ativa.
CommunicateIncomingAcceptAtender uma chamada recebida.
CommunicateIncomingRejectRejeitar uma chamada recebida.
CommunicateHFPCallStartInicie uma chamada telefônica Bluetooth HFP.
CommunicateHFPCallEndEncerrar uma chamada telefônica Bluetooth HFP.
CommunicateContentStartComece a transmitir conteúdo de áudio para o dispositivo.
CommunicateContentStopInterrompa a reprodução de conteúdo de áudio.
SocketReceiveStatusReceba uma atualização de status do WebSocket.

Comandos de áudio

Controle o volume do alto-falante, o ganho do microfone, os perfis de áudio e a reprodução de texto para fala.

AudioPlayStorageReproduza um arquivo de áudio armazenado no dispositivo.
AudioPlayContentReproduzir conteúdo de áudio transmitido por streaming.
AudioSetVolumeAjuste o volume de saída dos alto-falantes.

Comandos de LED

Configure a cor, o brilho e os padrões de animação do LED indicador do emblema.

DeviceIlluminationSetDefina a cor do LED e o padrão de iluminação.

Comandos internos

Comandos de despacho internos usados para entrega de contexto, histórico do canal, vocalização e decodificação de áudio.

InternalSendContextEnviar dados de contexto para o manipulador de contexto interno.
InternalSendChannelHistoryEnviar histórico do canal para o manipulador interno.
InternalRequestVocalizationSolicitar vocalização de texto para fala internamente.
InternalHandleVocalizationRTPProcessar um fluxo RTP de vocalização recebido.
InternalDecodeAudioDecodifique um fluxo de áudio recebido.

Comandos móveis

Comandos para coordenar o crachá com um aplicativo móvel emparelhado — notificações push, sincronização do estado do aplicativo e links diretos.

MobileServiceStatusInforme o status do serviço móvel para o dispositivo. (Celular → Dispositivo)
MobileSocketOpenInstrua o aplicativo móvel a abrir uma conexão WebSocket. (Dispositivo → Celular)
MobileSocketCloseInstrua o aplicativo móvel a fechar uma conexão WebSocket. (Dispositivo → Celular)
MobileSocketStatusReportar o status do WebSocket para o aplicativo móvel. (Dispositivo → Celular)
MobileReceiveStatusInforme o status de recebimento no aplicativo móvel. (Dispositivo → Celular)
MobileSocketUpdateEnviar uma atualização de dados WebSocket para o aplicativo móvel. (Dispositivo → Móvel)
MobilePTTStartNotifique o aplicativo móvel de que a transmissão PTT foi iniciada. (Dispositivo → Móvel)
MobilePTTStopNotifique o aplicativo móvel de que a transmissão PTT foi encerrada. (Dispositivo → Móvel)
MobileContextSetDefina os dados contextuais no aplicativo móvel. (Dispositivo → Celular)
MobileEchoComando Echo para testar a conectividade móvel. (Dispositivo → Móvel)

Pronto para construir?

Junte-se à comunidade de desenvolvedores do Connection e tenha acesso a dispositivos sandbox, SDKs e suporte dedicado.

Contate-nos