Integracja z systemami FK
1. Przegląd
BusiKM eksportuje dane kilometrówek i delegacji do polskich systemów FK. Eliminacja ręcznego przepisywania.
| System | Format | Faza |
|---|
| Insert GT / Rewizor GT / nexo | EDI++ (.epp) | MVP (Sprint 5–6) |
| Comarch ERP Optima | REST API | Post-Sprint 7 |
| Symfonia | XML/CSV | Post-Sprint 7 |
| KSeF | API e-faktur | Post-Sprint 7 |
2. Architektura — wzorzec Strategy
class AbstractFKIntegration(ABC):
"""Bazowa klasa dla integracji FK."""
@abstractmethod
def export_mileage_log(self, mileage_log) -> bytes: ...
@abstractmethod
def export_delegation(self, delegation) -> bytes: ...
@abstractmethod
def validate_data(self, data: dict) -> list[str]: ...
@abstractmethod
def get_file_extension(self) -> str: ...
# Implementacje:
class InsertGTIntegration(AbstractFKIntegration): ...
class OptimaPKIntegration(AbstractFKIntegration): ...
class SymfoniaIntegration(AbstractFKIntegration): ...
class WFirmaIntegration(AbstractFKIntegration): ...
3. Insert GT — format EDI++
Wymagania techniczne
| Parametr | Wartość |
|---|
| Kodowanie | Windows-1250 |
| Końce linii | CRLF (\r\n) |
| Separator pól | | (pipe) |
| Separator dziesiętny | , (przecinek) |
| Format daty | RRRR-MM-DD |
| Rozszerzenie pliku | .epp |
Struktura pliku kilometrówki
[NAGLOWEK]
TYP=EWIDENCJA_PRZEBIEGU
WERSJA=1.0
DATA_EXPORTU=2026-07-15
FIRMA_NIP=1234567890
FIRMA_NAZWA=Transport ABC Sp. z o.o.
[POJAZD]
REJESTRACJA=WA 12345
MARKA=Mercedes-Benz
MODEL=Sprinter 316 CDI
POJEMNOSC=2143
NUMER_VIN=WDB9066351S123456
DMC=3500
[EWIDENCJA]
DATA|CEL|TRASA_SKAD|TRASA_DOKAD|KM|STAWKA|KWOTA|KIEROWCA|UWAGI
2026-07-01|Dostawa towaru|Warszawa|Kraków|295,5|0,8358|247,0|Jan Kowalski|
2026-07-02|Odbiór paczek|Kraków|Łódź|260,0|0,8358|217,3|Jan Kowalski|
2026-07-03|Serwis|Łódź|Warszawa|135,8|0,8358|113,5|Jan Kowalski|pilne
[PODSUMOWANIE]
RAZEM_KM=691,3
RAZEM_KWOTA=577,8
4. Mapowanie BusiKM → EDI++
| Pole EDI++ | Źródło BusiKM | Transformacja |
|---|
| DATA | Trip.start_time | Format RRRR-MM-DD |
| CEL | Trip.purpose | Mapowanie enum → tekst |
| TRASA_SKAD | Trip.start_address | Reverse geocoding |
| TRASA_DOKAD | Trip.end_address | Reverse geocoding |
| KM | Trip.distance_km | Zaokrąglenie do 1 miejsca, przecinek |
| STAWKA | MileageRate.rate_per_km | Aktualna stawka MF |
| KWOTA | KM × STAWKA | Obliczenie, zaokrąglenie do 1 miejsca |
| KIEROWCA | User.full_name | Imię + Nazwisko |
5. Kodowanie znaków polskich
Insert GT wymaga Windows-1250. Python konwersja:
content = edi_content.encode('windows-1250', errors='replace')
# Znaki niedostępne w Win-1250 zastępowane '?'
Mapowanie znaków: ą→ą, ć→ć, ę→ę, ł→ł, ń→ń, ó→ó, ś→ś, ź→ź, ż→ż (poprawne w Windows-1250).
6. Endpoint eksportu
POST /api/v1/exports/mileage-log/
Content-Type: application/json
Authorization: Bearer <token>
{
"vehicle_id": "uuid",
"month": 7,
"year": 2026,
"provider": "insert_gt",
"format": "edi_plus_plus"
}
→ 200 OK (application/octet-stream, Content-Disposition: attachment)
7. Historia eksportów
| Pole | Typ | Opis |
|---|
| provider | CharField | insert_gt / optima / symfonia / ksef |
| export_type | CharField | mileage_log / delegation |
| status | CharField | pending / success / failed |
| file_url | URLField | Presigned URL do pobrania (TTL 15 min) |
| error_message | TextField | Opis błędu (jeśli failed) |
8. Planowane integracje (Post-MVP)
| System | Metoda | Planowany sprint |
|---|
| Comarch ERP Optima | REST API (XL API) | Post-Sprint 7 |
| Symfonia | Import XML/CSV | Post-Sprint 7 |
| KSeF | API e-faktur MF | Post-Sprint 7 |
| wFirma | REST API | Rok 2 |
