How to Integrate Lovable with DHL Express API

Before writing any code, you need a DHL API key and account number. Navigate to developer.dhl.com and sign in or create a free developer account. Once logged in, go to My Apps and click Create App. Give the app a name (e.g., 'Lovable Storefront') and select the APIs you want access to — at minimum, select Express Rating, Express Shipment, and Express Tracking. After creating the app, DHL generates an API key (a long alphanumeric string) visible on the app detail page. Importantly, DHL Express APIs also require your DHL account number — this is the 9-digit number associated with your DHL Express business account, not your developer portal account. If you don't have a DHL business account yet, contact DHL sales to open one; the developer sandbox works with a test account number provided in the developer portal documentation. Write down both your API key and account number before proceeding — you'll need both for the Cloud Secrets step. DHL's sandbox environment uses the base URL https://api-mock.dhl.com/mydhlapi for testing. Production uses https://api.dhl.com/mydhlapi. It is strongly recommended to build and test with the sandbox first, then swap to production credentials when you're ready to go live.

Now that you have your DHL API key and account number, store them securely in Lovable's Cloud Secrets panel. In your Lovable project, look at the top of the screen and click the '+' icon next to the Preview panel to open the Cloud tab. Inside the Cloud tab, click Secrets in the left-hand navigation. You'll see a list of encrypted environment variables — click Add Secret to add each credential. Add your first secret: set the name to DHL_API_KEY and paste your DHL API key as the value, then click Save. Add a second secret: set the name to DHL_ACCOUNT_NUMBER and enter your 9-digit account number as the value, then click Save. The secrets are now encrypted and stored — they will only be accessible from Edge Functions via Deno.env.get(), never from frontend React code or the browser. A critical rule: never paste your DHL API key directly into Lovable's chat prompt or into your React component code. On Lovable's free tier, chat history is publicly visible, and keys pasted in chat are recoverable from Git commit history. Always use Cloud → Secrets for any credential that authenticates an external API. Lovable's security layer blocks approximately 1,200 hardcoded API keys per day — use the Secrets panel to stay on the right side of that protection.

With credentials secured, ask Lovable to create the Edge Function that proxies DHL API calls. Type the following prompt into Lovable's chat interface. Lovable will generate the TypeScript code, create the file at supabase/functions/dhl-proxy/index.ts, and deploy it to your Cloud project automatically. The Edge Function uses a switch on an 'action' query parameter to route between the three DHL API endpoints: 'rates' calls the DHL Rate API, 'shipment' calls the Shipment API, and 'track' calls the Tracking API. The DHL Express REST API uses HTTP Basic Auth where the username is your account number and the password is your API key. The function constructs the Authorization header using btoa() to base64-encode the credentials retrieved from Deno.env.get(). All responses include CORS headers so your React frontend can call the function from the browser.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2
3const DHL_BASE_URL = 'https://api-mock.dhl.com/mydhlapi'
4
5const corsHeaders = {
6  'Access-Control-Allow-Origin': '*',
7  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
8}
9
10serve(async (req) => {
11  if (req.method === 'OPTIONS') {
12    return new Response('ok', { headers: corsHeaders })
13  }
14
15  try {
16    const apiKey = Deno.env.get('DHL_API_KEY')
17    const accountNumber = Deno.env.get('DHL_ACCOUNT_NUMBER')
18
19    if (!apiKey || !accountNumber) {
20      return new Response(
21        JSON.stringify({ error: 'DHL credentials not configured in Cloud Secrets' }),
22        { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
23      )
24    }
25
26    const authHeader = 'Basic ' + btoa(`${accountNumber}:${apiKey}`)
27    const url = new URL(req.url)
28    const action = url.searchParams.get('action')
29
30    let dhlUrl: string
31    let dhlMethod: string
32    let dhlBody: string | undefined
33
34    if (action === 'rates') {
35      dhlUrl = `${DHL_BASE_URL}/rates`
36      dhlMethod = 'POST'
37      dhlBody = await req.text()
38    } else if (action === 'shipment') {
39      dhlUrl = `${DHL_BASE_URL}/shipments`
40      dhlMethod = 'POST'
41      dhlBody = await req.text()
42    } else if (action === 'track') {
43      const trackingNumber = url.searchParams.get('trackingNumber')
44      dhlUrl = `${DHL_BASE_URL}/tracking?trackingNumber=${trackingNumber}&trackingView=all-checkpoints&levelOfDetail=all`
45      dhlMethod = 'GET'
46    } else {
47      return new Response(
48        JSON.stringify({ error: 'Invalid action. Use: rates, shipment, or track' }),
49        { status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
50      )
51    }
52
53    const dhlResponse = await fetch(dhlUrl, {
54      method: dhlMethod,
55      headers: {
56        'Authorization': authHeader,
57        'Content-Type': 'application/json',
58        'Accept': 'application/json',
59        'Message-Reference': crypto.randomUUID(),
60        'Message-Reference-Date': new Date().toISOString(),
61        'Plugin-Name': 'Lovable',
62        'Plugin-Version': '1.0',
63        'Shipper-Account': accountNumber,
64      },
65      body: dhlBody,
66    })
67
68    const data = await dhlResponse.json()
69
70    return new Response(JSON.stringify(data), {
71      status: dhlResponse.status,
72      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
73    })
74  } catch (error) {
75    return new Response(
76      JSON.stringify({ error: error.message }),
77      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
78    )
79  }
80})

With the Edge Function deployed, ask Lovable to build a rate calculator UI component that calls it. This component collects shipment details from the user — origin and destination countries, package weight, and dimensions — formats them as a DHL Rate API request body, sends it to your Edge Function, and displays the returned service options with prices and delivery dates. The DHL Rate API expects a specific JSON body structure with plannedShippingDateAndTime, unitOfMeasurement, isCustomsDeclarable, productCode ('EXPRESS_WORLDWIDE' or left empty for all products), packages array with weight and dimensions, and customerDetails with shipperDetails and receiverDetails including postal code, city, and countryCode. Lovable will generate all of this from the prompt below, including a TypeScript interface for the rate response and a properly typed component using Tailwind CSS and shadcn/ui. The component calls the Edge Function at /functions/v1/dhl-proxy?action=rates using the Supabase client's functions.invoke() method or a direct fetch to the function URL. Error states are handled gracefully — if DHL returns an error (e.g., invalid account number in sandbox), the component displays the error message rather than crashing. Successful responses show a list of available DHL services with price, currency, and estimated transit days.

Add a tracking page that lets customers look up a DHL shipment by tracking number. This calls the Edge Function with action=track and the tracking number as a query parameter, then displays a timeline of shipment events from DHL's Tracking API. Once both components are working, test the full flow end-to-end. For the sandbox environment, DHL provides test tracking numbers in their developer documentation (e.g., '1234567890' returns a pre-defined tracking response). Enter a test tracking number and verify the event timeline displays correctly — you should see events like 'Shipment picked up', 'Arrived at facility', and 'Delivered' with timestamps and locations. For complex integrations involving customs declarations, multi-piece shipments, or DHL account setup issues, RapidDev's team has experience configuring DHL Express integrations for international e-commerce apps and can help troubleshoot account provisioning and API authentication errors. Before going to production, switch your Cloud Secrets from sandbox values to your live DHL API key and account number, and update DHL_BASE_URL in the Edge Function from api-mock.dhl.com to api.dhl.com. Run a test rate request against the live API to confirm your production credentials work before launching.