Witaj w centrum pomocy Apilo
[API] Tworzenie dokumentu sprzedaży – logika wyboru adresu
Spis treści
Jak system wybiera adres do faktury?
Kluczowe Pola Adresowe Używane w Procesie (Odniesienie do API)
Poniżej opisany został proces automatycznego wyboru adresu do faktury na podstawie dostępnych danych, z odniesieniami do typowej struktury odpowiedzi API. Poznanie tej logiki jest kluczowe dla poprawnego generowania dokumentów sprzedażowych i interpretacji działania systemu.
## Kluczowe Pola Adresowe Używane w Procesie (Odniesienie do API)
System opiera swoje działanie na kilku kluczowych polach adresowych. W odpowiedzi API są to zazwyczaj obiekty JSON.
* **`addressInvoice`**:
* **Dla użytkownika:** Specjalne miejsce na wpisanie adresu, który ma się pojawić na fakturze. Jeśli chcesz, aby faktura trafiła na inny adres niż adres dostawy czy główny adres kontaktowy, tutaj należy go podać.
* **Dla programisty:** W odpowiedzi API jest to obiekt JSON, np. `response.addressInvoice`.
```json
"addressInvoice": {
"name": "Jan Kowalski",
"phone": "+48 500 000 000",
"email": "jan.kowalski@apilo.com",
"streetName": "Testowa",
"streetNumber": "4b/12",
"city": "Kraków",
"zipCode": "31-154",
"country": "PL",
"companyTaxNumber": "937-271-51-54", // NIP jeśli faktura na firmę
"companyName": "Apilo Sp. z o.o." // Nazwa firmy jeśli faktura na firmę
}
```
Jeśli ten obiekt istnieje (nie jest `null`) i zawiera dane (np. nie jest pustym obiektem `{}`), jego zawartość jest używana do faktury. To pole ma najwyższy priorytet.
* **`addressCustomer`**:
* **Dla użytkownika:** Główny adres powiązany z Twoim kontem lub danymi klienta. Może to być adres Twojego zamieszkania lub siedziby firmy. System rozróżnia typ tego adresu.
* **Dla programisty:** W odpowiedzi API jest to obiekt JSON, np. `response.addressCustomer`.
```json
"addressCustomer": {
"name": "Jan Kowalski",
// ... inne pola jak wyżej
"companyTaxNumber": "937-271-51-54",
"companyName": "Apilo Sp. z o.o."
}
```
Logika faktury opiera się na dodatkowym, koncepcyjnym polu `class` (np. `response.addressCustomer.class`), które kategoryzuje typ adresu:
* `”customer”`: Standardowy, ogólny adres klienta.
* `”house”`: Interpretowany jako adres domowy klienta.
* `”company”`: Interpretowany jako adres firmowy klienta.
* **`addressDelivery`**:
* **Dla użytkownika:** Adres, pod który zostanie dostarczony zamówiony produkt lub usługa.
* **Dla programisty:** W odpowiedzi API jest to obiekt JSON, np. `response.addressDelivery`.
„`json
"addressDelivery": {
"name": "Jan Kowalski",
// ... inne pola jak wyżej
"parcelIdExternal": "KRA32B", // Może zawierać dane punktu odbioru
"parcelName": "Paczkomat, ul. Testowa 12 (obok sklepu)"
}
```
Logika Wyboru Adresu do Faktury: Krok po Kroku (Perspektywa Programisty)
Zgodnie z nowymi wytycznymi, system wykorzystuje pole `isInvoice` (znajdujące się na głównym poziomie odpowiedzi API, np. `response.isInvoice`) oraz dostępność obiektu `addressInvoice` do określenia, który adres zostanie użyty na fakturze.
**Główne założenia logiki:**
* Pole `response.isInvoice` (typu boolean) sygnalizuje, czy dla danego zamówienia ma być użyty specyficzny adres do faktury (`addressInvoice`) lub, w przypadku jego braku, adres klienta (`addressCustomer`).
* Jeśli `response.isInvoice` jest `true` i `response.addressInvoice` istnieje i zawiera dane, to właśnie `response.addressInvoice` jest adresem do faktury.
* Jeśli `response.addressInvoice` nie istnieje (jest `null` lub puste), adresem do faktury staje się `response.addressCustomer`. Rola `isInvoice` w tym konkretnym przypadku jest taka, że sygnalizuje ogólną potrzebę wystawienia faktury, a system wybiera najlepszy dostępny adres zgodnie z tą regułą.
**Kroki wyboru adresu (dla programisty):**
1. **Sprawdzenie dedykowanego adresu do faktury (`response.addressInvoice`) w kontekście flagi `isInvoice`:**
* **Warunek:** Jeśli pole `response.isInvoice` ma wartość `true` ORAZ obiekt `response.addressInvoice` istnieje i zawiera dane (np. nie jest `null` i nie jest pustym obiektem `{}`).
* Np. w JavaScript:
```javascript if (response.isInvoice === true && response.addressInvoice && Object.keys(response.addressInvoice).length > 0) ```
* **Działanie:** Adresem do faktury jest zawartość obiektu `response.addressInvoice`.
2. **Użycie adresu klienta (`response.addressCustomer`) jako podstawowego lub fallbacku:**
* **Warunek:** Jeśli powyższy warunek (użycia `response.addressInvoice`) nie jest spełniony, czyli:
* `response.addressInvoice` nie istnieje lub jest pusty (niezależnie od flagi `isInvoice`, jeśli celem jest zawsze wybranie *jakiegoś* adresu, gdy faktura jest potrzebna), LUB * `response.isInvoice` jest `false` (w tym scenariuszu, jeśli `isInvoice` = `false` oznacza „użyj `addressCustomer` do faktury”, a nie „nie generuj faktury” – to wymagałoby potwierdzenia).
* **Działanie:** Adresem do faktury jest zawartość obiektu `response.addressCustomer`.
* Np. w JavaScript (jako część instrukcji `else` do powyższego `if`):
```javascript
else if (response.addressCustomer) {
// Użyj response.addressCustomer
}
```
**Uproszczony schemat decyzji :**
1. Czy `response.addressInvoice` istnieje i zawiera dane?
* **TAK:**
* Czy `response.isInvoice` jest `true`?
* **TAK:** Użyj `response.addressInvoice`.
* **NIE:** (Zachowanie nie w pełni zdefiniowane przez ostatni opis – czy użyć `addressCustomer`, czy nie fakturować specyficznie? Bazując na „dane do faktury są wybierane po polu isInvoice, który określa, który adres powinien być wybrany”, jeśli `isInvoice` jest `false`, to `addressInvoice` nie jest tym „wybranym adresem”. Prawdopodobnie system przechodzi do `addressCustomer` lub nie generuje faktury z tymi danymi). Dla spójności z drugim warunkiem, jeśli `isInvoice` jest `false`, `addressInvoice` nie jest używany, a system powinien sprawdzić `addressCustomer` jeśli faktura ma w ogóle powstać.
* **NIE (`response.addressInvoice` jest `null` lub puste):**
* Użyj `response.addressCustomer`.
Nadal potrzebujesz pomocy?
Porozmawiaj z konsultantem
