API Pública - Hivestr

Documentação completa da API pública para integração com sistemas externos.

Última atualização: 04/10/2025
Versão da API: v1
Base URL Produção: https://www.hivestr.com/api/v1

🔐 1. AUTENTICAÇÃO

POST /api/v1/auth/token

Gera um Access Token JWT válido por 1 hora.

Headers: Nenhum
Body:


{
  "api_key": "hvstr_abc123...",      // ✅ OBRIGATÓRIO
  "api_secret": "secret456..."        // ✅ OBRIGATÓRIO
}

Resposta:


{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Uso: Use o access_token em todas as requisições subsequentes no header:
Authorization: Bearer {access_token}

📦 2. INVENTÁRIO

GET /api/v1/public/inventory/list

Lista inventário de mídia da empresa.

Query Params (todos opcionais):

?media_type=DOOH          // OOH, DOOH, TV, RADIO, all
&city=Brasília            // Nome da cidade
&state=DF                 // UF (DF, SP, RJ, etc)
&is_active=true           // true, false, all
&page=1                   // Número da página (default: 1)
&limit=50                 // Itens por página (default: 50, máx: 100)

Resposta:


{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Painel Digital Shopping",
      "media_type": "DOOH",
      "city": "Brasília",
      "state": "DF",
      "address": "SCS Quadra 1",
      "bairro": "Asa Sul",
      "latitude": -15.7942,
      "longitude": -47.8822,
      "base_price": 500000,        // Em centavos
      "unit_price": 16667,         // Preço diário (centavos)
      "audience": 50000,
      "format": "LED 3x2m",
      "dimensions": "3x2",
      "description": "Painel no corredor principal",
      "photo_url": "https://...",
      "is_active": true,
      "is_occupied": false,
      "screen_quantity": 2,
      "environment": "Shopping Center",
      "insertions_per_day": 50,
      "total_daily_insertions": 100,
      "discounted_price": null,
      "discount_percentage": 0,
      "negotiation_margin_percentage": 15,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-05T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 45,
    "total_pages": 1
  }
}

GET /api/v1/public/inventory/{id}

Consulta item específico do inventário com programação (TV/Rádio).

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Rádio CBN Brasília - Manhã",
    "media_type": "RADIO",
    // ... todos os campos do list
    "media_schedules": [
      {
        "id": "uuid-schedule",
        "run_days": [1, 2, 3, 4, 5],  // Seg-Sex (0=Dom, 1=Seg, ..., 6=Sáb)
        "start_time": "07:00:00",
        "end_time": "09:00:00",
        "price_per_slot": 150000,     // R$ 1.500,00 em centavos
        "available_slots": 10,
        "program_name": "Jornal da Manhã",
        "social_class": "A,B",
        "audience": 100000,
        "is_active": true
      }
    ]
  }
}

👥 3. CLIENTES

GET /api/v1/public/clients

Lista clientes da empresa.

Query Params (todos opcionais):

?search=João              // Busca em name, email, company_name, cnpj, cpf
&status=lead              // lead, prospect, client, inactive, all
&page=1                   // Número da página
&limit=50                 // Itens por página (default: 50)

Resposta:


{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "phone": "(61) 99999-9999",
      "company_name": "Empresa XYZ Ltda",
      "cnpj": "12.345.678/0001-99",
      "cpf": null,
      "address": "Rua Exemplo, 123",
      "city": "Brasília",
      "state": "DF",
      "zip_code": "70000-000",
      "contact_person": "João Silva",
      "position": "Diretor",
      "notes": "Cliente VIP",
      "status": "client",
      "source": "Website",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-05T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 150, "total_pages": 3 }
}

POST /api/v1/public/clients

Cria novo cliente.

Body:


{
  "name": "João Silva",              // ✅ OBRIGATÓRIO
  "email": "joao@empresa.com",       // ⚪ Opcional
  "phone": "(61) 99999-9999",        // ⚪ Opcional
  "company_name": "Empresa XYZ",     // ⚪ Opcional
  "cnpj": "12.345.678/0001-99",      // ⚪ Opcional
  "cpf": "123.456.789-00",           // ⚪ Opcional
  "address": "Rua Exemplo, 123",     // ⚪ Opcional
  "city": "Brasília",                // ⚪ Opcional
  "state": "DF",                     // ⚪ Opcional
  "zip_code": "70000-000",           // ⚪ Opcional
  "contact_person": "João Silva",    // ⚪ Opcional
  "position": "Diretor",             // ⚪ Opcional
  "notes": "Cliente indicado",       // ⚪ Opcional
  "status": "lead",                  // ⚪ Opcional (default: "lead")
  "source": "Website"                // ⚪ Opcional (default: "API")
}

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid-gerado",
    "name": "João Silva",
    "email": "joao@empresa.com",
    "status": "lead",
    "created_at": "2024-01-06T16:00:00Z"
  },
  "message": "Cliente criado com sucesso"
}

GET /api/v1/public/clients/{id}

Consulta cliente específico com todas as propostas.

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "João Silva",
    // ... todos os campos do cliente
    "proposals": [
      {
        "id": "uuid-proposta",
        "proposal_number": "P0123",
        "title": "Campanha Verão 2025",
        "status": "approved",
        "total_value": 50000,
        "final_value": 40000,
        "discount_percentage": 20,
        "campaign_start_date": "2025-01-15",
        "campaign_end_date": "2025-01-29",
        "created_at": "2024-12-15T10:00:00Z"
      }
    ],
    "proposal_stats": {
      "total": 5,
      "approved": 2,
      "pending": 2,
      "rejected": 1,
      "total_value": 250000,
      "approved_value": 150000
    }
  }
}

PUT /api/v1/public/clients/{id}

Edita cliente existente.

Body (todos campos opcionais):


{
  "name": "João Silva Santos",      // ⚪ Opcional
  "email": "novo@email.com",         // ⚪ Opcional
  "phone": "(61) 98888-8888",        // ⚪ Opcional
  "company_name": "Empresa XYZ",     // ⚪ Opcional
  "cnpj": "12.345.678/0001-99",      // ⚪ Opcional
  "cpf": "123.456.789-00",           // ⚪ Opcional
  "address": "Rua Nova, 456",        // ⚪ Opcional
  "city": "São Paulo",               // ⚪ Opcional
  "state": "SP",                     // ⚪ Opcional
  "zip_code": "01234-567",           // ⚪ Opcional
  "contact_person": "Maria",         // ⚪ Opcional
  "position": "Gerente",             // ⚪ Opcional
  "notes": "Cliente VIP",            // ⚪ Opcional
  "status": "client"                 // ⚪ Opcional (lead, prospect, client, inactive)
}

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "João Silva Santos",
    "email": "novo@email.com",
    "status": "client",
    "updated_at": "2024-01-06T16:30:00Z"
  },
  "message": "Cliente atualizado com sucesso"
}

📋 4. PROPOSTAS

POST /api/v1/public/proposals/calculate

Calcula valores de proposta automaticamente (DOOH, OOH, TV/Rádio).

Body:


{
  "campaign_start_date": "2024-01-15",   // ✅ OBRIGATÓRIO (YYYY-MM-DD)
  "campaign_end_date": "2024-01-29",     // ✅ OBRIGATÓRIO (YYYY-MM-DD)
  "bonus_days": 2,                       // ⚪ Opcional (default: 0)
  "discount_percentage": 10,             // ⚪ Opcional (default: 0)
  "sell_by_insertions": false,           // ⚪ Opcional (default: false) - DOOH apenas
  "daily_insertions_per_screen": 50,     // ⚪ Opcional (default: 50) - Se sell_by_insertions=true
  "items": [                             // ✅ OBRIGATÓRIO (min: 1 item)
    {
      "vehicle_id": "uuid-dooh-1",       // ✅ OBRIGATÓRIO
      "is_bonus": false                  // ⚪ Opcional (default: false)
    },
    {
      "vehicle_id": "uuid-ooh-1",        // ✅ OBRIGATÓRIO
      "face_orientation": "Fluxo",       // ⚪ Opcional (OOH) - Fluxo ou Contra-Fluxo
      "is_bonus": false
    },
    {
      "vehicle_id": "uuid-tv-1",         // ✅ OBRIGATÓRIO
      "schedule_id": "uuid-schedule",    // ✅ OBRIGATÓRIO (TV/Rádio)
      "quantity": 10,                    // ⚪ Opcional (default: 1) - Qtd de inserções
      "is_bonus": false
    }
  ]
}

Resposta:


{
  "success": true,
  "data": {
    "campaign_period": {
      "start_date": "2024-01-15",
      "end_date": "2024-01-29",
      "campaign_days": 15,
      "is_bi_semana": false,
      "bonus_days": 2,
      "total_days": 17
    },
    "items": [
      {
        "vehicle_id": "uuid-dooh-1",
        "vehicle_name": "Painel Digital Shopping",
        "media_type": "DOOH",
        "is_bonus": false,
        "screen_quantity": 2,
        "pricing_mode": "daily",
        "daily_price": 16667,
        "campaign_days": 15,
        "unit_price": 500000,
        "quantity": 15,
        "discount_percentage": 0,
        "discount_value": 0,
        "final_price": 250005
      }
    ],
    "summary": {
      "campaign_days": 15,
      "is_bi_semana": false,
      "subtotal": 250005,
      "discount_percentage": 10,
      "discount_value": 25000,
      "final_value": 225005,
      "total_screens": 2
    }
  }
}

GET /api/v1/public/proposals

Lista propostas da empresa.

Query Params (todos opcionais):

?client_id=uuid           // Filtrar por cliente
&status=draft             // draft, sent, viewed, approved, rejected, all
&start_date=2024-01-01    // Filtro por data de criação (YYYY-MM-DD)
&end_date=2024-12-31      // Filtro por data de criação
&page=1                   // Número da página
&limit=50                 // Itens por página

Resposta:


{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "proposal_number": "PROP-0123-24",
      "title": "Campanha Verão 2024",
      "description": "Campanha de mídia exterior",
      "status": "approved",
      "total_value": 500000,
      "discount_percentage": 10,
      "discount_value": 50000,
      "final_value": 450000,
      "valid_until": "2024-01-10T23:59:59Z",
      "campaign_start_date": "2024-01-15",
      "campaign_end_date": "2024-01-29",
      "bonus_days": 0,
      "created_at": "2024-01-05T10:00:00Z",
      "created_via": "api",
      "client": {
        "id": "uuid",
        "name": "João Silva",
        "email": "joao@empresa.com",
        "company_name": "Empresa XYZ"
      }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 25, "total_pages": 1 }
}

POST /api/v1/public/proposals

Cria nova proposta (use valores calculados do /calculate).

Body:


{
  "client_id": "uuid-cliente",                    // ✅ OBRIGATÓRIO
  "title": "Campanha Verão 2024",                 // ✅ OBRIGATÓRIO
  "description": "Campanha de mídia exterior",    // ⚪ Opcional
  "campaign_start_date": "2024-01-15",            // ✅ OBRIGATÓRIO (YYYY-MM-DD)
  "campaign_end_date": "2024-01-29",              // ✅ OBRIGATÓRIO (YYYY-MM-DD)
  "bonus_days": 0,                                // ⚪ Opcional (default: 0)
  "discount_percentage": 0,                       // ⚪ Opcional (default: 0)
  "discount_value": 0,                            // ⚪ Opcional (default: 0) - Em centavos
  "valid_until": "2024-01-10",                    // ⚪ Opcional (YYYY-MM-DD)
  "commercial_notes": "Obs para cliente",         // ⚪ Opcional
  "notes": "Obs internas",                        // ⚪ Opcional
  "advertising_agency": "Agência ABC",            // ⚪ Opcional
  "agency_commission_percentage": 15,             // ⚪ Opcional (default: 0)
  "has_volume_commission": false,                 // ⚪ Opcional (default: false)
  "volume_commission_percentage": 0,              // ⚪ Opcional (default: 0)
  "sell_by_insertions": false,                    // ⚪ Opcional (default: false)
  "daily_insertions_per_screen": null,            // ⚪ Opcional (se sell_by_insertions=true)
  "items": [                                      // ✅ OBRIGATÓRIO (min: 1 item)
    {
      "vehicle_id": "uuid-dooh-1",                // ✅ OBRIGATÓRIO
      "schedule_id": null,                        // ⚪ Opcional (obrigatório para TV/Rádio)
      "quantity": 1,                              // ✅ OBRIGATÓRIO
      "unit_price": 500000,                       // ✅ OBRIGATÓRIO (centavos)
      "discount_percentage": 0,                   // ⚪ Opcional (default: 0)
      "discount_value": 0,                        // ⚪ Opcional (default: 0) - Em centavos
      "final_price": 250005,                      // ✅ OBRIGATÓRIO (centavos)
      "is_bonus": false,                          // ⚪ Opcional (default: false)
      "notes": "Observação do item",              // ⚪ Opcional
      "screen_quantity": 2,                       // ⚪ Opcional (DOOH)
      "face_details": null                        // ⚪ Opcional (OOH) - JSON com detalhes da face
    }
  ]
}

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid-proposta",
    "proposal_number": "PROP-0124-24",
    "title": "Campanha Verão 2024",
    "status": "draft",
    "final_value": 250005,
    "items_count": 1,
    "created_at": "2024-01-06T16:00:00Z",
    "created_via": "api"
  },
  "message": "Proposta criada com sucesso"
}

GET /api/v1/public/proposals/{id}

Consulta proposta específica com todos os detalhes.

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid",
    "proposal_number": "PROP-0123-24",
    "title": "Campanha Verão 2024",
    "description": "Campanha de mídia exterior",
    "status": "approved",
    "total_value": 500000,
    "discount_percentage": 10,
    "discount_value": 50000,
    "final_value": 450000,
    "campaign_start_date": "2024-01-15",
    "campaign_end_date": "2024-01-29",
    "bonus_days": 0,
    "valid_until": "2024-01-10T23:59:59Z",
    "notes": "Observações internas",
    "commercial_notes": "Observações para cliente",
    "created_at": "2024-01-05T10:00:00Z",
    "updated_at": "2024-01-06T15:00:00Z",
    "created_via": "api",
    "client": {
      "id": "uuid",
      "name": "João Silva",
      "email": "joao@empresa.com",
      "company_name": "Empresa XYZ"
    },
    "proposal_items": [
      {
        "id": "uuid-item",
        "vehicle_id": "uuid",
        "quantity": 1,
        "unit_price": 500000,
        "final_price": 250005,
        "is_bonus": false,
        "screen_quantity": 2,
        "media_vehicle": {
          "id": "uuid",
          "name": "Painel Digital Shopping",
          "media_type": "DOOH",
          "city": "Brasília",
          "state": "DF"
        }
      }
    ]
  }
}

PUT /api/v1/public/proposals/{id}

Edita proposta existente.

⚠️ Restrição: Não pode editar propostas com status approved ou rejected.

Body (todos campos opcionais):


{
  "title": "Novo Título",                   // ⚪ Opcional
  "description": "Nova descrição",          // ⚪ Opcional
  "status": "sent",                         // ⚪ Opcional (draft, sent, viewed, approved, rejected)
  "discount_percentage": 15,                // ⚪ Opcional
  "discount_value": 0,                      // ⚪ Opcional (centavos)
  "valid_until": "2024-02-10",              // ⚪ Opcional (YYYY-MM-DD)
  "notes": "Novas observações",             // ⚪ Opcional
  "commercial_notes": "Obs para cliente",   // ⚪ Opcional
  "items": [                                // ⚪ Opcional (se enviar, SUBSTITUI todos)
    {
      "vehicle_id": "uuid",                 // ✅ OBRIGATÓRIO (se enviar items)
      "quantity": 1,                        // ✅ OBRIGATÓRIO (se enviar items)
      "unit_price": 500000,                 // ✅ OBRIGATÓRIO (se enviar items)
      "final_price": 250005,                // ✅ OBRIGATÓRIO (se enviar items)
      "is_bonus": false,                    // ⚪ Opcional
      "screen_quantity": 2                  // ⚪ Opcional (DOOH)
    }
  ]
}

Comportamento:

Se enviar items: TODOS os itens atuais são DELETADOS e substituídos pelos novos
Se NÃO enviar items: Os itens atuais são MANTIDOS
Totais são recalculados automaticamente se mudar items ou descontos

Resposta:


{
  "success": true,
  "data": {
    "id": "uuid",
    "proposal_number": "PROP-0123-24",
    "title": "Novo Título",
    "status": "sent",
    "final_value": 200004,
    "updated_at": "2024-01-06T16:45:00Z"
  },
  "message": "Proposta atualizada com sucesso"
}

📊 RESUMO DE TODOS OS ENDPOINTS

Método	Endpoint	Descrição	Campos Obrigatórios
POST	`/auth/token`	Gerar access token	`api_key`, `api_secret`
GET	`/inventory/list`	Listar inventário	-
GET	`/inventory/{id}`	Consultar item	-
GET	`/clients`	Listar clientes	-
POST	`/clients`	Criar cliente	`name`
GET	`/clients/{id}`	Consultar cliente + propostas	-
PUT	`/clients/{id}`	Editar cliente	- (todos opcionais)
POST	`/proposals/calculate`	Calcular valores	`campaign_start_date`, `campaign_end_date`, `items`
GET	`/proposals`	Listar propostas	-
POST	`/proposals`	Criar proposta	`client_id`, `title`, `campaign_start_date`, `campaign_end_date`, `items`
GET	`/proposals/{id}`	Consultar proposta	-
PUT	`/proposals/{id}`	Editar proposta	- (todos opcionais)

🎯 FLUXO COMPLETO DE INTEGRAÇÃO


// 1. AUTENTICAÇÃO (1x por hora)
const tokenRes = await fetch('https://www.hivestr.com/api/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: process.env.API_KEY,
    api_secret: process.env.API_SECRET
  })
});
const { access_token } = await tokenRes.json();

// 2. BUSCAR/CRIAR CLIENTE
const clientRes = await fetch('https://www.hivestr.com/api/v1/public/clients?search=joao@empresa.com', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const clientData = await clientRes.json();

let clientId;
if (clientData.data.length > 0) {
  clientId = clientData.data[0].id;
} else {
  const createRes = await fetch('https://www.hivestr.com/api/v1/public/clients', {
    method: 'POST',
    headers: { 
      'Authorization': `Bearer ${access_token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: "João Silva", email: "joao@empresa.com" })
  });
  const newClient = await createRes.json();
  clientId = newClient.data.id;
}

// 3. CALCULAR PROPOSTA
const calcRes = await fetch('https://www.hivestr.com/api/v1/public/proposals/calculate', {
  method: 'POST',
  headers: { 
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaign_start_date: "2024-01-15",
    campaign_end_date: "2024-01-29",
    items: [{ vehicle_id: "uuid-vehicle" }]
  })
});
const calcData = await calcRes.json();

// 4. CRIAR PROPOSTA
const proposalRes = await fetch('https://www.hivestr.com/api/v1/public/proposals', {
  method: 'POST',
  headers: { 
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: clientId,
    title: "Campanha Verão 2024",
    campaign_start_date: "2024-01-15",
    campaign_end_date: "2024-01-29",
    items: calcData.data.items
  })
});
const proposal = await proposalRes.json();
const proposalId = proposal.data.id;

// 5. ENVIAR PROPOSTA (mudar status)
await fetch(`https://www.hivestr.com/api/v1/public/proposals/${proposalId}`, {
  method: 'PUT',
  headers: { 
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ status: "sent" })
});

// 6. CONSULTAR PROPOSTA
const getRes = await fetch(`https://www.hivestr.com/api/v1/public/proposals/${proposalId}`, {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const fullProposal = await getRes.json();

📌 OBSERVAÇÕES IMPORTANTES

Valores Monetários

Todos os valores são em centavos:

R$ 500,00 = 50000
R$ 1.234,56 = 123456

Datas

Formato ISO 8601: YYYY-MM-DD

Data: 2024-01-15
Data/Hora: 2024-01-15T10:30:00Z

created_via

Propostas criadas via API têm created_via: "api" automaticamente.

Rate Limiting

Básico: 1.000 req/hora
Professional: 5.000 req/hora
Enterprise: Ilimitado

Erros Comuns

401: Token expirado → Gerar novo em /auth/token
403: Sem permissão → Verificar permissões da API Key
404: Recurso não encontrado → Verificar ID
429: Rate limit excedido → Aguardar reset (1 hora)
500: Erro interno → Verificar logs/campos enviados

🔄 RENOVAÇÃO AUTOMÁTICA DE TOKEN


let currentToken = null;
let tokenExpiry = null;

async function getValidToken() {
  const now = Date.now();
  
  // Se token não existe ou expira em menos de 10min, renova
  if (!currentToken || !tokenExpiry || now >= tokenExpiry - (10 * 60 * 1000)) {
    const res = await fetch('https://www.hivestr.com/api/v1/auth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        api_key: process.env.API_KEY,
        api_secret: process.env.API_SECRET
      })
    });
    const data = await res.json();
    currentToken = data.access_token;
    tokenExpiry = now + (50 * 60 * 1000); // Renova a cada 50min
  }
  
  return currentToken;
}

Documentação completa de todos os endpoints! 📚

Documentação da API Hivestr

API Pública - Hivestr

🔐 1. AUTENTICAÇÃO

POST /api/v1/auth/token

📦 2. INVENTÁRIO

GET /api/v1/public/inventory/list

GET /api/v1/public/inventory/{id}

👥 3. CLIENTES

GET /api/v1/public/clients

POST /api/v1/public/clients

GET /api/v1/public/clients/{id}

PUT /api/v1/public/clients/{id}

📋 4. PROPOSTAS

POST /api/v1/public/proposals/calculate

GET /api/v1/public/proposals

POST /api/v1/public/proposals

GET /api/v1/public/proposals/{id}

PUT /api/v1/public/proposals/{id}

📊 RESUMO DE TODOS OS ENDPOINTS

🎯 FLUXO COMPLETO DE INTEGRAÇÃO

📌 OBSERVAÇÕES IMPORTANTES

Valores Monetários

Datas

created_via

Rate Limiting

Erros Comuns

🔄 RENOVAÇÃO AUTOMÁTICA DE TOKEN