Skip to main content

Create New Transport Auction

POST 
/company/auction

Creates a new freight transport auction following a structured flow. Requires valid JWT authentication and active payment plan verification.

📋 Complete Flow for Creating a New Shipment​

🔐 Step 1: Authentication and Preparation​

  • Prerequisites:
    • Valid JWT token obtained via login
    • Active payment plan on the company account
    • Verification of auction creation permissions

📝 Step 2: Shipment Data Preparation​

Mandatory information to collect:

  • Pickup point (ETL): Complete address, loading date and time
  • Delivery point (ETD): Complete address, unloading date and time
  • Cargo characteristics: Type, weight (kg), volume (m³)
  • Service code: Unique shipment identifier

Optional information:

  • Special notes (fragile goods, temperature, etc.)
  • Mark as favorite for reuse
  • Private assignment to specific trucker

🚀 Step 3: Draft Creation​

POST /company/auction
  • The system creates the auction in draft state
  • All input data is validated
  • UTC format is verified for dates
  • The service_code is automatically assigned if not provided

✏️ Step 4: Review and Editing (Optional)​

  • State: The auction remains in draft until published
  • Allowed edits: All fields can be modified
  • Validations: The system automatically verifies each change

📢 Step 5: Auction Publication​

  • State change: From draft to published
  • Notification: Alerts are sent to available truckers
  • Visibility: The auction appears in the public marketplace
  • Timer: Starts the offer reception period

💰 Step 6: Offer Reception​

  • Truckers: Can view shipment details
  • Bids: Truckers send their economic offers
  • Tracking: The company can monitor offers in real time
  • Communication: Messaging system for clarifications

🔒 Step 7: Evaluation and Locking​

  • Review: The company evaluates all received offers
  • Locking: Change to locked state to finalize bidding period
  • Prevention: No more offers are accepted once locked

✅ Step 8: Selection and Award​

  • Decision: The company selects the best offer
  • Acceptance: The chosen trucker's bid is accepted
  • Final state: The auction moves to completed
  • Contract: Documentation is automatically generated

📊 Step 9: Tracking and Management​

  • Tracking: Monitoring of transport status
  • Communication: Direct channel with assigned trucker
  • Documentation: Access to contracts and transport documents
  • Billing: Automatic payment and billing management

🎯 Specific Use Cases​

Standard Public Shipment​

  1. Create public auction (is_private: false)
  2. Publish in marketplace
  3. Receive multiple offers
  4. Select best price/service

Private/Direct Shipment​

  1. Create private auction (is_private: true)
  2. Assign specific trucker (trucker)
  3. Direct negotiation without competition
  4. Immediate acceptance

Urgent Shipment​

  1. Create with very close dates
  2. Publish immediately
  3. Accept first valid offer
  4. Prioritize speed over price

⚡ Critical Validations​

  • Dates: Mandatory UTC format (YYYY-MM-DDTHH:mm:ssZ)
  • Weight/Volume: Positive numeric values
  • Addresses: Valid address format
  • Payment plan: Active subscription verification
  • Limits: Respect to plan limits (number of shipments/month)

Request​

Responses​

Auction created successfully.