config.example.json

{
  "ksef": {
    "environment": "test",
    "nip": "1234567890",
    "token": "your-ksef-token-here",
    "description": "KSeF API Configuration. Environment: 'test', 'demo', or 'prod'. Get token from KSeF portal. Token can also be provided via KSEF_TOKEN env var or Docker secret.",
    "rate_limit": {
      "per_second": 10,
      "per_minute": 30,
      "per_hour": 120,
      "description": "Optional: KSeF API rate limits. Defaults match official limits. Lower these if sharing a token."
    }
  },
  "notifications": {
    "channels": ["pushover"],
    "message_priority": 0,
    "test_notification": true,
    "templates_dir": "/data/templates",
    "templates_description": "Optional: path to custom Jinja2 template directory. Templates found here override built-in defaults. Files: email.html.j2, slack.json.j2, discord.json.j2, pushover.txt.j2, webhook.json.j2",
    "description": "Multi-channel notification system. Enable one or more channels by listing them in 'channels' array. Secrets can be provided via config, environment variables, or Docker secrets.",
    "pushover": {
      "user_key": "your-pushover-user-key",
      "api_token": "your-pushover-api-token",
      "description": "Pushover mobile notifications. Get credentials from https://pushover.net/. Secrets: PUSHOVER_USER_KEY, PUSHOVER_API_TOKEN"
    },
    "discord": {
      "webhook_url": "https://discord.com/api/webhooks/...",
      "username": "KSeF Monitor",
      "avatar_url": "",
      "description": "Discord webhook notifications. Create webhook in Discord channel settings. Secret: DISCORD_WEBHOOK_URL"
    },
    "slack": {
      "webhook_url": "https://hooks.slack.com/services/...",
      "username": "KSeF Monitor",
      "icon_emoji": ":receipt:",
      "description": "Slack Incoming Webhook. Create in Slack App settings. Secret: SLACK_WEBHOOK_URL"
    },
    "email": {
      "smtp_server": "smtp.gmail.com",
      "smtp_port": 587,
      "use_tls": true,
      "username": "your-email@gmail.com",
      "password": "your-app-password",
      "from_address": "ksef-monitor@yourdomain.com",
      "to_addresses": ["recipient1@example.com", "recipient2@example.com"],
      "description": "Email notifications via SMTP. For Gmail use App Password. Secret: EMAIL_PASSWORD"
    },
    "webhook": {
      "url": "https://your-server.com/webhook",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
      },
      "timeout": 10,
      "description": "Generic webhook notifications. Sends JSON payload to any HTTP endpoint. Secret: WEBHOOK_TOKEN (for Authorization header)"
    },
    "ios_push": {
      "enabled": false,
      "worker_url": "https://push.monitorksef.com",
      "timeout": 15,
      "description": "iOS Push notifications via Monitor KSeF app. Set enabled=true to activate. Credentials (instance_id, instance_key) auto-generated by PushManager on first run and stored in DB. Secret: IOS_PUSH_INSTANCE_KEY"
    }
  },
  "monitoring": {
    "subject_types": ["Subject1", "Subject2"],
    "date_type": "Invoicing",
    "timezone": "Europe/Warsaw",
    "logging_level": "INFO",
    "description": "Monitoring settings. subject_types: Subject1 (sprzedażowe - you are seller), Subject2 (zakupowe - you are buyer). date_type: Issue | Invoicing | PermanentStorage. timezone: IANA timezone name (default: Europe/Warsaw). logging_level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: INFO). See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for valid timezone values."
  },
  "schedule": {
    "mode": "minutes",
    "interval": 5,
    "description": "Schedule configuration. MODES: 'simple' (seconds), 'minutes', 'hourly', 'daily' (specific time), 'weekly' (specific days/times)",
    "examples": {
      "every_5_minutes": {"mode": "minutes", "interval": 5},
      "every_2_hours": {"mode": "hourly", "interval": 2},
      "daily_at_9am": {"mode": "daily", "time": "09:00"},
      "daily_3_times": {"mode": "daily", "time": ["09:00", "14:00", "18:00"]},
      "weekly_workdays": {"mode": "weekly", "days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "time": "09:00"},
      "weekly_multi_times": {"mode": "weekly", "days": ["monday", "wednesday", "friday"], "time": ["08:00", "16:00"]}
    }
  },
  "storage": {
    "save_xml": false,
    "save_pdf": false,
    "output_dir": "/data/invoices",
    "folder_structure": "",
    "file_name_pattern": "{type}_{date}_{invoice_number}",
    "file_exists_strategy": "skip",
    "pdf_templates_dir": "/data/pdf_templates",
    "description": "File storage settings. save_xml/save_pdf: enable saving invoice XML/PDF files (default: false). output_dir: base directory for saved files (auto-created). folder_structure: subfolder pattern using placeholders {year}, {month}, {day}, {type}. Examples: '{year}/{month}' -> 2026/02/, '{type}/{year}/{month}/{day}' -> sprzedaz/2026/02/27/. Empty string = flat directory (default). file_name_pattern: file naming pattern using placeholders {type} (sprz/zak), {date} (YYYYMMDD), {invoice_number}, {ksef} (full KSeF number), {ksef_short} (last 6 chars), {seller_nip}, {buyer_nip}. Default: '{type}_{date}_{invoice_number}'. file_exists_strategy: what to do when file already exists - 'skip' (default, log and skip), 'rename' (add _1, _2 suffix), 'overwrite' (replace existing). pdf_templates_dir: optional custom HTML/CSS template directory for PDF generation."
  },
  "prometheus": {
    "enabled": true,
    "port": 8000,
    "bind_address": "0.0.0.0",
    "description": "Prometheus metrics endpoint. Exposes /metrics on specified port. bind_address: '0.0.0.0' for Docker (default), '127.0.0.1' for bare metal. Metrics: ksef_last_check_timestamp, ksef_new_invoices_total, ksef_monitor_up"
  },
  "database": {
    "enabled": true,
    "path": "/data/invoices.db",
    "description": "SQLite database for invoice metadata persistence. path: location of DB file (auto-created). Set enabled: false to disable DB and use JSON state file only."
  },
  "api": {
    "enabled": false,
    "port": 8080,
    "bind_address": "127.0.0.1",
    "auth_token": "",
    "ui_enabled": true,
    "rate_limit": {
      "enabled": true,
      "default": "60/minute",
      "trigger": "2/minute"
    },
    "description": "REST API for web UI and integrations. Disabled by default. If auth_token is empty when enabled, a random token is auto-generated and logged at startup. ui_enabled: enable server-rendered Web UI at /ui (default: true). rate_limit: slowapi rate limiting (60 req/min default, 2/min for trigger)."
  },
  "initial_load": {
    "enabled": false,
    "start_date": "2024-01-01",
    "subject_types": ["Subject1", "Subject2"],
    "date_type": "Invoicing",
    "description": "One-time historical invoice import via KSeF /invoices/exports API. Set enabled=true and start_date to trigger import on next startup. Date range: start_date to now, split into 90-day windows per subject_type. Progress tracked in DB (initial_load_jobs table) — safe to restart. subject_types: Subject1 (sprzedazowe), Subject2 (zakupowe). date_type: Invoicing | IssueDate. Manage via REST API: POST /api/v1/initial-load/start, GET /api/v1/initial-load/status, POST /api/v1/initial-load/cancel."
  }
}