API Pública - Hivestr

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

Escrita no CRM: além de consultar inventário, clientes e propostas, a API permite criar e atualizar dados — clientes, propostas, notas do cliente e cards do pipeline de vendas.

Última atualização: 02/06/2026
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"
  },
  "pipeline_deal": {
    "id": "uuid-do-card",
    "title": "João Silva — Empresa XYZ",
    "pipeline_stage": "Prospecção",
    "estimated_value": null,
    "notes": "Cliente indicado"
  },
  "message": "Cliente criado com sucesso"
}

Use pipeline_deal.id para atualizar título, valor e observações do card via PATCH /pipeline/deals/{id}.

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"
}

🧩 5. CRM (NOTAS E PIPELINE)

Endpoints para gravar dados no CRM externamente: notas do cliente, cards do pipeline e movimentação de estágios.

Permissão necessária na API Key: clients: true

Ao criar um cliente via POST /clients, um card é criado automaticamente no pipeline (estágio Prospecção).

Estágios do pipeline (`pipeline_stage`)

Valores exatos aceitos pela API (sempre em português, case-sensitive):

Valor	Descrição	Status da proposta vinculada*
`Prospecção`	Contato inicial; ainda sem proposta formal	`draft`
`Degustação`	Cliente conhecendo produto/serviço (demo/teste)	`draft`
`Proposta`	Proposta enviada, aguardando análise	`sent`
`Negociação`	Cliente avaliando valores e condições	`viewed`
`Aprovação`	Interesse confirmado; aprovação interna	`pre_approved`
`Ganho`	Negócio fechado	`approved`
`Perdido`	Cliente recusou ou deal não avançou	`rejected`

* Quando o card tem proposta vinculada, mover o estágio via PATCH /pipeline/deals/{id}/stage sincroniza o status da proposta automaticamente.

Regras importantes:

Default ao criar cliente ou card: Prospecção
Não use PATCH .../stage para Perdido — use POST .../mark-lost com o campo reason
Cards em Perdido não podem ser movidos nem editados
Cards em Ganho ou Perdido não entram no valor total ativo do pipeline

Exemplo de filtro:

GET /api/v1/public/pipeline/deals?pipeline_stage=Negociação

Exemplo de movimentação:


PATCH /api/v1/public/pipeline/deals/{id}/stage
{ "pipeline_stage": "Aprovação" }

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

Lista notas/interações do cliente.

Query Params (opcionais):

?note_type=follow_up    // note, task, reminder, follow_up, all
&page=1
&limit=50

Resposta:


{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "client_id": "uuid",
      "content": "Cliente pediu retorno na sexta",
      "note_type": "follow_up",
      "is_completed": false,
      "created_at": "2026-06-02T10:00:00Z",
      "user": { "id": "uuid", "full_name": "Maria Silva" }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 3, "total_pages": 1 }
}

POST /api/v1/public/clients/{id}/notes

Registra uma nota no histórico do cliente.

Body:


{
  "content": "Cliente recusou proposta por budget",  // ✅ OBRIGATÓRIO
  "note_type": "follow_up"                           // ⚪ Opcional (default: note)
}

Tipos válidos: note, task, reminder, follow_up

GET /api/v1/public/pipeline/deals

Lista cards do pipeline de vendas.

Query Params (opcionais):

?client_id=uuid
&pipeline_stage=Negociação    // Ver tabela de estágios acima
&page=1
&limit=50

Cada card inclui tasks_summary:


{
  "tasks_summary": {
    "pending": 2,
    "total": 3,
    "overdue": 1,
    "due_soon": 2,
    "next_due_at": "2026-06-02T14:30:00Z"
  }
}

GET /api/v1/public/pipeline/reminders

Lista tarefas com prazo vencido ou nas próximas 24 horas (equivalente ao sininho do pipeline).

Query Params (opcionais):

?user_id=uuid-vendedor    // Filtra por responsável da tarefa ou do deal

Resposta:


{
  "success": true,
  "count": 2,
  "overdue_count": 1,
  "data": [
    {
      "id": "uuid-tarefa",
      "title": "Ligar para o cliente",
      "due_at": "2026-06-02T10:00:00Z",
      "urgency": "overdue",
      "deal_id": "uuid-deal",
      "deal_title": "Campanha verão",
      "pipeline_stage": "Negociação",
      "client_name": "João Silva",
      "assignee_name": "Maria Vendedora"
    }
  ]
}

Valores de urgency: overdue (atrasada), due_today (hoje), due_soon (próximas 24h)

POST /api/v1/public/pipeline/deals

Cria um card manual no pipeline.

Body:


{
  "client_id": "uuid",                    // ✅ OBRIGATÓRIO
  "title": "Follow-up campanha verão",   // ✅ OBRIGATÓRIO
  "pipeline_stage": "Prospecção",        // ⚪ Opcional — ver tabela de estágios
  "estimated_value": 500000,             // ⚪ Opcional (centavos)
  "notes": "Lead vindo do RD Station",   // ⚪ Opcional
  "user_id": "uuid-vendedor"             // ⚪ Opcional (default: criador da API Key)
}

GET /api/v1/public/pipeline/deals/{id}

Consulta um card específico do pipeline.

PATCH /api/v1/public/pipeline/deals/{id}

Atualiza informações do card (título, valor, observações, responsável).

Body (todos opcionais, envie ao menos um):


{
  "title": "Campanha verão 2026",
  "estimated_value": 500000,
  "notes": "Budget aprovado pelo marketing",
  "user_id": "uuid-vendedor"
}

Restrições:

Cards em Perdido não podem ser editados
Para mover de estágio, use PATCH /pipeline/deals/{id}/stage
Valores monetários em centavos

PATCH /api/v1/public/pipeline/deals/{id}/stage

Move um card para outro estágio do pipeline.

Body:


{
  "pipeline_stage": "Negociação"   // ✅ OBRIGATÓRIO
}

Restrições:

Não use este endpoint para Perdido — use mark-lost com motivo
Cards já em Perdido não podem ser movidos

Se o card tiver proposta vinculada, o status da proposta é sincronizado automaticamente.

POST /api/v1/public/pipeline/deals/{id}/mark-lost

Marca o deal como perdido e registra nota no cliente.

Body:


{
  "reason": "Cliente escolheu concorrente"   // ✅ OBRIGATÓRIO
}

Comportamento:

Move o card para estágio Perdido
Se houver proposta vinculada, marca como rejected
Cria nota automática em client_notes com o motivo

GET /api/v1/public/pipeline/deals/{id}/tasks

Lista tarefas de um card do pipeline.

POST /api/v1/public/pipeline/deals/{id}/tasks

Cria tarefa com prazo opcional.

Body:


{
  "title": "Ligar para o cliente",       // ✅ OBRIGATÓRIO
  "due_at": "2026-06-02T14:30:00Z",      // ⚪ Opcional (ISO 8601)
  "user_id": "uuid-vendedor"             // ⚪ Opcional (default: criador da API Key)
}

PATCH /api/v1/public/pipeline/deals/{id}/tasks/{taskId}

Atualiza tarefa (marcar concluída, alterar prazo, etc.).

Body (envie ao menos um):


{
  "title": "Retornar ligação",
  "due_at": "2026-06-03T09:00:00Z",
  "is_completed": true,
  "user_id": "uuid-vendedor"
}

DELETE /api/v1/public/pipeline/deals/{id}/tasks/{taskId}

Remove uma tarefa.

📊 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)
GET	`/clients/{id}/notes`	Listar notas do cliente	-
POST	`/clients/{id}/notes`	Criar nota no cliente	`content`
GET	`/pipeline/deals`	Listar cards do pipeline	-
POST	`/pipeline/deals`	Criar card no pipeline	`client_id`, `title`
GET	`/pipeline/deals/{id}`	Consultar card do pipeline	-
PATCH	`/pipeline/deals/{id}`	Editar card do pipeline	- (title, notes, estimated_value, user_id)
PATCH	`/pipeline/deals/{id}/stage`	Mover card de estágio	`pipeline_stage`
POST	`/pipeline/deals/{id}/mark-lost`	Marcar deal como perdido	`reason`
GET	`/pipeline/reminders`	Lembretes de tarefas (24h)	-
GET	`/pipeline/deals/{id}/tasks`	Listar tarefas do card	-
POST	`/pipeline/deals/{id}/tasks`	Criar tarefa com prazo	`title`
PATCH	`/pipeline/deals/{id}/tasks/{taskId}`	Atualizar tarefa	-
DELETE	`/pipeline/deals/{id}/tasks/{taskId}`	Excluir tarefa	-
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;
let dealId;
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;
  dealId = newClient.pipeline_deal?.id;
}

// 2b. ATUALIZAR CARD DO PIPELINE (opcional)
if (dealId) {
  await fetch(`https://www.hivestr.com/api/v1/public/pipeline/deals/${dealId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${access_token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'Campanha verão — João Silva',
      estimated_value: 500000,
      notes: 'Lead captado via integração externa'
    })
  });
}

// 2c. REGISTRAR NOTA NO CRM (opcional)
await fetch(`https://www.hivestr.com/api/v1/public/clients/${clientId}/notes`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'Lead captado via integração externa',
    note_type: 'follow_up'
  })
});

// 2d. CRIAR CARD NO PIPELINE (opcional — POST /clients já cria card em Prospecção)
await fetch('https://www.hivestr.com/api/v1/public/pipeline/deals', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_id: clientId,
    title: 'Follow-up integração',
    pipeline_stage: 'Degustação'
  })
});

// 2e. CRIAR TAREFA COM PRAZO (opcional)
await fetch(`https://www.hivestr.com/api/v1/public/pipeline/deals/${dealId}/tasks`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Ligar para confirmar interesse',
    due_at: new Date(Date.now() + 3600000).toISOString()
  })
});

// 2f. CONSULTAR LEMBRETES (sininho)
const remindersRes = await fetch('https://www.hivestr.com/api/v1/public/pipeline/reminders', {
  headers: { 'Authorization': `Bearer ${access_token}` }
});
const reminders = await remindersRes.json();

// 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}

🧩 5. CRM (NOTAS E PIPELINE)

Estágios do pipeline (pipeline_stage)

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

POST /api/v1/public/clients/{id}/notes

GET /api/v1/public/pipeline/deals

GET /api/v1/public/pipeline/reminders

POST /api/v1/public/pipeline/deals

GET /api/v1/public/pipeline/deals/{id}

PATCH /api/v1/public/pipeline/deals/{id}

PATCH /api/v1/public/pipeline/deals/{id}/stage

POST /api/v1/public/pipeline/deals/{id}/mark-lost

GET /api/v1/public/pipeline/deals/{id}/tasks

POST /api/v1/public/pipeline/deals/{id}/tasks

PATCH /api/v1/public/pipeline/deals/{id}/tasks/{taskId}

DELETE /api/v1/public/pipeline/deals/{id}/tasks/{taskId}

📊 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

Estágios do pipeline (`pipeline_stage`)