[NEWS] Dostosujemy Allegro API do Pakietu eCommerce VAT / We will adapt Allegro API to the VAT e-commerce package

[AureliuszBrussy]

1 lipca 2021 Unia Europejska wprowadza Pakiet eCommerce VAT. Dlatego za część transakcji między przedsiębiorcami a konsumentami (B2C) na platformach elektronicznych, sprzedający spoza Unii Europejskiej będą się rozliczać na nowych zasadach. Więcej na ten temat dowiesz się w informacjach dla sprzedających.

W związku z tym, od 19 maja wprowadzimy nowy zasób:

• GET /sale/tax-settings?category.id={categoryId} - pobierz wszystkie ustawienia VAT dostępne we wskazanej kategorii. Na podstawie otrzymanej listy możesz skonfigurować ustawienia podatku VAT dla ofert sprzedającego wystawionych w danej kategorii.

Przykładowy request:

curl -X GET \
‘https://api.allegro.pl/sale/tax-settings?category.id=316194’ \
-H ‘Authorization: Bearer {token}’ \
-H ‘accept: application/vnd.allegro.public.v1+json’

Przykładowy response:

{
  “settings”: [                                         – lista dostępnych ustawień we
                                                        wskazanej w żądaniu kategorii
    {
      “id”: “f40ae51c-70a2-4882-98a7-6272404f0ec5”,     – identyfikator niezmiennego
                                                        stawienia podatku VAT
      “rate”: {                                         – obiekt reprezentujący stawkę
                                                        podatku VAT przypisaną do tego
                                                        ustawienia
        “id”: “OUT_OF_SCOPE_OF_VAT”,                    – identyfikator stawki VAT, w
                                                        zależności od kategorii
                                                        dostępne wartości to:
                                                        23.00, 8.00, 5.00, EXEMPT,
                                                        OUT_OF_SCOPE_OF_VAT.
                                                        Możemy rozszerzyć słownik
                                                        dostępnych wartości.
        “name”: “Out of scope of VAT”                   – nazwa stawki VAT
      },
      “subject”: {                                      – obiekt reprezentujący
                                                        przedmiot opodatkowania
                                                        przypisany do tego ustawienia
        “id”: “GOODS”,                                  – identyfikator przedmiotu
                                                        opodatkowania
        “name”: “Goods”                                 – nazwa przedmiotu
                                                        opodatkowania
      },
      “exemption”: {                                    – obiekt reprezentujący
                                                        zwolnienie z opodatkowania
                                                        przypisane temu ustawieniu
        “id”: “MPV”,                                    – identyfikator zwolnienia
        “name”: “MPV (multi-purpose voucher)”           – nazwa zwolnienia
      }
    }
    …
  ]
}

Ważne! W poszczególnych kategoriach dostępne ustawienia VAT mogą się różnić. Dlatego sprawdzaj, jakie stawki VAT są dla danej kategorii dostępne.

Równocześnie rozszerzymy obiekt tax o nowe pola na zasobach:

• /sale/offers,
• /sale/product-offers.

Nowe pola to:

• tax.id - identyfikator niezmiennego ustawienia podatku VAT,
• tax.rate - stawka podatkowa,
• tax.subject - przedmiot opodatkowania,
• tax.exemption - zwolnienie z opodatkowania.

Ważne! Aby wprowadzać ustawienia VAT wciąż możesz korzystać z pola tax.percentage, jednak w przyszłości całkowicie usuniemy to pole. Po wskazaniu stawki VAT w polu tax.percentage przypiszemy do oferty odpowiednie dla kategorii ustawienia VAT.

Aby wprowadzić lub zmienić ustawienia VAT w ofercie:

• przekaż odpowiednią kombinację wartości pól tax.rate, tax.subject oraz tax.exemption, na podstawie których znajdziemy identyfikator pasującego ustawienia. W przypadku braku dopasowania zwrócimy błąd walidacji z informacją, które pola powinny zostać uzupełnione lub komunikatem o całkowitym braku dopasowania.

Przykładowy request:

curl -X PUT
‘https://api.allegro.pl/sale/offers/9531382307’ \
-H ‘Authorization: Bearer {token}’ \
-H ‘Accept: application/vnd.allegro.public.v1+json’ \
-H ‘Content-Type: application/vnd.allegro.public.v1+json’ \
-d ’
{
    “id”: “9531382307”,
    “name”: “Oferta testowa”,
    “category”: {
        “id”: “257150”
},
…
  “tax”: {
    “rate”: “23.00”,
    “subject”: “GOODS”,
    “exemption”: “MONEY_EQUIVALENT”
  }
…
}’

Przykładowy response:

{
    “id”: “9531382307”,
    “name”: “Oferta testowa”,
    “category”: {
        “id”: “257150”
},
…
  “tax”: {
    “id”: “f40ae51c-70a2-4882-98a7-6272404f0ec5”,
    “rate”: “23.00”,
    “subject”: “GOODS”,
    “exemption”: “MONEY_EQUIVALENT”,
    “percentage”: “23.00”
  }
…
}

• w polu tax.id przekaż identyfikator ustawienia VAT pozyskany dzięki GET /sale/tax-settings?category.id={categoryId}.

Przykładowy request:

curl -X PATCH \
‘https://api.allegro.pl/sale/product-offers/9531382307’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v2+json' \
-H 'Content-Type: application/vnd.allegro.beta.v2+json' \
-d ’
{
  "tax": {
    "id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”
  }
}’

Przykładowy response:

{
    “id”: “9531382307”,
    “name”: “Przykładowy produkt”,
    “product”: {
        “id”: 5902719471797
    },
    …
  “tax”: {
    “id”: “f40ae51c-70a2-4882-98a7-6272404f0ec5”,
    “rate”: “23.00”,
    “subject”: “GOODS”,
    “exemption”: “MONEY_EQUIVALENT”,
    “percentage”: “23.00”
  }
…
}

Więcej informacji o pakiecie eCommerce VAT znajdziesz na stronie dla sprzedających.

---

On July 1st, 2021 the European Union is introducing the VAT e-commerce package. Therefore, for part of business-to-consumer (B2C) transactions on electronic platforms, sellers from outside the European Union will settle under the new rules. Read more about this in the information for sellers.

Therefore, from May 19th, we will introduce a new resource:

• GET /sale/tax-settings?category.id={categoryId} - get all VAT settings available in the given category. Based on the list you receive, you can configure the VAT settings for the seller's offers listed in a given category.

Sample request:

curl -X GET \
‘https://api.allegro.pl/sale/tax-settings?category.id=316194’ \
-H ‘Authorization: Bearer {token}’ \
-H ‘accept: application/vnd.allegro.public.v1+json’

Sample response:

{
  "settings": [                                         -- a list of tax settings in given
                                                        category
    {
      "id": "f40ae51c-70a2-4882-98a7-6272404f0ec5",     -- a unique identifier of an
                                                        immutable VAT setting
      "rate": {                                         -- an object representing VAT tax
                                                        rate assigned to this setting
        "id": "OUT_OF_SCOPE_OF_VAT",                    -- a unique identifier of a rate,
                                                        depending on the category, the
                                                        available values are:
                                                        23.00, 8.00, 5.00, EXEMPT,
                                                        OUT_OF_SCOPE_OF_VAT.
                                                        We can extend the dictionary 
                                                        of available values
        "name": "Out of scope of VAT"                   -- name for a VAT rate
      },
      "subject": {                                      -- an object representing a
                                                        subject of taxation assigned to
                                                        this setting
        "id": "GOODS",                                  -- a unique identifier of a subject 
        "name": "Goods"                                 -- name for a subject
      },
      "exemption": {                                    -- an object representing a 
                                                        exemption of taxation assigned
                                                        to this setting
        "id": "MPV",                                    -- a unique identifier of an
                                                        exemption
        "name": "MPV (multi-purpose voucher)"           -- name for an exemption
      }
    }
    ...
  ]
}

Note! In each category, the available VAT settings may differ. Therefore, check what VAT rates are available for the given category.

At the same time, we will extend the tax object with new fields on resources:

• /sale/offers,
• /sale/product-offers.

The new fields are:

• tax.id - the unique identifier of an immutable VAT setting,
• tax.rate - the tax rate,
• tax.subject - the subject of taxation,
• tax.exemption - the exemption of taxation.

Note! You can still use the tax.percentage field to enter VAT settings, but in the future we will remove this field entirely. After entering the VAT rate in the tax.percentage field, we will assign to the offer VAT settings appropriate for the category.

To enter or change the VAT settings in the offer:

• pass the appropriate combination of values for the tax.rate, tax.subject and tax.exemption fields, based on which we find the identifier of the matching VAT setting. If there is no match, we will return a validation error with information about which fields should be filled or a message that there is no match at all.

Sample request:

curl -X PUT
‘https://api.allegro.pl/sale/offers/9531382307’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d ’
{
    "id": "9531382307",
    "name": "Test offer",
    "category": {
        "id": "257150"
},
...
  "tax": {
    "rate": “23.00”,
    "subject": “GOODS”,
    "exemption": “MONEY_EQUIVALENT”
  }
…
}’

Sample response:

{
    "id": "9531382307",
    "name": "Test offer",
    "category": {
        "id": "257150"
},
...
  "tax": {
    "id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”,
    "rate": “23.00”,
    "subject": “GOODS”,
    "exemption": “MONEY_EQUIVALENT”,
    "percentage": “23.00”
  }
...
}

• in the tax.id field, pass the VAT setting ID obtained by GET /sale/tax-settings?category.id={categoryId}.

Sample request:

curl -X PATCH \
‘https://api.allegro.pl/sale/product-offers/9531382307’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.beta.v2+json' \
-H 'Content-Type: application/vnd.allegro.beta.v2+json' \
-d ’
{
  "tax": {
    "id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”
  }
}’

Sample response:

{
    "id": "9531382307",
    "name": "Sample product",
    "product": {
        "id": 5902719471797
    },
    …
  "tax": {
    "id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”,
    "rate": “23.00”,
    "subject": “GOODS”,
    "exemption": “MONEY_EQUIVALENT”,
    "percentage": “23.00”
  }
...
}

You can read more about the VAT e-commerce package on the for sellers page.

[alekskuc]

Dzień dobry, @AureliuszBrussy proszę o dodanie zmian dla VAT e-commerce do dokumentacji https://developer.allegro.pl/swagger.yaml

[AureliuszBrussy]

@alekskuc zaktualizujemy dokumentację zaraz po wdrożeniu funkcjonalności na produkcji.

[AureliuszBrussy]

@alekskuc aktualizowaliśmy dokumentację.