API Specifikace

Nákupní API pro Distributory

Changelog

1.0.0

  • První revize

1.0.1

  • Doplněny specifické 401 a 403 response
  • Doplněno zrušení objednávky časového poplatku do 15 minut

1.0.2

  • Vymazány všechny informace o evidenci v systému elektronického mýta
  • Do výzvy k úhradě doplněno nepovinně číslo účtu SFDI, SS, KS, 4x 100 znaků zpráva pro příjemce
  • Z výzvy k fakturaci provize odstraněny informace o zpracování faktury na straně SFDI
  • invoiceID přejmenováno commissionPaymentId

1.0.3

  • Odstraněn endpoint se seznamem obchodních případů Distributora
  • Odstraněn endpoint pro ověření potvrzení o úhradě časového poplatku

1.1.0

  • Drobné změny v textaci po interní revizi
  • Doplněn seznam kurzů jako samostatný endpoint
  • Doplněno SalesPointId do vstupu objednávky a kontrolu
  • Doplněn typ platby (ze statistických důvodů)
  • Změna cancelCode na changeCode a změna logiky (nelze stornovat, lze pouze provést změnu do 15 minut)

1.2.0

  • Změny v cestách camelCase na snake_case
  • Změny v pojmenování X-Api-Token na Api-Token (RFC2616 Compliance)
  • Změny v pojmenování X-Retry-After na Retry-After (RFC2616 Compliance)
  • Vyhozeny prefixy X-HMAC- z autorizačních hlaviček (RFC6648 Compliance)
  • Seznam kurzů nahrazen Cenovým výměrem pro úhradu časového poplatku v cizí měně
  • Zavedena logika createOrdersubmitOrderchangeOrder
  • Doplněna podrobnější dokumentace
  • Odstraněn validační regulární výraz na formát SPZ
  • Odstraněn typ platby
  • Přejmenován changeCode na authCode
  • Odstraněn notificationCode, protože se pro oba účely použije authCode
  • Doplněn přehled odstávek getOutages (nad rámec zadání, po interní konzultaci)

1.2.1

  • Změna typu code v chybových objektech

1.3.0

  • Přidána metoda getPaymentVolume pro zjištění objemu úhrad časových poplatků od významného data (výročně)

1.4.0

  • Úprava textace createOrder, resp. reqOrderAllocateObject
  • Úprava textace createOrder a submitOrder lépe vysvětlující chování při překryvu úhrad více časových poplatků pro stejnou SPZ
  • Změna formátu data If-Modified-Since (RFC7232 Compliance)
  • Modifikace popisu getPaymentVolume, pojem významné datum není smluvně zakotven
  • Modifikace createPaymentRequest změna logiky na denní generování výzev k úhradě
  • Generální změna textace výzva k úhraděvýzva k provedení platby objemu úhrad
  • Odebrána metoda getOutages poskytující informace o odstávkách
  • Změna getCreditLimitgetCreditExposure související s otočením logiky
  • Přetextování souvisejících objektů

1.4.1

  • Kosmetické změny typu uhrazený časový poplatekprovedená Úhrada časového poplatku

1.4.2

  • Změna z 28. v měsíci na ultimu měsíce (resp. poslední den v měsíci) pro generování řádných výzev k úhradě

1.4.3

  • Doplnění u mimořádné výzvy, že nelze dát požadavek na na den kdy jsou vystavovány řádné výzvy k úhradě

1.5.0 [ MD5 sum: 9e50d98dd45bcbd42c0e7d787dd4f954 ]

  • Masivní změna getCommissions na základě změn smlouvy mezi SFDI a distributorem
  • Přidán metadata objekt pro stránkování vybraných seznamů

1.5.1 [ MD5 sum: 132558746bbc50668c7ac444b9b971c8 ]

  • Fix: Přejmenování vstupu getCommissions amountdate

1.5.2 [ MD5 sum: 1bacc5cbb2125e23810f8285220ee996 ]

  • Fix: Změna datového typu PaymentRequestIdentifierConst

1.5.3 [ MD5 sum: 8a05cba3a11d0ced3ab30bd3923a7a7d ]

  • Fix: Odstranění redundantního id ze struktury ChargeObject

1.5.4 [ MD5 sum: 10e4f2976bd493acdab799936d09506d ]

  • Fix: Opravy textů a hlaviček u error response

1.5.5 [ MD5 sum: 800d4038e54d9febb6399b3fc783452b ]

  • Zrušen nepoužitelný atribut ChargeObject.description

1.5.6 [ MD5 sum: 5f8bd330f0b2ead94c33f05b44802d48 ]

  • Doplněny detailní chybové kódy

1.5.7 [ MD5 sum: c1c7d064370bf64c14415ca9adc685f5 ]

  • Nelze provést změnu changeOrder z jiného obchodního místa, salesPointId doplněno do objektu InboundPOChangeItem
  • Zkrácen authCode na 7 znaků
  • Lze provést změnu SPZ a platnosti do 15 minut, změna textace u changeOrder, doplnění parametru validSince

1.6.0 [ MD5 sum: ea0102c28c46592612684824b91955b6 ]

  • Přidán komponent EngineTypePrice
  • Přidán komponent ChargeValidity, převzán z e-shop API
  • Odstráněn atribut description z objektu ChargeObject
  • Odstráněn atribut price z objektů PriceList a ChargeObject
  • Přidáno pole prices do objektů PriceList a ChargeObject
  • Oprava názvu BIO_METHAN na BIO_METHANE
  • Úprava názvu atributů since a until v objektu PriceList na validSince a validUntil
  • Změnen atribut [int] validityDays na [ChargeValidity] validFor v objektu ChargeObject

2.0.0

  • přidán číselník countries /api/v2/enums/countries - všude komunikováno countryId

  • přidané verzování API do URL- přejmenování routes (z důvodu jednotnosti a RESTful principů):

    1. /codelists/charges -> ​/api​/v2​/enums​/charge_types
    2. /codelists/price_list/{targetCurrency} -> /api/v2/enums/price_list/{target_currency}
    3. /orders​/create -> /api/v2/charge_orders
    4. /orders/submit -> /api/v2/charge_orders/payment_confirmations
    5. /orders/{orderIdent} -> /api/v2/charge_orders/{country_id}/{license_plate}
  • změna metody u /orders/{orderIdent} z POST na PUT

  • odebraná dokumentace statusu 500 (není vhodné dokumentovat)

  • odebrán status 429 - bude se vracet z proxy, formát není znám

  • změněn plaintext návratový typ u 401, 403 na lépe zpracovatelné 4xx application/json responses

  • klientské chyby zavřené pod status kód 400 -> odebraná 304, 402, 405, místo toho přidány nové hodnoty pro type ve vraceném error objektu (např. VEHICLE_CHANGE_NOT_ALLOWED)- lower snakecase naming použit na všech query string parametrech

  • aktualizován popis VALID_SINCE_INVALID (doplněna informace o rozsahu 0-90 dnů)

  • přejmenování query string parametrů:

    1. includeObsoleted -> include_invalid
    2. onlyOpen -> only_unsettled
  • všechen request a response payload má nyní obalující typ, nikde se neposílá ani nevrací přímo array

  • změny parametrů:

    1. licensePlate zanořena pod objekt vehicle
    2. názvy hlavních kolekcí změněny na “items”
    3. změněny typy 4xx chybových schémat
    4. do GET /api/v2/finance/commissions přidán “lastDayDate”
    5. do GET /api/v2/finance/payment_requests přidán “lastDayDate” dle včerejšího dotazu
    6. v POST /api/v2/finance/payment_requests přejmenován “date” na “lastDayDate”
    7. vSymbol, sSymbol, cSymbol -> přejmenováno na “variableSymbol”, “specificSymbol” a “constantSymbol”
    8. přejmenování transferMsg -> message
    9. přejmenování orderIdent -> orderId
    10. změny 409 typu u createOrder -> přidán validUntil - nejdéle v budoucnosti z překrývajících se poplatků, licensePlate zanořen pod vehicle
    11. změny 409 typu u submitOrder -> licensePlate zanořen pod vehicle
    12. změny 409 typu u changeOrder
    13. currency, currency_code sjednoceno -> zůstalo pouze currency_code
    14. engineType -> fuelType
    15. salesPointId -> salespointId
    16. změna bankAccount requirementu z optional na required
    17. změna bankAccount maximální délky na formát IBAN (34 znaků)
  • přidán číselník pohonů /api/v2/enums/fuel_types

  • do submitOrder response přidán required parametr validUntil

  • přidáno potvrzení o změně do odpovědi /api/v2/charge_orders/{country_id}/{license_plate}

  • 409 obsahují seznam všech překryvů s osvobozeními i poplatky

  • přidáno externalId

  • změna message requirementu z optional na required

  • přidán nový error typ do POST /api​/v2​/charge_orders​/payment_confirmations ORDER_EXPIRED - objednávka expirovala

  • salespointId přidán do POST /api​/v2​/charge_orders

  • salespointId přesunut do root v request payloadu u POST /api​/v2​/charge_orders​/payment_confirmations

  • přídány nové error response typy v rámci POST /api​/v2​/charge_orders - SALESPOINT_INACTIVE, SALESPOINT_UNKNOWN

  • změna error response typů u POST /api​/v2​/charge_orders​/payment_confirmations, odebrané typy: SALESPOINT_INACTIVE, SALESPOINT_UNKNOWN, přidán typ: SALESPOINT_MISMATCH

  • změna error response typů u PUT /api​/v2​/charge_orders​/{country_id}​/{license_plate}, odebraný typ:SALESPOINT_UNKNOWN

  • přidání parametru If-Modified-Since do GET /api​/v2​/enums​/fuel_types

  • přidání cache control, conditional hlaviček do odpovědí cachovatelných žádostí, přidání etagu a If-None-Match optional parametru

  • validace výše volného zajištění a chybový stav PAYMENT_REQUIRED přidán do 400 stavů v rámci submitOrder

  • přidány nové error response typy v rámci POST /api/v2/finance/payment_requests - PAYMENT_REQUEST_NO_AMOUNT_AVAILABLE, PAYMENT_REQUEST_INVALID_DATE a PAYMENT_REQUEST_ALREADY_EXISTS

  • doplěno possibleExemption pro případy, kdy je detekováno možné osvobození dle SPZ a distributor na něj musí upozornit

2.0.1

  • opraven číselník PossibleExemptionReason - přidány hodnoty C, P
  • úprava vyžadované délky telefonního čísla

2.1.0

  • v endpointech submitOrder, getOrderPaymentConfirmations a changeOrder doplněn do response objekt payment s informací o ceně a měně, které se budou tisknout na potvrzení
  • změna v cestách pro zmíněné tři endpointy /api/v2 -> /api/v2.1

2.2.0

  • v endpointu getFuelTypes doplněna lokalizace
  • doplněny validSince a validUntil do objektu položky číselníku časových poplatků ChargeObject pro určení rozsahu začátku platnosti časového poplatku v createOrder
  • změna v cestách pro zmíněné endpointy /api/v2 -> /api/v2.2

2.3.0 produkční API

  • zrušeno předávání písmena osvobození v
    • submitOrder
    • createOrder
    • getOrderPaymentConfirmations
  • omezen formát vstupu objektů LicensePlate a ExternalId
  • opraven regex pattern u objektu PhoneNumber
  • formát licensePlate ve VehicleObj změnen na referenci

2.4.0 návrh

  • endpoint changeOrder nově umožňuje měnit časový poplatek na libovolném obchodním místě. Zůstává zachován neomezený počet změn v časovém okně 15 minut od okamžiku úhrady na stejném obchodním místě, po jeho skončení je možna maximálně jedna změna SPZ a jedna změna počátku platnosti.
  • v endpointu changeOrder rozdělen stav CHARGE_CHANGES_EXCEEDED na CHARGE_VALIDITY_CHANGES_EXCEEDED a CHARGE_VEHICLE_CHANGES_EXCEEDED
  • upraven popis InboundPOChangeItem
  • srovnání návratových kódů v resBadRequestChangeOrder dle konvence