Buyer and Invoice Import Guide

Import buyer and invoice data into Afakto to track accounts receivable, manage buyer relationships, and gain business insights.

Quick Start

flowchart LR
    subgraph Step1["1️⃣ Prepare"]
        A1[Create CSV files]
        A2[UTF-8 encoding]
    end
    subgraph Step2["2️⃣ Import Buyers"]
        B1[Upload buyers.csv]
        B2[Verify import]
    end
    subgraph Step3["3️⃣ Import Invoices"]
        C1[Upload invoices.csv]
        C2[Check results]
    end
    Step1 --> Step2 --> Step3

Essential steps:

Prepare CSV files with required headers (UTF-8 encoded)
Import buyers first — invoices reference buyers by BUYER_CODE
Import invoices — include ALL current invoices per company (missing ones are marked closed)
Verify results — check inserts, updates, and any failures

Key Concepts

flowchart TB
    subgraph DataHierarchy["Data Hierarchy"]
        Company["🏢 Company<br/><small>COMPANY_CODE</small>"]
        Buyer["👤 Buyer<br/><small>BUYER_CODE</small>"]
        Invoice["📄 Invoice<br/><small>INV_NUMBER</small>"]
        Company --> Buyer --> Invoice
    end    subgraph CurrencyRule["Currency Rule"]
        B1["Buyer A<br/>EUR only"]
        B2["Buyer B<br/>USD only"]
        I1["Invoice €100"]
        I2["Invoice €200"]
        I3["Invoice $500"]
        B1 --> I1
        B1 --> I2
        B2 --> I3
    end    subgraph ImportBehavior["Import Behavior"]
        direction TB
        New["New record → Insert"]
        Existing["Existing key → Update"]
        Missing["Missing invoice → Balance = 0"]
    end

Rule	Description
One currency per buyer	All invoices for a buyer must use the same currency. For multi-currency customers, create separate buyer records.
Complete invoice sets	Include ALL current invoices per company. Missing invoices are automatically closed (balance → 0).
Buyers before invoices	Import buyers first — invoices reference them by BUYER_CODE.
Upsert logic	Existing records are updated, not duplicated. Business keys: `COMPANY_CODE` + `BUYER_CODE` (buyers), `COMPANY_CODE` + `BUYER_CODE` + `INV_TYPE` + `INV_NUMBER` (invoices).
No duplicates in file	Duplicate records within the same import file are rejected. Ensure each buyer/invoice appears only once per file.
Unique filenames	The system blocks reimport of files with the same name. Use unique names for corrections.

Data Organization

Multi-Company Support

flowchart LR
    CSV["📁 CSV File"]
    CSV --> |"COMPANY_CODE: ACME01"| P1["Process ACME01"]
    CSV --> |"COMPANY_CODE: WIDGETS01"| P2["Process WIDGETS01"]
    CSV --> |"COMPANY_CODE: GADGETS01"| P3["Process GADGETS01"]    P1 --> R1["✓ ACME01 Data"]
    P2 --> R2["✓ WIDGETS01 Data"]
    P3 --> R3["✓ GADGETS01 Data"]

Each record specifies its company via COMPANY_CODE
A single file can contain data for multiple companies
Each company's data is processed independently
All COMPANY_CODE values must match companies you have access to

File Format Requirements

Requirement	Details
Format	CSV (Comma-Separated Values)
Separators	Both `,` (comma) and `;` (semicolon) are supported
Headers	Required in first row
Encoding	UTF-8 (for special characters)
Fields	All required fields must be present

Buyer Import

Buyers are your customers/debtors. Import buyers before invoices — invoices reference buyers by BUYER_CODE.

Required Headers

COMPANY_CODE,BUYER_CODE,BUYER_NAME,ID_TYPE,ID_NUMBER,PAYMENT_TERMS

Field Reference

Field	Required	Description
`COMPANY_CODE`	✓	Your company's identifier
`BUYER_CODE`	✓	Unique buyer identifier (max 15 chars recommended)
`BUYER_NAME`	✓	Customer/debtor name
`ID_TYPE`	✓	One of: `SIREN`, `SIRET`, `VAT`, `NATIONAL_REGISTRATION_NUMBER`, `DUNS_BRADSTREET`, `COMMERCIAL_REGISTER`
`ID_NUMBER`	✓	The identification number
`PAYMENT_TERMS`		Payment terms in days (e.g., 30, 60, 90)
`CURRENCY`		Currency code (e.g., EUR, USD, GBP)

Address Fields (Optional)

⚠️ While optional, address fields are typically required for credit insurance and factoring. Missing data must be added manually via the web interface.

Field	Description
`ADDRESS_STREET_NAME`	Street name
`ADDRESS_STREET_NUMBER`	Street number
`ADDRESS_POSTAL_CODE`	Postal/ZIP code
`ADDRESS_CITY`	City
`ADDRESS_STATE`	State or province
`ADDRESS_COUNTRY`	Country code (ISO standard)

Contact Fields (Optional)

⚠️ Contact info is typically required for buyers declared to insurers/factors.

Field	Description
`CONTACT_NAME`	Primary contact person
`CONTACT_EMAIL`	Contact email address
`CONTACT_PHONE`	Contact phone number

Examples

Full buyer record (with address and contact):

COMPANY_CODE,BUYER_CODE,BUYER_NAME,ID_TYPE,ID_NUMBER,PAYMENT_TERMS,CURRENCY,ADDRESS_STREET_NAME,ADDRESS_STREET_NUMBER,ADDRESS_POSTAL_CODE,ADDRESS_CITY,ADDRESS_COUNTRY,CONTACT_NAME,CONTACT_EMAIL,CONTACT_PHONE
ACME01,B001,Widgets Inc.,VAT,FR12345678901,30,EUR,"Main St","123",75001,"Paris","FR","Jean Dupont","[email protected]","+33123456789"
ACME01,B002,Gadgets Corp,SIREN,123456789,45,EUR,"Tech Blvd","456",10115,"Berlin","DE","Hans Schmidt","[email protected]","+49987654321"

Minimal buyer record:

COMPANY_CODE,BUYER_CODE,BUYER_NAME,ID_TYPE,ID_NUMBER,PAYMENT_TERMS,CURRENCY
ACME01,B004,Simple Company,VAT,ES12345678B,30,EUR
ACME01,B005,Basic Corp,SIREN,987654321,45,USD

Best Practices

Use consistent BUYER_CODE values across all imports
Validate ID numbers match the ID_TYPE format
Each buyer needs a unique COMPANY_CODE + BUYER_CODE combination
Use unique filenames when correcting errors (reimports of same filename are blocked)

Invoice Import

⚠️ Import buyers first — invoices reference buyers by BUYER_CODE.

Required Headers

COMPANY_CODE,BUYER_CODE,INV_TYPE,INV_NUMBER,INV_DATE,DUE_DATE,CURRENCY,AMOUNT,BALANCE,PAYMENT_METHOD

Field Reference

Field	Required	Description
`COMPANY_CODE`	✓	Company identifier (must exist in system)
`BUYER_CODE`	✓	Buyer identifier (must exist in system)
`INV_TYPE`	✓	`INVOICE`, `CREDIT_NOTE`, `PAYMENT`, or `OTHER`
`INV_NUMBER`	✓	Unique invoice identifier
`REFERENCE`		Order reference (also accepts: `ORDER_REF`, `ORDER_REFERENCE`)
`INV_DATE`	✓	Issue date (YYYY-MM-DD or DD/MM/YYYY)
`DUE_DATE`	✓	Due date (YYYY-MM-DD or DD/MM/YYYY)
`CURRENCY`	✓	Three-letter code (EUR, USD, GBP, etc.)
`AMOUNT`	✓	Total invoice amount
`BALANCE`	✓	Current outstanding balance
`PAYMENT_METHOD`	✓	See values below
`RECONCILIATION_JOURNAL`		Reconciliation reference

INV_TYPE values:

Value	Description
`INVOICE`	Standard invoice
`CREDIT_NOTE`	Credit note/refund (use negative amounts)
`PAYMENT`	Unallocated or rejected payment
`OTHER`	Miscellaneous document

PAYMENT_METHOD values: BANK_CHECK, BANK_TRANSFER, BAO, DRAFT, DRAFT_NOT_ACCEPTED, POSTAL_TRANSFER, OTHERS, STANDING_ORDER

Examples

Single company:

COMPANY_CODE,BUYER_CODE,INV_TYPE,INV_NUMBER,REFERENCE,INV_DATE,DUE_DATE,CURRENCY,AMOUNT,BALANCE,PAYMENT_METHOD
ACME01,B001,INVOICE,INV-2023-001,ORDER-2023-001,2023-05-01,2023-06-01,USD,1000.00,1000.00,BANK_TRANSFER
ACME01,B001,INVOICE,INV-2023-002,PO-2023-456,2023-05-15,2023-06-15,USD,2500.00,2500.00,BANK_TRANSFER
ACME01,B001,CREDIT_NOTE,CN-2023-001,,2023-05-20,2023-05-20,USD,-500.00,-500.00,BANK_TRANSFER

Multi-company file:

COMPANY_CODE,BUYER_CODE,INV_TYPE,INV_NUMBER,REFERENCE,INV_DATE,DUE_DATE,CURRENCY,AMOUNT,BALANCE,PAYMENT_METHOD
ACME01,B001,INVOICE,INV-2023-001,ORDER-2023-001,2023-05-01,2023-06-01,USD,1000.00,1000.00,BANK_TRANSFER
WIDGETS01,W001,INVOICE,W-INV-2023-001,W-ORDER-2023-001,2023-05-02,2023-06-02,EUR,1500.00,1500.00,BANK_TRANSFER
GADGETS01,G001,INVOICE,G-INV-2023-001,G-ORDER-2023-001,2023-05-03,2023-06-03,GBP,2000.00,2000.00,BANK_CHECK

Each company's invoices are processed independently.

Best Practices

Verify all referenced buyers exist before importing
Use unique invoice numbers within each company
Use consistent date format (YYYY-MM-DD recommended)
Balance should reflect current outstanding amount
Credit notes: use CREDIT_NOTE type with negative amounts
Include ALL current invoices per company (missing ones → balance = 0)
Use unique filenames for corrections

Import Process

flowchart LR
    subgraph Prepare["1. Prepare"]
        P1["Create CSV<br/>UTF-8 encoded"]
        P2["Validate data"]
    end    subgraph Transfer["2. Transfer"]
        T1["Manual Upload"]
        T2["SFTP"]
        T3["Azure Blob"]
        T4["REST API"]
    end    subgraph Process["3. Process"]
        PR1["Parse records"]
        PR2["Validate keys"]
        PR3["Upsert data"]
    end    subgraph Verify["4. Verify"]
        V1["Check counts"]
        V2["Review errors"]
    end    Prepare --> Transfer --> Process --> Verify

File Preparation

Create CSV files per the formats above
Validate data accuracy and completeness
Use descriptive filenames (e.g., 20231015_acme01_buyers.csv)
See FAQ for encoding and formatting details

Transfer Methods

Method	Description
Manual Upload	Web interface upload
SFTP	Secure file transfer protocol
Azure Blob Storage	Azure integration
REST API	Programmatic upload

Data flow modes:

Push — Your systems send files to Afakto
Pull — Afakto retrieves files on schedule

Contact your Afakto implementation team to determine the best approach.

REST API

Endpoint	Method	Content-Type
`/api/buyers/upload`	POST	`multipart/form-data`
`/api/invoices/upload`	POST	`multipart/form-data`

Example:

curl -X POST "https://your-instance.com/api/buyers/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

Response:

{"id": "...", "name": "buyers.csv", "type": "BUYER", "inserts": 5, "updates": 3, "deletes": 0, "failures": []}

Records are matched by business keys: COMPANY_CODE + BUYER_CODE for buyers, COMPANY_CODE + BUYER_CODE + INV_TYPE + INV_NUMBER for invoices. Missing invoices have their balance reset to 0.

Manual Upload

Log in to Afakto web application
Navigate to Datastreams
Click Upload
Select type (BUYER or INVOICE)
Upload file and review results

Verifying Results

After import:

Check insert/update counts
Review any failures
Verify data in Buyers or Invoices sections

Troubleshooting

Issue	Solution
Missing buyers	Import buyers before invoices
Date format errors	Use YYYY-MM-DD (recommended), DD/MM/YYYY, or ISO datetime
Number format issues	Both `.` and `,` decimal separators are supported
Special characters corrupted	Save CSV with UTF-8 encoding
Duplicate buyer/invoice in file	Each record must appear only once per file. Remove duplicate rows with the same key

Record Update Behavior

Existing records are updated, not duplicated (matched by COMPANY_CODE + BUYER_CODE for buyers, COMPANY_CODE + BUYER_CODE + INV_TYPE + INV_NUMBER for invoices)
For invoice imports, missing invoices have balance reset to 0
Each invoice file must contain ALL current invoices per company

Best Practices

Practice	Why
Import buyers before invoices	Invoices reference buyers by code
Update data frequently	Daily or before each cession operation
Include complete data sets	Missing invoices are marked closed
Validate before importing	Prevents errors and failures
Address errors promptly	Maintains data integrity

Need Help?

For assistance with specific import issues, contact your system administrator or Afakto support.