How to Integrate DHL API with V0

Start by prompting V0 to create the React components for your shipping interface. Depending on your use case, this might be a rate calculator form, a tracking search page, or a checkout shipping selector. V0 is particularly good at generating forms with country dropdowns, package dimension inputs, and results display cards. For a rate calculator, you need two main sections: an input form where users enter shipment details, and a results area that displays the service options DHL returns. The input form should collect the origin country code (ISO 2-letter format like 'US', 'DE', 'JP'), destination country code, weight in kilograms (DHL uses metric), and optionally the package dimensions. DHL's API returns multiple service options with different transit times and prices, so the results area should display these as cards or a list. When prompting V0, specify the exact API endpoints your UI will call so V0 wires up the fetch requests correctly. The component should handle three states: idle (showing the empty form), loading (showing a spinner while the API request is in progress), and results (showing the shipping options). Include error handling so users see a friendly message if the API call fails rather than a broken UI. V0 will generate the full React component with TypeScript types and Tailwind CSS styling. Review the generated fetch call to make sure it sends a POST request to your API route with the correct JSON body structure, and that it handles the response correctly by rendering the rates or tracking data.

Create the server-side Next.js API route that your V0 UI will call. This route proxies the request to DHL's API using your credentials — credentials that must never be exposed in browser code. Create the file at app/api/dhl/rates/route.ts in your project. DHL's Express Rate and Date-Time API is available at https://express.api.dhl.com/mydhlapi/rates. It accepts GET requests with query parameters, but for a clean Next.js integration, accept POST from your UI and convert to a DHL GET request on the server side. Authentication uses HTTP Basic Auth — you encode your DHL API key and secret as base64 and pass them in the Authorization header as 'Basic [encoded-credentials]'. The DHL Rate API requires several parameters: accountNumber (your DHL account number — different from the API key, this is your shipping account), originCountryCode, originCityName, destinationCountryCode, destinationCityName, weight (in kg), unitOfMeasurement ('SI' for metric), plannedShippingDateAndTime (ISO 8601 format), and isCustomsDeclarable (true for international shipments). For a rate calculator, set isCustomsDeclarable to true for cross-border routes and false for domestic. The DHL API response contains a 'products' array where each product represents a different service option with its ownPrice breakdown (basePrice, taxes, charges) and deliveryCapabilities (deliveryTypeCode, estimatedDeliveryDateAndTime). Parse this response and return a simplified version to your frontend — service name, transit days, total price, and currency. Error handling is important: DHL returns detailed error responses with an 'id', 'detail', and 'additionalDetails' fields. Catch these and return appropriate HTTP status codes to your UI.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface DHLRateRequest {
4  originCountry: string;
5  destinationCountry: string;
6  weight: number;
7  originCity?: string;
8  destinationCity?: string;
9}
10
11export async function POST(request: NextRequest) {
12  try {
13    const { originCountry, destinationCountry, weight, originCity = 'New York', destinationCity = 'London' }: DHLRateRequest = await request.json();
14
15    // Build DHL Basic Auth header
16    const credentials = Buffer.from(
17      `${process.env.DHL_API_KEY}:${process.env.DHL_API_SECRET}`
18    ).toString('base64');
19
20    // Build the DHL rate query
21    const now = new Date();
22    const shippingDate = new Date(now.getTime() + 24 * 60 * 60 * 1000) // Tomorrow
23      .toISOString()
24      .replace('Z', '+00:00');
25
26    const params = new URLSearchParams({
27      accountNumber: process.env.DHL_ACCOUNT_NUMBER!,
28      originCountryCode: originCountry,
29      originCityName: originCity,
30      destinationCountryCode: destinationCountry,
31      destinationCityName: destinationCity,
32      weight: weight.toString(),
33      unitOfMeasurement: 'SI',
34      plannedShippingDateAndTime: shippingDate,
35      isCustomsDeclarable: 'true',
36      nextBusinessDay: 'false',
37    });
38
39    const response = await fetch(
40      `https://express.api.dhl.com/mydhlapi/rates?${params.toString()}`,
41      {
42        method: 'GET',
43        headers: {
44          Authorization: `Basic ${credentials}`,
45          'Content-Type': 'application/json',
46        },
47      }
48    );
49
50    if (!response.ok) {
51      const error = await response.json();
52      console.error('DHL API error:', error);
53      return NextResponse.json(
54        { error: error.detail || 'DHL API request failed' },
55        { status: response.status }
56      );
57    }
58
59    const data = await response.json();
60
61    // Transform DHL response to simplified format
62    const rates = (data.products || []).map((product: any) => ({
63      serviceCode: product.productCode,
64      serviceName: product.productName,
65      transitDays: product.deliveryCapabilities?.transitDays || 'N/A',
66      estimatedDelivery: product.deliveryCapabilities?.estimatedDeliveryDateAndTime,
67      currency: product.totalPrice?.[0]?.priceCurrency || 'USD',
68      price: product.totalPrice?.[0]?.price || 0,
69    }));
70
71    return NextResponse.json({ rates });
72  } catch (error) {
73    console.error('DHL rate fetch error:', error);
74    return NextResponse.json(
75      { error: 'Failed to fetch shipping rates' },
76      { status: 500 }
77    );
78  }
79}

Tracking is often more immediately useful than rate quotes for many app use cases. Create a second API route at app/api/dhl/track/route.ts that accepts a DHL waybill number (also called AWB — Air Waybill) and returns the tracking events. DHL's Tracking API is at https://express.api.dhl.com/mydhlapi/shipments/{shipment-tracking-number}/tracking. It uses the same Basic Auth as the rates API. The waybill number is the tracking number printed on DHL shipment labels, typically 10 digits. The Tracking API response contains a 'shipments' array. Each shipment has an 'events' array with individual tracking events. Each event has a timestamp, location (serviceArea), status description, and event code. Events are returned in reverse chronological order (newest first). The 'status' field on the top-level shipment object shows the current high-level status: 'transit', 'delivered', 'exception', or 'pickup'. For a tracking dashboard, transform the events array into a timeline-friendly format: timestamp, location description, and a human-readable status message. DHL's event codes are not always self-explanatory (PU = Pickup, AA = Arrived at DHL Facility, WC = With Delivery Courier, OK = Delivered), so you may want to map the common codes to friendly labels in your response transformation. Note that the Tracking API is rate-limited to 10 requests per second per API key. For high-volume tracking dashboards, implement client-side caching with localStorage or server-side caching with a Redis store to avoid hammering the API unnecessarily.

1import { NextRequest, NextResponse } from 'next/server';
2
3export async function GET(request: NextRequest) {
4  try {
5    const trackingNumber = request.nextUrl.searchParams.get('trackingNumber');
6
7    if (!trackingNumber) {
8      return NextResponse.json(
9        { error: 'trackingNumber query parameter is required' },
10        { status: 400 }
11      );
12    }
13
14    const credentials = Buffer.from(
15      `${process.env.DHL_API_KEY}:${process.env.DHL_API_SECRET}`
16    ).toString('base64');
17
18    const response = await fetch(
19      `https://express.api.dhl.com/mydhlapi/shipments/${trackingNumber}/tracking`,
20      {
21        method: 'GET',
22        headers: {
23          Authorization: `Basic ${credentials}`,
24          'Content-Type': 'application/json',
25        },
26      }
27    );
28
29    if (!response.ok) {
30      const error = await response.json();
31      return NextResponse.json(
32        { error: error.detail || 'Tracking lookup failed' },
33        { status: response.status }
34      );
35    }
36
37    const data = await response.json();
38    const shipment = data.shipments?.[0];
39
40    if (!shipment) {
41      return NextResponse.json(
42        { error: 'Shipment not found' },
43        { status: 404 }
44      );
45    }
46
47    const events = (shipment.events || []).map((event: any) => ({
48      timestamp: event.timestamp,
49      location: event.location?.address?.addressLocality || event.serviceArea?.[0]?.description || 'Unknown',
50      description: event.description,
51      code: event.typeCode,
52    }));
53
54    return NextResponse.json({
55      trackingNumber,
56      status: shipment.status,
57      estimatedDelivery: shipment.estimatedTimeOfDelivery,
58      events,
59    });
60  } catch (error) {
61    console.error('DHL tracking error:', error);
62    return NextResponse.json(
63      { error: 'Failed to retrieve tracking information' },
64      { status: 500 }
65    );
66  }
67}

Your API routes require three DHL credentials: the API key, API secret, and your DHL account number. These must be added to Vercel's environment configuration — never hardcoded in your source code. Go to your Vercel Dashboard and open your project. Click the Settings tab, then click Environment Variables in the left sidebar. Add the following variables: DHL_API_KEY: Your DHL Developer Portal API key. Found in the Developer Portal under your application's credentials. This is not the same as your DHL shipping account number — it is specific to API access. DHL_API_SECRET: Your DHL Developer Portal API secret, paired with the API key for Basic Auth. DHL_ACCOUNT_NUMBER: Your DHL Express account number (typically a 9-digit number). This is required for rate quotes — DHL needs to know which account to price against. You can find this in your DHL account profile or invoices. None of these variables should use the NEXT_PUBLIC_ prefix. They are all server-only credentials that belong exclusively in your Next.js API routes. Setting them with NEXT_PUBLIC_ would expose them in the browser's JavaScript bundle. For the environment scope, set each variable for Production, Preview, and Development. For local development, create a .env.local file in your project root with the same three variables — this file is already in .gitignore for V0-generated projects. After adding all variables, click Save. Trigger a new Vercel deployment by pushing a commit to your GitHub repository — environment variable changes require a redeployment to take effect in production.

Test your DHL integration end-to-end before showing it to users. DHL's sandbox environment at https://express.api.dhl.com/mydhlapi/test accepts the same requests as production but with sandbox credentials. The sandbox returns simulated rates and tracking data that let you validate your integration without creating real shipments. For rate quote testing: submit a request with a known valid route, such as origin 'US' to destination 'DE' with a weight of 2 kg. The DHL sandbox should return several service options including DHL Express Worldwide. Check that your UI correctly displays the service name, transit days, and price from the response. Try edge cases: very light packages (0.1 kg), heavy packages (70 kg), same-country routes, and routes to less common destinations. For tracking testing: DHL provides test tracking numbers in their developer documentation. Look up the test waybill numbers in the DHL Developer Portal sandbox section. Alternatively, once you have a real DHL account, you can use actual shipment tracking numbers from your DHL Express bookings. Vercel's Function Logs (Vercel Dashboard → your project → Functions) are helpful for debugging. Any console.error() calls in your API routes appear here in real-time. Check these logs if the UI shows an error state but you are not sure what the API returned. For production DHL integrations that need shipment creation (actually booking a pickup and generating a label), the API adds complexity around account configuration and customs data. For complex DHL integrations involving label generation and customs documentation, RapidDev's team can help configure the full shipment creation workflow in your V0 app.