# TechKeeper — rejestr formatów eksportu danych

Wersja 1, 25 września 2026. Interfejs wydania danych firmy: `GET /api/v1/company/export.zip`.
Dostęp bez dodatkowej opłaty we wszystkich planach, także po wygaśnięciu abonamentu, dopóki dane
istnieją. Wymagane konto administratora całej firmy (aktualna rola Admin we wszystkich aktywnych lokalizacjach), zwykły token Bearer uzyskany przez logowanie i wymagane 2FA. Sesja wsparcia
nie może wykonać eksportu. Brak dostępu do konta wymaga weryfikacji upoważnienia
przez obsługę. Endpoint nie przyjmuje identyfikatora cudzej firmy. To wydanie danych kontraktowych,
nie automatyczna realizacja indywidualnego prawa osoby z art. 20 RODO.

## Format i odbiór

ZIP zawiera `data/<nazwa>.ndjson`: jeden obiekt JSON UTF-8 na wiersz, klucze camelCase, wartości
enum jako tekst camelCase, daty ISO 8601 (timestampy UTC), liczby JSON. Identyfikatory UUID zachowują
powiązania między zbiorami. Rekordy archiwalne są uwzględnione, o ile nadal istnieją.
Nie ma limitu 200000 wierszy w archiwum. XLSX i stary JSON są raportami wybranych modułów;
przekroczenie ich limitu powoduje jawny błąd i wskazanie archiwum ZIP.

Oryginalne pliki dokumentów (w tym zdjęcia awarii): `files/documents/<Document.Id>`; nazwę, MIME
oraz relację do urządzenia wskazuje zbiór Documents. Zarchiwizowane pliki rozliczeń:
`files/invoices/<Invoice.Id>/invoice.pdf`, `invoice.xml`, `upo.xml`; UPO bezpośredniego KSeF:
`files/ksef/<InvoiceId>/upo.xml`. XML faktury bezpośredniego KSeF znajduje się także w polu
KsefSubmissions.invoiceXml. Brak zarchiwizowanego pliku rozliczenia nie oznacza jego wygenerowania:
rekord faktury i istniejące artefakty są wydawane; niezarchiwizowane wizualizacje zamawia się
przez standardowy interfejs billingowy lub obsługę.

`manifest.json` jest zapisywany na końcu i zawiera wersję, companyId, complete=true, liczniki,
listę typów/pól, liczbę plików oraz wyłączenia. Przy braku istniejącego pliku lub błędzie odczytu
transfer jest przerywany; bez poprawnego ZIP i manifestu nie wolno potwierdzać kompletności.
Baza jest odczytywana jako spójna migawka; magazyn plików nie ma wspólnej transakcji z bazą.
Usunięcie pliku podczas eksportu może wymagać powtórzenia transferu.

Jednocześnie jeden pełny eksport na proces serwera, limit pojedynczej próby 30 minut.
Przy konflikcie zwracane jest 409; po przekroczeniu czasu transfer jest przerwany. Dla pakietów
przekraczających ten czas obsługa korzysta z narzędzia offline TechKeeper.DataExport (ta sama
whitelista i zakres danych), ustala budżet 1–1440 minut i limit dysku przed uruchomieniem oraz
zabezpieczony kanał odbioru. Nieudane częściowe paczki są usuwane, sukces ma sumę SHA-256. Te limity nie powodują cichego obcięcia danych.

## Procedura przenoszenia

`POST /api/v1/company/switching/start` z JSON `{"confirm":true}` rozpoczyna przenoszenie i zapisuje
30 dni okresu przejściowego oraz minimum kolejne 30 dni odzyskania. `GET /api/v1/company/switching`
zwraca terminy. Po zweryfikowanym odbiorze klient wywołuje `POST /api/v1/company/switching/complete`
z tym samym potwierdzeniem; okres odzyskania nie będzie krótszy niż 30 dni od potwierdzenia ani
krótszy niż już wyznaczony. Ponowienia tych poleceń są idempotentne. Sam GET eksportu nie zmienia
terminów. Przedłużenie transferu i szczególne przypadki wymagają uzgodnienia z obsługą przed
upływem terminu. Automatyczne usuwanie całej firmy respektuje ten okres; wnioski osób dotyczące
ich danych osobowych są obsługiwane osobno. Wygaśnięcie okresu nie usuwa danych natychmiast:
obowiązują odrębne harmonogramy retencji i zakończenia umowy.

## Zbiory i pola

Każda poniższa nazwa odpowiada plikowi `data/<nazwa>.ndjson`; pola w pliku mają camelCase.

| Zbiór | Pola |
|---|---|
| Companies | Id, CreatedAt, Name, Nip, Address, SubscriptionPlan, SubscriptionExpiresAt, SubscriptionStatus, BillingPeriodStartedAt, BillingPeriodInvoiceId, PlanManuallyManaged, StripeCustomerId, StripeSubscriptionId, PaymentMethod, SubscriptionBillingCycle, PendingPlan, PendingBillingCycle, ExtraUsers, ExtraLocations, ExtraDevices, ExtraStorageMb, AddonPriceOverrideNetZl, AddonDescription, PendingExtraUsers, PendingExtraLocations, PendingExtraDevices, PendingExtraStorageMb, GraceUntil, TrialReminderSentAt, RenewalReminderSentAt, IsSuspended, SuspendedAt, PendingDeletionAt, SwitchingRequestedAt, SwitchingCompletedAt, DataRetrievalUntil, DeletionRequestedByUser, NipVerifiedAt, DigestFrequency, DigestIncludeManagers |
| Locations | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, CustomType, Name, Address, City, Type, Subtype, ConstructionYear, Area, EnergyClass, LastDigestSentAt |
| Users | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Email, FirstName, LastName, Phone, EmailNotificationsEnabled, EmailVerified, PendingEmail, TwoFactorEnabled, TermsAcceptedAt, TermsVersion, PrivacyPolicyAcceptedAt, PrivacyPolicyVersion |
| UserLocations | Id, CreatedAt, UserId, LocationId, Role, AssignedAt |
| UserPermissionOverrides | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, UserId, Permission, Allow |
| Devices | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, OrganizationalStatus, RequiredQualificationKind, LocationId, Group, Name, UdtRegistryNumber, InventoryNumber, SerialNumber, Manufacturer, ManufactureYear, SupervisionType, Category, SelfService, ExternalService, HasDtr, CalibrationType, MeasuringRange, MeasuringUnit, AccuracyClass, Resolution, CalibrationIntervalMonths, MetrologicalStatus, ProtectionClass, TestIntervalMonths, Notes, IsSuspended, SuspendedAt, Status, StatusBeforeSuspension, ResourceMonitoringEnabled, ResourceCyclesTotal, ResourceHoursTotal, ResourceAlertedThreshold, AutoSuspendOnResourceExhaustion, ServiceIntervalCycles, ServiceIntervalHours, LastServiceCycles, LastServiceHours, ServiceReminderSent, ResponsibleEmployeeId, UdtCaretakerName, CurrentFieldLocation, FieldTakenByEmployeeId, TypeCode |
| Inspections | Id, CreatedAt, DeviceId, PerformedBy, Type, PerformedAt, NextDueAt, Result, Notes, CertificateNumber, PerformedByLab, AccreditationNumber, MeasurementUncertainty, TraceabilityReference, InsulationResistance, ProtectiveConductorContinuity, LeakageCurrent |
| Documents | Id, CreatedAt, CustomType, DeviceId, UploadedBy, Name, Type, FileSizeKb, MimeType, ValidUntil |
| MaintenanceLogs | Id, CreatedAt, DeviceId, PerformedBy, PerformedAt, Description, PartsUsed |
| DeviceOperators | Id, CreatedAt, DeviceId, UserId, EmployeeId, QualificationNumber, QualificationValidUntil, AssignedAt |
| AlertContacts | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Email, Name |
| AuditLogs | Id, CreatedAt, UserId, CompanyId, Action, EntityType, EntityId, OldValues (filtrowane), NewValues (filtrowane), IsPlatformAction |
| WorkOrders | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, DeviceId, InspectionId, AssignedToUserId, Title, Description, Status, Priority, Source, ExternalServiceProvider, ReporterName, ReporterContact, CausedSuspension, ClosedAt, LaborHours, LaborRate |
| WorkOrderStatusChanges | Id, CreatedAt, WorkOrderId, OldStatus, NewStatus, Comment, ChangedByUserId |
| WorkOrderParts | Id, CreatedAt, WorkOrderId, Name, CatalogNumber, Quantity, UnitPrice, WarehousePartId |
| DeviceStatusHistory | Id, CreatedAt, DeviceId, OldStatus, NewStatus, Reason, ChangedByUserId |
| Notifications | Id, CreatedAt, UserId, CompanyId, Type, Title, Message, Link, EntityId, IsRead, ReadAt |
| Comments | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, EntityType, EntityId, AuthorId, Content, IsInternal, UpdatedAt |
| Installations | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, LocationId, Name, Type, Subtype, LastInspectionDate, NextInspectionDate, Notes |
| CalendarEvents | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, LocationId, Date, Title, Description |
| Vehicles | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, CustomType, LocationId, Name, RegistrationNumber, Vin, Brand, Model, ManufactureYear, Type, InsuranceExpiryDate, TechnicalInspectionDate, Notes |
| ResourceLogs | Id, CreatedAt, DeviceId, RecordedByUserId, RecordedAt, Cycles, Hours, Notes |
| Employees | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, FirstName, LastName, Status, Position, PhoneNumber, Notes, UserId |
| EmployeeQualifications | Id, CreatedAt, EmployeeId, Kind, KindCode, Number, IssuedAt, ValidUntil, Notes |
| FaultReports | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, DeviceId, EmployeeId, ReportedByUserId, ReporterName, Description, DeviceStopped, PhotoDocumentId, Status, ReviewedByUserId, ReviewedAt, WorkOrderId |
| ApiKeys | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Name, Scope, LastUsedAt, CreatedByUserId, ExpiresAt |
| WebhookSubscriptions | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, EventTypes, CreatedByUserId |
| ProtocolTemplates | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Name, Group |
| ProtocolTemplateItems | Id, CreatedAt, TemplateId, Order, Text |
| InspectionChecklistItems | Id, CreatedAt, InspectionId, Order, Text, Status, Note |
| PreWorkChecks | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, DeviceId, EmployeeId, EmployeeName, PerformedAt, IsFitForUse, Notes |
| PreWorkCheckItems | Id, CreatedAt, PreWorkCheckId, Order, Text, Status, Note |
| ProductSubscriptions | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Product, Tier, Status, ExpiresAt, StripeSubscriptionId, StripePriceId |
| AlertAcknowledgements | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, EntityType, EntityId, AcknowledgedByUserId, AcknowledgedAt, Note, SnoozeUntil |
| Invoices | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Number, SequenceNo, IsTest, Year, CorrectionOfId, CorrectedInvoiceNumber, CorrectedKsefNumber, CorrectedInvoiceIssuedAt, CorrectionTargetNetAmount, CorrectionReason, IssuedAt, DueAt, PaidAt, BillingPackageJson, EntitlementsAppliedAt, Status, Plan, Cycle, PeriodStart, PeriodEnd, Description, LinesJson, FakturowniaAccount, FakturowniaId, FakturowniaStatus, FakturowniaAttemptedAt, FakturowniaCheckedAt, FakturowniaConfirmedAt, FakturowniaKsefAttemptedAt, FakturowniaCorrectedId, FakturowniaPaymentSyncedAmount, FakturowniaPaymentStatus, FakturowniaPaymentCheckedAt, FakturowniaArchiveStatus, FakturowniaArchiveCheckedAt, NetAmount, VatRate, VatAmount, GrossAmount, Currency, VatExemptionLegalBasis, CustomerDeliveryRequestedAt, CustomerDeliveryAttemptedAt, CustomerDeliveryClaimedAt, RetentionHold, SellerName, SellerNip, SellerAddress, SellerBankAccount, SellerBankName, BuyerName, BuyerNip, BuyerAddress, KsefNumber, CustomerNotifiedAt |
| InvoicePayments | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, InvoiceId, Amount, ReceivedOn, Reference, Reason, ReversesPaymentId |
| WarehouseParts | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, LocationId, Name, CatalogNumber, Manufacturer, Supplier, Unit, UnitPrice, Quantity, MinStock, StoragePlace, Notes, DeviceId, LowStockNotifiedAt |
| StockMovements | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, WarehousePartId, Type, Quantity, BalanceAfter, Note, WorkOrderId, CreatedByUserId |
| Tools | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, LocationId, Name, ToolTypeId, CatalogNumber, Manufacturer, Diameter, Length, Material, Quantity, MinStock, StoragePlace, Notes, Status, CheckedOutToDeviceId, CheckedOutToEmployeeId, CheckedOutAt, SharpeningCount, LastSharpenedAt |
| ToolEvents | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, ToolId, Type, DeviceId, EmployeeId, Note, CreatedByUserId |
| ChoiceValues | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Field, Name, NormalizedName |
| ToolTypeDefinitions | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, Name |
| KsefSubmissions | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, InvoiceId, Status, Environment, KsefNumber, InvoiceHash, InvoiceXml, Attempts, LastErrorCode, NextRetryAt, SentAt, AcceptedAt, CustomerNotifiedAt, DelayNotifiedAt, UpdatedAt |
| ConsentLogs | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, UserId, Type, DocumentVersion, Context |
| LegalAcceptances | Id, CreatedAt, CompanyId, IsActive, DeactivatedAt, UserId, BundleId, ManifestSha256, Context, ConfirmedAuthority, Statement, ReceiptEmail, DocumentPackage, ProviderAcceptedAt |

## Wyłączenia

- Hasła, hashe PIN/kluczy, tokeny QR, sesje, refresh tokeny, recovery codes, sekrety 2FA,
  klucze webhooków/push, URL webhooka mogący zawierać hasło, klucze storage i upoważnienia wsparcia.
  Metadane konfiguracji API/webhooków są w pakiecie; po przeniesieniu poświadczenia trzeba utworzyć od nowa.
- AuthSession, RefreshToken, PushSubscription i TwoFactorRecoveryCode: bezpieczeństwo uwierzytelnienia.
- AlertLog: wewnętrzna deduplikacja wysyłek jobów, bez treści wiadomości; powiadomienia klienta
  i potwierdzenia są wydawane w Notifications i AlertAcknowledgements.
- TrialLedger: wewnętrzny rejestr zapobiegania nadużyciom; AddonPricing i MaintenanceSetting: globalna
  konfiguracja usługodawcy; WebhookDelivery: kolejka operacyjna z niezweryfikowanymi payloadami/błędami.
- Audyt obejmuje zdarzenia i historyczne wartości wyłącznie dozwolonych pól skalarnych. Nieznane pola,
  zagnieżdżone obiekty, historyczne sekrety, adresy IP i wewnętrzna diagnostyka nie są wydawane automatycznie.
- Nie odtwarzamy danych już trwale usuniętych zgodnie z retencją ani logów infrastruktury,
  baz innych klientów, kopii bezpieczeństwa, konfiguracji platformy i jej sekretów.
- Dowody przyjęcia dokumentów umownych zawierają utrwalony DocumentPackage; liczniki ponowień
  doręczenia są wewnętrzną kolejką operacyjną i nie wchodzą do pakietu.

Brakujący lub sporny zakres klient zgłasza obsłudze; zostaje sklasyfikowany przed uznaniem transferu
za zakończony. Wyłączenia bezpieczeństwa nie ograniczają praw osób ani danych, które odrębna
ocena żądania każe udostępnić innym bezpiecznym sposobem.