How to Integrate Lovable with Freightos WebCargo

Freightos WebCargo API access is not self-service — it requires a business application and approval process. Navigate to freightos.com/freight-tools/freightos-api/ and click Request API Access. Fill in your company details, intended use case (e.g., 'Building a freight rate calculator for B2B e-commerce buyers'), and expected monthly quote volume. Freightos reviews applications to ensure the integration makes business sense and that the applicant has a legitimate freight use case. Once approved (typically 3-7 business days), you'll receive access to the Freightos WebCargo API portal where you can generate your Client ID and Client Secret. These are OAuth2 credentials used to obtain bearer tokens for API authentication. The WebCargo API documentation, available at developer.freightos.com, covers the full rate request and booking flow including the asynchronous quote collection pattern. Freightos provides a sandbox environment for development. The sandbox simulates carrier responses with mock data so you can build and test your integration without requesting real freight quotes or making actual bookings. Note your Client ID and Client Secret from the API portal — you'll need both for the Cloud Secrets step. Also note whether your access is for the production API or sandbox, as the base URLs differ.

With your Freightos credentials in hand, store them securely in Lovable's Cloud Secrets panel. In your Lovable project, click the '+' icon next to the Preview panel at the top to open the Cloud tab. Inside the Cloud tab, click Secrets in the left sidebar. Click Add Secret for each credential. Add FREIGHTOS_CLIENT_ID with your Client ID value and click Save. Add FREIGHTOS_CLIENT_SECRET with your Client Secret value and click Save. If you're using the Freightos sandbox, also add FREIGHTOS_ENV with value 'sandbox' so your Edge Function knows which base URL to use. For production, set it to 'production'. Never paste Freightos credentials into Lovable's chat prompt — the Freightos Client Secret in particular is a sensitive OAuth2 credential that grants access to quote real freight rates on your account. Lovable's Cloud Secrets panel encrypts values at rest with the same security posture as Supabase's encrypted secrets (SOC 2 Type II certified). Once stored, the values are only accessible from your Edge Functions via Deno.env.get(), never from the React frontend or browser.

Create the Edge Function that handles Freightos API authentication and proxies rate, booking, and tracking requests. Type the following prompt into Lovable's chat. Lovable will generate the TypeScript code at supabase/functions/freightos-proxy/index.ts and deploy it to Cloud. The Edge Function handles two key concerns: OAuth2 token management and request routing. The function first calls Freightos's token endpoint with the Client ID and Secret to get a bearer token, then uses that token to call the actual API endpoints. The Freightos WebCargo API uses an asynchronous rate request pattern: you submit a rate request and receive a request ID, then poll a status endpoint until all carrier quotes have been collected. The Edge Function implements this polling loop — waiting for quotes to accumulate and returning results when complete or when a timeout is reached. Three actions are supported: 'quote' (submit a freight rate request and poll for results), 'book' (confirm a booking from a quote), and 'track' (get tracking milestones for a booking reference). CORS headers are included on all responses for browser compatibility.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2
3const corsHeaders = {
4  'Access-Control-Allow-Origin': '*',
5  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
6}
7
8async function getAccessToken(clientId: string, clientSecret: string, isSandbox: boolean): Promise<string> {
9  const tokenUrl = isSandbox
10    ? 'https://api-sandbox.webcargo.co/oauth/token'
11    : 'https://api.webcargo.co/oauth/token'
12
13  const response = await fetch(tokenUrl, {
14    method: 'POST',
15    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
16    body: new URLSearchParams({
17      grant_type: 'client_credentials',
18      client_id: clientId,
19      client_secret: clientSecret,
20    }),
21  })
22
23  const data = await response.json()
24  if (!response.ok) throw new Error(`Token error: ${data.error_description || data.error}`)
25  return data.access_token
26}
27
28serve(async (req) => {
29  if (req.method === 'OPTIONS') {
30    return new Response('ok', { headers: corsHeaders })
31  }
32
33  try {
34    const clientId = Deno.env.get('FREIGHTOS_CLIENT_ID')
35    const clientSecret = Deno.env.get('FREIGHTOS_CLIENT_SECRET')
36    const env = Deno.env.get('FREIGHTOS_ENV') || 'sandbox'
37    const isSandbox = env === 'sandbox'
38
39    if (!clientId || !clientSecret) {
40      return new Response(
41        JSON.stringify({ error: 'Freightos credentials not configured in Cloud Secrets' }),
42        { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
43      )
44    }
45
46    const accessToken = await getAccessToken(clientId, clientSecret, isSandbox)
47    const baseUrl = isSandbox ? 'https://api-sandbox.webcargo.co/v2' : 'https://api.webcargo.co/v2'
48
49    const url = new URL(req.url)
50    const action = url.searchParams.get('action')
51
52    const authHeaders = {
53      'Authorization': `Bearer ${accessToken}`,
54      'Content-Type': 'application/json',
55      'Accept': 'application/json',
56    }
57
58    if (action === 'quote') {
59      const body = await req.text()
60      // Submit rate request
61      const quoteRes = await fetch(`${baseUrl}/rates`, {
62        method: 'POST',
63        headers: authHeaders,
64        body,
65      })
66      const quoteData = await quoteRes.json()
67
68      if (!quoteRes.ok) {
69        return new Response(JSON.stringify(quoteData), {
70          status: quoteRes.status,
71          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
72        })
73      }
74
75      const requestId = quoteData.id
76      // Poll for results up to 30 seconds
77      let results = quoteData
78      for (let i = 0; i < 15; i++) {
79        await new Promise(resolve => setTimeout(resolve, 2000))
80        const pollRes = await fetch(`${baseUrl}/rates/${requestId}`, { headers: authHeaders })
81        results = await pollRes.json()
82        if (results.status === 'COMPLETED' || (results.quotes && results.quotes.length > 0)) break
83      }
84
85      return new Response(JSON.stringify(results), {
86        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
87      })
88    } else if (action === 'book') {
89      const body = await req.text()
90      const bookRes = await fetch(`${baseUrl}/bookings`, {
91        method: 'POST',
92        headers: authHeaders,
93        body,
94      })
95      const bookData = await bookRes.json()
96      return new Response(JSON.stringify(bookData), {
97        status: bookRes.status,
98        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
99      })
100    } else if (action === 'track') {
101      const bookingRef = url.searchParams.get('bookingRef')
102      const trackRes = await fetch(`${baseUrl}/shipments/${bookingRef}/milestones`, { headers: authHeaders })
103      const trackData = await trackRes.json()
104      return new Response(JSON.stringify(trackData), {
105        status: trackRes.status,
106        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
107      })
108    } else {
109      return new Response(
110        JSON.stringify({ error: 'Invalid action. Use: quote, book, or track' }),
111        { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
112      )
113    }
114  } catch (error) {
115    return new Response(
116      JSON.stringify({ error: error.message }),
117      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
118    )
119  }
120})

With the Edge Function deployed, ask Lovable to build a freight rate comparison component. This is the core UI of a Freightos integration — a form that collects cargo details and displays multiple carrier quotes in a comparison view. The Freightos rate request body requires: origin and destination port codes (UNLOCODE format, e.g., 'CNSHA' for Shanghai, 'USLAX' for Los Angeles), cargo type (LCL, FCL_20, FCL_40, AIR), commodity (general cargo, dangerous goods, temperature controlled), weight in kg, volume in CBM for ocean or dimensions for air, and required by date. Lovable will generate a TypeScript interface for the rate response and render each quote as a comparison card. For complex freight integrations involving dangerous goods classifications, temperature-controlled cargo, or multi-leg routing, RapidDev's team can help configure the Freightos API request structure to match your specific cargo types and trade lanes. Once the rate comparison UI is working in sandbox, test with representative cargo specifications matching your actual business use case before switching to production credentials.