API de dispositivos: acionar uma placa por HTTP
Desde 26/10/2026, um servidor, um script ou outra placa manda uma mensagem a um dispositivo pela nuvem, com uma chave de acesso daquele dispositivo, e recebe a resposta do firmware dele. É o mesmo canal da página: a nuvem não interpreta nada, entrega à placa os bytes que o chamador mandou e devolve os bytes que a placa respondeu, com os mesmos limites, papéis e entrega no máximo uma vez.
Uma placa também chama outra pela própria conexão, sem chave nem segunda conexão TLS (Ligar um dispositivo a outro).
A mesma chave também lê o último estado que a nuvem guardou do dispositivo e ouve os eventos dele ao vivo (o que a placa publica e quando ela cai), se o dono der a ela esses escopos; e o dono pode prender a chave a faixas de IP. A nuvem também chama o seu servidor a cada estado e mudança de presença (webhooks), sem conexão aberta.
O fabricante também declara ações com nome no manifesto do bundle que publica com devui publish, e quem chama pede acionar sem conhecer o JSON da placa (Ações com nome).
A chave de acesso
- Quem cria é o dono do dispositivo, na página dele no portal, em "Acesso por API", com um nome ("portão da garagem"), um papel (dono, operador ou leitor, nunca acima do de quem cria), o que ela pode fazer (os escopos), se quiser faixas de IP e, se quiser, um prazo. O texto
bwd_<id>_<segredo>aparece uma vez só; a nuvem guarda só o SHA-256 do segredo. - A chave vale para um dispositivo, e só para o que os escopos dela deixam, mais a presença. Não convida, não renomeia, não desvincula.
- Ela morre quando o dono a revoga, quando vence o prazo, quando o dispositivo é desvinculado, transferido ou ganha época nova, e quando quem a criou perde o acesso ao dispositivo. A página mostra o último uso (data e IP).
- É um segredo: nunca no código nem no git. Na placa, ela fica na flash; revogue-a quando a placa sair das suas mãos.
- Sem CORS: a chave não é para página web, onde vazaria no primeiro acesso.
Nos exemplos abaixo, a chave está na variável de ambiente TF_CHAVE (export TF_CHAVE=bwd_... no terminal, ou o cofre de segredos do seu servidor), nunca escrita no comando.
O que a chave pode fazer: os escopos
| Escopo | No portal | Abre |
|---|---|---|
send | Enviar comandos | POST /v1/devices/{id}/messages |
state | Ler o último estado | GET /v1/devices/{id}/state |
events | Receber eventos ao vivo | GET /v1/devices/{id}/events |
- A presença,
GET /v1/devices/{id}, vale com qualquer escopo. - Na criação, o padrão é só
send; o dono marca os outros. Uma chave tem pelo menos um escopo. - As chaves criadas antes dos escopos
stateeeventsficaram com["send"]: continuam fazendo o que faziam, e nada mais. - A rota de um escopo que a chave não tem responde
403com{"erro":"escopo"}, sem chegar à placa.
Faixas de IP
- Opcionais: até 10 faixas por chave, em CIDR, IPv4 ou IPv6 (
203.0.113.0/24,2001:db8::/32), ou um endereço só (vale como/32ou/128). Sem faixa nenhuma, a chave vale de qualquer IP. - A nuvem guarda cada faixa na forma canônica: os bits de host vão a zero (
203.0.113.7/24vira203.0.113.0/24), um IPv4 escrito como IPv6 (::ffff:203.0.113.7) vira o IPv4, e as repetidas saem. - A faixa é conferida logo depois da chave, antes de tudo o mais: fora dela, a resposta é
403com{"erro":"ip"}, e a chamada não chega à placa nem gasta o limite de 60 por minuto. O IP é o do cliente como a nuvem o vê de fora (atrás de um NAT, o IP público da sua rede). - O dono edita os escopos e as faixas de uma chave depois da criação ("Editar", na página do dispositivo), sem trocar o segredo: quem usa a chave continua com o mesmo texto. Uma mudança que tira alguma coisa (um escopo, ou um IP que a faixa deixava) fecha o que a chave tem aberto, inclusive o fluxo de eventos, que reabre já com as regras novas.
Mandar uma mensagem
POST https://api.thingface.com/v1/devices/{device_id}/messages?wait=reply&timeout_ms=10000
Authorization: Bearer bwd_...
Content-Type: application/json
{"acao":"pulso","nonce":"9f2c4be07a1d3355"}
| Parte | Valor |
|---|---|
Authorization | Bearer bwd_<id>_<segredo> |
Content-Type | application/json ou text/*: chega à placa como texto (DEVUI_TEXT); qualquer outro, como bytes |
?wait= | reply (padrão): espera a resposta da placa; delivered: o callback da placa recebeu; accepted: a fila da nuvem aceitou |
?timeout_ms= | quanto a nuvem espera a placa: padrão 10000 (10 s), que também é o máximo |
| Corpo | o payload, até 4 KB |
Com curl:
curl -sS -X POST "https://api.thingface.com/v1/devices/<id>/messages" \
-H "Authorization: Bearer $TF_CHAVE" -H "Content-Type: application/json" \
-d '{"acao":"pulso","nonce":"9f2c4be07a1d3355"}'
Precisa do escopo send.
A presença
GET /v1/devices/{device_id}, com a mesma chave e qualquer escopo, diz o nome, se a placa está online (e desde quando) e a versão do firmware, sem abrir sessão na placa:
curl -sS "https://api.thingface.com/v1/devices/<id>" -H "Authorization: Bearer $TF_CHAVE"
{"id":"<id>","name":"Portão","online":true,"since":"2026-10-26T09:12:03Z","fw_version":"1.4.0"}
O último estado
GET /v1/devices/{device_id}/state (escopo state) devolve o último estado que a nuvem guardou do dispositivo, sem falar com ele: nenhuma sessão abre na placa, e a resposta vem mesmo com ela desligada.
curl -sS -i "https://api.thingface.com/v1/devices/<id>/state" -H "Authorization: Bearer $TF_CHAVE"
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Last-Modified: Mon, 26 Oct 2026 09:14:27 GMT
Bw-State-At: 2026-10-26T09:14:27.512Z
Cache-Control: no-store
{"luz":true,"temp":24.5}
- O corpo é o payload como a placa o mandou, sem a nuvem ler:
text/plain; charset=utf-8se a mensagem veio comDEVUI_TEXT, senãoapplication/octet-stream. Bw-State-Até quando o estado chegou à nuvem (ISO 8601, UTC, pelo relógio da nuvem, com a fração de segundo quando há);Last-Modified, o mesmo instante como data HTTP, sem a fração.- O estado só existe se o produto tem ligada a opção "Guardar o último estado dos dispositivos" (o opt-in do desenvolvedor, no portal do desenvolvedor) e se a placa já mandou um estado depois disso. É o mesmo estado que a página mostra ao abrir (
lastKnown): a última mensagem de broadcast comDEVUI_STATE, de até 4 KB, da época atual do dispositivo (um desvínculo ou uma troca de dono o apaga). - Sem o opt-in, ou sem estado guardado:
404com{"erro":"sem_estado"}. - Cada leitura conta no limite de 60 chamadas por minuto da chave e aparece nos eventos do dispositivo, como uma chamada.
Os eventos ao vivo (SSE)
GET /v1/devices/{device_id}/events (escopo events) abre um fluxo de Server-Sent Events: a conexão HTTP fica aberta, e a nuvem escreve nela cada evento do dispositivo assim que ele acontece. Com curl, use -N para ver cada evento na hora, sem o buffer:
curl -sS -N "https://api.thingface.com/v1/devices/<id>/events" \
-H "Authorization: Bearer $TF_CHAVE" -H "Accept: text/event-stream"
event: presence
data: {"online":true,"since":"2026-10-26T09:12:03Z"}
event: message
data: {"text":"{\"luz\":true,\"temp\":24.5}"}
: keepalive
event: message
data: {"base64":"AQID"}
event: presence
data: {"online":false,"since":"2026-10-26T10:02:41Z"}
| Evento | data | Quando |
|---|---|---|
presence | {"online":bool,"since":"<ISO 8601>"} | o primeiro, logo na abertura (online: true); e o último, quando a placa cai (online: false), e o fluxo termina |
message | {"text":"..."} ou {"base64":"..."} | cada mensagem que a placa manda a quem está aberto: os broadcasts (DEVUI_ALL) e uma mensagem à própria sessão do fluxo. text quando ela veio com DEVUI_TEXT e é UTF-8 válido; senão, os bytes em base64 |
reconnect | {"retry_after_ms":1000} | o fluxo chegou ao tempo máximo (1 h) ou o servidor vai reiniciar: ele fecha logo depois, e o cliente abre outro depois da espera |
closed | {"erro":"proibido"} | a placa recusou o fluxo (o firmware fechou a sessão com 4405, abaixo): ele fecha logo depois, e reabrir não adianta enquanto o firmware recusar |
: keepalive | (um comentário, sem evento) | a cada 25 s, para nenhum proxy fechar a conexão parada; quem lê com uma biblioteca de SSE nem o vê |
As regras do fluxo:
- Um por chave. Com um fluxo da chave aberto, o segundo recebe
409com{"erro":"ja_aberto"}. Quem precisa de dois leitores cria duas chaves. - Até 1 h. Depois, o evento
reconnecte o fim; o cliente reconecta (a abertura conta 1 no limite de 60 por minuto; o fluxo aberto, não). As bibliotecas de SSE reconectam sozinhas quando a conexão fecha; oretry_after_msdiz quanto esperar. - Ocupa uma sessão da placa enquanto está aberto, como uma aba (4 no ESP8266 e nas placas sem PSRAM). Com todas em uso, a resposta é
503com{"erro":"ocupado"}eRetry-After: o fluxo nunca derruba a aba de uma pessoa. Placa desconectada na abertura:503 offline; SDK anterior a 26/10/2026:422 firmware_sem_api. - Quem lê devagar perde mensagens. A nuvem não segura a placa por causa de um cliente lento: o que não cabe no buffer do fluxo é descartado (entrega no máximo uma vez), e o fim (o
reconnect, a queda da placa) chega do mesmo jeito. O fluxo não repete o que se perdeu nem o que aconteceu enquanto ele estava fechado: para o estado atual, leia o/stateao reconectar. - A placa caiu: o evento
presencecomonline: false, e o fluxo termina. Na volta dela, ele não reabre sozinho: o cliente abre outro (até lá, recebe503 offline; a presença diz quando ela voltou). - Fechado sem evento: a revogação da chave, uma edição que tira o escopo
eventsou o IP do cliente, o prazo da chave que venceu, o desvínculo, a troca de dono e o bloqueio fecham o fluxo sem aviso (a chave é conferida de novo a cada keepalive, então em até 25 s). A reconexão recebe o motivo:401 nao_autenticado,403 escopo,403 ipou403 proibido. - A placa recusou: o evento
closedcom{"erro":"proibido"}, e o fluxo termina. A reconexão abre de novo (a nuvem não sabe se o firmware mudou de ideia) e, com o mesmo firmware, recebe outroclosed: ao ver esse evento, não reabra sozinho. - Nada do que a placa manda é gravado na nuvem nem em log: os eventos do dispositivo registram só a abertura e o fim do fluxo (a chave, quanto durou e o motivo do fim).
O que o firmware faz pelo fluxo
Para a placa, o fluxo de eventos é uma sessão de API comum (DEVUI_EV_SESSION_OPEN com ev->session_kind == DEVUI_SESSION_API, o papel da chave em ev->role e o pseudônimo dela em ev->user), só que longa: ela abre na abertura do fluxo e fecha (DEVUI_EV_SESSION_CLOSE) quando ele termina, e nenhuma mensagem chega por ela. O firmware não precisa de nada novo: o que ele já manda às abas por broadcast (devui_send(DEVUI_ALL, ...)) chega ao fluxo como message. Para o fluxo e o /state mostrarem o estado da placa, mande-o por broadcast, como para as abas, com DEVUI_STATE quando a mensagem é o estado inteiro (só essa a nuvem guarda como o último estado); o que o firmware mandar a uma sessão só (devui_send(session, ...) com a sessão de uma aba) não vai ao fluxo.
O broadcast vai a todas as sessões abertas, a do fluxo inclusive, como vai à aba de um leitor. Quem decide primeiro se uma máquina ouve a placa é o dono, ao dar ou não o escopo events à chave; o firmware vê quem está ouvindo pelos eventos da sessão, se quiser contar.
Recusar o fluxo. O fluxo não manda nada à placa, então não há pedido a responder com erro (abaixo): o firmware que não quer máquina nenhuma ouvindo fecha a sessão com devui_session_close(sessao, 4405) (desde 27/10; o 4405 é o código da recusa do firmware). Quem lê o fluxo recebe o evento closed com {"erro":"proibido"}, e o fluxo termina; uma chamada fechada assim recebe 403 com {"erro":"proibido"}. A placa esquece a sessão na hora: devui_session_info passa a responder ESP_ERR_NOT_FOUND, o que ainda estava na fila do SDK para ela é descartado, e o DEVUI_EV_SESSION_CLOSE não vem para ela (quem fechou foi o app); uma mensagem da nuvem para ela que ainda estava a caminho é descartada, e uma devui_send para ela depois disso é aceita e descartada, como para qualquer sessão fechada. Pode ser chamada de dentro do callback de eventos, como abaixo:
static void on_event(const devui_event_t *ev, void *ctx)
{
(void)ctx;
if (ev->type == DEVUI_EV_SESSION_OPEN && ev->session_kind == DEVUI_SESSION_API) {
/* nenhuma máquina ouve esta placa: o fluxo termina com o evento closed, e uma chamada recebe 403 proibido */
(void)devui_session_close(ev->session, 4405);
}
}
/* no app_main, depois do devui_start: */
devui_on_event(on_event, NULL);
No Arduino (ESP32 e ESP8266), o mesmo com DevUI.sessionClose:
void onEvent(const devui_event_t *ev, void *ctx)
{
if (ev->type == DEVUI_EV_SESSION_OPEN && ev->session_kind == DEVUI_SESSION_API) {
DevUI.sessionClose(ev->session, 4405); // o fluxo termina com o evento closed
}
}
// no setup(), depois do DevUI.begin:
DevUI.onEvent(onEvent);
Em Rust, com devui::session_close:
devui::on_event(Some(Box::new(|ev: &devui::Event<'_>| {
if let devui::Event::SessionOpen { session, kind: devui::SessionKind::Api, .. } = ev {
let _ = devui::session_close(*session, 4405); // o fluxo termina com o evento closed
}
})));
Fechar na abertura recusa toda sessão de API, as chamadas inclusive: a placa não distingue o fluxo da chamada pela abertura, só pelo que recebe (a chamada traz o pedido logo em seguida; o fluxo, nada). Para aceitar chamadas e recusar só o fluxo, feche a sessão de API que ficar aberta sem mensagem nenhuma. Com o motivo 0, a sessão fecha sem motivo (a nuvem lê 1000): o fluxo termina sem evento, como num fechamento da nuvem, e a chamada recebe 503 offline.
Ações com nome
Desde 27/10, o desenvolvedor do firmware declara as ações que a placa entende (nome, descrição, papel mínimo e o payload modelo), e quem chama pela API pede a ação pelo nome, sem conhecer o JSON do firmware: POST /v1/devices/{id}/actions/acionar em vez de montar {"acao":"pulso","nonce":"..."}. A nuvem continua sem interpretar a resposta: ela só monta o payload a partir do modelo e o entrega como uma mensagem.
Declarar: o acoes.json
As ações moram no manifesto do bundle, no campo acoes, e o desenvolvedor as escreve num arquivo acoes.json ao lado da pasta web/ (nunca dentro dela: o que está em web/ vai para o navegador):
| Projeto | Arquivo |
|---|---|
ESP-IDF (devui_add_bundle(web) em main/) | main/acoes.json |
Arduino (devui pack web/ no sketch) | acoes.json na pasta do sketch |
| Outro lugar | devui pack web/ --acoes <arquivo> (e devui_add_bundle(web --acoes <arquivo>)) |
O portão, com a ação acionar e uma de exemplo com parâmetro:
[
{
"nome": "acionar",
"descricao": "Aciona o portão",
"papel_minimo": "dono",
"payload": {"acao": "pulso", "nonce": "{{nonce}}"}
},
{
"nome": "abrir-por",
"descricao": "Abre e fecha sozinho depois de um tempo",
"papel_minimo": "dono",
"payload": {"acao": "abrir", "segundos": "{{p:segundos}}", "nonce": "{{nonce}}"},
"params": {"segundos": {"tipo": "inteiro", "min": 5, "max": 120}}
}
]
| Campo | Regra |
|---|---|
nome | [a-z0-9-], de 1 a 32 caracteres, único no arquivo; vai na URL |
descricao | de 1 a 120 caracteres, sem caractere de controle (nem quebra de linha) |
papel_minimo | dono, operador ou leitor: a chave precisa ter papel igual ou acima (a de leitor só chega à placa se o firmware aceitar dados de leitor, DEVUI_OPT_READER_DATA; senão, 403 proibido) |
payload | o JSON que a placa recebe, com os marcadores abaixo |
params | opcional: {"<nome>": {"tipo": ...}}, nome em [a-z0-9_-] de 1 a 32 caracteres |
Os marcadores do payload, sempre como o valor inteiro de um campo (ou de um item de lista), nunca dentro de um texto nem no nome de um campo:
"{{nonce}}"vira 16 dígitos hexadecimais sorteados pela nuvem a cada chamada, ou ononceque o chamador mandou no corpo (abaixo);"{{p:<nome>}}"vira o parâmetro<nome>que o chamador mandou, com o tipo dele ("{{p:segundos}}"vira30, sem aspas; nunca"abrir {{p:segundos}}").
Os tipos de parâmetro:
tipo | Opções | Vira |
|---|---|---|
texto | max_len de 1 a 64 (padrão 64) | um texto JSON |
inteiro | min e max (padrão: o inteiro de 64 bits) | um número inteiro |
booleano | nenhuma | true ou false |
E os limites: no máximo 32 ações; o manifesto inteiro, com as ações, cabe em 8 KB; cada payload final cabe em 4 KB no pior caso dos parâmetros (o texto mais longo, cada caractere escapado, e o inteiro mais comprido da faixa); todo parâmetro declarado aparece no payload; o payload não tem número com casa decimal (use inteiro ou texto) nem um campo chamado container_sha256 (o firmware confere o manifesto por esse nome), e aninha no máximo 124 níveis de listas e objetos (o que a nuvem lê do manifesto).
Empacotar e publicar
devui pack e devui publish leem o acoes.json sozinhos e o validam antes de gravar ou enviar qualquer coisa: um erro para tudo com código de saída 2, apontando a ação e o campo.
devui pack: acoes.json[1] ("abrir-por").params.segundos.min: min acima de max
devui pack: acoes.json[0] ("acionar").payload.acao: {{nonce}} e {{p:<nome>}} valem só como o valor inteiro do campo, nunca dentro de um texto (concatenação): 'pulso {{nonce}}'
devui pack: acoes.json: linha 4, coluna 5: JSON inválido (Expecting ',' delimiter)
As ações chegam à nuvem só pela publicação (devui publish, que manda o manifesto no cabeçalho Devui-Manifest, assinado ou não). A placa nunca manda o manifesto (o HELLO traz só o hash dele): um firmware só gravado, com o bundle dele e sem devui publish, não tem ações, mesmo com o acoes.json embutido. A nuvem serve a cada dispositivo as ações da publicação do bundle que ela serve a ele: a publicação em vigor no produto, ou a publicação assinada daquele bundle quando é o que o dispositivo anuncia. Empacotar o firmware com o mesmo acoes.json, --product igual ao project_key do produto e a mesma --version da publicação deixa o manifesto embutido igual, byte a byte, ao publicado. A assinatura (--sign-key) cobre as ações, como cobre o resto do manifesto. A nuvem confere a lista de novo ao receber a publicação (um erro é o 422 invalid_manifest, que o devui publish mostra como "manifesto recusado", com a ação e o campo), e a resposta lista os nomes que ela guardou; o devui publish confere essa lista e sai com erro se a nuvem publicou sem guardar as ações (uma nuvem anterior a elas).
Sem acoes.json, o manifesto fica igual ao de antes, byte a byte, e o dispositivo não tem ações.
As ações são do produto do dispositivo. Uma placa pareada sem project_key não tem produto e, por isso, não tem ações; o dono a liga a um produto (dele, ou de uma organização em que publica) na página do dispositivo, em "Produto deste dispositivo", sem parear de novo: ela reconecta e passa a oferecer as ações da publicação desse produto, e as chaves de acesso continuam valendo.
Listar e chamar
GET /v1/devices/{device_id}/actions, com qualquer escopo, lista as ações do dispositivo (todas, qualquer que seja o papel da chave), sem abrir sessão na placa; o payload modelo nunca aparece:
curl -sS "https://api.thingface.com/v1/devices/<id>/actions" -H "Authorization: Bearer $TF_CHAVE"
[{"nome":"acionar","descricao":"Aciona o portão","papel_minimo":"dono","params":{}},
{"nome":"abrir-por","descricao":"Abre e fecha sozinho depois de um tempo","papel_minimo":"dono",
"params":{"segundos":{"tipo":"inteiro","min":5,"max":120}}}]
params vem {} numa ação sem parâmetros, e min, max e max_len só aparecem quando declarados. Sem ações, a lista é [].
POST /v1/devices/{device_id}/actions/{nome}, com o escopo send, chama uma; o corpo é opcional e leva os parâmetros e, se quiser, o nonce (16 dígitos hexadecimais) que entra no lugar do {{nonce}}:
curl -sS -X POST "https://api.thingface.com/v1/devices/<id>/actions/acionar" \
-H "Authorization: Bearer $TF_CHAVE"
curl -sS -X POST "https://api.thingface.com/v1/devices/<id>/actions/abrir-por?timeout_ms=8000" \
-H "Authorization: Bearer $TF_CHAVE" -H "Content-Type: application/json" \
-d '{"params":{"segundos":30},"nonce":"9f2c4be07a1d3355"}'
A chamada tem os mesmos ?wait= e ?timeout_ms= e as mesmas respostas de Mandar uma mensagem: a placa recebe o payload montado como uma mensagem de texto com DEVUI_REQUEST, numa sessão de API com o papel da chave, e a resposta dela é o corpo do 200. Além dos códigos de lá:
| Resposta | Quando |
|---|---|
404 acao_inexistente | a publicação do bundle que a nuvem serve ao dispositivo não tem essa ação (ou não tem ações, ou o bundle não foi publicado pela CLI) |
403 papel | o papel da chave está abaixo do papel_minimo da ação |
400 parametro | um parâmetro falta (todos são obrigatórios), sobra, tem o tipo errado ("30" não é inteiro) ou sai da faixa; o corpo diz qual: {"erro":"parametro","campo":"segundos"}; "campo":"nonce" para um nonce que não é 16 dígitos hexadecimais |
400 invalido | o corpo não é vazio nem um objeto só com params (objeto) e nonce |
413 grande_demais | o payload montado passou de 4 KB |
Sem nonce no corpo, a nuvem sorteia um novo a cada chamada, e uma repetição depois de um 424 (ou de um 504 da borda) chega à placa como uma ordem nova. Para o firmware reconhecer a repetição, sorteie você o nonce (16 dígitos hexadecimais) e mande-o no corpo; depois de um 424, repita com o mesmo nonce, como em O nonce contra a repetição.
Webhooks: a nuvem chama o seu servidor
O fluxo de eventos pede uma conexão aberta. Para um servidor que não quer ficar conectado, o dono cadastra um webhook na página do dispositivo, em "Webhooks": a nuvem faz um POST numa URL dele a cada estado que a placa publica e a cada mudança de presença. Não precisa de chave de acesso.
- Cadastro: só o dono, até 3 por dispositivo. A URL é
https://na porta 443, sem usuário nem senha, e o host tem de resolver só para endereços públicos (a nuvem não chama a sua rede interna, nemlocalhost, nem os endereços de metadados das nuvens). O segredowhsec_...aparece uma vez só, na criação; guarde-o como a chave de acesso (cofre de segredos, nunca no git). Adicionar um webhook pede o mesmo segundo fator da criação da chave de acesso (a página pede a confirmação quando falta); remover não pede, como revogar uma chave. Os donos recebem um e-mail a cada webhook criado. O webhook morre com o desvínculo, a transferência ou a época nova do dispositivo. - O que dispara:
- o estado: cada mensagem que a placa manda por broadcast com
DEVUI_STATE(devui_send(DEVUI_ALL, DEVUI_TEXT | DEVUI_STATE, ...), a mesma que vira o último estado). Broadcast semDEVUI_STATEnão vai ao webhook; - a presença: a placa entrou ou caiu.
- o estado: cada mensagem que a placa manda por broadcast com
- A sessão na placa: como a placa só manda o estado a quem está aberto, enquanto houver webhook e a placa estiver online a nuvem mantém uma sessão de API aberta nela (
ev->session_kind == DEVUI_SESSION_API, papel de leitor), igual à do fluxo de eventos: ela ocupa uma vaga, nunca derruba a aba de uma pessoa (com as vagas cheias, a nuvem tenta de novo alguns segundos depois) e é reaberta quando a placa volta. Uma sessão por dispositivo, qualquer que seja o número de webhooks. O firmware que a recusar (devui_session_close) fica sem o estado nos webhooks; a presença continua. - Teste: o botão "Testar" da página manda um evento
testena hora e mostra o resultado. - As últimas entregas: a página mostra as 20 últimas de cada webhook: hora, tipo, código HTTP (ou o erro:
dns,conexao,tls,prazo,nao_publico,resposta) e quanto demorou. O corpo não é guardado.
O que chega
POST /seu/caminho HTTP/1.1
Content-Type: application/json
User-Agent: ThingFace-Webhook/1
ThingFace-Signature: t=1793440323,v1=5b0c...e1
{"tipo":"estado","device_id":"<id>","em":"2026-10-27T09:12:03Z","text":"{\"luz\":true,\"temp\":24.5}"}
tipo | Campos | Quando |
|---|---|---|
estado | text (o estado com DEVUI_TEXT, em UTF-8 válido) ou base64 (os bytes) | cada broadcast com DEVUI_STATE |
presenca | online (true/false) | a placa entrou ou caiu; em é quando |
teste | (nenhum) | o botão "Testar" da página |
Todos levam device_id e em (ISO 8601, UTC). Responda com qualquer 2xx logo (em menos de 5 s) e processe depois.
As regras da entrega
- No máximo uma vez, sem repetição. Um erro do seu servidor (
500), um prazo esgotado ou uma queda da rede não fazem a nuvem tentar de novo: o evento se perde. Para o estado atual depois de uma falha, leia o/statecom uma chave de escopostate. - Prazo de 5 s para tudo (DNS, conexão, TLS, resposta).
- Redirecionamento não é seguido: um
301/302fica registrado como a resposta, e nada mais é chamado. - 60 entregas por minuto por dispositivo, somados os webhooks dele: acima disso, a entrega é descartada (e contada pela nuvem). Um firmware que publica o estado várias vezes por segundo perde estados no webhook; publique o estado quando ele mudar.
- A ordem não é garantida entre webhooks; dentro de um webhook, as entregas saem uma de cada vez. Use o
em.
Conferir a assinatura
ThingFace-Signature é t=<segundos desde 1970>,v1=<hex>, com v1 = HMAC-SHA256 com o texto inteiro do segredo (whsec_..., em UTF-8) como chave, sobre t, um ponto e o corpo exato que chegou (os bytes, antes de qualquer parse do JSON). Confira antes de acreditar no corpo:
- separe
tev1do cabeçalho; - recuse
ta mais de 5 minutos do seu relógio (umPOSTcapturado e reenviado depois fica de fora); - calcule o HMAC e compare com
v1em tempo constante.
Python:
import hashlib, hmac, os, time
SEGREDO = os.environ["TF_WEBHOOK_SEGREDO"].encode() # whsec_...
def assinatura_valida(cabecalho: str, corpo: bytes, tolerancia_s: int = 300) -> bool:
partes = dict(p.split("=", 1) for p in cabecalho.split(",") if "=" in p)
try:
t = int(partes["t"])
v1 = partes["v1"]
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerancia_s:
return False
esperado = hmac.new(SEGREDO, f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperado, v1)
Node.js (Express, com o corpo cru):
const crypto = require("node:crypto");
const express = require("express");
const SEGREDO = process.env.TF_WEBHOOK_SEGREDO; // whsec_...
function assinaturaValida(cabecalho, corpo, toleranciaS = 300) {
const partes = Object.fromEntries(
(cabecalho || "").split(",").map((p) => p.split("=", 2)).filter((p) => p.length === 2),
);
const t = Number.parseInt(partes.t, 10);
if (!Number.isFinite(t) || !partes.v1) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranciaS) return false;
const esperado = crypto
.createHmac("sha256", SEGREDO)
.update(`${t}.`)
.update(corpo)
.digest("hex");
const a = Buffer.from(esperado);
const b = Buffer.from(partes.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
const app = express();
app.post("/thingface", express.raw({ type: "application/json" }), (req, res) => {
if (!assinaturaValida(req.get("ThingFace-Signature"), req.body)) return res.sendStatus(401);
res.sendStatus(204); // responda logo; processe depois
const evento = JSON.parse(req.body);
console.log(evento.tipo, evento.device_id, evento.text ?? evento.online);
});
app.listen(8080);
O express.raw é o que guarda os bytes do corpo: um express.json() antes dele já transformou o corpo em objeto, e o HMAC sobre o objeto reserializado não confere.
Os códigos
| Resposta | Quando |
|---|---|
200 + o corpo da resposta | a placa respondeu (devui_reply); o Content-Type segue a flag de texto da resposta |
202 | wait=delivered ou accepted cumprido |
400 invalido | corpo vazio, wait ou timeout_ms fora da faixa |
400 parametro | ações: um parâmetro inválido, com "campo":"<nome>" no corpo |
401 nao_autenticado | chave ausente, malformada, vencida ou revogada |
403 ip | o IP do cliente está fora das faixas da chave |
403 escopo | a chave não tem o escopo da rota (send, state ou events) |
403 papel | ações: o papel da chave está abaixo do papel_minimo da ação |
403 proibido | a chave tem papel de leitor (ao mandar mensagem ou chamar ação, num firmware sem DEVUI_OPT_READER_DATA), o dispositivo ou a conta estão bloqueados, ou o firmware fechou a sessão da chamada com 4405 (devui_session_close) |
404 nao_encontrado | o dispositivo não existe ou a chave não é dele (a mesma resposta, para não revelar ids) |
404 acao_inexistente | ações: o dispositivo não tem essa ação |
404 sem_estado | /state: o produto não guarda o último estado, ou ainda não há estado guardado |
409 ja_aberto | /events: a chave já tem um fluxo aberto |
413 grande_demais | payload acima de 4 KB |
422 firmware_sem_api | a placa roda um SDK anterior a 26/10/2026, que não atende a API; a nuvem nem tenta |
429 limite | 60 chamadas por minuto por chave, ou a cota do dispositivo; com Retry-After |
503 offline | a placa está desconectada |
503 ocupado | a placa está com todas as sessões em uso; com Retry-After. A chamada nunca derruba a aba de uma pessoa |
424 sem_resposta | o prazo passou sem resposta da placa: o pedido pode ter sido executado |
O corpo de um erro é {"erro":"<codigo>","retry_after_ms":N} (o retry_after_ms quando há). A nuvem confere nesta ordem e para na primeira recusa: a chave (401, 404, e 403 proibido com o dispositivo bloqueado), as faixas de IP (403 ip), o escopo (403 escopo), o limite de 60 por minuto (429) e só então o dispositivo.
A api nunca responde 504. Um 504 que ainda chegue vem da borda (o proxy entre você e a nuvem desistiu de esperar), não da api, e o corpo dele não é o JSON acima: trate-o igual ao 424, porque o pedido pode ter sido executado.
O nonce contra a repetição
A nuvem não deduplica (entrega no máximo uma vez): repetir é decisão de quem chama. E um 424 (ou um 504 da borda) não diz que nada aconteceu: a placa pode ter executado e a resposta não ter chegado a tempo. Por isso o payload leva um nonce aleatório, e o firmware chamado guarda os últimos que executou:
- quem chama sorteia um
noncenovo para cada ordem nova; - depois de um
424, de um504ou de uma queda da rede com o pedido já enviado, repete com o mesmononce; - o firmware que vê de novo um
noncejá executado não executa outra vez e responde que é repetição (o portão responderepetido).
O exemplo examples/api-chamada faz exatamente isso, em ESP-IDF, com esp_http_client e o bundle de certificados do IDF, a chave vinda do menuconfig.
O que a placa chamada vê
Cada chamada abre na placa uma sessão de tipo API, que dura um pedido:
DEVUI_EV_SESSION_OPENcomev->session_kind == DEVUI_SESSION_API(2), o papel da chave emev->rolee, emev->user, um pseudônimo da chave, que nunca coincide com o de uma pessoa;- a mensagem chega ao
devui_on_messagecomDEVUI_REQUEST, como um pedido da página; - o firmware responde com
devui_reply, e a resposta vira o corpo do200; - a sessão fecha (
DEVUI_EV_SESSION_CLOSE). O que a placa mandar por broadcast enquanto ela estiver aberta não vai ao chamador.
devui_session_info(session, &info) diz o mesmo a qualquer momento: info.kind é DEVUI_SESSION_BROWSER (0, a aba de uma pessoa) ou DEVUI_SESSION_API (2). Na casca Arduino, os mesmos campos: ev->session_kind no DevUI.onEvent e info.kind em DevUI.sessionInfo (ESP32 e ESP8266). Ambos são adições à API v1 (campos no fim das structs). No binding Rust, o campo kind: SessionKind (Browser, Api ou Other(u8)) de Event::SessionOpen e de SessionInfo; esse é um campo novo em tipos que já existiam (decisão de 26/10), e quem desmonta um deles sem .. precisa acrescentá-lo (O que mudou).
A sessão da API ocupa uma das sessões da placa enquanto dura (4 no ESP8266 e nas placas sem PSRAM). O fluxo de eventos abre a mesma sessão de tipo 2, longa e sem mensagens (O que o firmware faz pelo fluxo).
O firmware que não quer chamadas de máquina
O SDK novo atende a API sempre (decisão de 26/10): ele anuncia no HELLO que atende (bit 2 de OPTIONS), sem opção do firmware. A chave só existe se o dono a criar; mesmo assim, o firmware que não deve obedecer a uma máquina recusa pelo tipo da sessão, respondendo um erro seu e não executando nada:
static void on_msg(const devui_msg_t *m, void *ctx)
{
devui_session_info_t info;
(void)ctx;
/* só a aba de uma pessoa passa: a API, um tipo que um SDK futuro trouxer e a sessão que já fechou, não */
if (devui_session_info(m->session, &info) != ESP_OK || info.kind != DEVUI_SESSION_BROWSER) {
if ((m->flags & DEVUI_REQUEST) != 0) {
static const char no[] = "{\"erro\":\"sem_api\"}";
(void)devui_reply(m, no, sizeof no - 1); /* o chamador recebe 200 com este corpo */
}
return; /* uma chamada de máquina não aciona nada aqui */
}
/* ... a aba de uma pessoa: o tratamento de sempre ... */
}
No Arduino, o mesmo com DevUI.sessionInfo(m->session, &info) e DevUI.reply(m, ...).
Em Rust, com devui::session_info e SessionKind:
devui::on_message(Some(Box::new(|m: &devui::Message<'_>| {
// só a aba de uma pessoa passa: a API, um tipo que um SDK futuro trouxer e a sessão que já fechou, não
let pessoa = matches!(devui::session_info(m.session()), Ok(i) if i.kind == devui::SessionKind::Browser);
if !pessoa {
if m.is_request() {
let _ = m.reply(br#"{"erro":"sem_api"}"#); // o chamador recebe 200 com este corpo
}
return; // uma chamada de máquina não aciona nada aqui
}
// ... a aba de uma pessoa: o tratamento de sempre ...
})));
Confira o tipo dentro do callback, enquanto a sessão está aberta, e recuse quando não der para saber: a sessão da API fecha logo depois da entrega com wait=delivered ou accepted, e no fim do prazo; um firmware que guarda a mensagem numa fila e só pergunta o tipo depois recebe ESP_ERR_NOT_FOUND, e não pode tratar isso como a aba de uma pessoa. Quem processa fora do callback guarda o info.kind junto com a mensagem.
Responda sempre ao pedido recusado: sem resposta, quem chama recebe 424 sem_resposta, que quer dizer "pode ter sido executado". Para aceitar a API só de algumas chaves, confira também o papel (info.role, 1 dono, 2 operador, 3 leitor): o portão aceita a chamada só com papel de dono, como na página.
Ligar um dispositivo a outro
Desde 27/10, uma placa chama outra pela própria conexão com a nuvem, sem uma segunda conexão TLS e sem chave de acesso no firmware. É o caminho do ESP8266, que não aguenta duas conexões TLS, e o mais simples para qualquer placa que já fala com a nuvem: uma placa aperta o portão de outra com uma linha.
A ligação
O dono liga as duas placas no portal, na página da placa que chama, em "Ligar a outro dispositivo": escolhe o dispositivo chamado, um apelido (portao; de 1 a 32 caracteres, só a–z, 0–9 e -, único naquela placa) e o papel com que a chamada chega (dono, operador ou leitor; nunca acima do papel de quem liga no dispositivo chamado). Com o mesmo dono, liga direto. Entre contas, o dono do dispositivo chamado gera um código de uso único (8 caracteres, vale 24 h), e o dono da placa que chama o resgata na página dela, escolhendo o apelido.
A ligação morre com o desvínculo, a transferência ou a época nova de qualquer das duas placas, e quando qualquer dos dois donos a revoga no portal. No máximo 20 ligações saem de uma placa e 20 chegam a uma placa.
Chamar
O firmware só conhece o apelido:
static void ao_resultado(const devui_call_result_t *r, void *ctx)
{
(void)ctx;
/* na task do SDK: curto, sem bloquear; r e r->data valem só aqui dentro */
if (r->status == DEVUI_CALL_OK) {
printf("portao respondeu: %.*s\n", (int)r->len, (const char *)r->data);
} else if (r->status == DEVUI_CALL_NO_REPLY) {
printf("sem resposta: o portão PODE ter aberto; repita com o mesmo nonce\n");
} else {
printf("não foi: %u\n", r->status);
}
}
static const char abrir[] = "{\"acao\":\"pulso\",\"nonce\":\"9f2c4be07a1d3355\"}";
esp_err_t e = devui_call("portao", abrir, sizeof abrir - 1, 0 /* 10 s */, ao_resultado, NULL);
devui_call é assíncrona: devolve ESP_OK quando a chamada entrou na fila do SDK, e o callback vem uma vez, na task do SDK, com o que voltou. O payload chega à placa chamada como um pedido (DEVUI_REQUEST), em bytes (sem DEVUI_TEXT); a resposta dela (devui_reply) volta em r->data, com r->text quando ela respondeu como texto. O prazo (timeout_ms) vai de 1 a 10.000 ms; 0, ou acima, vale 10 s. Até 4 chamadas esperam resposta ao mesmo tempo, e o payload vai até 4 KB (no ESP8266, até o que cabe na fila do SDK).
No Arduino (ESP32 e ESP8266), DevUI.call("portao", abrir, sizeof abrir - 1, ao_resultado), com o contexto e o prazo opcionais; no ESP8266 o callback vem no loop(), como os outros. Em Rust, devui::call("portao", abrir, 0, Box::new(|r| ...)), com r.status um CallStatus. Os exemplos examples/chamar-outro (ESP-IDF) e arduino/examples/ChamarOutro fazem o ciclo inteiro: chamam no botão, repetem o nonce quando devem e atendem as chamadas das outras placas.
status | Quer dizer | O que fazer |
|---|---|---|
DEVUI_CALL_OK | a outra placa respondeu: data, len, text | — |
DEVUI_CALL_NO_REPLY | sem_resposta: o prazo passou sem resposta (ou a conexão caiu depois de a chamada sair); a outra placa pode ter feito | repetir, se for o caso, com o mesmo nonce |
DEVUI_CALL_NOT_SENT | a conexão desta placa caiu (ou o SDK parou) antes de a chamada sair: nada foi feito | pode repetir |
DEVUI_CALL_OFFLINE | offline: a outra placa não está conectada, ou caiu durante a chamada; se caiu depois de a chamada chegar a ela, pode ter feito (como o 503 da API) | repetir, se for o caso, com o mesmo nonce |
DEVUI_CALL_NOT_LINKED | nao_ligado: não há ligação com esse apelido nesta placa (ou ela está no limbo) | o dono liga no portal |
DEVUI_CALL_FORBIDDEN | proibido: bloqueio, papel de leitor num dispositivo que não aceita, ou o firmware de lá fechou a sessão com 4405 | — |
DEVUI_CALL_LIMIT | limite: 2 chamadas por segundo e 60 por minuto por ligação, 4 de uma vez, ou a cota de uma das placas; retry_after_ms diz a espera | esperar |
DEVUI_CALL_UNSUPPORTED | firmware_sem_suporte: a outra placa roda um SDK anterior a 27/10/2026 | gravar nela um SDK novo |
DEVUI_CALL_BUSY | ocupado: as sessões da outra placa estão cheias | — |
DEVUI_CALL_TOO_LARGE | grande_demais: a chamada passou do que a outra placa recebe, ou a resposta do que esta recebe | — |
DEVUI_CALL_ERROR | um resultado que esta versão não conhece (result) ou a nuvem recusou o quadro (error_code) | registrar |
Os nomes são os mesmos da API por HTTP (Os códigos): sem_resposta é o 424, nao_ligado o 404, e assim por diante. A nuvem não repete chamada nenhuma: o nonce no payload é a defesa, como na API (O nonce contra a repetição).
O que devui_call recusa na hora, sem chamar o callback: ESP_ERR_INVALID_ARG (apelido fora da regra), ESP_ERR_INVALID_SIZE (acima de 4 KB ou da fila do SDK), ESP_ERR_INVALID_STATE (parado ou offline), ESP_ERR_NO_MEM (4 chamadas esperando, ou a fila do SDK cheia: espere um callback ou DEVUI_EV_TX_READY) e DEVUI_ERR_OVER_QUOTA.
O que a placa chamada vê
Como na API, cada chamada abre na placa chamada uma sessão que dura um pedido, agora de tipo dispositivo:
DEVUI_EV_SESSION_OPENcomev->session_kind == DEVUI_SESSION_DEVICE(3), o papel da ligação emev->rolee, emev->user, um pseudônimo da ligação, que nunca coincide com o de uma pessoa nem com o de uma chave;- a mensagem chega ao
devui_on_messagecomDEVUI_REQUEST; - o firmware responde com
devui_reply, e a resposta volta ao callback da placa que chamou; - a sessão fecha. O que a placa chamada mandar por broadcast enquanto ela estiver aberta vai às abas, não à chamada.
O SDK novo atende a sessão de outro dispositivo sempre (bit 3 de OPTIONS no HELLO, como a API). O firmware que só obedece a pessoas recusa pelo tipo, como na seção "O firmware que não quer chamadas de máquina", abaixo: o exemplo de lá, que só deixa passar DEVUI_SESSION_BROWSER, já recusa também o tipo 3. Para aceitar a outra placa e recusar a API, troque a condição por info.kind != DEVUI_SESSION_BROWSER && info.kind != DEVUI_SESSION_DEVICE. Para recusar sem responder, feche a sessão com 4405 (devui_session_close): quem chamou recebe DEVUI_CALL_FORBIDDEN.
No Arduino, os mesmos campos; em Rust, SessionKind::Device.
Compatibilidade
- Placa com o SDK anterior a 26/10/2026: recusa a sessão de tipo API (
SESSION_CLOSE4400), e por isso a nuvem nem a abre; quem chama recebe422 firmware_sem_api. Basta gravar o SDK novo. - O tipo 1 de sessão (o túnel, reservado) e qualquer tipo desconhecido continuam recusados com 4400.
- Placa chamada com o SDK anterior a 27/10/2026: não anuncia o bit 3 de
OPTIONS, a nuvem não abre nela a sessão de tipo dispositivo, e quem chama recebeDEVUI_CALL_UNSUPPORTED. Placa que chama com o SDK novo e nuvem anterior a 27/10/2026: a nuvem ignora a chamada, e o callback vem comDEVUI_CALL_NO_REPLYdepois do prazo. - No ESP8266, o
HELLOcresce 7 bytes (oOPTIONS, quando o app não liga nenhuma opção): com o perfil "8266", o host mais longo que cabe com os demais campos no máximo cai de 48 para 41 caracteres. Desde 30/10/2026 oHELLOleva também oKEY_STORE(5 bytes, onde a chave mora; ver o changelog), e esse máximo cai para 36. O host do serviço tem 16.
