Automated Address Validation with Billbee & Endereco API in n8n

1. Opening Problem Statement

Meet Anna, an operations manager at a mid-sized e-commerce company using Billbee for order management. She constantly battles with shipping errors caused by incorrect or incomplete customer addresses. Every week, her warehouse team spends hours manually verifying and correcting these addresses, leading to delayed shipments and unhappy customers. Anna estimates this manual process wastes over 10 hours weekly and causes costly reshipments and customer dissatisfaction.

This frustration is directly linked to the accuracy of the shipping data pulled from Billbee orders. If only there was a way to automatically validate and correct these addresses before they reach the warehouse!

2. What This Automation Does

This n8n workflow is built specifically to automate shipping address validation for Billbee orders using the Endereco API, delivering these key outcomes:

• Automatically fetch order shipping addresses from Billbee using the order ID provided by a webhook trigger.
• Map and clean address fields like first name, last name, street, house number, ZIP code, city, and country code.
• Validate the shipping address via Endereco’s address validation API to check for accuracy and misspellings.
• Handle common issues with house numbers including cases where house numbers are appended to a second address line.
• Update corrected addresses directly back in Billbee when the API suggests a fix.
• Tag orders in Billbee to mark whether address validation passed, failed, or needs manual review.

This workflow can save around 10+ hours weekly by eliminating manual address checking, reduces shipment errors significantly, and keeps transparent tracking of validation status inside Billbee.

3. Prerequisites ⚙️

• Billbee API Access: Developer and User API keys for Billbee (HTTP Basic Auth).
• Endereco API Key: For address validation service (https://www.endereco.de/en/integrations/address-api/).
• n8n account: Cloud or self-hosted instance to run this workflow. (Consider self-hosting with Hostinger via https://buldrr.com/hostinger if preferred.)

4. Step-by-Step Guide ⚙️

1. Setting up the Webhook to Receive Billbee Order IDs
   Go to n8n’s workflow editor. Click Add Node → Webhook. Set the webhook path (e.g., a generated unique string). Activate the webhook.
   You will receive a Billbee webhook call here with the order ID query parameter.
   Expected: A webhook URL that can be linked from Billbee’s automation rules.
   Mistake: Not activating the webhook or misconfiguring the path leads to no trigger firing.
2. Configure Access Keys in the ConfigNode
   Add a Set node named “ConfigNode”. Enter your Billbee API key under the variable X-Billbee-Api-Key and Endereco API key under X-Auth-Key-Endereco. Also set orderID from webhook query parameter.
   You should see these keys stored for use in subsequent HTTP requests.
   Mistake: Entering wrong or expired API keys will cause authentication failures later.
3. Wait Node to Simplify Execution Flow
   Add a Wait node after ConfigNode set to 1 second to ensure ordered execution.
   Expectation: Helps stabilize timing around asynchronous HTTP requests.
   Mistake: Skipping wait sometimes causes race conditions when fetching data.
4. Getting Full Order Data from Billbee
   Add an HTTP Request node called “get order data”. Set the URL to Billbee’s orders API with the order ID variable.
   Method: GET. Include Billbee API Key in headers.
   Result: Retrieve customer’s shipping address data.
   Mistake: Forgetting API key or wrong URL causes 401 or 404 errors.
5. Splitting Out the Shipping Address Data
   Use a Split Out node to isolate the shipping address fields like first name, last name, street, house number, ZIP, city, and country code.
   Expectation: You get separate fields from nested JSON.
   Mistake: Incorrect field names or misspelling the fieldToSplitOut strings will cause empty data.
6. Setting Address Fields for Validation
   Add a Set node to map and clean fields, including replacing slashes in house numbers.
   Example: Set first_name = {{ $json["Data.ShippingAddress.FirstName"] }}, etc.
   Mistake: Wrong expressions cause empty or malformed data.
7. Filtering Out Pickup Shops and Parcel Stations
   Add a Filter node named “Filter Out PickUpShops” to exclude orders where street contains “Postfiliale”, “Packstation”, or “Paketshop”.
   This prevents unnecessary validation on pickup locations.
   Mistake: Set filters incorrectly, and you might skip valid addresses.
8. House Number Validation and Adjustment
   Add a series of If nodes to check if house number is empty. If so, check if AddressLine2 contains a number or number+letter.
   Use Set nodes to reassign these values correctly as the house number.
   This handles common input errors where house numbers are misplaced.
   Mistake: Overlooking these checks leads to failing API validation.
9. Calling Endereco Address Validation API
   Use a HTTP Request node named “Check Address endereco api” to POST a JSON-RPC request with the address parameters.
   Add required headers including API keys and content type.
   Example JSON body:

   {
     "jsonrpc": "2.0",
     "id": 1,
     "method": "addressCheck",
     "params": {
       "country": "{{ $json['CountryISO2']}}",
       "language": "{{ $json['CountryISO2'] }}",
       "postCode": "{{ $json['zip'] }}",
       "cityName": "{{ $json['location'] }}",
       "street": "{{ $json['Street'] }}",
       "houseNumber": "{{ $json['housenumber'] }}"
     }
   }

   Mistake: Missing or incorrect headers cause authentication errors.

10. Evaluating API Response for Corrections
    Use an If node to check if result.predictions from Endereco API response is not empty.
    If a corrected address suggestion exists, use a Split Out node to process it.
    Mistake: Ignoring empty predictions leads to unnecessary address updates.
11. Updating Address in Billbee
    Add an HTTP Request node named “set new delivery address to billbee” with a PATCH method to update the shipping address fields via Billbee API.
    Ensure you use BillbeeShippingAddressID and include corrected address fields.
    Mistake: Using wrong IDs or missing fields prevent updates.
12. Tagging Orders in Billbee Based on Validation Outcome
    Use HTTP Request nodes to POST tags to Billbee orders such as “endereco_address_validated”, “endereco_address_failed”, or “manual_address_check” depending on validation success or issues.
    Mistake: Not authenticating or formatting JSON body incorrectly prevents tagging.
13. Wait Nodes for Execution Stability
    Strategically place Wait nodes after key stages to ensure API calls complete before next steps.
    Mistake: Removing waits may cause race conditions leading to API failures.

5. Customizations ✏️

• Change Tag Names in Billbee Tag Nodes
  In the HTTP Request nodes setting tags, update the “Tags” array with your preferred tag labels to better suit your order management workflow.
• Extend Address Fields in Validation
  Add extra address fields like `NameAddition` or `AddressLine2` in the Set Address Fields node and include them in the validation API body for more precise checks.
• Filter More Pickup Locations
  Edit the Filter Out PickUpShops node to include additional keywords based on your local pickup stations to avoid validation on those addresses.
• Adjust Wait Times
  Modify the amount parameter in Wait nodes for optimized throughput depending on API rate limits and workflow response times.
• Handle Multi-Country Addresses
  Add conditional logic to set the Endereco API request language parameter dynamically based on different country codes.

6. Troubleshooting 🔧

• Problem: “401 Unauthorized” when calling Billbee API.
  Cause: Incorrect or expired API keys.
  Solution: Go to ConfigNode, verify and update your API keys. Test with curl or Postman to confirm credentials.
• Problem: Endereco API returns empty predictions.
  Cause: Address data sent is incomplete or improperly formatted.
  Solution: Check Set Address Fields node for correct field mappings, especially correct house number and street fields.
• Problem: Orders incorrectly tagged “manual_address_check” unnecessarily.
  Cause: The regex or number + letter checks misfire.
  Solution: Review logic in the “check if addressline 2 contains number and letter” If node and adjust expression if needed.

7. Pre-Production Checklist ✅

• Confirm Billbee API keys are valid and have necessary permissions.
• Test webhook trigger with a sample valid order ID.
• Validate output from “get order data” HTTP node matches expected shipping address JSON schema.
• Inspect Split Out node outputs for all necessary address fields are correctly extracted.
• Confirm Endereco API returns valid predictions on tested addresses.
• Run test to see tagging occurs correctly on Billbee orders.
• Create backup of existing address data before deploying changes in live Billbee orders.

8. Deployment Guide

Activate your workflow by toggling the activation switch in n8n. Then, set up your Billbee automation rule to call the webhook URL with the order ID parameter whenever a new order is imported or updated.

Monitor the workflow executions from the n8n dashboard for any errors or warnings. Use execution logs to troubleshoot.

This setup does not require complex infrastructure and can run on the n8n cloud or self-hosted environments.

10. Conclusion

By following this guide, you’ve automated shipping address validation for your Billbee orders using the powerful Endereco API. This solution reduces manual work, improves shipping accuracy, and keeps clear records of validation results directly in your Billbee system.

Anna from our story can now save over 10 hours each week and drastically reduce costly shipping mistakes. Next steps you might consider include automating customer notifications for corrected addresses, integrating with shipment tracking, or extending validation to billing addresses as well.

You’re now equipped with a robust, tailor-made n8n workflow for reliable address validation — congrats!