How to Integrate Freightos with V0

Start by prompting V0 to generate the front-end interface for your freight quote tool. The UI needs two main sections: a quote request form where users enter shipment details, and a results area that displays the carrier quotes returned by the API. For the quote form, the typical Freightos rate request requires origin and destination (usually port codes like SHA for Shanghai or NLRTM for Rotterdam), cargo type (FCL for full container, LCL for less-than-container, or air freight), commodity weight and volume, and optionally an HS code or commodity description. V0 is good at generating clean, accessible form components with Tailwind CSS — tell it exactly what fields you need and what API endpoint the form should POST to. For the results display, a card grid or sortable table works well. Each quote from Freightos includes the carrier name, service type, transit time in days, departure and arrival dates, and the rate. A sortable table that lets users click column headers to re-sort by price or transit time is a practical feature that V0 can generate with a few lines of React state. After V0 generates the components, check that the form's submit handler calls fetch('/api/freightos/quotes', { method: 'POST', ... }) with the correct request body shape. You will define the exact request schema when you build the API route in the next step, so it is fine if the form just sends all the fields as a JSON object for now. Make sure the results component handles the loading state with a spinner or skeleton while the API call is in progress — Freightos quotes can take a few seconds to return.

Now create the Next.js API route that proxies requests to the Freightos WebCargo API. This server-side route keeps your API credentials secure and handles the HTTP communication with Freightos on behalf of your V0-generated frontend. Create the file app/api/freightos/route.ts in your project. The Freightos WebCargo API uses REST endpoints with API key authentication. The primary endpoint for fetching freight rates is typically a POST request to the WebCargo API that accepts your shipment parameters and returns available quotes. Authentication is via an Authorization header with your API key. The WebCargo API may return quotes synchronously for some routes and asynchronously (requiring polling) for others. For a robust implementation, your API route should handle both cases: if the initial response includes quotes directly, return them immediately; if the response includes a quote request ID, return that ID so the frontend can poll a status endpoint. For the initial version, focus on the synchronous flow where quotes are returned directly. Structure the route to accept the form data from your V0 components — origin, destination, cargo details — transform them into the format the WebCargo API expects, make the authenticated request, and return the normalized quote data to the client. Add proper error handling for cases where the API is unavailable or returns an error status code. Note that V0 generates standard Next.js App Router code, which means your route handler uses the Web Fetch API (not the Node.js http module). You can use fetch() natively in your route handler without importing any HTTP library, which keeps the implementation clean.

1import { NextRequest, NextResponse } from 'next/server';
2
3const WEBCARGO_API_URL = 'https://api.webcargo.co/v1';
4
5interface FreightQuoteRequest {
6  origin: string;
7  destination: string;
8  shipmentType: 'FCL' | 'LCL' | 'AIR';
9  weightKg: number;
10  volumeCbm: number;
11}
12
13interface FreightQuote {
14  carrierId: string;
15  carrierName: string;
16  transitDays: number;
17  departureDate: string;
18  arrivalDate: string;
19  rateUsd: number;
20  serviceType: string;
21}
22
23export async function POST(request: NextRequest) {
24  try {
25    const body: FreightQuoteRequest = await request.json();
26
27    if (!body.origin || !body.destination) {
28      return NextResponse.json(
29        { error: 'Origin and destination are required' },
30        { status: 400 }
31      );
32    }
33
34    const apiKey = process.env.FREIGHTOS_API_KEY;
35    if (!apiKey) {
36      return NextResponse.json(
37        { error: 'Freightos API key not configured' },
38        { status: 500 }
39      );
40    }
41
42    // Map shipment type to WebCargo format
43    const modeMap = { FCL: 'ocean_fcl', LCL: 'ocean_lcl', AIR: 'air' };
44
45    const quotePayload = {
46      origin: { port_code: body.origin.split(' ')[0] },
47      destination: { port_code: body.destination.split(' ')[0] },
48      cargo: {
49        mode: modeMap[body.shipmentType] || 'ocean_fcl',
50        weight: { value: body.weightKg, unit: 'kg' },
51        volume: { value: body.volumeCbm, unit: 'cbm' },
52      },
53    };
54
55    const response = await fetch(`${WEBCARGO_API_URL}/rates`, {
56      method: 'POST',
57      headers: {
58        'Authorization': `Bearer ${apiKey}`,
59        'Content-Type': 'application/json',
60        'Accept': 'application/json',
61      },
62      body: JSON.stringify(quotePayload),
63    });
64
65    if (!response.ok) {
66      const errorText = await response.text();
67      console.error('Freightos API error:', response.status, errorText);
68      return NextResponse.json(
69        { error: `Freightos API returned ${response.status}` },
70        { status: response.status }
71      );
72    }
73
74    const data = await response.json();
75
76    // Normalize the response to our quote format
77    const quotes: FreightQuote[] = (data.rates || data.quotes || []).map(
78      (rate: Record<string, unknown>) => ({
79        carrierId: String(rate.carrier_id || rate.carrierId || ''),
80        carrierName: String(rate.carrier_name || rate.carrierName || 'Unknown Carrier'),
81        transitDays: Number(rate.transit_days || rate.transitDays || 0),
82        departureDate: String(rate.departure_date || rate.departureDate || ''),
83        arrivalDate: String(rate.arrival_date || rate.arrivalDate || ''),
84        rateUsd: Number(rate.total_price?.amount || rate.rateUsd || 0),
85        serviceType: String(rate.service_type || rate.serviceType || body.shipmentType),
86      })
87    );
88
89    return NextResponse.json({ quotes, total: quotes.length });
90  } catch (error) {
91    console.error('Freightos route error:', error);
92    return NextResponse.json(
93      { error: 'Failed to fetch freight quotes' },
94      { status: 500 }
95    );
96  }
97}

Your API route reads FREIGHTOS_API_KEY from environment variables. You need to configure this in Vercel so it is available when your serverless functions run in production — it should never be hardcoded in your source code or sent to the browser. Go to your Vercel Dashboard and open your project. Click the Settings tab, then click Environment Variables in the left sidebar. Add the following variable: FREIGHTOS_API_KEY — set this to your Freightos WebCargo API key from your developer portal. This key must only live on the server side. Do not add the NEXT_PUBLIC_ prefix — that would expose it to the browser and anyone who inspects your JavaScript bundle. Select all three environment scopes: Production, Preview, and Development. If your Freightos API setup requires additional credentials (such as a client ID, account ID, or separate secret), add those as separate environment variables following the same SCREAMING_SNAKE_CASE naming convention. Update your API route code to read these additional variables using process.env.VARIABLE_NAME. After saving the environment variables in Vercel, you must redeploy your project for the new variables to take effect in serverless functions. Trigger a redeployment by pushing any commit to your connected GitHub repository. For local development, create a .env.local file in your project root and add FREIGHTOS_API_KEY=your_key_here. This file should already be listed in .gitignore in your V0-generated project — verify this before committing to avoid accidentally leaking the key to GitHub.

The Freightos WebCargo API uses an asynchronous quote model for some routes and carrier types. Instead of returning quotes immediately, the initial rate request returns a quote request ID, and you must poll a status endpoint until the quotes are ready. This is particularly common for complex multi-leg shipments or routes with limited spot market coverage. To handle this pattern in your V0 app, you need two API routes: one for submitting the initial quote request (app/api/freightos/route.ts, which you already created) and one for polling the status (app/api/freightos/status/route.ts). The frontend polls the status endpoint every 2-3 seconds until the quotes are populated or a timeout is reached. On the frontend side, V0 can generate the polling logic using React's useEffect hook and a state machine pattern. The UI transitions through states: idle (form shown), loading (request submitted, polling), results (quotes received), and error (timeout or API failure). Ask V0 to generate a component that manages this state and auto-stops polling after a reasonable timeout like 30 seconds. For the status polling API route, it should accept a GET request with the quote request ID, call the Freightos status endpoint, and return either the quotes (if ready) or a status indicator (if still processing). Include appropriate caching headers to prevent Vercel from caching intermediate polling responses. This asynchronous pattern is a V0 limitation to be aware of: V0's preview sandbox runs in Vercel Sandbox VMs with real server execution, but complex polling logic with state management may need refinement after initial generation. If V0's polling implementation does not behave correctly in the preview, pull the code locally and test with your real Freightos credentials before deploying.

1import { NextRequest, NextResponse } from 'next/server';
2
3const WEBCARGO_API_URL = 'https://api.webcargo.co/v1';
4
5export async function GET(request: NextRequest) {
6  const { searchParams } = new URL(request.url);
7  const requestId = searchParams.get('requestId');
8
9  if (!requestId) {
10    return NextResponse.json(
11      { error: 'requestId parameter is required' },
12      { status: 400 }
13    );
14  }
15
16  const apiKey = process.env.FREIGHTOS_API_KEY;
17  if (!apiKey) {
18    return NextResponse.json(
19      { error: 'Freightos API key not configured' },
20      { status: 500 }
21    );
22  }
23
24  try {
25    const response = await fetch(
26      `${WEBCARGO_API_URL}/rates/requests/${requestId}`,
27      {
28        headers: {
29          'Authorization': `Bearer ${apiKey}`,
30          'Accept': 'application/json',
31        },
32        // Disable Next.js data cache for polling endpoints
33        cache: 'no-store',
34      }
35    );
36
37    if (!response.ok) {
38      return NextResponse.json(
39        { error: `Status check failed: ${response.status}` },
40        { status: response.status }
41      );
42    }
43
44    const data = await response.json();
45    const status = data.status || 'processing';
46
47    if (status === 'completed' || status === 'ready') {
48      const quotes = (data.rates || data.quotes || []).map(
49        (rate: Record<string, unknown>) => ({
50          carrierId: String(rate.carrier_id || ''),
51          carrierName: String(rate.carrier_name || 'Unknown Carrier'),
52          transitDays: Number(rate.transit_days || 0),
53          departureDate: String(rate.departure_date || ''),
54          arrivalDate: String(rate.arrival_date || ''),
55          rateUsd: Number((rate.total_price as Record<string, unknown>)?.amount || 0),
56          serviceType: String(rate.service_type || ''),
57        })
58      );
59      return NextResponse.json({ status: 'ready', quotes });
60    }
61
62    return NextResponse.json({ status: 'processing', quotes: [] });
63  } catch (error) {
64    console.error('Freightos status check error:', error);
65    return NextResponse.json(
66      { error: 'Failed to check quote status' },
67      { status: 500 }
68    );
69  }
70}

With the API routes working, the final step is to ensure your V0-generated UI presents the freight quotes in a way that is useful for making booking decisions. Raw quote data from Freightos includes a mix of carriers, service types, transit times, and prices — giving users filtering and sorting controls dramatically improves the experience. Ask V0 to add filter controls to the results panel: a price range slider, transit time filter (e.g., fastest, balanced, cheapest), and carrier type filter (e.g., ocean only, air only). V0 can implement these as client-side filters that operate on the already-fetched quote array, which is more responsive than re-querying the API for each filter change. For the quote cards, include enough context for a decision: not just the price and transit time, but also the service type (port-to-port, door-to-door), whether the rate includes customs clearance or just freight, and the validity date of the quote if the API provides it. Freightos quotes are often valid for a limited window, so displaying the expiry date prevents stale quotes from being acted on. V0 has a known limitation for complex data tables with many dynamic interactions: the generated code works well for simple sorting but may need refinement for multi-column filters or draggable rows. If you need advanced table features, ask V0 to use the @tanstack/react-table library, which V0 knows well and generates clean integration code for. For production use, consider adding a 'Request to Book' button on the cheapest or best-matched quote that either opens the Freightos booking flow (if available via API) or captures the user's intent and sends them an email with the selected quote details. This keeps your app useful even before you build a full booking integration. RapidDev's team can help you connect the Freightos quote selection to a booking confirmation workflow.