Como funciona a autenticação HMAC-SHA256?

O dispositivo usa uma chave secreta (SECRET_KEY) para gerar uma assinatura única a cada requisição. O servidor verifica se a assinatura é válida antes de aceitar os dados. A biblioteca DadosCorp faz tudo automaticamente.

Quais formatos de dados são aceitos?

JSON, MsgPack, CBOR, form-urlencoded e texto puro. Basta adicionar ?fmt=json (ou o formato desejado) na URL.

Qual o limite do plano gratuito?

5 dispositivos, 1 requisição a cada 10 segundos por dispositivo. Payload máximo de 4096 bytes.

As mensagens de erro são em português?

As mensagens de erro são retornadas no idioma do usuário. O servidor detecta automaticamente entre português, inglês, espanhol, francês, alemão, chinês e japonês.

API DadosCorp

A plataforma expõe uma API HTTP com autenticação HMAC-SHA256 para integração com qualquer linguagem.

Modelos de Autenticação

Tipo	Uso
Sessão Flask	Usuário logado no dashboard
HMAC-SHA256	Dispositivos IoT — header `Authorization: HMAC device_key:nonce:signature`
Token (e-mail)	Confirmações por link (ativação, exclusão)
pwa_auth	PWA isolado — sessão separada para usuários do app

Endpoint principal: POST /receive

O endpoint que recebe a telemetria dos dispositivos. Formato do header de autenticação:

Authorization: HMAC <device_key>:<nonce>:<signature>

Onde:
  device_key = identificador público do dispositivo (32 caracteres hex)
  nonce      = número que nunca se repete (use millis() ou time.time())
  signature  = HMAC-SHA256(secret_bytes, (device_key + nonce) + body_bytes)

Formatos aceitos: json, msgpack, cbor, form, text. Payload máximo: 4096 bytes.

Exemplo Python

import requests
import hashlib
import hmac
import time

DEVICE_KEY = "ff8dcabb..."
SECRET_KEY = "a1b2c3d4..."
nonce = str(int(time.time() * 1000))
payload = '{"temperatura": 23.5, "umidade": 68}'

msg = (DEVICE_KEY + nonce).encode() + payload.encode()
signature = hmac.new(bytes.fromhex(SECRET_KEY), msg, hashlib.sha256).hexdigest()

headers = {"Authorization": f"HMAC {DEVICE_KEY}:{nonce}:{signature}"}
res = requests.post("https://dadoscorp.com.br/receive?fmt=json", data=payload, headers=headers)
print(res.json())  # {"status":"accepted","job_id":123}

Exemplo Arduino / ESP32 (C++)

#include <WiFi.h>
#include <HTTPClient.h>
#include <mbedtls/md.h>

void sendTelemetry(String json) {
    String nonce = String(millis());
    String message = DEVICE_KEY + nonce + json;

    byte hmacResult[32];
    mbedtls_md_hmac(mbedtls_md_info_from_type(MBEDTLS_MD_SHA256),
                     secretKeyBytes, 32,
                     (const unsigned char*)message.c_str(), message.length(),
                     hmacResult);

    String signature = "";
    for (int i = 0; i < 32; i++)
        signature += String(hmacResult[i], HEX);

    http.begin("https://dadoscorp.com.br/receive?fmt=json");
    http.addHeader("Authorization", "HMAC " + DEVICE_KEY + ":" + nonce + ":" + signature);
    http.POST(json);
}

Códigos de Erro

Todas as mensagens de erro são retornadas no idioma do usuário (7 idiomas: português, inglês, espanhol, francês, alemão, chinês, japonês). O idioma é detectado automaticamente pelo cadastro ou navegador.

✅ Sucesso

Error Code	HTTP	Causa	Correção
sem erro	202	Payload aceito e enfileirado para processamento.	—

🔐 Autenticação

Error Code	HTTP	Causa	Correção
`AUTH_MISSING`	401	Cabeçalho Authorization ausente.	Inclua: Authorization: HMAC device_key:nonce:signature
`AUTH_FORMAT`	400	Formato inválido do cabeçalho Authorization.	Use o formato exato: HMAC key:nonce:assinatura
`AUTH_DEVICEKEY`	400	DEVICE_KEY inválida. Deve ter exatamente 32 caracteres hex (0-9, a-f).	Copie a device_key completa do painel.
`AUTH_NONCE`	400	Nonce não é um número.	Use millis() no Arduino ou int(time.time()*1000) no Python.
`AUTH_SIGNATURE`	403	Assinatura HMAC não confere. SECRET_KEY errada ou fórmula incorreta.	Verifique a SECRET_KEY no painel e a ordem do cálculo HMAC.
`AUTH_INVALID`	401	Falha geral na autenticação. Credenciais inválidas.	Confira device_key e secret_key.

📡 Dispositivo

Error Code	HTTP	Causa	Correção
`DEVICE_UNKNOWN`	404	Dispositivo não encontrado ou inativo.	Verifique se o device está ativo no painel.

📦 Dados enviados

Error Code	HTTP	Causa	Correção
`BODY_EMPTY`	400	Payload vazio.	Envie dados no corpo da requisição.
`BODY_TOO_LARGE`	413	Payload maior que 4096 bytes.	Reduza o tamanho ou envie em partes.
`BODY_NOT_UTF8`	400	Encoding inválido para JSON.	Garanta que o body está em UTF-8.
`BODY_NOT_JSON`	400	JSON malformado.	Verifique a sintaxe: aspas duplas, sem vírgulas extras.
`INVALID_JSON`	400	Body não é JSON válido.	Envie um objeto JSON no corpo.

🔤 Formato

Error Code	HTTP	Causa	Correção
`FMT_INVALID`	400	Formato não suportado no parâmetro ?fmt=.	Use: json, msgpack, cbor, form ou text.

⏱ Rate Limit

Error Code	HTTP	Causa	Correção
`TIER_LIMITED`	429	Plano gratuito: 1 requisição a cada 10 segundos.	delay(10000) no Arduino, time.sleep(10) no Python.
`RATE_LIMITED`	429	Excedeu o limite de requisições por minuto.	Aguarde e tente novamente.

🚨 Comandos / Metadados

Error Code	HTTP	Causa	Correção
`CMD_ID_MISSING`	400	command_id é obrigatório no ACK.	Inclua o command_id recebido no comando.
`CMD_ID_INVALID`	400	command_id inválido.	Use o ID retornado pelo GET /command.
`ACK_STATUS_INVALID`	400	Status do ACK inválido.	Use "success" ou "error".
`VARIABLES_INVALID`	400	Lista de variáveis inválida no metadata.	Envie um array JSON em "variables".

🛠 Servidor

Error Code	HTTP	Causa	Correção
`INTERNAL_ERROR`	500	Erro interno do servidor.	Tente novamente em alguns segundos.
`STREAM_UNAVAILABLE`	503	Serviço de ingestão temporariamente indisponível.	Aguarde e tente novamente.

Rate Limit

Conta gratuita: 1 requisição a cada 10 segundos por device. Exceder retorna HTTP 429 com error_code=TIER_LIMITED.

Labels iniciadas com _ são reservadas para uso interno. Use nomes comuns para seus dados. O campo _ts pode ser usado para timestamp customizado (Unix ou ISO 8601).

Todas as mensagens de erro são traduzidas para 7 idiomas — o servidor detecta o idioma do usuário automaticamente e responde na língua correta.