# Integracje kurierskie

Ta część dokumentacji poświęcona jest opisem działania integracji z poszczególnymi serwisami kurierskimi

- [DHL PL](<#>)
- [DHL Express](<https://docs.logintegra.com/apollo-backend/11. Couriers integration/dhl-express/index.md>)
- [TNT Express](<https://docs.logintegra.com/apollo-backend/11. Couriers integration/tnt/index.md>)

## Uzyskanie wycen kurierów

### Flagi

1. Uzyskaj ceny kurierów -\> `shouldGetCourierQuotesByDefault`.

   Label PL: Domyślnie uzyskaj wyceny kurierów Label EN: Get courier quotes by default Flaga ta określa domyślną wartość pola "Uzyskaj wyceny kurierów" → "TAK" lub "NIE"
2. Widoczność pola "Uzyskaj wyceny kurierów". -\> `isGetCourierQuotesFieldVisibility`

   Label PL: Widoczność pola "Uzyskaj wyceny kurierów" Label EN: Visibility of the field "Get courier quotes" Flaga ta określa czy w formularzu tworzenia zlecenia pojawi się pole "Uzyskaj wyceny kurierów"

Flagi dostępne są w typie transportu w zakładce "Ustawienia kurierskie": !['Nie znaleziono zdjęcia'](<https://docs.logintegra.com/apollo-backend/static/Couriers integration/couriers-settings-tab.png>) Ustawienia możemy tworzyć nowe lub usunąć już istniejące: !['Nie znaleziono zdjęcia'](<https://docs.logintegra.com/apollo-backend/static/Couriers integration/couriers-settings.png>)

### Obowiązkowość pól

#### Ze względu na wartość w polu "Uzyskaj wyceny kurierów":

| Opcja TAK | Opcja NIE |
| --- | --- |
| pola związane z integracją z kurierami powinny być obowiązkowe | pola związane z integracją z kurierami powinny być nieobowiązkowe |

Po wybraniu opcji "TAK" w "Uzyskaj wyceny kurierów" powinniśmy walidować to, że:

- w sekcji opakowań jest dodana przynajmniej jedna paczka (paczki są w [A-5911](<https://youtrack.logintegra.com/issue/A-5911>)),
- musi być dokładnie jedno miejsce załadunku i dodkłanie jedno miejsce rozładunku,
- w przypadku przynajmniej jednego kraju spoza UE obowiązkowe muszą być pola Wartość towaru, Waluta, Incoterms.

**Uwaga:**  
Po zapisaniu transportu z wartością "TAK" w polu "Uzyskaj wyceny kurierów", te pole nie powinno być możliwe do edycji

### Domyślna waluta i incoterms

Ustawienia kurierskie typu transportu mają dwa pola z wartościami domyślnymi dla sekcji Kurierzy. Oba pola są opcjonalne i działają niezależnie od siebie.

| Pole w `CourierSetting` | Label PL | Słownik |
| --- | --- | --- |
| `defaultGoodsValueCurrency` | Domyślna waluta wartości towaru | symbole walut z tabeli `currency` |
| `defaultIncoterms` | Domyślna wartość pola incoterms | lista `incoterms` w `enum-service` frontendu |

Frontend wpisuje te wartości w pola `goodsValueCurrency` i `incoterms` nowego zlecenia. Robi to przy tworzeniu zlecenia z typu transportu, z trasy i z panelu planowania. Puste pole w ustawieniach zostawia odpowiednie pole zlecenia puste. Użytkownik może zmienić obie wartości przed zapisem zlecenia i po nim.

Wartości domyślne nie trafiają do zleceń tworzonych przez API. Opcja "Utwórz podobne" kopiuje walutę i incoterms ze zlecenia źródłowego. Zmiana ustawień typu transportu nie zmienia zleceń już utworzonych.

Przy zleceniu z trasy, która ma walutę, pierwszeństwo ma waluta z trasy \[[A-18130](<https://youtrack.logintegra.com/issue/A-18130>)\]. Domyślny incoterms działa w takim zleceniu bez zmian.

Wartości obowiązują dla wszystkich zleceń typu, bez względu na kraj załadunku i rozładunku. Typ z dostawami krajowymi i z UE ma więc jedną wspólną wartość.

## Osoby kontaktowe

W ramach integracji kurierskich dodaliśmy nowe pola w formularzu, które przedstawiają:

- Osobe kontaktową na załadunku,
- Numer telefonu osoby kontaktowej na załadunku,
- Osobe kontaktową na rozładunku,
- Numer telefonu osoby kontaktowej na rozładunku.

### Wyświetlanie pól

Pola wyświetlamy w formularzu przy stepach załadunku oraz rozładunku. !['Nie znaleziono zdjęcia'](<https://docs.logintegra.com/apollo-backend/static/Couriers integration/contact-person-form.png>)

### Konfiguracja pól

Dodaliśmy dwie nowe flagi w typie transportu: 1. Wyświetlanie pól osoba kontaktowa i numer telefonu osoby kontaktowej -\> `isContactDetailsFieldsVisible`

```
Label PL: Widoczność pól osoba kontaktowa, numer telefonu osoby kontaktowej w formularzu zlecenia
Label EN: Visibility of the fields - contact person, telephone number of the contact person in the order form
```

2. Obowiązkowość pól przy tworzeniu zlecenia -\> `isContactDetailsFieldsRequired`

   Label PL: Obligatoryjność pól osoba kontaktowa, numer telefonu osoby kontaktowej Label EN: Fields obligatory - contact person, telephone number of the contact person

Flagi możemy edytować na froncie (Typ transportu -\> Ustawienia typu transportu) w sekcji "Ustawienia związane z formularzem transportu".

### Uprawnienia

Edycja tych pól jest podpięta pod uprawnienie do edycji pól danego typu transportu - `Edycja głównych pól transportu`.

### Obowiązkowość pól osoba kontaktowa i telefon

1. Obowiązkość pól w momencie tworzenia zlecenia. Jeżeli user oznaczy ustawienie obowiązkowości już przy tworzeniu zlecenia, to pola będą obowiązkowe już przy tworzeniu.
2. Obowiązkowość pól przy próbie przekazania do kuriera. Te pola zawsze są obowiązkowe przy próbie przekazania zlecenia do kuriera

## Automatyczne potwierdzanie statusów na podstawie trackingu

U pryncypałów, którzy mają skonfigurowanych kurierów automatycznie, potwierdzają się statusy po odebraniu oraz dostarczeniu przesyłki przez kuriera.

### Konfiguracja

Dodaliśmy dwie nowe flagi przy statusach:

1. Automatyczne potwierdzenie statusu po odbiorze przez kuriera -\> `confirmCheckpointAfterCourierPickup`
2. Automatyczne potwierdzenie statusu po dostarczeniu przez kuriera -\> `confirmCheckpointAfterCourierDelivered`

Flagi możemy włączyć na froncie przy dowolnym statusie: !['Nie znaleziono zdjęcia'](<https://docs.logintegra.com/apollo-backend/static/Couriers integration/new-tasks-flags.png>)

**Uwaga:**  
Dla zachowania odpowiedniego działania pamiętaj, aby włączyć ustawienie "Określa, czy można potwierdzać statusy poza kolejnością": !['Nie znaleziono zdjęcia'](<https://docs.logintegra.com/apollo-backend/static/Couriers integration/out-of-order-setting.png>)

### Kiedy potwierdzamy dany status

Po zamówieniu kuriera dla danego zlecenia, w mikroserwisie kurierskim zaczynamy cykliczne odpytywanie serwisu kurierskiego o tracking paczki. W zależności od otrzymanego statusu paczki z trackingu kuriera, potwierdzony zostanie odpowiednio przyporządkowany status w apollo do flagi:

1. Status z flagą `confirmCheckpointAfterCourierPickup` Status otrzymany z trackingu to `PU` -\> odbiór paczki przez kuriera
2. Status z flagą `confirmCheckpointAfterCourierDelivered` Status otrzymany z trackingu to `OK` -\> dostarczenie paczki przez kuriera
