efka-api-integration

---
name: efka-api-integration
description: Greek social security (EFKA) integration — employee records, contribution calculations, APD declarations. Human approval for submissions.
version: 1.0.0
author: openclaw-greek-accounting
homepage: https://github.com/satoshistackalotto/openclaw-greek-accounting
tags: ["greek", "accounting", "efka", "social-security", "payroll"]
metadata: {"openclaw": {"requires": {"bins": ["jq", "curl"], "env": ["OPENCLAW_DATA_DIR", "EFKA_USERNAME", "EFKA_PASSWORD"]}, "optional_env": {"SLACK_WEBHOOK_URL": "Notifications for EFKA submission status updates", "GOOGLE_CALENDAR_ID": "Google Calendar ID for EFKA deadline sync (optional)"}, "notes": "EFKA credentials required only for submitting declarations. Payroll calculations work offline. All submissions require human approval (four-eyes workflow). Slack notification is optional."}}
---

# EFKA API Integration

This skill provides comprehensive integration with the Greek Social Security organization (EFKA) through OpenClaw's file processing capabilities, enabling automated employee record management, contribution calculations, and compliance monitoring for Greek businesses.


## Setup

```bash
export OPENCLAW_DATA_DIR="/data"
export EFKA_USERNAME="your-efka-username"
export EFKA_PASSWORD="your-efka-password"
which jq curl || sudo apt install jq curl
```

EFKA credentials are required only for submitting social security declarations. Payroll calculations and contribution processing work offline. All government submissions require human approval (four-eyes workflow).


## Core Philosophy

- **OpenClaw Artifact Ready**: Designed specifically for upload and deployment to OpenClaw instances
- **File-Based Processing**: Robust file system approach suitable for production deployment
- **Greek Employment Law Compliance**: Complete adherence to Greek social security regulations
- **Payroll Integration**: Seamless connection with existing Greek payroll systems
- **Production Scalability**: Built to handle multiple clients and high transaction volumes

## OpenClaw Commands

### Core EFKA Operations
```bash
# Primary employee and contribution management
openclaw efka employee-register --new-hire --calculate-contributions --generate-forms
openclaw efka monthly-process --payroll-period 2026-02 --all-employees --submit-ready
openclaw efka contributions-calculate --employee-id {id} --salary-changes --bonus-payments
openclaw efka compliance-check --deadlines --missing-submissions --penalty-warnings

# Employee lifecycle management
openclaw efka employee-onboard --personal-data --employment-terms --insurance-category
openclaw efka employee-update --salary-changes --position-updates --insurance-modifications
openclaw efka employee-terminate --final-calculations --clearance-certificates --archive-records

# Bulk processing and automation
openclaw efka batch-process --payroll-file /data/efka/payroll/input/ --validate-contributions
openclaw efka export-submissions --aade-format --efka-format --ready-for-upload
openclaw efka reconcile-payments --bank-statements --contribution-receipts --variance-analysis
```

### Advanced Integration Commands
```bash
# Integration with other OpenClaw skills
openclaw efka integrate-payroll --greek-compliance-aade --banking-integration --tax-calculations
openclaw efka coordinate-deadlines --cli-deadline-monitor --automatic-reminders --calendar-sync  # Syncs EFKA deadlines to calendar if configured
openclaw efka employee-expenses --individual-taxes --personal-contributions --annual-statements

# Reporting and analytics
openclaw efka generate-reports --monthly --quarterly --annual --management-dashboard
openclaw efka cost-analysis --employer-contributions --employee-deductions --budget-projections
openclaw efka audit-preparation --employee-records --contribution-history --compliance-documentation
```

### File Processing & Monitoring
```bash
# File-based EFKA data processing
openclaw efka monitor-files --watch-payroll-updates --auto-process --error-recovery
openclaw efka import-employee-data --csv --excel --validation --duplicate-detection
openclaw efka export-government --efka-xml --aade-integration --submission-ready

# Quality control and validation
openclaw efka validate-data --employee-records --contribution-calculations --regulatory-compliance
openclaw efka error-recovery --failed-submissions --data-corrections --resubmission-queue
openclaw efka backup-restore --employee-database --contribution-history --disaster-recovery
```

## OpenClaw File Processing Architecture

### EFKA File System Organization
```yaml
EFKA_File_Structure:
  employee_data:
    - /data/efka/employees/active/           # Current employee records
    - /data/efka/employees/terminated/       # Former employee records  
    - /data/efka/employees/pending/          # New hires pending registration
    - /data/efka/employees/updates/          # Employee data change requests
    
  payroll_processing:
    - /data/efka/payroll/input/              # Payroll data imports
    - /data/efka/payroll/processed/          # Calculated contributions
    - /data/efka/payroll/validated/          # Quality-checked data
    - /data/efka/payroll/ready-submit/       # Submission-ready files
    
  contributions_management:
    - /data/efka/contributions/monthly/       # Monthly contribution calculations
    - /data/efka/contributions/quarterly/     # Quarterly summaries
    - /data/efka/contributions/annual/        # Annual statements
    - /data/efka/contributions/payments/      # Payment confirmations
    
  government_integration:
    - /data/efka/submissions/efka-portal/     # EFKA portal submissions
    - /data/efka/submissions/aade-cross/      # Cross-reference with AADE
    - /data/efka/responses/confirmations/     # Government acknowledgments
    - /data/efka/responses/corrections/       # Required corrections
    
  compliance_monitoring:
    - /data/efka/deadlines/upcoming/          # Approaching deadlines
    - /data/efka/deadlines/overdue/           # Missed deadlines requiring action
    - /data/efka/audit/employee-records/      # Audit-ready documentation
    - /data/efka/audit/contribution-proof/    # Payment verification records
```

### EFKA Processing Pipeline
```yaml
Processing_Workflow:
  step_1_employee_data:
    command: "openclaw efka import-employees --source-file --validate-format --check-duplicates"
    input: "/data/efka/employees/imports/"
    output: "/data/efka/employees/validated/"
    functions: ["Data validation", "Duplicate detection", "Format standardization"]
    
  step_2_contribution_calculation:
    command: "openclaw efka calculate-contributions --salary-data --insurance-categories --rates-2026"
    input: "/data/efka/payroll/input/"
    output: "/data/efka/contributions/calculated/"
    functions: ["Contribution calculation", "Rate application", "Regulatory compliance"]
    
  step_3_cross_validation:
    command: "openclaw efka cross-validate --aade-data --banking-data --consistency-check"
    input: "/data/efka/contributions/calculated/"
    output: "/data/efka/contributions/validated/"
    functions: ["AADE cross-reference", "Banking reconciliation", "Error detection"]
    
  step_4_submission_prep:
    command: "openclaw efka prepare-submissions --efka-xml --government-format --digital-signatures"
    input: "/data/efka/contributions/validated/"
    output: "/data/efka/submissions/ready/"
    functions: ["Government format", "Digital signing", "Submission packaging"]
    
  step_5_monitoring:
    command: "openclaw efka monitor-compliance --deadlines --penalties --corrective-actions"
    input: "/data/efka/submissions/ready/"
    output: "/data/efka/compliance/monitoring/"
    functions: ["Deadline tracking", "Penalty calculation", "Action planning"]
```

## Greek Social Security Integration

### EFKA Employee Categories & Contributions (2026)
```yaml
EFKA_Employee_Categories:
  main_insurance:
    category_code: "101"
    description: "Main insurance - private sector employees"
    employer_rate: 24.56
    employee_rate: 16.00
    calculation_base: "gross_salary"
    max_monthly_base: 6177.84
    
  auxiliary_insurance:
    category_code: "201"  
    description: "Auxiliary insurance - supplementary pension"
    employer_rate: 3.00
    employee_rate: 3.00
    calculation_base: "gross_salary"
    max_monthly_base: 6177.84
    
  employment_account:
    category_code: "301"
    description: "Employment account - unemployment benefits"
    employer_rate: 1.55
    employee_rate: 0.55
    calculation_base: "gross_salary"
    max_monthly_base: 6177.84
    
  health_contributions:
    category_code: "401"
    description: "Health insurance contributions (EOPYY)"
    employer_rate: 9.76
    employee_rate: 2.55
    calculation_base: "gross_salary"
    no_maximum_base: true

Specialized_Categories:
  management_staff:
    category_code: "105"
    description: "Management and executive positions"
    additional_requirements: ["Higher contribution rates", "Extended coverage"]
    
  part_time_workers:
    category_code: "110"
    description: "Part-time employment"
    calculation_method: "proportional_to_hours"
    minimum_hours_threshold: 15
    
  seasonal_workers:
    category_code: "115"  
    description: "Seasonal employment (agriculture, tourism)"
    special_rates: "reduced_rates_applicable"
    documentation_required: ["Seasonal contract", "Industry certification"]
```

### Contribution Calculation Engine
```yaml
Contribution_Calculations:
  monthly_processing:
    gross_salary_input: "Base salary + allowances + bonuses"
    contribution_base_calculation: "Min(gross_salary, max_contribution_base)"
    
    employer_contributions:
      main_insurance: "contribution_base × 24.56%"
      auxiliary_insurance: "contribution_base × 3.00%"
      employment_account: "contribution_base × 1.55%"
      health_insurance: "gross_salary × 9.76%"
      total_employer: "sum of all employer contributions"
      
    employee_deductions:
      mai

... (truncated)