Skip to content

External Resources and References

This document contains links to all external resources, documentation, specifications, and repositories referenced in the accounting service project. No code dependencies are included here.

Table of Contents

Google Drive Documents

Invoice Country-Specific Requirements 2025

Purpose: Specification of footer texts for different countries and tax jurisdictions

URL: https://docs.google.com/spreadsheets/d/1Jeuw5JoiONfZxk9_5HtaIW-jhjpfDezd/edit?gid=758256549#gid=758256549

Content:

  • Country-specific invoice footer requirements
  • Legal text variations by jurisdiction
  • Tax registration information display rules
  • Footer text mapped to TiskoveId first character

Used For:

  • Determining invoice footer text based on TiskoveId
  • Legal compliance for different tax jurisdictions
  • Invoice template rendering

Tax Registrations by Country

Purpose: Overview of jurisdictions where FTMO holds local tax registrations

URL: https://docs.google.com/spreadsheets/d/14v7UJb8Cs5thIAM3FVuLOJ_48nVXSkErfq1QrxJAqo4/edit?gid=746490938#gid=746490938

Content:

  • List of countries with FTMO tax registrations
  • VAT/Tax rates by country
  • Tax ID numbers for each jurisdiction
  • Zero-rated VAT countries (countries without registration)

Used For:

  • Setting up test data for different countries
  • Determining VAT rates and tax handling
  • Finance configuration validation
  • Referenced in enums.enums_company.Company

Vertex - Tax Manual

Purpose: Manual for Vertex tax integration and calculations.

URL: https://docs.google.com/document/d/1kGPnsYkduayzlBv1jR1DCjE-XYOzQ4ls3V3vkO0dTZ4/edit?tab=t.0#heading=h.3or32u4qiej8

ASS Documentations

Purpose: General documentation for the Accounting Service System (ASS).

URL: https://docs.google.com/document/d/1ivH9vWpd3M2tViVcqTHZPfrOEg__0k4qmz7j39vWoCg/edit?tab=t.0

Generování faktur a dopropisů pro testy na dev env

Purpose: Guide for generating invoices and credit notes for testing on the dev environment.

URL: https://docs.google.com/document/d/1FnvU0fd_MygqT5_2Q6ZbxE3XVBgcysgW8TutvqvWMFk/edit?tab=t.0#heading=h.64neo8190co9

Helios Import spec účetní 2022

Purpose: Accounting specification for Helios imports from 2022.

URL: https://docs.google.com/spreadsheets/d/1bMAvMPpAhEu1Vjp50YIin6MZ0tMSUmpwwRmNqkuPUcY/edit?gid=1873659250#gid=1873659250

Helios - Account Numbers (Čísla účetních účtů)

Purpose: Specification of Helios accounting account numbers

URL: https://docs.google.com/spreadsheets/d/1Z0tHyu3aEmcEEhzzkn7_Up1LQkL6o8BK884r7K1G2Ho/edit?gid=0#gid=0

Content:

  • Complete list of Helios account numbers (CisloUcetPol)
  • Account number mappings to item types
  • General ledger account structure
  • Revenue, expense, and liability accounts

Used For:

  • Defining CisloUcetPol enum values
  • Account mapping for invoice items
  • Financial reporting classification
  • Referenced in enums.enums_item_types.CisloUcetPol

Helios - External attributes 2025

Purpose List of external attributes needed from 1.7.2025 on an invoice record

URL https://docs.google.com/spreadsheets/d/1ExnUDoEKrJk_6BWY_JTH8cMhomI7tvbs0Y4pc8TIZII/edit?gid=0#gid=0

FinSys - Domain Experts

Purpose: List of domain experts for different financial systems.

URL: https://docs.google.com/spreadsheets/d/15MJeFfKOU2VfICD5ja0td6htHntZ3P1Y-mVGezSdWGc/edit?gid=1919984391#gid=1919984391

GitLab Repositories

Accounting Service Main Repository

Purpose: Main codebase for accounting service (PHP backend + Python QA tests)

Base URL: https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service

Key References:

Test Data Directory

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/blob/5844fc2dde8acce78e704db5430fa33ff1a765dc/qa/test_data

Content:

  • Payment info JSON files
  • Test data fixtures
  • Sample documents

DatabaseSetting Enum

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/-/blob/2866212037ea0de2d31736a051d07fad8ff9172e/qa/enums/enums_db_setting.py#L77

Content:

  • Database configuration enum
  • Platform mappings (Helios, Xero, NetSuite, Oanda)
  • Company assignments per database

Company Enum

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/-/blob/b73546e4e8a2b38cafc1d50df42e5ff3f1c854ed/qa/enums/enums_company.py#L43

Content:

  • FTMO company entities
  • Company details (address, registration numbers)
  • GDPR group assignments
  • Tax registration setup

BankAccount Enum

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/-/blob/18aa4a9d31cceddb5dd4a2cd56c6930227bc85e3/qa/enums/enums_bank_account.py#L16

Content:

  • Bank account information by company and currency
  • Account numbers, routing numbers
  • Bank names and addresses

CisloUcetPol Enum

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/-/blob/981818b205711dd71bab2946907fba8cc783230a/qa/enums/enums_item_types.py#L11

Content:

  • Account number definitions
  • Item type to account number mapping
  • Platform-specific account logic

Document Helper - Bank Info

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/blob/d545f6b6f6add59b40e8ee11480e735801a438f6/qa/helpers/document_helper.py#L105

Content:

  • get_bank_info() function
  • Bank account selection logic
  • Currency-based bank routing

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/blob/d545f6b6f6add59b40e8ee11480e735801a438f6/qa/helpers/document_helper.py#L93

Content:

  • Footer legal text selection
  • TiskoveId interpretation logic
  • Company and print format handling

FooterVat Enum

**URL: ** https://gitlab.fftrader.cz/fftrader/accounting-service-team/accounting-service/blob/5844fc2dde8acce78e704db5430fa33ff1a765dc/qa/model/enums.py#L13

Content:

  • Footer VAT text definitions
  • Legal compliance text per jurisdiction
  • Tax registration display text

QA Framework Monorepo

Purpose: Shared QA framework and utilities

URL: https://gitlab.fftrader.cz/qa-team/monorepo

Content:

  • Common test utilities
  • Shared test helpers
  • Framework dependencies

Setup: Clone to the same parent directory as accounting-service for Python tests with Poetry.

Technical Specifications

Helios Orange Documentation

System: Czech accounting software used as primary platform

Key Features:

  • Document import via staging tables
  • Stored procedures for data processing
  • Master data tables (TabDokladyZbozi, TabCisOrg)
  • External attributes support (TabDokladyZboziExt)

Integration Points:

  • Universal import tables (TabUniImportOrg, TabUniImportOZ)
  • Document retrieval APIs
  • PDF/HTML template rendering

ISO Standards

ISO 4217 - Currency Codes

Standard: International currency code standard

Examples:

  • CZK - Czech Crown
  • USD - US Dollar
  • EUR - Euro
  • GBP - British Pound

Used In:

  • Mena field (invoice currency)
  • LokalniMena field (local currency)
  • Currency enum definitions

ISO 3166-1 Alpha-2 - Country Codes

Standard: Two-letter country codes

Examples:

  • CZ - Czech Republic
  • US - United States
  • GB - United Kingdom
  • AU - Australia
  • DE - Germany

Used In:

  • ZemeDPH field (VAT country)
  • IdZeme field (country ID)
  • MistoZdaneni field (place of taxation)

Platform Documentation

Xero API Documentation

Platform: Cloud-based accounting software

Relevant Features:

  • Custom account mappings
  • Item ID references
  • Tracking categories
  • Rate limiting (requires 1.5s delay)

Integration Notes:

  • Platform-specific account number handling
  • Different item type codes vs Helios
  • Xero-specific validation logic

Oracle NetSuite API

Platform: Oracle ERP system

Relevant Features:

  • Entity IDs
  • Custom item mappings
  • Different naming conventions

Integration Notes:

  • Platform-specific item type handling
  • Empty TiskoveId for NetSuite
  • Custom validation rules

Oanda Trading Platform

Platform: Trading platform for rewards/payouts

Relevant Features:

  • Reward processing
  • Payout calculations
  • Trading account management

Integration Notes:

  • Special JSON response format
  • Google Cloud Storage integration
  • Different document structure vs Helios

Internal Systems

Google Cloud Platform

Cloud Storage Bucket

Bucket Name: ftmo-oanda-invoices-data

Purpose:

  • Store Oanda invoice documents
  • Document archival
  • Backup storage

Access:

  • Requires Google Cloud authentication
  • Service account credentials in application_default_credentials.json
  • DevOps team manages access

Setup Command:

gcloud auth application-default login --project ftmo-cr-ps-backoffice-0

Fallback: If credentials not available, documents stored locally in /accounting/var/oanda

Keycloak Identity Management

Purpose: Authentication and authorization system

Features:

  • User authentication via JWT tokens
  • Role-based access control
  • GDPR group management
  • Service account tokens

Roles:

  • accounting - Read access
  • accounting_editor - Write access

GDPR Groups:

  • ftmo-eval-global
  • ftmo-trading-global
  • jv-prop-eval-us
  • oanda-prop-trading-us
  • vrgk

GitLab CI/CD

Purpose: Continuous integration and deployment

Features:

  • Automated test execution
  • Build pipelines
  • Deployment automation
  • Test result reporting

Configuration Files:

  • .gitlab-ci.yml (main pipeline)
  • qa-pipeline-patch.yml (QA-specific config)

Development Tools

Docker Network

Network Name: infra-demo

Creation Command:

docker network ls | grep infra-demo || docker network create infra-demo

Purpose:

  • Container communication
  • Service isolation
  • Development environment networking

Poetry Package Manager

Purpose: Python dependency management

Project File: pyproject.toml

Setup:

poetry install

Advantages:

  • Deterministic builds via uv.lock
  • Virtual environment management
  • Dependency resolution

Makefile Commands

Purpose: Build automation and shortcuts

Key Commands:

  • make run - Run all tests
  • make run-smoke - Run regression tests
  • make run-regression - Run regression tests
  • make run-dev-container - Start Docker development container
  • make ci - Composer install
  • make cu - Composer update

Document Cross-References

Internal Documentation

For code-related documentation, see:

  • DEVELOPER_GUIDE.md - Setup, test users, Helios integration, and daily workflow
  • ARCHITECTURE.md - Technical architecture and design patterns
  • INVOICE_IMPORT_WITH_PAYMENT_INFO_WALKTHROUGH.md - End-to-end flow documentation

Access and Permissions

Required Access

Google Cloud Storage:

  • Read/write access to ftmo-oanda-invoices-data bucket
  • Contact: DevOps team

GitLab Repositories:

  • Member of fftrader/accounting-service-team
  • Member of qa-team (for framework monorepo)

Keycloak Test Users:

  • Test user accounts configured with appropriate roles
  • GDPR group memberships assigned
  • Contact: QA Lead or DevOps team

Google Sheets:

  • View access to specification spreadsheets
  • Contact: Finance team or Product Owner

Update Procedures

When Specifications Change

Google Sheets Updates:

  1. Review changed requirements in Google Sheets
  2. Update corresponding enum definitions in code
  3. Update test data to match new specifications
  4. Update this document with new sheet versions if URLs change

Platform API Changes:

  1. Review platform (Xero/NetSuite/Oanda) API documentation
  2. Update integration code in service layer
  3. Update test expectations
  4. Update validation logic

Tax Registration Changes:

  1. Update "Tax registrations by country" spreadsheet
  2. Update enums.enums_company.Company definitions
  3. Update test cases for new jurisdictions
  4. Update VAT rate enums

Support Contacts

For Access Issues:

  • DevOps Team - Infrastructure, GCP access, Keycloak
  • Finance Team - Tax specifications, account numbers
  • Product Owner - Business requirements, country specifications

For Technical Issues:

  • Accounting Service Team - Backend integration, Helios
  • QA Team - Test framework, test data
  • Platform Teams - Xero/NetSuite/Oanda integrations