EN NL FR

INTEGREREN MET POSTBIRD ?

Volg onderstaande documentatie om de integratiemogelijkheden te ontdekken.

1. Introductie

Postbird is gebaseerd op het Ecerium Elements microservices platform en biedt een aantal verschillende manieren van integratie aan. Onderstaand document geeft een overzicht van de verschillende integratiemogelijkheden en details van elke mogelijkheid

2. Drie manieren van integratie

Momenteel bieden wij 3 manieren aan om te integreren met de Postbird applicatie. Hieronder vind je de use cases van elk.

Wie betaalt Integreer via Integratie complexiteit
Postbird klant Klant Desktop applicatie Laag
Api Integrator Account Integrator REST call Medium
E-mail Integrator Account Integrator E-Mail Laag

2.1 De Postbird Desktop applicatie gebruiken

Software die op de computer van de klant wordt uitgevoerd kan de mogelijkheid bieden om een PDF document op te slaan in de verwerkings directory van Postbird. De Postbird klant zal het PDF document ophalen en verwerken.

Vereisten

  • De software moet worden uitgevoerd op de computer van de klant
  • De klant moet de Postbird klant applicatie hebben geïnstalleerd
  • De Postbird klant applicatie moet uitgevoerd worden
  • Het verzenden van het document wordt beheerd door de gebruikersaccount van de klant en is afhankelijk van de voorziene balans van de account

Integratie complexiteit

Laag

2.2 De Postbird API gebruiken

Postbird heeft een API ontwikkeld (zie documentatie in het hoofdstuk over de API referentie) die kan gebruikt worden om te integreren met eender welke applicatie.


Een algemeen integratiescenario zou zijn dat u een Postbird account aanmaakt en dat uw applicatie deze account zal gebruiken. In dat geval moet u er altijd voor zorgen dat u voldoende geld op uw account voorziet. Uw klanten kunnen de diensten die uw applicatie aanbiedt gebruiken. En uw applicatie kan op zijn beurt ook Postbird gebruiken. Of, en hoeveel u aanrekent voor het gebruik van onze diensten valt volledig onder uw eigen verantwoordelijkheid.

Vereisten

  • U moet een Postbird account aanmaken en een applicatie definiëren
  • U moet een applicatie token aanmaken dat u kan gebruiken voor het communiceren met Postbird
  • U moet de API gebruiken om uw applicatie te integreren met Postbird

Integratie complexiteit

Medium

2.3 E-mail gebruiken met het account van de integrator

U kan simpelweg een Postbird account aanmaken en de e-mail feature inschakelen. U kan het specifieke e-mail adres gebruiken en het gebruiken als bestemmingsadres voor een e-mail met de bijgevoegde PDF (zie e-mail integratie verder in dit document).

Vereisten

  • U moet een Postbird account aanmaken en de e-mail feature inschakelen (de balans van dit Postbird account zal worden gebruikt)
  • Uw applicatie moet de PDF verzenden als bijlage naar dit e-mail adres

Integratie complexiteit

Laag

3 De integratie uitvoeren

Hieronder vind je de beschrijving om op één van de opgegeven mogelijkheden te integreren met Postbird.
Zijn er nog onduidelijkheden? Dan mag je ons altijd mailen via i.want.to.integrate@postbird.be

 

3.1 Desktop applicatie installeren

Download de applicatie van Postbird onderaan op onze homepagina of log je in via jouw persoonlijke account en klik in de balk op 'Desktop App' om deze te downloaden. Installeer vervolgens de applicatie en ga aan de slag! 

3.2 Connecteer via onze API


De swagger documentatie en uitleg over onze API vind je op https://api-prd2.postbird.be/swagger/ui/index

 

  • The first step

Go to our identity server (https://login-prd2.ecerium.be/Manage) and select integration Token.

  • The second step

Create a Token, select a name and enter your password for security reasons.


 

  • Almost there…

Make sure your token is now available in the Active Token section.

  • The Call:                                                                                             

POST 
https://api-prd2.postbird.be/integration/sendMyDocument
Content-Type: application/jsoncache-control: no-cache
Authorization: Bearer a626e76d73547c68555e969168f4bc3d1f08aac00a3233a14ca1c7692a6a79b5
Accept: */*
Host: api-prd2.postbird.be
accept-encoding: gzip, deflate
content-length: 55854
Connection: keep-alive

 
{

  "attachment": {

    "fileName": "string",

    "base64Content": "string"

  },

  "config": {

    "color": true,

    "rectoVerso": true,

    "registered": true,

    "selectedSendMethod": "overWriteAddressField",

    "address": {

      "recipientName": "Homer Simpson",

      "street": "Evergreen Terrace",

      "houseNumber": "742",

      "postcode": "65806",

      "city": "Springfield",

      "isoCountryCode": "BE"

    }

  }

}

Attachment section

filename:                                 the name of your pdf file (myLetter.pdf)

base64Content:                      the content of your pdf file (encoded as base64)

 

Config section

color:                                       document printed in color (true/false)

rectoVerso:                             document printed on both sides of a page (true/false)

registered:                              do you want your letter to be delivered

                                                 registered (true/false)

 

selectedSendMethod (optional)        

  1. normal (send letter as seen in pdf) ,
  2. addWhitePage (add a white cover page with the address printed on the correct position, this will cost you an extra page)
  3. overWriteAddressField (add a white textbox with the address provided on the correct position this will overwrite any text or image in that position)

 

Address Section (optional, unless selectedSendMethod is addWhitePage or overWriteAddressField)

 recipientName                    First and last name of recipient                         

 street                                   Street name

 houseNumber                    House number

 postcode                             Postal code

 city                                       City

 isoCountryCode                  Iso country code, two characters

                                                 (https://nl.wikipedia.org/wiki/ISO_3166-1)

 

  • API

If you want to check our documentation on our API: https://api-prd2.postbird.be/swagger/ui/index

3.3 Verstuur een brief via email

 

  • Create an account on Postbird

Go to https://webapp.postbird.be/ and create your own account on Postbird. Charge your account with a sufficient amount in order to send letters. If there is not enough credit available, the letters won’t be sent.

 

  •  Set up an IMAP mailbox

Make sure you have a mailbox which supports IMAP. This is possible with your own mail provider, but also with tools like Gmail. This mailbox will only be used for receiving the letters. Postbird will scan the inbox every 15 minutes and search for letters in order to send them. The daily deadline for processing is 16h30.

TIP: Use an isolated email address and not a frequently used one! Postbird will automatically import all mails and will transfer them to a separate folder in the inbox.

If you’re using Gmail:

  • Switch on IMAP (Settings – Forwarding and POP/IMAP - Select IMAP
  • Allow user and password authentication for IMAP (Settings – Accounts and Import – other Settings Google account – Security – Apps accessing your account – Allow apps with lower security – “Allow”)

 

  • The startup
  1. Go to our identity server ( https://login-prd2.ecerium.be/Manage ) and select integration Token.



  1. Create a Token, select a name and enter your password of the Postbird account for security reasons.

       

  

  1. Make sure your token is now available in the Active Token section.

       

  1. Go to your personal Postbird account in the web application and click on
    My Postbird – Settings.

Fill in the fields with the requested data:

  • The mail address of the IMAP account
  • The integration token (see above)
  • Choose your sending options
  • The mailbox configuration (For Gmail: Settings – Forwarding and POP/IMAP – IMAP access – More information – Step 2)
  • Fill once again in the email address and its password.
  • Click on save!

 

 

  • Format of the files

Postbird only recognizes PDF-files format A4 with the receiver information in the right position for window envelopes (top right). Consult this attachment for the exact position of the receiver data. Our service will automatically read out the address in the PDF-file.  

 

  • Sending a letter

Send your PDF-file to the email address. After maximum 15 minutes you will see in your personal dashboard that the letter is ready for sending.