API V1 naar V2 migratie

In versie 1 van onze API heeft elke template slechts één pagina. Anders gezegd; in versie 1 heb je twee templates nodig om een bestelling te plaatsen. We wilden dit graag verbeteren en daarom hebben we een nieuwe versie van de API ontwikkeld.

In onze nieuwe versie van de API (v2) bevat een template meerdere pagina's. Daarom is er nog maar één template nodig om een order aan te maken.

Door deze structuurwijziging is het niet mogelijk om v1 templates op onze v2 API te gebruiken en vice-versa. Er staat een simpele oplossing klaar in de portal om jouw v1 templates naar v2 templates te migreren. Deze pagina zal je door deze migratie stappen heen leiden.

Let op: we zullen versie 1 van de API draaiende houden tot 1 maart 2024. Er is dus geen haast bij. Je hebt alle tijd om de oude templates te migreren. En wanneer je hulp nodig hebt, neem dan gerust contact met ons op.

Stap 1 - Migreer design template

De eerste stap in het migreren naar onze nieuwe versie is het updaten van je templates. Om dit makkelijker te maken vindt je een migratie wizard in onze portal. In deze wizard is het nodig om een voor- en achterkant te selecteren. Daarna zijn deze twee te combineren naar een enkele template (zie voorbeeld afbeelding hieronder):

Na het selecteren van de twee paginas kan er gekozen worden om de oude versies van de templates te behouden. Let op: we raden het aan om deze oude templates nog wel te bewaren voor het geval je deze in je integratie gebruikt. Wanneer je nog geen live orders verstuurd zou het veilig moeten zijn oude templates direct te verwijderen.

Stap 2 - Update de integratie

Onze intregraties

Wanneer je een van onze integraties gebruikt kun je de nieuwe versie gebruiken wanneer deze beschikbaar is.

Eigen integraties

Om je eigen integratie te updaten van v1 naar v2 is een update in de API calls nodig. De volgende JSON is hoe de JSON op v1 eruit ziet.

Voorbeeld JSON body v1

1{
2  "sender": { ... },
3  "recipient": { ... },
4  "mergeVariables": { ... },
5  "pages": {
6    "1": "tmpl_12345678900987654321",
7    "2": "tmpl_09876543211234567890"
8  },
9  "format": "POSTCARD_A5",
10  "billingId": "..."
11}

In de voorbeeld JSON hieronder zie je dat er delen van de JSON body veranderd zijn. Deze wijzigingen horen bij onze v2 API.

Voorbeeld JSON body v2 verschillen

1{
2  "sender": { ... },
3  "recipient": { ... },
4  "mergeVariables": { ... },
5  "templateId": "tmpl_12345678900987654321",
6  "finish": "MATTE",
7  "billingId": "..."
8}

Zoals te zien is hoeft er geen pages object meer meegestuurd te worden. Er kang ewoon een enkele templateId gebruikt worden.

Stap 3 - Verstuur een test-order om de migratie te controleren

Om te controleren of het migratieproces goed gegaan is, raden we aan om een test order via de portal aan te maken. In deze flow zullen alleen v2 templates staan. Nadat de order successful is en er een juiste order preview te zien is - is het migratie proces afgreond.

Herhaal stap 1 zo vaak als nodig, dit zal afhankelijk zijn van het aantal v1 templates wat in je account aanwezig zijn.

Kan ik v2 templates gebruiken in mijn v1 integratie?

Nee, het is niet mogelijk v2 templates in de v1 API te gebruiken. Onze V1 API accepteert namelijk alleen maar V1 templates. Dit is nodig om rendering fouten te voorkomen tijdens het migratie proces.

Mocht je nu vragen hebben neem dan gerust contact met ons op