T2Mark Docs
Painel
Docs / API Reference / POST /api/register

POST /api/register

POST /api/register

Registra uma nova máquina (agente) no T2Mark. Primeiro endpoint chamado pelo agente. Retorna uma apiKey para uso em requisições subsequentes.

Quando é Chamado

Agente iniciando pela primeira vez:

1. Carrega config.ini
2. Vê que ApiKey está vazio
3. Executa POST /api/register
4. Envia TenantKey (do instalador)
5. Recebe ApiKey
6. Salva em config.ini
7. Marca registro como "ok"

Requisição

URL

POST https://t2mark.setor9.net/api/register

Headers

Content-Type: application/json
User-Agent: T2Mark-Agent/1.0

Corpo

curl -X POST https://t2mark.setor9.net/api/register \
  -H "Content-Type: application/json" \
  -H "User-Agent: T2Mark-Agent/1.0" \
  -d '{
    "tenantKey": "tk_a1b2c3d4e5f6ghijklmnop1234567890abcdef",
    "hostname": "PC-VENDAS-001",
    "hwid": "550e8400-e29b-41d4-a716-446655440000",
    "osVersion": "Windows 11 Pro Build 23H2"
  }'

Parâmetros Obrigatórios

Campo Tipo Descrição Exemplo
tenantKey string Chave da empresa tk_a1b2c3d4...
hostname string Nome da máquina Windows PC-VENDAS-001
hwid string Hardware ID único (gerado Windows) 550e8400-e29b-41d4...

Parâmetros Opcionais

Campo Tipo Descrição Exemplo
osVersion string Versão do Windows Windows 11 Pro Build 23H2
agentVersion string Versão do agente 1.0.0
domainName string Domínio LDAP/AD ACME.LOCAL

Resposta — 201 Created (Novo Registro)

{
  "status": "registered",
  "apiKey": "ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
  "machineId": 42,
  "message": "Machine registered successfully"
}

Campos da Resposta

Campo Tipo Significado
status string Sempre "registered" (novo) ou "reactivated" (antigo)
apiKey string Chave para futuras requisições (64 chars hex)
machineId integer ID interno da máquina
message string Mensagem descritiva

⚠️ IMPORTANTE: Armazenar ApiKey

A ApiKey é retornada apenas uma vez. O agente deve salvá-la em C:\T2Mark\config.ini:

[Agent]
ApiKey=ak_5f1b3c8e9d2a4b6c7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b

Se perdida, a máquina precisa re-registrar (gera novo ApiKey, revoga o antigo).

Resposta — 200 OK (Re-ativação)

Se o HWID já existe (máquina já foi registrada antes):

{
  "status": "reactivated",
  "apiKey": "ak_novo_hash_diferente_5f1b3c8e9d2a4b6c...",
  "machineId": 42,
  "message": "Machine reactivated with new API key"
}

O que acontece:

  1. ✅ Servidor verifica HWID existente
  2. ✅ Revoga ApiKey anterior
  3. ✅ Gera novo ApiKey
  4. ✅ Máquina continua com mesmo machineId
  5. ✅ Histórico é preservado

Respostas de Erro

400 Bad Request

{
  "error": "Bad Request",
  "message": "Missing required fields: tenantKey, hostname, hwid"
}

Causas:

Solução: Verifique se todos os campos estão presentes e com formato correto.

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid tenant key"
}

Causas:

Solução: Baixe novamente o instalador (contém TenantKey correta).

403 Forbidden

{
  "error": "Forbidden",
  "message": "Tenant is disabled"
}

Causas:

Solução: Contacte vendas ou admin para reativar.

409 Conflict

{
  "error": "Conflict",
  "message": "Machine already registered with this HWID",
  "suggestion": "Machine will be reactivated"
}

Causas:

Solução: Esperado — servidor reativa a máquina com novo ApiKey (veja resposta 200 OK acima).

Fluxo Prático: Primeira Instalação

Máquina A, Usuário João

┌─────────────────────────────────┐
│ 1. Instalador baixado            │
│    Contém: TenantKey             │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 2. Agente inicia                │
│    Lê config.ini                │
│    ApiKey vazio? Sim!           │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 3. POST /api/register            │
│    Body:                         │
│    {                             │
│      "tenantKey": "tk_...",     │
│      "hostname": "PC-VENDAS-001",│
│      "hwid": "550e8400-e29b..."  │
│    }                             │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 4. Servidor valida              │
│    ✓ TenantKey existe?          │
│    ✓ Tenant ativo?              │
│    ✓ HWID novo ou conhecido?    │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 5. Resposta 201 Created          │
│    {                             │
│      "status": "registered",     │
│      "apiKey": "ak_5f1b3c...",  │
│      "machineId": 42             │
│    }                             │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 6. Agente recebe               │
│    Salva em config.ini:         │
│    [Agent]                      │
│    ApiKey=ak_5f1b3c...         │
│    Deleta TenantKey             │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 7. Status: Pronto!              │
│    Próxima requisição:          │
│    GET /api/policy              │
│    Header: X-API-Key: ak_5f... │
└─────────────────────────────────┘

Fluxo Prático: Reinstalação na Mesma Máquina

Mesma Máquina A, 1 mês depois (reinstalação)

┌─────────────────────────────────┐
│ 1. Agente desinstalado          │
│    config.ini deletado          │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 2. Reinstalar agente            │
│    Mesmo instalador (TenantKey)│
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 3. Agente inicia                │
│    HWID = mesmo (hardware igual)│
│    ApiKey = vazio (novo install)│
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 4. POST /api/register (novamente)│
│    HWID: "550e8400-e29b..." ← já existe!
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 5. Resposta 200 OK              │
│    {                             │
│      "status": "reactivated",    │
│      "apiKey": "ak_novo...",    │
│      "machineId": 42             │
│    }                             │
│    (ApiKey anterior revogado)    │
└──────────┬──────────────────────┘
           │
           ↓
┌─────────────────────────────────┐
│ 6. No painel:                   │
│    Máquina volta a aparecer     │
│    Status: Online               │
│    Histórico preservado         │
└─────────────────────────────────┘

Timings Esperados

Operação Tempo
POST /api/register → Resposta 100-500 ms
Agente processa resposta 50-100 ms
Aparece no painel 5-10 segundos
Primeira política sincroniza ~30 segundos
Marca d’água aparece ~35 segundos total

Resumo Rápido

QUANDO CHAMADO:
  Agente inicia, primeira vez
  ApiKey vazio em config.ini

O QUE ENVIA:
  TenantKey (do instalador)
  Hostname, HWID
  (opcionais: osVersion, agentVersion)

O QUE RECEBE:
  ApiKey (64 chars)
  MachineId

ARMAZENAR:
  ApiKey em C:\T2Mark\config.ini
  
PRÓXIMO PASSO:
  Usa X-API-Key: ak_... em todas as requisições
  GET /api/policy
  POST /api/heartbeat
  etc