Integratietips voor de Push API

Dit artikel geeft tips over hoe je kunt voorkomen dat jouw Push API-integratie mislukt en uiteindelijk wordt uitgeschakeld.

De belangrijkste oorzaak van het mislukken van de Push API is het niet retourneren van een HTTP 2xx-respons, zelfs wanneer je een Push API-oproep met succes hebt ontvangen. De Push API van Paazl beschouwt alles behalve een HTTP 2xx-code als een teken dat er iets is misgegaan. Het aantal onterecht als "mislukt" aangemerkte oproepen stapelt zich op in de back-end van Paazl tot het moment dat Paazl gedwongen is de Push API uit te schakelen.

Als jouw Push API-service is uitgeschakeld, moet je de service handmatig weer inschakelen in jouw Paazl webapp-account. Bestaande gebeurtenissen in de Push API-wachtrij of nieuwe gebeurtenissen die worden gegenereerd terwijl de service is uitgeschakeld, gaan verloren.

De volgende tips behandelen veelvoorkomende integratiefouten die leiden tot onjuiste Push API-reacties en het daaropvolgende uitschakelen van de Push API.

Tip 1 - Valideer het bearer-token

Zorg ervoor dat jouw server het bearer-token dat Paazl met zijn Push API-verzoeken meestuurt, controleert, verifieert en hier correct op reageert. Het bearer-token wordt meegestuurd in de header van het verzoek. Als jouw server niet correct met het token omgaat, zal de resulterende HTTP 404-statuscode door de Paazl Push API als een fout worden beschouwd.

Tip 2 - Houd het server-token up-to-date

Om veiligheidsredenen is het verstandig om periodiek een nieuw bearer-token te genereren in jouw Paazl webapp-account. Dit is het beveiligingstoken dat Paazl meestuurt met zijn Push API-verzoeken. Zorg ervoor dat je niet vergeet om ook het verwachte bearer-token aan de serverzijde bij te werken. Als Paazl het nieuwe token verstuurt en jouw server nog steeds het oude token verwacht, zal er een uitzondering (exception) optreden.

Tip 3 - Houd datavalidatie gescheiden

Het Push API-verzoek bevat gegevens zoals de referentie of barcode van een bestelling. Jouw webshop valideert deze gegevens correct, maar geeft validatiefouten mogelijk aan de Push API door in de vorm van HTTP 4XX- of 5XX-statuscodes.

Houd er rekening mee dat dergelijke uitzonderingen niets direct te maken hebben met het Push API-verzoek zelf; dat is immers geslaagd, anders had je geen gegevens ontvangen om te valideren. Zorg ervoor dat je deze twee zaken gescheiden houdt. Als een Push API-verzoek is geslaagd, zorg er dan voor dat je een HTTP 200-statuscode retourneert, ongeacht wat jouw webshop daarna met de informatie doet.

Tip 4 - Maak of bevestig geen bestellingen

Het Push API-verzoek bevat een status-element dat de waarde CREATED kan hebben. De integratie van jouw webshop gebruikt de Push API mogelijk om het aanmaken van bestellingen in jouw webshop te triggeren of om bestellingen te bevestigen. Gebruik de Push API niet voor het aanmaken of bevestigen van bestellingen — daar is deze niet voor ontworpen. Paazl garandeert bijvoorbeeld geen 100% uptime voor zijn Push API.

Bovendien loop je het risico dat HTTP 4XX- of 5XX-uitzonderingen onnodig worden doorgegeven aan de REST API. Dergelijke uitzonderingen hebben niets direct te maken met een Push API-verzoek zelf en kunnen ertoe leiden dat jouw Push API-implementatie wordt uitgeschakeld.

Tip 5 - Bereid je voor op asynchrone berichten

Houd er rekening mee dat je meerdere Push-notificaties per minuut kunt ontvangen. Zorg ervoor dat jouw integratie asynchroon is.