Volgende lichting: 16:30

bel voor advies 078 - 780 23 59

BlogAPI Documentatie

Jeffrey Hagenstein 6 March, 2018 on 3:57 pm

Met een API integratie is het mogelijk om jouw interne systemen en processen met de digitale postkamer van Postbode.nu te koppelen. Hierdoor kunnen postzendingen automatisch verzonden worden. Ideaal voor bijvoorbeeld de maandelijkse facturatie of een welkomstbrief bij een aanmelding.

Authenticatie

Via https://app.postbode.nu/settings/api kunt u uw eigen API key aanmaken en/of ophalen, deze key moet via de “X-Authorization”-header meegestuurd worden bij iedere request.

  • Wij adviseren om het account in “Sandbox mode” te zetten onder instellingen.
  • Documentatie is ook in PDF (indent friendly) te downloaden.

De header ziet er dan als volgt uit:
Content-Type: application/json
X-Authorization: XXXXXXXXX-UW-API-KEY-XXXXXXXXX

Methoden

GET MAILBOXES

Via deze call worden alle beschikbare mailboxen voor de gebruiker, behorende bij de API-Key weergegeven.

Request
Method URL
GET https://app.postbode.nu/api/mailbox/

 

Type Params Values
HEAD X-Authorization string

Response
Status Response
200 [
{
"id": 1,
"Name": "Demomailbox",
"vat_shifted": 0,
"balance": 100.00,
"available_balance": 100.00
}
]

Get letters

Ophalen van alle brieven in een betreffende mailbox

Request

Method URL            
GET https://app.postbode.nu/api/mailbox/[mailbox_id]/letters

 

Type Params Values
HEAD X-Authorization string

 

Response

Status Response
200 {
"id": 1,
"envelope_id": 2,
"service": "send",
"status": "concept",
"color": "full color",
"printing": "simplex",
"paper_weight": "80g",
"paper_size": "A4",
"tracking_code": null,
"formatted_id": "PB00000001",
"shipping_id": 1,
"weight": 13,
"pages": 1,
"sheets": 1
}

 

Post letters

Document verzenden via Postbode.nu

 

Request

Method URL            
POST https://app.postbode.nu/api/mailbox/[mailbox_id]/letters

 

Type Params Values
HEAD
POST
X-Authorization

String

{
"documents": [
{
"name": "Documentnaam.pdf",
"content": base64encoded file
}
],
"envelope_id": 2,
"country": "NL",
"registered": false,
"send": true
}

 

documents (array)
Binnen documents geeft u de documenten mee die verzonden moeten worden, waarbij het eerste document een geldig adres moet bevatten dat zichtbaar is in het envelopvenster.

cover_address (string) (optioneel)
Door het meegeven van een adres via ‘cover_address’ zal er een voorblad worden toegevoegd zodat het adres zichtbaar zal zijn voor het venster.

envelope_id (int)
Standaard kunt u envelop 2 gebruiken, een overzicht van beschikbare enveloppen kunt u vinden op https://app.postbode.nu/mailbox/envelopes onder de betreffende mailbox.

country (string)
De ISO-3166-2 geformatteerde landcode van het land van bestemming

registered (bool)
Aangetekende zending, bij true zal de zending aangetekend verzonden worden

send (bool)
Direct verzenden (true) of enkel toevoegen aan app.postbode.nu (false)

Response

Status Response
200 {
"id": 1,
"envelope_id": 2,
"service": "send",
"status": "concept",
"color": "full color",
"printing": "simplex",
"paper_weight": "80g",
"paper_size": "A4",
"tracking_code": null,
"formatted_id": "PB10000001",
"shipping_id": 2,
"weight": 23,
"pages": 3,
"sheets": 3,
"pricing": {
"sale_price": 1.99,
"sale_price_in_vat": 2.408,
"printing": {
"name": "Print - Kleur \/ Enkelzijdig \/ 80g \/ A4",
"sale_price": "0.210",
"sale_price_in_vat": "0.254",
"type": "send_printing"
},
"envelope": {
"name": "Verpakking - Onbedrukte envelop \/ C5",
"sale_price": "0.120",
"sale_price_in_vat": "0.145",
"type": "send_envelope"
},
"shipment": {
"name": "PostNL (Brief 20 - 50 g) (Nederland) (24uur)",
"sale_price": "1.660",
"sale_price_in_vat": "2.009",
"type": "send_shipping"
},
"vat": "0.418",
"available_balance": "10.00"
},
"documents": [
{
"id": 1,
"name": "Documentnaam.pdf",
"source": "api",
"pages": 3,
"order": 0,
"created_at": "2018-02-26 07:58:45",
"updated_at": "2018-02-26 07:58:45",
"deleted_at": null
}
]
}

 

Glossary

Conventions

  • Client – Client application.
  • Status – HTTP status code of response.
  • All response are in JSON format.

Status Codes

All status codes are standard HTTP status codes. The below ones are used in this API.

2XX – Success of some kind
4XX – Error occurred in client’s part
5XX – Error occurred in server’s part

Status Code Description
200 OK
201 Created
202 Accepted (Request accepted, and queued for execution)
400 Bad request
401 Authentication failure
403 Forbidden
404 Resource not found
405 Method Not Allowed
409 Conflict
412 Precondition Failed
413 Request Entity Too Large
500 Internal Server Error
501 Not Implemented
503 Service Unavailable

Bestandstype

Let op! Postbode.nu accepteert alleen PDF-bestanden en geen Word bestanden of andere formaten.

Webhooks

Wat zijn webhooks?

Het concept van een Webhook is simpeler dan het klinkt. Een Webhook is een HTTP (Hypertext Transfer Protocol) callback, een Webhook wordt gestimuleerd door een ‘event’ in een bronapplicatie en levert een actie op in een doelapplicatie. Webhooks worden ook wel eens als HTTP Push, web callback en ‘Reverse API’s’ beschreven. Door middel van Webhooks kan men waardevolle informatie verzamelen wanneer het ‘event’ plaatsvindt.

Hoe stel je een webhook in?

Via instellingen kan je webhook instellen, deze doet een POST naar de gewenste URL met de volgende body:

letter”: {

“id”: 1,

“mailbox_id”: 1,

“envelope_id”: 2,

“shipping_method_id”: 23,

“service”: “send”,

“status”: “sandbox”,

“color”: “full color”,

“printing”: “simplex”,

“paper_weight”: “80g”,

“paper_size”: “A4”,

“tracking_code”: null,

“formatted_id”: “PB10000016”,

“shipping_id”: 23,

“weight”: 13,

“pages”: 1,

“sheets”: 1

Bij iedere wijziging in een van deze variabelen zal er een nieuwe post gedaan worden.


Advies & Ondersteuning

Mocht je nog vragen hebben of is de expertise niet in huis om een koppeling te maken. Wij helpen je graag verder, neem contact op.

 






Stel een vraag



[recaptcha]

nieuwsbrief

Wil je op de hoogte blijven van de laatste ontwikkelingen, schrijf je dan in voor de nieuwsbrief.

Share
gerelateerde blogs

Postbode.nu Neem contact met ons op!