-
Notifications
You must be signed in to change notification settings - Fork 7
/
index.html
executable file
·8152 lines (8110 loc) · 296 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en-us">
<head>
<meta charset="UTF-8" />
<title>MyParcel API documentation</title>
<meta name="description" content="The documentation to make a connection with MyParcel">
<meta content="width=device-width, initial-scale=1" name="viewport" />
<link rel="shortcut icon" href="https://backoffice.myparcel.nl/images/favicon/favicon.ico">
<link href="css/normalize.css" media="screen" rel="stylesheet" type="text/css" />
<link href="css/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700" rel="stylesheet" type="text/css" />
<link href="css/stylesheet.css" media="screen" rel="stylesheet" type="text/css" />
<link href="css/github-light.css" media="screen" rel="stylesheet" type="text/css" />
<script src="js/jquery-3.0.0.min.js"></script>
<script src="js/bootstrap.min.js"></script>
<script src="js/auto_menu.js"></script>
</head>
<body>
<script>
// redirect to the new API manual on the developer portal
(() => {
window.location.replace('https://developer.myparcel.nl/api-reference/');
})();
</script>
<div class="container-fluid">
<div class="row">
<div class="menu col-xs-4 col-lg-3">
<nav class="navbar nav nav-pills nav-stacked">
<div class="menu-items">
</div>
</nav>
</div>
<section class="page-header col-xs-8 col-xs-offset-4 col-lg-9 col-lg-offset-3">
<h1 class="project-name">
API Documentation for MyParcel, Flespakket and SendMyParcel
</h1>
<p class="project-tagline">
Last adjustments: <span id="current_version"></span>
</p>
<a target="_blank" class="btn" href="https://github.com/myparcelnl/api/commits/">Latest adjustments</a>
<div class="postman-run-button"></div>
<a target="_blank" class="btn" href="https://join.slack.com/t/myparcel-dev/shared_invite/enQtNDkyNTg3NzA1MjM4LWQ5MWE5MTQ3MDg4YjU5NzdjYjk0OTY1ZDJiYjU5YzJjNzk3Yzk3NGY0OWFkZDU4MDYwZDEyZDlhZTgzOWM1MjI">Need help? Slack us</a>
</section>
<section class="main-content col-xs-8 col-xs-offset-4 col-lg-7 col-lg-offset-4">
<h1>Introduction</h1>
<p>
This is the documentation for the MyParcel.nl Core API.
Our API is build in such a way to easily handle bulk operations. We try to follow the REST
architecture as much as possible but deviate from it when we need to achieve high performance.
</p>
<p>
This documentation is applicable to MyParcel.nl, Flespakket and SendMyParcel.be. Keep in mind that some
examples will only be applicable to one of those platforms, since there are differences in carriers,
shipping options and package types between the different platforms.
</p>
<div class="box">
<p>
Do you want to connect with MyParcel using PHP, C# or Ruby? Then you can use the following github
projects instead of the API. Create an issue on github to contact the programmer.
</p>
<ul>
<li><a href="https://github.com/myparcelnl/sdk" target="_blank">PHP</a></li>
<li><a href="https://github.com/janssenr/MyParcelApi.Net" target="_blank">C#/.net</a></li>
<li><a href="https://github.com/paypronl/myparcel" target="_blank">Ruby</a></li>
</ul>
</div>
<div>
<b>Sandbox</b>
<p>
To show delivery options to customers, you can use our javascript <a href="http://github.com/myparcelnl/checkout" target="_blank">code</a>. Use our <a href="https://myparcelnl.github.io/delivery-options/" target="_blank">sandbox</a> for an example and easier integration.
</p>
<b>Test environment</b>
<p>
We do not currently have a test environment. You can create an account and print labels. These will only be invoiced if you actually send them. Note: Digital stamps/Digitale postzegel (package_type 4) will be charged immediately.
</p>
<b>Need help?</b>
<p>
<img src="media/logo_slack.jpg" alt="Slack" class="pull-left" width="20">
Do you want to be kept informed of new functionalities or do you just need help? You can contact us via our <a target="_blank" href="https://join.slack.com/t/myparcel-dev/shared_invite/enQtNDkyNTg3NzA1MjM4LWQ5MWE5MTQ3MDg4YjU5NzdjYjk0OTY1ZDJiYjU5YzJjNzk3Yzk3NGY0OWFkZDU4MDYwZDEyZDlhZTgzOWM1MjI">Slack channel</a>.
</p>
<b>Status API</b>
<p>
Sometimes we or an external party that we use have a malfunction. View the malfunctions at <a href="https://status.myparcel.nl/" target="_blank">status.myparcel.nl</a>. These malfunctions are also visible in our Slack channel.
</p>
</div>
<div class="postman-run-button pull-right"></div>
<div style="margin-top:10px">
<h1 id="1">1. Requests</h1>
<h2 id="1_A">1.A Base URL</h2>
<p>BaseURL: <strong>https://api.myparcel.nl</strong></p>
<h2 id="1_B">1.B User-Agent</h2>
<p>
To give us insight that you use the API documentation, you should always send an User-Agent in your header. If you do not use a known CMS system, use the following header:<br>
<code>User-Agent: CustomApiCall/2</code><br>
<br>
If you are using a known CMS system then you must use the name of the CMS system followed by a version number (User-Agent: <product> / <product-version>). Here's an example if your CMS system is Wordpress: <code>User-Agent: Wordpress/4.8.1</code>.
</p>
<h2 id="1_C">1.C HTTP methods</h2>
<p>
The API is REST(ful) and uses JSON as it's primary data exchange format.
Communication with the API goes through HTTPS thereby insuring data
confidentiality and integrity. Here is a list of all supported HTTP methods
</p>
<h3 id="1_C_1">1.C.1 GET</h3>
<p>
GET method is used for retrieving data and is idempotent. Data can be returned in
JSON, PDF, CSV, XML or other formats.
</p>
<h3 id="1_C_2">1.C.2 POST</h3>
<p>
POST is used to create new objects or send data to MyParcel.
</p>
<h3 id="1_C_3">1.C.3 DELETE</h3>
<p>
DELETE is used to delete an existing object (piece of data). This method always returns HTTP/1.1
204 No Content unless otherwise specified.
</p>
<h2 id="1_D">1.D Rate limiting</h2>
<p>
Rate limits apply to many of our endpoints. You cannot receive data after you have exceeded
the limit. The rate limiting will be reached when you make more than 100 requests per minute.
The limit automatically resets after 1 minute.<br><br>
Example: If you make 100 requests to the same endpoint within 15 seconds, you will be able to continue 45 seconds later.
</p>
<h1 id="2">2. Responses</h1>
<p>
As stated earlier data is usually sent back in JSON format. Exceptions to this rule
are shipment label, invoice and CSV export. Shipment label and invoice are sent
back in PDF format while CSV export is sent back in CSV format.
Usually a response will have a response body. Exceptions are DELETE requests
which will only contain a status code (204) indicating success.
A failed request with a 4xx status code will always send back a response body with
the error description.
A failed request with a 5xx status code will probably mean you've hit a snag in our API.
We try to monitor these kind of errors, but if you keep having trouble... Don't hesitate to <a href="https://www.myparcel.nl/contact">reach out!</a>
</p>
<h2 id="2_A">2.A HTTP statuses</h2>
<p>
HTTP status codes are used to indicate success or failure of a request. Here's a list of
supported status codes.
For a more comprehensive list of HTTP status codes <a
href="https://en.wikipedia.org/wiki/List_of_HTTP_status_codes" target="_blank">visit
Wikipedia </a> or W3C.
</p>
<p>Example of a 200 Status code in our API (you can try this in your browser, then you know our API is online)</p>
<p>
<strong>Request:</strong>
<pre>
GET https://api.myparcel.nl/
Request Headers (example):
GET / HTTP/1.1
Host: api.myparcel.nl
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
Upgrade-Insecure-Requests: 1
Accept-Encoding: gzip, deflate, sdch, br
</pre>
<strong>Response:</strong>
<pre>
{
"title":"MyParcel API",
"status":"OK"
}
Response Headers (example!)
HTTP/1.1 200 OK
Date: Tue, 31 Jan 2017 13:37:00 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
</pre>
</p>
<h2 id="2_A_I">2.A.I 2xx</h2>
<p>
Used for successful requests. Successful requests may contain a response body e.g.
object id of new object or none when modifying an existing object.
</p>
<h3>2.A.I 200 - OK</h3>
<p>
This status code is used for successful requests that have a response body.
</p>
<h3>2.A.I 202 - Accepted</h3>
<p>
This status code is used for requests that have been received successfully and will
be processed at a later time. This is mostly used for processing shipments and
addresses CSV.
</p>
<h3>2.A.I 204 - No Content</h3>
<p>
This status is used primarily for DELETE requests.
</p>
<h2 id="2_A_II">2.A.II 3xx</h2>
<h3>2.A.II 304 - Not Modified</h3>
<p>
This status is used by the server when the resource is the same as the one the client has.
</p>
<h2 id="2_A_III">2.A.III 4xx</h2>
<p>
Used for failed requests. Failed requests always contain a response body with the
error description.
</p>
<h3>2.A.III 400 - Bad Request</h3>
<p>
When the request received is malformed.
</p>
<h3>2.A.III 401 - Unauthorized</h3>
<p>
No credentials have been sent with the request, or the wrong credentials are sent.
Tip: check if the API key is properly attached in the header: <br>
<pre>Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==</pre>
</p>
<h3>2.A.III 402 - Payment Required</h3>
<p>
When payment is required. An Invoice object may be sent with this response.
</p>
<h3>2.A.III 403 - Forbidden</h3>
<p>
When the given credentials are not authorized to perform a certain action.
</p>
<h3>2.A.III 404 - Not Found</h3>
<p>
When a resource cannot be found.
</p>
<h3>2.A.III 405 - Method not allowed</h3>
<p>
When you used a method on an endpoint that is either not supported or not
allowed for the given credentials.
</p>
<h3>2.A.III 406 - Not acceptable</h3>
<p>
When the client requests a given format for a resource that is not supported.
</p>
<h3>2.A.III 415 - Unsupported media type</h3>
<p>
When the client specifies a content-type in the request that is not supported.
</p>
<h3>2.A.III 422 - Unprocessable Entity</h3>
<p>
When the client sends a request object with invalid data.
The error message will specify what's wrong with the request or the data sent to the API.
</p>
<h3>2.A.III 409 - Conflict</h3>
<p>
When the client request conflicts with the current state of the resource.
</p>
<h2 id="2_A_IV">2.A.IV 5xx</h2>
<p>
Used for server-side errors. This happens when we (i.e. MyParcel.nl / the API) are having problems.
</p>
<h1 id="3">3. Character encoding</h1>
<p>
All content must be encoded in UTF-8 and include the charset=utf-8.<br><br>
Example:
<pre>Content-Type: application/json;charset=utf-8</pre>
</p>
<h1 id="4">4. Data Types</h1>
<p>
Our API defines its own data types.
</p>
<h2>4.1 Contents</h2>
<ul>
<li><a href="#array">array</a></li>
<li><a href="#boolean">boolean</a></li>
<li><a href="#carrier">carrier</a></li>
<li><a href="#coordinates">coordinates</a></li>
<li><a href="#country_code">country_code</a></li>
<li><a href="#currency">currency</a></li>
<li><a href="#date">date</a></li>
<li><a href="#delivery_type">delivery_type</a></li>
<li><a href="#description">description</a></li>
<li><a href="#eori_number">eori_number</a></li>
<li><a href="#float">float</a></li>
<li><a href="#integer">integer</a></li>
<li><a href="#isic_code">isic_code</a></li>
<li><a href="#label_position">label_position</a></li>
<li><a href="#main">main</a></li>
<li><a href="#month_digit">month_digit</a></li>
<li><a href="#package_contents">package_contents</a></li>
<li><a href="#package_type">package_type</a></li>
<li><a href="#paper_size">paper_size</a></li>
<li><a href="#price">price</a></li>
<li><a href="#printer_identifier">printer_identifier</a></li>
<li><a href="#shipment_status">shipment_status</a></li>
<li><a href="#sort_order">sort_order</a></li>
<li><a href="#webhook_status">webhook_status</a></li>
<li><a href="#string">string</a></li>
<li><a href="#text">text</a></li>
<li><a href="#time">time</a></li>
<li><a href="#timestamp">timestamp</a></li>
<li><a href="#vat_number">vat_number</a></li>
<li><a href="#weekday_digit">weekday_digit</a></li>
<li><a href="#weekday_string">weekday_string</a></li>
</ul>
<h2 id="array">array</h2>
<table>
<tr>
<th>description</th>
<td>array of elements. Can contain all other data types.</td>
</tr>
<tr>
<td>pattern</td>
<td>*</td>
</tr>
<tr>
<td>example</td>
<td></td>
</tr>
</table>
<h2 id="boolean">boolean</h2>
<table>
<tr>
<th>description</th>
<td>boolean value</td>
</tr>
<tr>
<td>pattern</td>
<td>1 or 0</td>
</tr>
<tr>
<td>example</td>
<td>0 (false), 1 (true)</td>
</tr>
</table>
<h2 id="platform">platform</h2>
<table>
<tr>
<th>description</th>
<td>Platform name</td>
</tr>
<tr>
<td>pattern</td>
<td>[a-z]</td>
</tr>
<tr>
<td>example</td>
<td>
<ul>
<li>myparcel</li>
<li>flespakket</li>
<li>belgie</li>
</ul>
</td>
</tr>
</table>
<h2 id="carrier">carrier</h2>
<table>
<tr>
<th>description</th>
<td>Carrier id</td>
</tr>
<tr>
<td>pattern</td>
<td>\d</td>
</tr>
<tr>
<td>example</td>
<td>
<ul>
<li>1 (PostNL)</li>
<li>2 (bpost. Only available on Sendmyparcel.be)</li>
<li>3 (CheapCargo/pallets)</li>
<li>4 (DPD. Only available on Sendmyparcel.be)</li>
<li>5 (Instabox. Only available on MyParcel.nl)</li>
<li>8 (UPS. Only available on MyParcel.nl)</li>
</ul>
</td>
</tr>
</table>
<h2 id="coordinates">coordinates</h2>
<table>
<tr>
<th>description</th>
<td>The position of the pickup locations</td>
</tr>
<tr>
<td>pattern</td>
<td>[-+]?[\d]{1,2}\.\d+</td>
</tr>
<tr>
<td>example</td>
<td>52.192150633052</td>
</tr>
</table>
<h2 id="country_code">country_code</h2>
<table>
<tr>
<th>description</th>
<td>ISO3166-1 alpha2 country code</td>
</tr>
<tr>
<td>pattern</td>
<td>[A-Z]{2,2}</td>
</tr>
<tr>
<td>example</td>
<td>NL, BE, CW</td>
</tr>
</table>
<h2 id="currency">currency</h2>
<table>
<tr>
<th>description</th>
<td>ISO 4217 currency code</td>
</tr>
<tr>
<td>pattern</td>
<td>EUR</td>
</tr>
<tr>
<td>example</td>
<td>EUR</td>
</tr>
</table>
<h2 id="date">date</h2>
<table>
<tr>
<th>description</th>
<td>Date</td>
</tr>
<tr>
<td>pattern</td>
<td>[YYYY-MM-DD]</td>
</tr>
<tr>
<td>example</td>
<td>2015-01-01</td>
</tr>
</table>
<h2 id="delivery_type">delivery_type</h2>
<table>
<tr>
<th>description</th>
<td>The delivery type.</td>
</tr>
<tr>
<td>pattern</td>
<td>[1 – 7]</td>
</tr>
<tr>
<td>example</td>
<td>
<ol>
<li>morning</li>
<li>standard</li>
<li>evening</li>
<li>pickup</li>
</ol>
</td>
</tr>
</table>
<h2 id="description">description</h2>
<table>
<tr>
<th>description</th>
<td>You can translate the endpoint by sending the correct header (Accept-Language: en_GB)</td>
</tr>
<tr>
<td>pattern</td>
<td>.{0,255}</td>
</tr>
<tr>
<td>example</td>
<td>Zending bezorgd</td>
</tr>
</table>
<h2 id="eori_number">eori_number</h2>
<table>
<tr>
<th>description</th>
<td>
Economic Operators Registration and Identification. This field is required for DPD shipments
to United Kingdom. In this field you can enter the EORI number of the sender in case of a
B2C shipment and the EORI number of the recipient in case of a B2B shipment.
</td>
</tr>
<tr>
<td>pattern</td>
<td>[A-Z]{2}[0-9]{9,12}</td>
</tr>
<tr>
<td>example</td>
<td>NL012345678</td>
</tr>
</table>
<h2 id="float">float</h2>
<table>
<tr>
<th>description</th>
<td>Numeric value with decimal fractions</td>
</tr>
<tr>
<td>pattern</td>
<td>[0-9]*\.?[0-9]+</td>
</tr>
<tr>
<td>example</td>
<td>51.70326781</td>
</tr>
</table>
<h2 id="integer">integer</h2>
<table>
<tr>
<th>description</th>
<td>Whole numeric value</td>
</tr>
<tr>
<td>pattern</td>
<td>[0-9]+</td>
</tr>
<tr>
<td>example</td>
<td>10. 20. NOT 2,3</td>
</tr>
</table>
<h2 id="isic_code">isic_code</h2>
<table>
<tr>
<th>description</th>
<td>
International Standard Industry Classification. This is mandatory for the customs form when
shipping outside EU. Codes can be found on the
<a target="_blank"
href="https://tarief.douane.nl/arctictariff-public-web/#!/taric/nomenclature/sbn?d=I&cc=&l=nl&ql=nl&ea=false">Douane</a>
website.
</td>
</tr>
<tr>
<td>pattern</td>
<td>[0-9]{1,4}</td>
</tr>
<tr>
<td>example</td>
<td>0111 (Growing of cereals (except rice), leguminous crops and oil seeds)</td>
</tr>
</table>
<h2 id="label_position">label_position</h2>
<table>
<tr>
<th>description</th>
<td>The position of the label on the paper.</td>
</tr>
<tr>
<td>pattern</td>
<td>[1 - 4]</td>
</tr>
<tr>
<td>example</td>
<td>
<ol>
<li>(top-left)</li>
<li>(top-right)</li>
<li>(bottom-left)</li>
<li>(bottom-right)</li>
</ol>
</td>
</tr>
</table>
<h2 id="main">main</h2>
<table>
<tr>
<th>description</th>
<td>
All statuses are divided into 5 main "categories". Only the last status in a category gets
this attribute, meaning if there are consecutive duplicate statuses still only the most recent
status gets the `main` attribute. Other statuses get the value `null`.
</td>
</tr>
<tr>
<td>pattern</td>
<td>[a-z]</td>
</tr>
<tr>
<td>example</td>
<td>
<ul>
<li>registered</li>
<li>handed_to_carrier</li>
<li>sorting</li>
<li>distribution</li>
<li>delivered</li>
</ul>
</td>
</tr>
</table>
<h2 id="month_digit">month_digit</h2>
<table>
<tr>
<th>description</th>
<td>The month in digit preceded by a zero for single digit months</td>
</tr>
<tr>
<td>pattern</td>
<td>[0-1]{1}[1-9]{1}</td>
</tr>
<tr>
<td>example</td>
<td>01 (Jan), 02 (Feb) etc.</td>
</tr>
</table>
<h2 id="package_contents">package_contents</h2>
<p>
The package contents are only needed in case of shipping outside EU, this is mandatory info for
customs
form.
</p>
<table>
<tr>
<th>description</th>
<td>The content type of a package.</td>
</tr>
<tr>
<td>pattern</td>
<td>[1 - 5]</td>
</tr>
<tr>
<td>example</td>
<td>
<ol>
<li>commercial goods</li>
<li>commercial samples</li>
<li>documents</li>
<li>gifts</li>
<li>return shipment</li>
</ol>
</td>
</tr>
</table>
<h2 id="package_type">package_type</h2>
<table>
<tr>
<th>description</th>
<td>The different shipments you can create. For SendMyParcel only package type 1 (package) is allowed.</td>
</tr>
<tr>
<td>pattern</td>
<td>[1 – 4]</td>
</tr>
<tr>
<td>example</td>
<td>
<ol>
<li>package</li>
<li>mailbox package</li>
<li>letter</li>
<li>digital stamp</li>
</ol>
</td>
</tr>
</table>
<h2 id="paper_size">paper_size</h2>
<table>
<tr>
<th>description</th>
<td>The size of a paper as specified in ISO216.</td>
</tr>
<tr>
<td>pattern</td>
<td>A4 or A6</td>
</tr>
<tr>
<td>example</td>
<td>A4</td>
</tr>
</table>
<h2 id="price">price</h2>
<table>
<tr>
<th>description</th>
<td>
composite type containing integer and currency. The amount is without decimal separators (in
cents).
</td>
</tr>
<tr>
<td>pattern</td>
<td>{"amount": integer, "currency": currency }</td>
</tr>
<tr>
<td>example</td>
<td>{"amount": 10000, "currency": "EUR"}</td>
</tr>
</table>
<h2 id="printer_identifier">printer_identifier</h2>
<table>
<tr>
<th>description</th>
<td>
In this field you can enter your printer identifier. This field is also sent with the
webhook shipment_label_created. You are responsible for controlling your own printer based
on a printer identifier.
</td>
</tr>
<tr>
<td>pattern</td>
<td>.{0,255}</td>
</tr>
<tr>
<td>example</td>
<td>printer_12</td>
</tr>
</table>
<h2 id="shipment_status">shipment_status</h2>
<table>
<tr>
<th>description</th>
<td>shipment_status</td>
</tr>
<tr>
<td>pattern</td>
<td>[1-99]</td>
</tr>
<tr>
<td>example</td>
<td>
<ul>
<li>1 pending - concept</li>
<li>2 pending - registered</li>
<li>3 enroute - handed to carrier</li>
<li>4 enroute - sorting</li>
<li>5 enroute - distribution</li>
<li>6 enroute - customs</li>
<li>7 delivered - at recipient</li>
<li>8 delivered - ready for pickup</li>
<li>9 delivered - package picked up</li>
<li>10 delivered - return shipment ready for pickup</li>
<li>11 delivered - return shipment package picked up</li>
<li>12 printed - letter</li>
<li>13 inactive - credited</li>
<li>14 printed - digital stamp</li>
<li>30 inactive - concept</li>
<li>31 inactive - registered</li>
<li>32 inactive - enroute - handed to carrier</li>
<li>33 inactive - enroute - sorting</li>
<li>34 inactive - enroute - distribution</li>
<li>35 inactive - enroute - customs</li>
<li>36 inactive - delivered - at recipient</li>
<li>37 inactive - delivered - ready for pickup</li>
<li>38 inactive - delivered - package picked up</li>
</ul>
</td>
</tr>
</table>
<h2 id="sort_order">sort_order</h2>
<table>
<tr>
<th>description</th>
<td>sort order value</td>
</tr>
<tr>
<td>pattern</td>
<td>ASC or DESC</td>
</tr>
<tr>
<td>example</td>
<td>ASC (ascending), DESC (descending)</td>
</tr>
</table>
<h2 id="webhook_status">webhook status</h2>
<table>
<tr>
<th>description</th>
<td>A webhook status</td>
</tr>
<tr>
<td>pattern</td>
<td>[a-z]+</td>
</tr>
<tr>
<td>example</td>
<td>success, failed</td>
</tr>
</table>
<h2 id="string">string</h2>
<table>
<tr>
<th>description</th>
<td>Any alphanumeric value up to 255 characters.</td>
</tr>
<tr>
<td>pattern</td>
<td>.{0,255}</td>
</tr>
<tr>
<td>example</td>
<td>3SMYPA123456789; Antareslaan 31; Nederland; </td>
</tr>
</table>
<h2 id="text">text</h2>
<table>
<tr>
<th>description</th>
<td>Any character up to a limit of 2048 characters.</td>
</tr>
<tr>
<td>pattern</td>
<td>.{0,2048}</td>
</tr>
<tr>
<td>example</td>
<td>This is a test text.</td>
</tr>
</table>
<h2 id="time">time</h2>
<table>
<tr>
<th>description</th>
<td>Time.</td>
</tr>
<tr>
<td>pattern</td>
<td>HH:MM:SS</td>
</tr>
<tr>
<td>example</td>
<td>08:00:00</td>
</tr>
</table>
<h2 id="timestamp">timestamp</h2>
<table>
<tr>
<th>description</th>
<td>Date and time.</td>
</tr>
<tr>
<td>pattern</td>
<td>YYYY-MM-DD HH:MM:SS(.[0-9]{6})?</td>
</tr>
<tr>
<td>example</td>
<td>
<ul>
<li>2015-01-01 08:00:00</li>
<li>2015-01-01 08:00:00.000000</li>
</ul>
</td>
</tr>
</tr>
</table>
<h2 id="vat_number">vat_number</h2>
<table>
<tr>
<th>description</th>
<td>This field is required for DPD shipments to United Kingdom. In this field you can enter the VAT number of the sender in case of a B2C shipment and the VAT number of the recipient in case of a B2B shipment.</td>
</tr>
<tr>
<td>pattern</td>
<td>*{,15}</td>
</tr>
<tr>
<td>example</td>
<td>NL000099998B57</td>
</tr>
</table>
<h2 id="weekday_digit">weekday_digit</h2>
<table>
<tr>
<th>description</th>
<td>Weekday in digit</td>
</tr>
<tr>
<td>pattern</td>
<td>[0-6]{1}</td>
</tr>
<tr>
<td>example</td>
<td>0 (Sunday), 1 (Monday), ...</td>
</tr>
</table>
<h2 id="weekday_string">weekday_string</h2>
<table>
<tr>
<th>description</th>
<td>Weekday in string</td>
</tr>
<tr>
<td>pattern</td>
<td>sunday OR monday OR tuesday OR wednesday OR thursday OR friday OR saturday</td>
</tr>
<tr>
<td>example</td>
<td>sunday</td>
</tr>
</table>
<h1 id="5">5. Authentication</h1>
<p>
HTTP basic access authentication on top of SSL is used for authentication. Every request must include
an Authorization header with base64 encoded API Key. Go to
<a target="_blank" href="https://www.base64encode.org/">base64encode.org</a> to convert your key to base64.
</p>
<pre>
GET /somelink HTTP/1.1
Authorization: basic eUVJV1hFc3ZhMkxPeWRvVlM1bDVVZVJwamJNdVZQQXJSUGhFVkpCYw==
</pre>
<p>
Our API uses API keys for access control. When a <strong>Merchant</strong> wants to connect an external system
to
our API he/she needs to create an <strong>API Key.</strong> This API Key will be assigned the <strong>Broker</strong> role.
Currently the Merchant is not able to create or assign another Role to a API Key. When the Merchant
wants to invalidate an API Key he/she just disables the API Key. An Intermediate system, such as
the <a href="https://backoffice.myparcel.nl/">MyParcelNL backoffice</a> or
<a href="https://backoffice.sendmyparcel.be">SendMyParcel backoffice</a>,
has its own API Key but cannot access user resources. For this it needs to request
a <strong>Session</strong>
Token so that it can perform actions on behalf of the user. The API Key and Session Token are send
in
the Authorization header.
</p>
<h2>5.1 Error codes</h2>
<p>
Our API defines a list of error codes besides the HTTP status codes. Error codes are divided in
ranges
to make it easier for developers to quickly diagnose and solve problems. Errors are returned as an
Error object.
</p>
<h1 id="6">6. Shipments</h1>
<p>
We’ll start the shipment section with the different shipment option combinations available in
MyParcel (6.a). It is highly recommended that you read this first as this section helps you understand what
all the shipment options are and which combinations are possible. We will not list every possible
combination since there are too many to list. We will look at the different package types and then
look at the different options available to them. Then we bring all of it together with some examples.
</p>
<div class="postman-run-button"></div>
<h2 id="6_A">6.A Shipment option combinations</h2>
<h3>Contents</h3>
<h3 id="6_A_1">6.A.1 Package types</h3>
<p>
There are four different packages types available and determine the type of shipment. The value is
send
with the <a href="#7_C">ShipmentOptions</a>.package_type field.
</p>
<h4>1. Package</h4>
<p>
This is the standard package type used for NL, EU and Global shipments. It supports a variety of
additional options such as insurance, xl format etc. We will look at these options in more detail
later.
This package is most commonly used when creating shipments.
</p>
<h4>2. Mailbox package</h4>
<p>
This package type is only available on MyParcel.nl and Flespakket for NL shipment that fit into a mailbox. It does not support
additional options.<br>
<strong>Note: If you still make the request with additional options, bear in mind that you need to pay more than is necessary!</strong>
</p>
<h4>3. Letter</h4>
<p>
This package type is available on MyParcel.nl for NL, EU and Global shipments. The label for this shipment is unpaid
meaning that you will need to pay the postal office/courier to sent this letter/package. Therefore,
it does not support additional options.
</p>
<h4>4. Digital stamp</h4>
<p>
This package type is only available on MyParcel.nl for NL shipments and does not support any additional options. Its price is calculated using the package <a href="#7_N">weight</a>.<br>
<strong>Note: This shipment will appear on your invoice on <a href="#shipment_status">shipment_status</a> 2 (pending - registered) as opposed to all other package types, which won't appear on your invoice until shipment status 3 (enroute - handed to carrier).</strong>
</p>
<h3 id="6_A_2">6.A.2 Delivery types</h3>
<p>
There are five different delivery types and these specify how the package is delivered. The value is send
with the ShipmentOptions.delivery_type field. Currently delivery types are only available for NL and BE
shipments with package type 1. Delivery types 1-5 for NL and 1,4 for BE. The address of the package determines the delivery types available.
You need to use the DeliveryOptions interface to fetch the delivery types for a specific address. It is also
possible to specify a date on which the package has to be delivered with the ShipmentOptions.delivery_date field.
With delivery types 1 & 3 ShipmentOptions.delivery_date is required.
</p>
<h4>1. Morning</h4>
<p>
This options is only available for certain NL addresses. It allows a Customer/Consumer to have their
package delivered early in the morning on the delivery date specified except on Saturday and
Sunday.
</p>
<h4>2. Standard</h4>
<p>This is the standard delivery type.</p>
<h4>3. Evening</h4>
<p>
This options is only available on MyParcel.nl and Flespakket for certain NL addresses. It allows a Customer/Consumer to have their
package delivered in the evening on the specified delivery date.
</p>
<h4>4. Pickup</h4>
<p>The package is delivered at the chosen drop off point specified by the Consumer/Customer.</p>
<h4>5. Pickup express</h4>
<p>
The same as pickup but the package is available for pickup before 8:30AM on the delivery date
specified
at the drop off location. Only available on MyParcel.nl and Flespakket.
</p>
<h3 id="6_A_3">6.A.3 Options</h3>
<p>
These are the different package options such as insurance, recipient only, signature on receipt, XL
format etc. These options are specified in the <a href="#7_C">ShipmentOptions</a> object. These options are only
available for <a href="#package_type">package type</a> 1 (package).
</p>
<h4>only_recipient</h4>
<p>
Deliver the package only at address of the intended recipient. This option is required for Morning
and
Evening delivery types.