Pular para o conteúdo
ThingFace

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

EscopoNo portalAbre
sendEnviar comandosPOST /v1/devices/{id}/messages
stateLer o último estadoGET /v1/devices/{id}/state
eventsReceber eventos ao vivoGET /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 state e events ficaram com ["send"]: continuam fazendo o que faziam, e nada mais.
  • A rota de um escopo que a chave não tem responde 403 com {"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 /32 ou /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/24 vira 203.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 é 403 com {"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"}
ParteValor
AuthorizationBearer bwd_<id>_<segredo>
Content-Typeapplication/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
Corpoo 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-8 se a mensagem veio com DEVUI_TEXT, senão application/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 com DEVUI_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: 404 com {"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"}
EventodataQuando
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 409 com {"erro":"ja_aberto"}. Quem precisa de dois leitores cria duas chaves.
  • Até 1 h. Depois, o evento reconnect e 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; o retry_after_ms diz 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 é 503 com {"erro":"ocupado"} e Retry-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 /state ao reconectar.
  • A placa caiu: o evento presence com online: false, e o fluxo termina. Na volta dela, ele não reabre sozinho: o cliente abre outro (até lá, recebe 503 offline; a presença diz quando ela voltou).
  • Fechado sem evento: a revogação da chave, uma edição que tira o escopo events ou 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 ip ou 403 proibido.
  • A placa recusou: o evento closed com {"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 outro closed: 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):

ProjetoArquivo
ESP-IDF (devui_add_bundle(web) em main/)main/acoes.json
Arduino (devui pack web/ no sketch)acoes.json na pasta do sketch
Outro lugardevui 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}}
  }
]
CampoRegra
nome[a-z0-9-], de 1 a 32 caracteres, único no arquivo; vai na URL
descricaode 1 a 120 caracteres, sem caractere de controle (nem quebra de linha)
papel_minimodono, 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)
payloado JSON que a placa recebe, com os marcadores abaixo
paramsopcional: {"<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 o nonce que o chamador mandou no corpo (abaixo);
  • "{{p:<nome>}}" vira o parâmetro <nome> que o chamador mandou, com o tipo dele ("{{p:segundos}}" vira 30, sem aspas; nunca "abrir {{p:segundos}}").

Os tipos de parâmetro:

tipoOpçõesVira
textomax_len de 1 a 64 (padrão 64)um texto JSON
inteiromin e max (padrão: o inteiro de 64 bits)um número inteiro
booleanonenhumatrue 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á:

RespostaQuando
404 acao_inexistentea 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 papelo papel da chave está abaixo do papel_minimo da ação
400 parametroum 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 invalidoo corpo não é vazio nem um objeto só com params (objeto) e nonce
413 grande_demaiso 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, nem localhost, nem os endereços de metadados das nuvens). O segredo whsec_... 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 sem DEVUI_STATE não vai ao webhook;
    • a presença: a placa entrou ou caiu.
  • 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 teste na 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}"}
tipoCamposQuando
estadotext (o estado com DEVUI_TEXT, em UTF-8 válido) ou base64 (os bytes)cada broadcast com DEVUI_STATE
presencaonline (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 /state com uma chave de escopo state.
  • Prazo de 5 s para tudo (DNS, conexão, TLS, resposta).
  • Redirecionamento não é seguido: um 301/302 fica 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:

  1. separe t e v1 do cabeçalho;
  2. recuse t a mais de 5 minutos do seu relógio (um POST capturado e reenviado depois fica de fora);
  3. calcule o HMAC e compare com v1 em 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

RespostaQuando
200 + o corpo da respostaa placa respondeu (devui_reply); o Content-Type segue a flag de texto da resposta
202wait=delivered ou accepted cumprido
400 invalidocorpo vazio, wait ou timeout_ms fora da faixa
400 parametroações: um parâmetro inválido, com "campo":"<nome>" no corpo
401 nao_autenticadochave ausente, malformada, vencida ou revogada
403 ipo IP do cliente está fora das faixas da chave
403 escopoa chave não tem o escopo da rota (send, state ou events)
403 papelações: o papel da chave está abaixo do papel_minimo da ação
403 proibidoa 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_encontradoo dispositivo não existe ou a chave não é dele (a mesma resposta, para não revelar ids)
404 acao_inexistenteaçõ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_demaispayload acima de 4 KB
422 firmware_sem_apia placa roda um SDK anterior a 26/10/2026, que não atende a API; a nuvem nem tenta
429 limite60 chamadas por minuto por chave, ou a cota do dispositivo; com Retry-After
503 offlinea placa está desconectada
503 ocupadoa placa está com todas as sessões em uso; com Retry-After. A chamada nunca derruba a aba de uma pessoa
424 sem_respostao 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 nonce novo para cada ordem nova;
  • depois de um 424, de um 504 ou de uma queda da rede com o pedido já enviado, repete com o mesmo nonce;
  • o firmware que vê de novo um nonce já executado não executa outra vez e responde que é repetição (o portão responde repetido).

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:

  1. DEVUI_EV_SESSION_OPEN com ev->session_kind == DEVUI_SESSION_API (2), o papel da chave em ev->role e, em ev->user, um pseudônimo da chave, que nunca coincide com o de uma pessoa;
  2. a mensagem chega ao devui_on_message com DEVUI_REQUEST, como um pedido da página;
  3. o firmware responde com devui_reply, e a resposta vira o corpo do 200;
  4. 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.

statusQuer dizerO que fazer
DEVUI_CALL_OKa outra placa respondeu: data, len, text—
DEVUI_CALL_NO_REPLYsem_resposta: o prazo passou sem resposta (ou a conexão caiu depois de a chamada sair); a outra placa pode ter feitorepetir, se for o caso, com o mesmo nonce
DEVUI_CALL_NOT_SENTa conexão desta placa caiu (ou o SDK parou) antes de a chamada sair: nada foi feitopode repetir
DEVUI_CALL_OFFLINEoffline: 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_LINKEDnao_ligado: não há ligação com esse apelido nesta placa (ou ela está no limbo)o dono liga no portal
DEVUI_CALL_FORBIDDENproibido: bloqueio, papel de leitor num dispositivo que não aceita, ou o firmware de lá fechou a sessão com 4405—
DEVUI_CALL_LIMITlimite: 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 esperaesperar
DEVUI_CALL_UNSUPPORTEDfirmware_sem_suporte: a outra placa roda um SDK anterior a 27/10/2026gravar nela um SDK novo
DEVUI_CALL_BUSYocupado: as sessões da outra placa estão cheias—
DEVUI_CALL_TOO_LARGEgrande_demais: a chamada passou do que a outra placa recebe, ou a resposta do que esta recebe—
DEVUI_CALL_ERRORum 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:

  1. DEVUI_EV_SESSION_OPEN com ev->session_kind == DEVUI_SESSION_DEVICE (3), o papel da ligação em ev->role e, em ev->user, um pseudônimo da ligação, que nunca coincide com o de uma pessoa nem com o de uma chave;
  2. a mensagem chega ao devui_on_message com DEVUI_REQUEST;
  3. o firmware responde com devui_reply, e a resposta volta ao callback da placa que chamou;
  4. 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_CLOSE 4400), e por isso a nuvem nem a abre; quem chama recebe 422 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 recebe DEVUI_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 com DEVUI_CALL_NO_REPLY depois do prazo.
  • No ESP8266, o HELLO cresce 7 bytes (o OPTIONS, 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 o HELLO leva também o KEY_STORE (5 bytes, onde a chave mora; ver o changelog), e esse máximo cai para 36. O host do serviço tem 16.