Przejdź do głównej zawartości

Standardy i Formaty

Ta sekcja zawiera wytyczne dotyczące standardów i formatów danych używanych w naszym systemie. Ich przestrzeganie zapewnia spójność i poprawność działania aplikacji.

1. Formaty Daty i Czasu​

Format ISO 8601 z przesunięciem strefy czasowej (UTC offset)​

Jest to główny format daty i czasu używany w naszych systemach. Zapewnia precyzję i jednoznaczność, uwzględniając strefę czasową.

Przykładowy format: YYYY-MM-DDTHH:mm:ss±HH:mm

Wyjaśnienie elementów:

  • YYYY: Rok (cztery cyfry, np. 2025)
  • MM: Miesiąc (dwie cyfry, np. 03)
  • DD: Dzień miesiąca (dwie cyfry, np. 09)
  • T: Separator daty i czasu (stała litera "T")
  • HH: Godzina (dwie cyfry, 24-godzinny format, np. 13)
  • mm: Minuty (dwie cyfry, np. 37)
  • ss: Sekundy (dwie cyfry, np. 59)
  • ±HH:mm: Przesunięcie strefy czasowej względem UTC (np. +02:00 dla czasu środkowoeuropejskiego, -05:00 dla czasu wschodniego w USA). Znak + oznacza przesunięcie na wschód od UTC, a - na zachód.

Przykład:

2025-03-09T13:37:59+02:00

Powyższy przykład wskazuje, że data to 3 marca 2025, godzina 13:37:59 w strefie czasowej, która jest 2 godziny do przodu względem Coordinated Universal Time (UTC).

2. Formaty Kwot​

Format Decimal​

Wszystkie pola związane z kwotami pieniężnymi są reprezentowane jako typ decimal. Zapewnia to precyzję obliczeń finansowych i eliminuje błędy zaokrągleń charakterystyczne dla liczb zmiennoprzecinkowych.

Charakterystyka:

  • Typ danych: decimal
  • Precyzja: Minimalna precyzja to dwa miejsca po przecinku (dla waluty)
  • Format: Liczba dziesiętna z kropką jako separatorem dziesiętnym (np. 123.45)
  • Zakres: Wartości dodatnie i opcjonalnie ujemne (w zależności od kontekstu)

Przykłady:

  • amount: 100.00 - kwota sto jednostek waluty
  • amount: 1234.56 - kwota tysiąc dwieście trzydzieści cztery jednostki i 56 setnych
  • amount: 0.99 - kwota mniejsza niż jedna jednostka waluty

Ważne uwagi:

  • Nigdy nie używaj typów zmiennoprzecinkowych (float, double) do reprezentacji kwot pieniężnych
  • Zawsze zachowuj co najmniej dwa miejsca po przecinku, nawet dla kwot całkowitych (np. 100.00 zamiast 100)
  • W komunikacji API używaj formatu string dla zachowania pełnej precyzji dziesiętnej

3. Kody Walut​

Standard ISO 4217​

Wszystkie waluty w systemie są reprezentowane za pomocą trzyliterowych kodów zgodnych ze standardem ISO 4217. Standard ten zapewnia jednoznaczność i spójność w reprezentacji walut na całym świecie.

Charakterystyka:

  • Format: Trzyliterowy kod alfabetyczny (np. PLN, EUR, USD)
  • Wielkość liter: Zawsze wielkie litery
  • Standard: ISO 4217
  • Kodowanie: UTF-8

Przykłady popularnych kodów walut:

  • PLN - Polski Złoty
  • EUR - Euro
  • USD - Dolar Amerykański
  • GBP - Funt Szterling
  • CHF - Frank Szwajcarski
  • CZK - Korona Czeska
  • JPY - Jen Japoński

Przykład użycia w JSON:

{
  "amount": "100.00",
  "currency": "PLN"
}

Ważne uwagi:

  • Zawsze używaj trzyliterowych kodów ISO 4217, nigdy symboli walutowych (np. EUR zamiast €)
  • Kody walut są zawsze zapisywane wielkimi literami
  • Nie używaj pełnych nazw walut w komunikacji API (np. PLN zamiast "Polski Złoty")
  • Pełną listę kodów walut można znaleźć na stronie: ISO 4217 Currency Codes

4. Kody Krajów​

Standard ISO 3166-1 alpha-2​

Kody krajów w systemie są reprezentowane za pomocą dwuliterowych kodów zgodnych ze standardem ISO 3166-1 alpha-2. Jest to międzynarodowy standard identyfikacji krajów i terytoriów zależnych.

Charakterystyka:

  • Format: Dwuliterowy kod alfabetyczny (np. PL, US, DE)
  • Wielkość liter: Zawsze wielkie litery
  • Standard: ISO 3166-1 alpha-2
  • Zastosowanie: Adresy, numery telefonów, lokalizacje, podatki

Przykłady popularnych kodów krajów:

  • PL - Polska
  • DE - Niemcy
  • US - Stany Zjednoczone
  • GB - Wielka Brytania

Przykład użycia w JSON:

{
  "customer": {
    "name": "Jan Kowalski",
    "country": "PL",
    "phone": "+48123456789"
  }
}

Ważne uwagi:

  • Zawsze używaj dwuliterowych kodów ISO 3166-1 alpha-2
  • Kody krajów są zawsze zapisywane wielkimi literami
  • Nie używaj pełnych nazw krajów w komunikacji API (np. PL zamiast "Polska")
  • Pełną listę kodów krajów można znaleźć na stronie: ISO 3166 Country Codes

5. Adresy Email​

Format RFC 5322​

Adresy email w systemie muszą być zgodne ze standardem RFC 5322. Jest to podstawowy standard definiujący format adresów poczty elektronicznej.

Charakterystyka:

  • Format: local-part@domain (np. [email protected])
  • Wielkość liter: Małe litery (rekomendowane, chociaż standard dopuszcza wielkie)
  • Maksymalna długość: 254 znaki (cały adres)
  • Dopuszczalne znaki: Litery, cyfry, kropka, myslnik, podkreślnik w części lokalnej

Przykłady poprawnych adresów email:

Przykład użycia w JSON:

{
  "customer": {
    "email": "[email protected]",
    "name": "Jan Kowalski"
  }
}

Ważne uwagi:

  • Zawsze waliduj format adresu email przed zapisaniem w systemie
  • Rekomendowane jest użycie małych liter dla spójności
  • Adresy email są zawsze przesyłane jako string
  • System powinien obsługiwać adresy z międzynarodowymi domenami (IDN)
  • Przed wysłaniem kluczowych informacji zaleca się weryfikację adresu email

6. Numery Telefonów​

Format E.164​

Numery telefonów w systemie muszą być zapisywane zgodnie ze standardem E.164. Jest to międzynarodowy standard numeracji telefonicznej rekomendowany przez ITU-T.

Charakterystyka:

  • Format: +[kod kraju][numer] (np. +48123456789)
  • Znak +: Obowiązkowy prefix
  • Maksymalna długość: 15 cyfr (wliczając kod kraju, bez znaku +)
  • Bez spacji i separatorów: Tylko cyfry po znaku +

Przykłady poprawnych numerów telefonów:

  • +48123456789 - numer polski
  • +491234567890 - numer niemiecki
  • +442012345678 - numer brytyjski
  • +16175551212 - numer amerykański
  • +33123456789 - numer francuski

Przykład użycia w JSON:

{
  "customer": {
    "phone": "+48123456789",
    "country": "PL"
  }
}

Ważne uwagi:

  • Zawsze zapisuj numery w formacie międzynarodowym z prefiksem +
  • Nie używaj spacji, myślników ani nawiasów w zapisie numeru (np. +48123456789 zamiast +48 123 456 789)
  • Numery telefonów są zawsze przesyłane jako string
  • Przed zapisaniem zaleca się walidację formatu i długości numeru
  • Format E.164 ułatwia integracje z usługami SMS i telefonii