Public API - Hivestr

Complete documentation for the public API for integration with external systems.

CRM write access: in addition to querying inventory, clients, and proposals, the API allows you to create and update data — clients, proposals, client notes, and sales pipeline cards.

Last updated: 02/06/2026
API version: v1
Production Base URL: https://www.hivestr.com/api/v1

🔐 1. AUTHENTICATION

POST /api/v1/auth/token

Generates a JWT Access Token valid for 1 hour.

Headers: None
Body:


{
  "api_key": "hvstr_abc123...",      // ✅ REQUIRED
  "api_secret": "secret456..."        // ✅ REQUIRED
}

Response:


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

Usage: Use the access_token in all subsequent requests in the header:
Authorization: Bearer {access_token}

📦 2. INVENTORY

GET /api/v1/public/inventory/list

Lists the media owner's out-of-home inventory.

Query Params (all optional):

?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)

Response:


{
  "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,        // In cents
      "unit_price": 16667,         // Daily price (cents)
      "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}

Retrieves a specific inventory item with programming (TV/Radio).

Response:


{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Rádio CBN Brasília - Manhã",
    "media_type": "RADIO",
    // ... all fields from list
    "media_schedules": [
      {
        "id": "uuid-schedule",
        "run_days": [1, 2, 3, 4, 5],  // Mon-Fri (0=Sun, 1=Mon, ..., 6=Sat)
        "start_time": "07:00:00",
        "end_time": "09:00:00",
        "price_per_slot": 150000,     // R$ 1,500.00 in cents
        "available_slots": 10,
        "program_name": "Jornal da Manhã",
        "social_class": "A,B",
        "audience": 100000,
        "is_active": true
      }
    ]
  }
}

👥 3. CLIENTS

GET /api/v1/public/clients

Lists the media owner's clients.

Query Params (all optional):

?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)

Response:


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

Creates a new client.

Body:


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

Response:


{
  "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 to update the card title, value, and notes via PATCH /pipeline/deals/{id}.

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

Retrieves a specific client with all proposals.

Response:


{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "João Silva",
    // ... all client fields
    "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}

Updates an existing client.

Body (all fields optional):


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

Response:


{
  "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. PROPOSALS

POST /api/v1/public/proposals/calculate

Automatically calculates proposal values (DOOH, OOH, TV/Radio).

Body:


{
  "campaign_start_date": "2024-01-15",   // ✅ REQUIRED (YYYY-MM-DD)
  "campaign_end_date": "2024-01-29",     // ✅ REQUIRED (YYYY-MM-DD)
  "bonus_days": 2,                       // ⚪ Optional (default: 0)
  "discount_percentage": 10,             // ⚪ Optional (default: 0)
  "sell_by_insertions": false,           // ⚪ Optional (default: false) - DOOH only
  "daily_insertions_per_screen": 50,     // ⚪ Optional (default: 50) - If sell_by_insertions=true
  "items": [                             // ✅ REQUIRED (min: 1 item)
    {
      "vehicle_id": "uuid-dooh-1",       // ✅ REQUIRED
      "is_bonus": false                  // ⚪ Optional (default: false)
    },
    {
      "vehicle_id": "uuid-ooh-1",        // ✅ REQUIRED
      "face_orientation": "Fluxo",       // ⚪ Optional (OOH) - Fluxo or Contra-Fluxo
      "is_bonus": false
    },
    {
      "vehicle_id": "uuid-tv-1",         // ✅ REQUIRED
      "schedule_id": "uuid-schedule",    // ✅ REQUIRED (TV/Radio)
      "quantity": 10,                    // ⚪ Optional (default: 1) - Number of insertions
      "is_bonus": false
    }
  ]
}

Response:


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

Lists the media owner's proposals.

Query Params (all optional):

?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

Response:


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

Creates a new proposal (use values calculated by /calculate).

Body:


{
  "client_id": "uuid-cliente",                    // ✅ REQUIRED
  "title": "Campanha Verão 2024",                 // ✅ REQUIRED
  "description": "Campanha de mídia exterior",    // ⚪ Optional
  "campaign_start_date": "2024-01-15",            // ✅ REQUIRED (YYYY-MM-DD)
  "campaign_end_date": "2024-01-29",              // ✅ REQUIRED (YYYY-MM-DD)
  "bonus_days": 0,                                // ⚪ Optional (default: 0)
  "discount_percentage": 0,                       // ⚪ Optional (default: 0)
  "discount_value": 0,                            // ⚪ Optional (default: 0) - In cents
  "valid_until": "2024-01-10",                    // ⚪ Optional (YYYY-MM-DD)
  "commercial_notes": "Obs para cliente",         // ⚪ Optional
  "notes": "Obs internas",                        // ⚪ Optional
  "advertising_agency": "Agência ABC",            // ⚪ Optional
  "agency_commission_percentage": 15,             // ⚪ Optional (default: 0)
  "has_volume_commission": false,                 // ⚪ Optional (default: false)
  "volume_commission_percentage": 0,              // ⚪ Optional (default: 0)
  "sell_by_insertions": false,                    // ⚪ Optional (default: false)
  "daily_insertions_per_screen": null,            // ⚪ Optional (if sell_by_insertions=true)
  "items": [                                      // ✅ REQUIRED (min: 1 item)
    {
      "vehicle_id": "uuid-dooh-1",                // ✅ REQUIRED
      "schedule_id": null,                        // ⚪ Optional (required for TV/Radio)
      "quantity": 1,                              // ✅ REQUIRED
      "unit_price": 500000,                       // ✅ REQUIRED (cents)
      "discount_percentage": 0,                   // ⚪ Optional (default: 0)
      "discount_value": 0,                        // ⚪ Optional (default: 0) - In cents
      "final_price": 250005,                      // ✅ REQUIRED (cents)
      "is_bonus": false,                          // ⚪ Optional (default: false)
      "notes": "Observação do item",              // ⚪ Optional
      "screen_quantity": 2,                       // ⚪ Optional (DOOH)
      "face_details": null                        // ⚪ Optional (OOH) - JSON with face details
    }
  ]
}

Response:


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

Retrieves a specific proposal with all details.

Response:


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

Updates an existing proposal.

⚠️ Restriction: Cannot edit proposals with status approved or rejected.

Body (all fields optional):


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

Behavior:

If you send items: ALL current items are DELETED and replaced with the new ones
If you do NOT send items: Current items are KEPT
Totals are recalculated automatically if items or discounts change

Response:


{
  "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 (NOTES AND PIPELINE)

Endpoints to write data to the CRM externally: client notes, pipeline cards, and stage movement.

Required API Key permission: clients: true

When creating a client via POST /clients, a card is automatically created in the pipeline (stage Prospecção).

Pipeline stages (`pipeline_stage`)

Exact values accepted by the API (always in Portuguese, case-sensitive):

Value	Description	Linked proposal status*
`Prospecção`	Initial contact; no formal proposal yet	`draft`
`Degustação`	Client exploring product/service (demo/trial)	`draft`
`Proposta`	Proposal sent, awaiting review	`sent`
`Negociação`	Client evaluating pricing and terms	`viewed`
`Aprovação`	Interest confirmed; internal approval	`pre_approved`
`Ganho`	Deal closed	`approved`
`Perdido`	Client declined or deal did not progress	`rejected`

* When the card has a linked proposal, moving the stage via PATCH /pipeline/deals/{id}/stage automatically syncs the proposal status.

Important rules:

Default when creating a client or card: Prospecção
Do not use PATCH .../stage for Perdido — use POST .../mark-lost with the reason field
Cards in Perdido cannot be moved or edited
Cards in Ganho or Perdido do not count toward the active pipeline total value

Filter example:

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

Stage movement example:


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

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

Lists client notes/interactions.

Query Params (optional):

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

Response:


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

Records a note in the client's history.

Body:


{
  "content": "Cliente recusou proposta por budget",  // ✅ REQUIRED
  "note_type": "follow_up"                           // ⚪ Optional (default: note)
}

Valid types: note, task, reminder, follow_up

GET /api/v1/public/pipeline/deals

Lists sales pipeline cards.

Query Params (optional):

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

Each card includes 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

Lists tasks that are overdue or due in the next 24 hours (equivalent to the pipeline notification bell).

Query Params (optional):

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

Response:


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

urgency values: overdue (overdue), due_today (today), due_soon (next 24h)

POST /api/v1/public/pipeline/deals

Creates a manual card in the pipeline.

Body:


{
  "client_id": "uuid",                    // ✅ REQUIRED
  "title": "Follow-up campanha verão",   // ✅ REQUIRED
  "pipeline_stage": "Prospecção",        // ⚪ Optional — see stages table
  "estimated_value": 500000,             // ⚪ Optional (cents)
  "notes": "Lead vindo do RD Station",   // ⚪ Optional
  "user_id": "uuid-vendedor"             // ⚪ Optional (default: API Key creator)
}

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

Retrieves a specific pipeline card.

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

Updates card information (title, value, notes, assignee).

Body (all optional, send at least one):


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

Restrictions:

Cards in Perdido cannot be edited
To move stages, use PATCH /pipeline/deals/{id}/stage
Monetary values in cents

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

Moves a card to another pipeline stage.

Body:


{
  "pipeline_stage": "Negociação"   // ✅ REQUIRED
}

Restrictions:

Do not use this endpoint for Perdido — use mark-lost with a reason
Cards already in Perdido cannot be moved

If the card has a linked proposal, the proposal status is synced automatically.

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

Marks the deal as lost and records a note on the client.

Body:


{
  "reason": "Cliente escolheu concorrente"   // ✅ REQUIRED
}

Behavior:

Moves the card to stage Perdido
If there is a linked proposal, marks it as rejected
Creates an automatic note in client_notes with the reason

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

Lists tasks for a pipeline card.

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

Creates a task with an optional due date.

Body:


{
  "title": "Ligar para o cliente",       // ✅ REQUIRED
  "due_at": "2026-06-02T14:30:00Z",      // ⚪ Optional (ISO 8601)
  "user_id": "uuid-vendedor"             // ⚪ Optional (default: API Key creator)
}

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

Updates a task (mark complete, change due date, etc.).

Body (send at least one):


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

Removes a task.

📊 ALL ENDPOINTS SUMMARY

Method	Endpoint	Description	Required Fields
POST	`/auth/token`	Generate access token	`api_key`, `api_secret`
GET	`/inventory/list`	List inventory	-
GET	`/inventory/{id}`	Retrieve item	-
GET	`/clients`	List clients	-
POST	`/clients`	Create client	`name`
GET	`/clients/{id}`	Retrieve client + proposals	-
PUT	`/clients/{id}`	Update client	- (all optional)
GET	`/clients/{id}/notes`	List client notes	-
POST	`/clients/{id}/notes`	Create client note	`content`
GET	`/pipeline/deals`	List pipeline cards	-
POST	`/pipeline/deals`	Create pipeline card	`client_id`, `title`
GET	`/pipeline/deals/{id}`	Retrieve pipeline card	-
PATCH	`/pipeline/deals/{id}`	Update pipeline card	- (title, notes, estimated_value, user_id)
PATCH	`/pipeline/deals/{id}/stage`	Move card stage	`pipeline_stage`
POST	`/pipeline/deals/{id}/mark-lost`	Mark deal as lost	`reason`
GET	`/pipeline/reminders`	Task reminders (24h)	-
GET	`/pipeline/deals/{id}/tasks`	List card tasks	-
POST	`/pipeline/deals/{id}/tasks`	Create task with due date	`title`
PATCH	`/pipeline/deals/{id}/tasks/{taskId}`	Update task	-
DELETE	`/pipeline/deals/{id}/tasks/{taskId}`	Delete task	-
POST	`/proposals/calculate`	Calculate values	`campaign_start_date`, `campaign_end_date`, `items`
GET	`/proposals`	List proposals	-
POST	`/proposals`	Create proposal	`client_id`, `title`, `campaign_start_date`, `campaign_end_date`, `items`
GET	`/proposals/{id}`	Retrieve proposal	-
PUT	`/proposals/{id}`	Update proposal	- (all optional)

🎯 COMPLETE INTEGRATION FLOW


// 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();

📌 IMPORTANT NOTES

Monetary Values

All values are in cents:

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

Dates

ISO 8601 format: YYYY-MM-DD

Date: 2024-01-15
Date/Time: 2024-01-15T10:30:00Z

created_via

Proposals created via API automatically have created_via: "api".

Rate Limiting

Basic: 1,000 req/hour
Professional: 5,000 req/hour
Enterprise: Unlimited

Common Errors

401: Token expired → Generate a new one at /auth/token
403: No permission → Check API Key permissions
404: Resource not found → Check ID
429: Rate limit exceeded → Wait for reset (1 hour)
500: Internal error → Check logs/submitted fields

🔄 AUTOMATIC TOKEN RENEWAL


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

Complete documentation for all endpoints! 📚

Hivestr API Documentation

Public API - Hivestr

🔐 1. AUTHENTICATION

POST /api/v1/auth/token

📦 2. INVENTORY

GET /api/v1/public/inventory/list

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

👥 3. CLIENTS

GET /api/v1/public/clients

POST /api/v1/public/clients

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

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

📋 4. PROPOSALS

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 (NOTES AND PIPELINE)

Pipeline stages (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}

📊 ALL ENDPOINTS SUMMARY

🎯 COMPLETE INTEGRATION FLOW

📌 IMPORTANT NOTES

Monetary Values

Dates

created_via

Rate Limiting

Common Errors

🔄 AUTOMATIC TOKEN RENEWAL

Pipeline stages (`pipeline_stage`)