API pro předplatné sledovacích čísel Advanced Integrated Visibility (AIV) umožňuje předplatitelům Advanced Integrated Visibility přidružit sledovací čísla k projektu webhooku AIV pomocí koncových bodů API. Funkce přidružení sledovacího čísla podporuje dvě metody zpracování:

• Přidružení sledovacího čísla – synchronní vrací výsledky zpracování ve stejné odpovědi HTTP. Tato možnost je nejvhodnější pro aplikace, které vyžadují okamžité potvrzení při přidružení menšího počtu sledovacích čísel. 
• Přidružení sledovacího čísla – asynchronní odešle požadavek ke zpracování na pozadí a vrátí ID úlohy, které lze později použít k načtení stavu zpracování a výsledků. Tato možnost je nejvhodnější pro zpracování větších dávek sledovacích čísel. 

Vyberte metodu zpracování, která nejlépe splňuje požadavky vaší aplikace na výkon a pracovní zátěž.

Poznámka:

• Pro svůj projekt Advanced Integrated Visibility musíte mít oprávnění správce nebo přispěvatele
• Další informace o službě Advanced Integrated Visibility a jejích funkcích uvádí stránka dokumentace Advanced Integrated Visibility.

Rozhraní API předplatného sledovacích čísel Advanced Integrated Visibility nabízí následující výhody:

• Pomocí API koncových bodů můžete snadno přidružovat, aktualizovat a spravovat sledovací čísla svého projektu Advanced Integrated Visibility.
• Můžete přidružit více sledovacích čísel k jednomu požadavku API místo toho, abyste zpracovávali každé sledovací číslo zvlášť.
• Vyberte mezi synchronním zpracováním pro okamžité výsledky nebo asynchronním zpracováním pro větší dávkové operace.

K správě vašeho projektu Advanced Integrated Visibility použijte níže uvedené koncové body:

• Přidružení sledovacího čísla – synchronní: umožňuje přidružit sledovací čísla k webhooku a přijímat konečný stav zpracování v rámci stejné odpovědi HTTP.
• Přidružení sledovacího čísla – asynchronní: umožňuje přidružit sledovací čísla k webhooku a později použít vrácenou hodnotu jobId ke kontrole stavu asynchronní úlohy nebo ke stažení podrobností pomocí souvisejících koncových bodů:    
  • Stav úlohy podle sledovacího čísla
  • Detaily úlohy podle sledovacího čísla

Tato rozhraní API jsou k dispozici v přehledu projektu Advanced Integrated Visibility.

K těmto rozhraním API lze přistupovat pouze prostřednictvím přehledu projektu, jak je znázorněno na výše uvedeném snímku obrazovky.

Následující tabulka shrnuje rozdíly mezi synchronními a asynchronními koncovými body přidružení sledovacích čísel.
 

Synchronní koncový bod použijte, pokud potřebujete okamžité potvrzení pro menší dávky sledovacích čísel. Asynchronní koncový bod použijte při zpracování větších dávek, které nevyžadují okamžitou odpověď.

Tento koncový bod slouží k přidružení jednoho nebo více sledovacích čísel k projektu webhooku Advanced Integrated Visibility a k přijetí výsledků zpracování v rámci stejné odpovědi HTTP.

Tento koncový bod je určen pro aplikace, které vyžadují okamžité potvrzení, a podporuje požadavky obsahující až 150 sledovacích čísel.

Požadovaný vstup: 

• subscriptionID
• trackingNumber

Výhody

Synchronní koncový bod nabízí následující výhody:

• Okamžité výsledky zpracování
• Podrobné informace o úspěchu a neúspěchu v jedné odpovědi
• Podpora až 150 sledovacích čísel na jeden požadavek
• Vyžádání ověření a vynucení obchodních pravidel před zpracováním
• Strojově čitelné chybové kódy a popisné chybové zprávy
• ID transakcí pro sledování požadavků a řešení problémů

Přidružení sledovacího čísla – synchronní koncový bod vynucuje několik ověřovacích pravidel, včetně těchto:

• Vyžaduje se platné a aktivní subscriptionId
• Je povoleno pouze jedno subscriptionId na požadavek
• Vyžaduje se trackingNumber
• Je zajištěno, aby sledovací čísla splňovala požadavky FedEx na formátování, včetně maximálního limitu sledovacího čísla 6 až 22 číslic

Chybové odpovědi mají konzistentní strukturu ve formátu errors[], která obsahuje kód a zprávu pro snadnou analýzu.

"errors": [

{

"code": "ERROR.CODE",

"message": "Popisná chybová zpráva"

}

Přidružení čísla transakce – synchronní koncový bod umožňuje dílčí úspěchy. Pokud některá sledovací čísla selžou, synchronní API stále vrátí kód 200 OK a zobrazí následující:

• failedTrackingNumbers
• Popisná zpráva

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "Níže uvedená sledovací čísla se nenahrála kvůli chybám při validaci nebo v systému"

      }

    }

Další podrobnosti a pravidla najdete v oddílech obchodních pravidel.

Tento koncový bod použijte k odeslání jednoho nebo více sledovacích čísel, pro která jste přihlášeni k odběru, aby se zpracovala na pozadí.

Požadavek vrátí ID úlohy, které můžete použít s koncovým bodem Stav úlohy podle sledovacího čísla k monitorování zpracování a s koncovým bodem Detaily úlohy podle sledovacího čísla ke stažení výsledků zpracování po dokončení úlohy.

Požadovaný vstup:

• Akce
• Detaily sledovacího čísla

V rámci jednoho požadavku můžete přiřadit až 1 000 sledovacích čísel.

Výhody

Asynchronní koncový bod nabízí následující výhody:

• Podporuje odesílání ve velkých dávkách až 1 000 sledovacích čísel
• Umožňuje zpracování dlouhotrvajících požadavků na pozadí
• Umožňuje sledování stavu úloh a stahování zpráv o zpracování
• Eliminuje problémy s časovým limitem požadavků u velkých úloh

Použijte tento koncový bod ke zjištění stavu asynchronní úlohy (jednoho nebo více po sobě jdoucích požadavků ve frontě) nebo stavu všech odeslaných úloh.

Požadované vstupní údaje pro tento požadavek jsou:

• jobID – Zadejte ID úlohy, pro kterou chcete získat stav.

Poznámka: Zadání ID úlohy není pro tento koncový bod povinné. Pokud nezadáte ID úlohy, zobrazí se stav všech odeslaných úloh.

Úspěšná odpověď na tento požadavek vrátí jobID, aktuální stav úlohy a časová razítka vytvoření a dokončení úlohy. Odpověď zobrazí aktuální stav úloh. Odpověď navíc obsahuje i hlášení o úspěchu, chyby nebo varování, která si uživatelé mohou prohlédnout a podle potřeby použít k diagnostice problému.

• Pokud je stav úlohy zobrazen jako DOKONČENO, znamená to, že všechna sledovací čísla byla úspěšně ověřena a zpracována.
  • Stav DOKONČENO znamená, že sledovací čísla byla úspěšně ověřena a zpracována. Tento stav neznamená, že všechna sledovací čísla byla úspěšně začleněna do projektu Advanced Integrated Visibility.
  • U úloh s více sledovacími čísly lze stav považovat za DOKONČENO, i když se některá čísla nepodaří přiřadit k projektu a jiná jsou úspěšná. Chcete-li ověřit stav každého sledovacího čísla v původní žádosti o přidružení, stáhněte si zprávu o dávce.

Poznámka: Pokud je stav úlohy zobrazen jako NEÚSPĚŠNÝ, znamená to, že z různých důvodů či kvůli závažným chybám nebyl požadavek zpracován a uživatel jej musí opakovat.

Následující tabulka zobrazuje stavy úloh a jejich příslušné popisy:

Použijte tento koncový bod ke stažení JSON zprávy pro asynchronní úlohu ve stavu DOKONČENO.

Požadované vstupní údaje pro tento požadavek jsou:

• jobID – Zadejte ID úlohy, pro kterou chcete získat stav. Pro tento koncový bod je ID úlohy povinné.

Poznámka:

• Najednou lze stáhnout pouze jednu zprávu o asynchronní úloze.
• Pokud úloha není ve stavu DOKONČENO a pokusíte se stáhnout zprávu, zobrazí se chybová zpráva.

Úspěšná odpověď na tento požadavek vám poskytne zprávu o úloze ve formátu JSON.

Běžná obchodní pravidla

• Celkový počet sledovacích čísel, která lze přidružit k projektu Advanced Integrated Visibility, není omezen.
• Přidružení sledovacích čísel s projektem Advanced Integrated Visibility je zrušeno 40 dnů po jejich úspěšném přidružení k webhooku.
• Zabezpečené informace o sledování, jako je adresa příjemce, podpis příjemce a citlivé informace o doručení, nejsou prostřednictvím rozhraní API pro předplatné sledovacích čísel k dispozici.

Obchodní pravidla pro synchronní koncový bod

• Maximálně 150 sledovacích čísel na požadavek.
• Všechna sledovací čísla musí používat stejné subscriptionId.
• Zadané předplatné webhooku Advanced Integrated Visibility musí být platné a aktivní.
• Na požadavky se vztahuje 30sekundový časový limit.

Obchodní pravidla pro asynchronní koncový bod

• Maximálně 1 000 sledovacích čísel na požadavek.
• Stav úlohy a podrobnosti úlohy pro asynchronní požadavek se uchovávají po dobu 90 dnů od úspěšného přidružení sledovacích čísel k webhooku Advanced Integrated Visibility.