[NEWS] Zamówienia - rozszerzymy dane do faktury o numery fakturowe i dodamy informacje o płatniku VAT / Orders - we will expand the invoice data with invoice numbers and add information about the VAT payer

**27 czerwca** rozszerzymy dane do faktury o numery fakturowe i dodamy informacje o płatniku VAT.

**Jakich zasobów dotyczy zmiana?**

Zmiana dotyczy:

- [GET /order/checkout-forms](https://developer.allegro.pl/documentation#operation/getListOfOrdersUsingGET),
- [GET /order/checkout-forms/{id}](https://developer.allegro.pl/documentation#operation/getOrdersDetailsUsingGET).

**Jak jest obecnie?**

Uzupełniony przez kupującego numer podatkowy zwracamy w polu **“invoice.address.company.taxId”**:

```
…
"invoice":{
"required":true,
"address":{
"street":"Grunwaldzka 182",
"city":"Poznań",
"zipCode":"60-166",
"countryCode":"PL",
"company":{
"name":"Allegro",
"taxId":"5252674798"
},
…
```

i różni się w zależności od kraju adresu (**“invoice.address.countryCode”**):

- **“PL”** - poprawny (zwalidowany) NIP: "5252674798",
- **Inne kraje**: ciąg znaków, który nie jest dokładnie walidowany. Dopuszczamy tutaj znaki alfanumeryczne i średnik; Kupujący może więc wpisać tam jeden lub dwa numery do faktury.

**Jakie zmiany wprowadzimy?**

**27 czerwca** wprowadzimy numery fakturowe i informacje o płatniku VAT.

1. W sekcji **“invoice.address.company”** dodamy nową tablicę **“ids”,** w którym zwrócimy następujące pola:

- **“type”** - typ identyfikatora podatkowego; możliwe wartości, które możemy zwrócić:

- PL_NIP,
- CZ_ICO,
- CZ_DIC,
- OTHER,
- **“value”** - wartość identyfikatora podatkowego.

2. W sekcji **“invoice.address.company”** dodamy nowy obiekt **"vatPayerStatus"** - status płatnika VAT, dla którego zwrócimy jedną z trzech możliwych wartości:

- ACTIVE – użytkownik podczas zakupu zadeklarował, że jest aktywnym podatnikiem VAT,
- NON_ACTIVE – użytkownik zadeklarował, że nie jest aktywnym podatnikiem VAT,
- NOT_APPLICABLE – nie dotyczy, np. jeśli użytkownik z Czech nie podał w procesie zakupowym numeru CZ_DIC - opcja deklaracji płatnika VAT nie jest wtedy dostępna.

3. Pole **“invoice.address.company.taxId”** oznaczymy jako **Deprecated** i w przyszłości je **usuniemy**.

**Przykładowy response dla “countryCode”: “PL”:**

```
…
{
"countryCode": "PL",
"company": {
"name": "Allegro",
"ids": [
{
"type": "PL_NIP" - typ identyfikatora podatkowego
"value": "6793094529" - wartość identyfikatora podatkowego.
}
],
"vatPayerStatus": "NOT_APPLICABLE", - możliwe statusy: “ACTIVE” - użytkownik
podczas zakupu zadeklarował, że jest
aktywnym podatnikiem VAT,
“NON_ACTIVE” - użytkownik zadeklarował, że
nie jest aktywnym podatnikiem VAT, “NOT
APPLICABLE” - nie dotyczy, np. jeśli użytkownik
z Czech nie podał w procesie zakupowym
numeru CZ_DIC - opcja deklaracji płatnika VAT
nie jest wtedy dostępna.
"taxId": "6793094529" - obecnie zwracany numer podatkowy -
w procesie zakupowym użytkownik może wprowadzić
więcej niż jeden.
Pole oznaczymy jako deprecated
i w przyszłości je usuniemy.
}
}
…
```
**Przykładowy response dla “countryCode”: “CZ”:**

```
…
{
"countryCode": "CZ",
"company": {
"name": "Firmex",
"ids": [
{
"type": "CZ_ICO"
"value": "02565269"
},
{ // opcjonalnie
"type": "CZ_DIC",
"value": "CZ02565269"
}
],
"vatPayerStatus": "ACTIVE"
"taxId": "IČO 02565269; DIČ CZ02565269"
}
}
…
```

**Ważne!** Dla wszystkich zamówień sprzed wdrożenia zmian, w polu **“invoice.address.company.ids.type”** zwrócimy wartość “OTHER”.

**Dlaczego wprowadzamy zmiany?**

1. Chcemy rozszerzyć nasze API w kontekście obsługi numerów fakturowych dla pozostałych serwisów Allegro, np. **allegro-cz**, w którym regulacje podatkowe są dość specyficzne. Mamy tutaj bowiem dwa numery fakturowe:

- **IČO** – ID firmy,
- VAT **DIČ** – numer do rozliczeń podatkowych, dla płatników VAT.

2. Jednocześnie chcemy zoptymalizować obsługę numerów fakturowych i nie zwracać ich w jednym miejscu, dlatego rozdzielimy je odrębnych polach, w tablicy **“invoice.address.company.ids[]”**.

---------

**On June 27**, we will expand the invoice data to include invoice numbers and add information about the VAT payer.

**What resources are affected by the change?**

The change concerns:

- [GET /order/checkout-forms](https://developer.allegro.pl/documentation#operation/getListOfOrdersUsingGET),
- [GET /order/checkout-forms/{id}](https://developer.allegro.pl/documentation#operation/getOrdersDetailsUsingGET).

**How it works now?**

We return the tax number completed by the buyer in the **“invoice.address.company.taxId”** field :

```
…
"invoice":{
"required":true,
"address":{
"street":"Grunwaldzka 182",
"city":"Poznań",
"zipCode":"60-166",
"countryCode":"PL",
"company":{
"name":"Allegro",
"taxId":"5252674798"
},
…
```
and it varies depending on the country of address (**“invoice.address.countryCode”**):

- **“PL”** - correct (validated) NIP: "5252674798",
- **other countries**: a string that is not thoroughly validated. We allow alphanumeric characters and semicolons here; The buyer can therefore enter one or two invoice numbers there.

**What changes will we introduce?**

**On June 27**, we will introduce invoice numbers and VAT payer information.

1. In the **“invoice.address.company”** section we will add a new array **“ids”**, in which we will return the following fields:

- **“type”** - tax ID type; possible values ​​we can return:

- PL_NIP,
- CZ_ICO,
- CZ_DIC,
- OTHER,
- **“value”** - tax ID value.

2. In the **“invoice.address.company”** section we will add a new object **"vatPayerStatus"** - VAT payer status, for which we will return one of three possible values:

- ACTIVE – during the purchase, the user declared that he or she is an active VAT payer,
- NON_ACTIVE – the user has declared that he or she is not an active VAT payer,
- NOT_APPLICABLE – not applicable, e.g. if a user from the Czech Republic did not provide the CZ_DIC number in the purchasing process - the VAT payer declaration option is then not available.

3. We will mark the **“invoice.address.company.taxId”** field as **Deprecated** and we will remove it in the future.

**Sample response for “countryCode”: “PL”:**

```
…
{
"countryCode": "PL",
"company": {
"name": "Allegro",
"ids": [
{
"type": "PL_NIP" - tax ID type
"value": "6793094529" - tax ID value
}
],
"vatPayerStatus": "NOT_APPLICABLE", - possible statuses: “ACTIVE” - user
during the purchase he declared that it was
active VAT payer,
“NON_ACTIVE” - the user declared that
is not an active VAT payer, “NOT
APPLICABLE” - not applicable, e.g. if user
from the Czech Republic did not specify in the purchasing process
CZ_DIC number - VAT payer declaration option
is then not available.

"taxId": "6793094529" - tax number currently being returned -
in the purchasing process, the user can enter
more than one.
We will mark this field as Deprecated
and we will remove it in the future.

}
}
…
```
**Sample response for “countryCode”: “CZ”:**

```
…
{
"countryCode": "CZ",
"company": {
"name": "Firmex",
"ids": [
{
"type": "CZ_ICO"
"value": "02565269"
},
{ // opcjonalnie
"type": "CZ_DIC",
"value": "CZ02565269"
}
],
"vatPayerStatus": "ACTIVE"
"taxId": "IČO 02565269; DIČ CZ02565269"
}
}
…
```

**Note!** For all orders before the changes were implemented, we will return the "OTHER" value in the **"invoice.address.company.ids.type"** field.

**Why are we making changes?**

1. We want to expand our API in the context of handling invoice numbers for other Allegro websites, e.g. **allegro-cz**, where tax regulations are quite specific. We have two invoice numbers here:

- **IČO** – company ID,
- VAT **DIČ** – tax settlement number for VAT payers.

2. At the same time, we want to optimize the handling of invoice numbers and not return them in one place, so we will separate them in separate fields, in the **"invoice.address.company.ids[]"** array.