> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affelios.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XML FTP Integration

> Complete guide for integrating your Affelios affiliate program with XML FTP data sources

<Info>
  This comprehensive guide walks through the process of integrating your Affelios program with XML FTP data sources. The integration enables automatic data synchronization and seamless affiliate tracking for your business.
</Info>

## Prerequisites

Before starting the integration process, ensure you have the following:

* **Active Affelios subscription** - Any plan (Flex, Pro, or Enterprise)
* **FTP Server Access** - Valid FTP server credentials and access
* **XML Data Files** - Registration and Transaction XML files available on your FTP server
* **Whitelisted IP Addresses** - FTP server must allow connections from Affelios IP addresses
* **Admin Access** - Full administrative privileges to your Affelios account

<Warning>
  The integration process requires coordination with your FTP server administrator to whitelist Affelios IP addresses. Contact us via Intercom or email [support@affelios.com](mailto:support@affelios.com) to obtain the required IP addresses before proceeding.
</Warning>

***

## Integration Benefits

<Card title="Key Features" icon="star">
  The Affelios XML FTP integration provides powerful features to streamline your affiliate program management and boost performance.
</Card>

<AccordionGroup>
  <Accordion title="Automated Data Import">
    **Seamless Data Management:**

    * Daily automatic import of customer registrations and transactions
    * Real-time commission calculations based on actual revenue
    * Automated deduction handling for payment fees and taxes
    * No manual data entry required
  </Accordion>

  <Accordion title="Flexible Data Mapping">
    **Comprehensive Revenue Tracking:**

    * Custom field mapping for your specific XML format
    * Support for multiple product categories
    * Individual product revenue and transaction tracking
    * Detailed commission breakdowns by product type
  </Accordion>

  <Accordion title="Advanced Attribution">
    **Precise Customer Attribution:**

    * Configurable cookie tracking periods
    * Automatic ClickKey generation for proper attribution
    * Customer registration and transaction linking
    * Anonymous transaction prevention
  </Accordion>
</AccordionGroup>

***

## Step-by-Step Integration Guide

### Step 1: Create a Brand in Affelios

<Steps>
  <Step title="Access Brand Creation">
    Navigate to your Affelios dashboard and go to the **"Brands"** section in the left-hand navigation menu.
  </Step>

  <Step title="Create New Brand">
    Click **"Create Brand"** and fill in the required information for your business website.
  </Step>

  <Step title="Configure Brand Settings">
    Set up your brand with the proper tracking parameters and commission settings.
  </Step>
</Steps>

<Info>
  If you already have a brand set up, you can skip to Step 2. If you need help creating a brand, follow our [Brand Creation Guide](/knowledge-base/operators/setup-guide#create--configure-a-brand).
</Info>

#### Brand Configuration Example

For a brand called **"YourBusiness.com"**, use these settings:

<Card title="Brand Step 1 - Basic Information" icon="gear">
  | **Field**        | **Example**                                                                                   | **Description**                                   |
  | ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- |
  | Name             | Your Business                                                                                 | Display name shown to affiliates and in reports   |
  | Industry         | Your Industry                                                                                 | Used to categorize and filter brands              |
  | External ID      | yourbusiness                                                                                  | Unique value used externally (best practice)      |
  | Landing Page URL | [https://yourbusiness.com?clickkey=\[ClickKey](https://yourbusiness.com?clickkey=\[ClickKey)] | Your website with ClickKey parameter for tracking |
</Card>

<Card title="Brand Step 2 - Advanced Settings" icon="settings">
  | **Field**                    | **Example** | **Description**                                     |
  | ---------------------------- | ----------- | --------------------------------------------------- |
  | Auto-Approve Commissions     | Enabled     | Recommended to avoid data delays                    |
  | Allow Anonymous Transactions | Disabled    | **Important:** Keep disabled for proper attribution |
  | Deposit Fees                 | 3%          | Payment fees deducted from Net Revenue              |
  | Tax Rate Deduction           | 21%         | Applicable taxes                                    |
  | Net Revenue Deduction        | 15%         | Platform and operational costs                      |
</Card>

### Step 2: Configure XML FTP Integration Settings

<Steps>
  <Step title="Access Integration Settings">
    Navigate to the **"Brands"** page and click the three dots next to your brand, then select **"Integration Settings"**.
  </Step>

  <Step title="Select XML FTP Integration">
    Choose **"Xml Ftp"** from the available integration methods.
  </Step>

  <Step title="Configure FTP Connection">
    Enter the FTP server details and credentials.
  </Step>
</Steps>

### Step 3: Set Up FTP Connection Settings

<Card title="FTP Connection Configuration" icon="link">
  Configure the connection settings for your FTP server:

  | **Field**                      | **Example**                                     | **Description**                             |
  | ------------------------------ | ----------------------------------------------- | ------------------------------------------- |
  | FTP Hostname                   | ftp.yourbusiness.com                            | Your FTP server hostname                    |
  | FTP Port                       | 21                                              | Standard FTP port (21) or custom port       |
  | Username                       | your\_username                                  | FTP server username                         |
  | Password                       | your\_password                                  | FTP server password                         |
  | Registration Filename Template | /data/registrations/\[YEAR]-\[MONTH]-\[DAY].xml | Path to Registrations file with date tokens |
  | Transactions Filename Template | /data/transactions/\[YEAR]-\[MONTH]-\[DAY].xml  | Path to Transactions file with date tokens  |
</Card>

<Info>
  The filename templates use automatic token replacement: \[YEAR] (e.g., 2030), \[MONTH] (e.g., 12), \[DAY] (e.g., 31). Affelios will request the previous day's data each morning.
</Info>

### Step 4: Configure Field Mapping

After establishing a valid connection, you'll need to map the XML fields to Affelios fields.

#### Customer Field Mapping

<Card title="Registration Data Mapping" icon="user">
  Map the available fields from the Registrations XML to Affelios fields:

  | **Affelios Field**   | **Description**                       | **External Field Example** |
  | -------------------- | ------------------------------------- | -------------------------- |
  | Registration Date    | The date the customer registered      | registration\_date         |
  | External Customer ID | Your system's ID for the customer     | customer\_id               |
  | Click Key            | Unique value generated by Affelios    | click\_key                 |
  | Customer Username    | Customer username or email            | username                   |
  | Country Code         | 2-letter country code of the customer | country                    |
</Card>

#### Transaction Field Mapping

<Card title="Transaction Data Mapping" icon="dollar-sign">
  Map the available fields from the Transactions XML to Affelios fields:

  | **Affelios Field**   | **Description**                   | **External Field Example** |
  | -------------------- | --------------------------------- | -------------------------- |
  | External Customer Id | Your system's ID for the customer | customer\_id               |
  | Transaction Date     | The Date of the transaction       | transaction\_date          |
  | Deposits             | Sum total of Deposits             | deposits                   |
  | Gross Revenue        | Sum total of Revenue              | revenue                    |
  | Wagering             | Sum total of Wagering/Bets        | wagering                   |
</Card>

### Step 5: Enable Daily Import

<Steps>
  <Step title="Configure Import Settings">
    Toggle the import setting to **"Enabled"** and set the import time to **"03:00 AM"**.
  </Step>

  <Step title="Save Integration">
    Click **"Save Integration"** to complete the setup process.
  </Step>

  <Step title="Verify Connection">
    Affelios will automatically test the connection and validate the field mappings.
  </Step>
</Steps>

<Info>
  Affelios will now automatically download data from your FTP server each morning at 3 AM and import data into your affiliate program according to your integration settings.
</Info>

***

## Data Import Management

<Card title="Automatic Import Features" icon="rotate">
  Once enabled, data import happens automatically and keeps your affiliate program synchronized with your FTP data.
</Card>

### Import Process

<AccordionGroup>
  <Accordion title="Daily Data Retrieval">
    **Automated Process:**

    * Affelios connects to your FTP server each morning at 3 AM
    * Downloads previous day's registration and transaction XML files
    * Data is processed and mapped according to your configuration
    * Commissions are calculated automatically
  </Accordion>

  <Accordion title="Data Validation">
    **Quality Assurance:**

    * Connection validation before each import
    * Field mapping verification
    * XML format validation
    * Error logging and reporting
  </Accordion>

  <Accordion title="Import Monitoring">
    **Track Performance:**

    * View import logs in Settings > Imports
    * Retry failed import attempts
    * Reimport historical data by date range
    * Monitor import success rates
  </Accordion>
</AccordionGroup>

### Managing Imports

<Steps>
  <Step title="Monitor Import Status">
    Check the import logs in your Affelios dashboard to ensure data is being imported successfully.
  </Step>

  <Step title="Review Data Quality">
    Verify that customer registrations and transactions are being processed correctly.
  </Step>

  <Step title="Handle Import Errors">
    Use the retry functionality for any failed imports or contact support if issues persist.
  </Step>

  <Step title="Historical Data">
    Reimport historical data if needed using the date range selector in the imports section.
  </Step>
</Steps>

***

## Commission Management

<Card title="Automated Commission Processing" icon="dollar-sign">
  The XML FTP integration automatically processes commissions based on your configured settings and field mappings.
</Card>

### Commission Calculation

<AccordionGroup>
  <Accordion title="Revenue-Based Commissions">
    **Revenue Tracking:**

    * Commissions calculated on Gross Revenue
    * Automatic deduction handling for fees and taxes
    * Real-time commission updates
    * Flexible commission structures
  </Accordion>

  <Accordion title="Deduction Management">
    **Automated Deductions:**

    * Deposit fees (e.g., 3% payment processing fees)
    * Tax rate deductions (e.g., 21% applicable taxes)
    * Net revenue deductions (e.g., 15% operational costs)
    * Transparent deduction reporting
  </Accordion>

  <Accordion title="Custom Commission Plans">
    **Flexible Commission Structures:**

    * Different rates for different product categories
    * Customizable commission structures per product
    * Tiered commission plans based on performance
    * Automatic commission approval (recommended)
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<Card title="Common Issues" icon="wrench">
  Here are solutions to common problems you might encounter during the XML FTP integration process.
</Card>

<AccordionGroup>
  <Accordion title="Connection Issues">
    **Cannot Connect to FTP Server:**

    * Verify that your FTP server has whitelisted the required Affelios IP addresses
    * Check that your FTP hostname and port are correct
    * Ensure your FTP credentials are valid and active
    * Contact your FTP server administrator to verify access
  </Accordion>

  <Accordion title="Data Import Problems">
    **Data Not Importing:**

    * Check that your filename templates are correct
    * Verify that XML files are being generated in the expected location
    * Ensure your XML files are in the correct format and well-formed
    * Review import logs for specific error messages
  </Accordion>

  <Accordion title="Field Mapping Issues">
    **Incorrect Data Mapping:**

    * Verify that XML field names match your mapping configuration
    * Check that all required fields are properly mapped
    * Ensure XML files contain the expected data structure
    * Test with a small sample of data first
  </Accordion>

  <Accordion title="Commission Calculation Problems">
    **Commissions Not Calculating:**

    * Verify that your commission plans are properly configured
    * Check that field mappings include revenue fields
    * Ensure auto-approve commissions is enabled
    * Review deduction settings and percentages
  </Accordion>
</AccordionGroup>

### Getting Help

<Steps>
  <Step title="Check Import Logs">
    Review the import logs in Settings > Imports for specific error messages and details.
  </Step>

  <Step title="Contact FTP Administrator">
    Reach out to your FTP server administrator for access or server-related issues.
  </Step>

  <Step title="Contact Affelios Support">
    Contact Affelios support via Intercom or email for integration-specific problems.
  </Step>

  <Step title="Provide Details">
    Include information about error messages, import logs, and steps you've already tried.
  </Step>
</Steps>

***

## Best Practices

<Card title="Optimization Tips" icon="lightbulb">
  Follow these best practices to ensure your XML FTP integration runs smoothly and effectively.
</Card>

<AccordionGroup>
  <Accordion title="Data Management">
    **Keep Your Data Clean:**

    * Regularly monitor import logs for any issues
    * Ensure XML files are generated consistently and are well-formed
    * Verify that all required fields are being populated
    * Keep historical data for reporting and analysis
  </Accordion>

  <Accordion title="Commission Planning">
    **Optimize Your Commission Structure:**

    * Set competitive commission rates for your industry
    * Consider different rates for different product categories
    * Monitor affiliate performance and adjust rates accordingly
    * Provide clear commission information to affiliates
  </Accordion>

  <Accordion title="Integration Monitoring">
    **Stay on Top of Performance:**

    * Set up alerts for failed imports
    * Regularly review commission calculations
    * Monitor data quality and consistency
    * Keep backup records of important transactions
  </Accordion>

  <Accordion title="Affiliate Support">
    **Support Your Affiliates:**

    * Provide clear information about your products
    * Share performance insights and marketing tips
    * Respond promptly to affiliate questions
    * Recognize top-performing affiliates
  </Accordion>
</AccordionGroup>

***

## Next Steps

<Card title="Your Integration is Complete!" icon="circle-check">
  Congratulations! Your XML FTP integration is now successfully set up with Affelios. Your affiliates can begin marketing your products immediately.
</Card>

### What Happens Next

<Steps>
  <Step title="Data Synchronization">
    Affelios will automatically download and import customer registrations and transactions from your FTP server each day.
  </Step>

  <Step title="Commission Processing">
    Commissions will be calculated and processed automatically based on your configured settings.
  </Step>

  <Step title="Affiliate Onboarding">
    Start inviting affiliates to join your program or promote it to attract new partners.
  </Step>

  <Step title="Performance Monitoring">
    Use the Affelios dashboard to monitor clicks, conversions, and commission payouts.
  </Step>

  <Step title="Program Optimization">
    Continuously optimize your program based on performance data and affiliate feedback.
  </Step>
</Steps>

### Additional Resources

<Card title="Further Reading" icon="book">
  * [Brand Creation Guide](/knowledge-base/operators/setup-guide) - Complete brand configuration
  * [Commission Plan Management](/knowledge-base/operators/create-manage-commission-plans) - Advanced commission strategies
  * [Affiliate Onboarding](/knowledge-base/getting-started/for-affiliates) - Guide for your new affiliates
  * [Reporting & Analytics](/knowledge-base/reporting/reporting) - Understanding your program performance
  * [API Documentation](/developers/api/overview) - Advanced integration options
</Card>

<Info>
  Need additional help? Our support team is available to assist with any questions or issues you might have with your XML FTP integration. Contact us via Intercom or email [support@affelios.com](mailto:support@affelios.com).
</Info>