EN NL FR

INTEGREREN MET POSTBIRD ?

Volg onderstaande documentatie om de integratiemogelijkheden te ontdekken.

1. Introductie

Postbird is gebaseerd op het Ecerium 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. 8 manieren van integratie

Momenteel bieden wij 8 manieren aan om te integreren met de Postbird applicatie. Hieronder vindt u de use cases van elk.

Wie betaalt Applicatie type Integratie complexiteit
Postbird klant Klant Desktop Laag
Api Integrator Account Integrator Elke Medium
Api Klant Account Klant Elke Medium
Javascript Integrator Account Integrator Web Laag
Javascript Klant Account Klant Web Laag
E-mail Integrator Account Integrator Elke Laag
E-mail Klant Account Klant Elke Laag
Postbird App Klant APP Laag

2.1 De Postbird klant 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 werken
  • Het verzenden van het document moet worden beheerd door de gebruikersaccount en zijn/haar balans.

Integratie complexiteit

Laag

2.2 De Postbird API met integrator account gebruiken

Postbird heeft een API (zie documentatie in het hoofdstuk over de API referentie) dat 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 dit account zal gebruiken. In dat geval moet u er altijd voor zorgen dat u genoeg geld op uw account hebt. Uw klanten kunnen dan de diensten die uw applicatie aanbiedt gebruiken, dat op zijn beurt ook Postbird gebruikt. Of, en hoeveel u aanrekent voor alle 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 De Postbird API gebruiken met het account van de klant

Postbird heeft een API (zie documentatie in het hoofdstuk over de API referentie) dat gebruikt kan worden om te integreren met eender welke applicatie. Een algemeen integratiescenario zou zijn dat u het Postbird account van uw klanten gebruikt. Betaling voor de Postbird diensten zal onmiddellijk worden aangerekend aan uw klant.

Vereisten

  • U maakt een Postbird account aan en definieert een applicatie (de balans van deze account zal niet worden gebruikt)
  • U zal een applicatie token aanmaken dat u gebruikt om te communiceren met Postbird
  • Uw klant moet een Postbird account aanmaken
  • Uw klant moet uw applicatie toestaan om zijn Postbird balans te raadplegen (maak inlogtoken aan)
  • Uw klant moet de inlogtoken ingeven richting zijn Postbird account in uw applicatie
  • U gebruikt de API om uw applicatie te integreren met Postbird door gebruik te maken van het inlogtoken voorzien door uw klant

Integratie complexiteit

Medium

2.4 Een Javascript snippet gebruiken met account van de klant

Webapplicaties kunnen een Javascript snippet gebruiken (zie documentatie onder Javascript snippet referentie) als een erg gemakkelijke manier van integratie. Een algemeen scenario zou zijn dat uw webapplicatie een PDF document genereert dat beschikbaar is door het gebruiken van een toegewijde URL. Simpelweg door het snippet toe te voegen aan de klantcode van uw webapplicaties zal een Postbird knop toegevoegd worden aan uw webapplicatie. Bij het klikken op de knop zal de Postbird applicatie worden geopend, wat de gebruiker zal toestaan het PDF document te verzenden door Postbird te gebruiken.

Vereisten

  • U maakt een Postbird account aan en definieert een applicatie (de balans van dit account zal niet worden gebruikt)
  • U voegt een codesnippet toe aan uw webapplicatie
  • Uw klant maakt een Postbird account aan

Integratie complexiteit

Laag

2.5 Een Javascript snippet gebruiken met het account van de integrator

Webapplicaties kunnen een Javascript snippet gebruiken (zie documentatie onder de Javascript referentie) als een erg gemakkelijke vorm van integratie. Een algemeen scenario zou zijn dat uw webapplicatie een PDF document genereert dat beschikbaar is door het gebruiken van een toegewijde URL. Simpelweg door het toevoegen van het snippet aan de klantcode van uw webapplicaties zal een Postbird knop worden toegevoegd aan uw webapplicatie. Bij het klikken op deze knop zal de Postbird applicatie worden geopend, wat de gebruiker in staat stelt het PDF document te verzenden door Postbird te gebruiken.

Vereisten

  • U maakt een Postbird account aan en definieert een applicatie (de balans van dit account zal worden gebruikt)
  • U voegt een codesnippet toe aan uw webapplicatie

Integratie complexiteit

Laag

2.6 De Android/IOS app gebruiken

De Android/IOS apps kunnen de feature ‘delen’ gebruiken om PDF files te delen. Een klant dat de Postbird app op zijn/haar toestel heeft geïnstalleerd kan het dan gebruiken om brieven te verzenden.

Vereisten

  • Uw app moet de feature ‘delen’ inschakelen voor het gespecifieerde apparaat (Android/IOS)
  • Uw klant moet de Postbird app geïnstalleerd hebben en moet een Postbird account aanmaken

Integratie complexiteit

Laag

2.7 E-mail gebruiken met het account van de klant

Als uw applicatie de gebruiker toestaat een specifiek e-mail adres in te geven voor het ontvangen van de gegenereerde PDF file, kan de gebruiker onze e-mail feature gebruiken om PDF’s te verzenden via Postbird (zie e-mail integratie verder in dit document).

Vereisten

  • Uw applicatie moet de mogelijkheid aanbieden om de PDF naar een specifiek e-mail adres te verzenden
  • Uw klant moet een Postbird account aanmaken en de e-mail feature inschakelen

Integratie complexiteit

Laag

2.8 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 deze Postbird account zal worden gebruikt)
  • Uw applicatie moet de PDF verzenden als bijlage naar dit e-mail adres

Uw applicatie moet de PDF verzenden als bijlage naar dit e-mail adres Integratie complexiteit

Laag

3 APi Reference

The Postbird API is based on REST. This documentation lists and describes the individual resources you can use to manipulate objects on the Postbird platform.

3.1 Typical Server Responses

200 OK The request was successful (some API calls may return 201 instead).
201 Created The request was successful and a resource was created.
204 No Content The request was successful but there is no representation to return (that is, the response is empty).
400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or user does not have permissions for the requested operation.
403 Forbidden Access denied.
404 Not found Resource was not found.
405 Method Not Allowed Requested method is not supported for the specified resource.
429 Too Many Requests Exceeded Postbird API limits.
503 Service Unavailable The service is temporary unavailable.

3.2 Live Documentation

Live and interactive documentation of the APi is provided with swagger on the following URL:

https://api-prd2.postbird.be/swagger

3.3 Options to connect

Live and interactive documentation of the APi is provided with swagger on the following URL:

Postbird Api Security Token Server

3.3.1 Using your own identity token

After you have created an account on the Postbird Identity Server you receive a username/password combination. With these credentials you can request a token from the API.  It is the user’s responsibility to have money available on his account before he starts to make calls.  Also it’s his responsible to recover his costs on his customers.

3.3.2 Using your customers token

Another option is to use a token granted to you by one of your customers. In that case your customer is responsible to have money on his account.

3.3.3 Using a JavaScript hook

This feature is currently announced but not yet available.

3.4 Uploading a document

3.4.1 Obtaining a token

Authorize yourself to the Postbird Identity Server.

                            
                                    public static async Task GetAuthorizationToken()
                                    {
                                        var tokenClient = new TokenClient($"https://login-dev2.ecerium.be/connect/token", "postbird-integration-test", AuthenticationStyle.PostValues);
                                        var tokenResponse = await tokenClient.RequestResourceOwnerPasswordAsync("tester", "secret", "service.postbird");
                                     
                                        return tokenResponse.AccessToken;
                                    }
                                
                            

3.4.2 Using the token

Use the bearer token in the header for all calls to the Postbird platform.

                            
                                    var result = await HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Get, $"document/all?{query}")
                                    {
                                        Headers = { { "Authorization", $"Bearer {await GetAuthorizationToken()}" } }
                                    });
                                
                            

3.4.3 Start uploading documents

After obtaining the bearer token you can upload a document to the server.  There a few scenario’s that you can follow.

3.4.3.1 1 document and 1 recipient

This is when you want to send 1 document to 1 recipient.

                                
                                    var result = await PostDocument(File.ReadAllBytes(Path.Combine(TestContext.CurrentContext.TestDirectory,
                                                 @"Files\MoreThen65Pages.pdf")), null,
                                                 new List()
                                                 {
                                                        new CreateRecipientModel()
                                                        {
                                     
                                                            AddressLines =   new AddressLinesModel()
                                                            {
                                                                Line1 = "",
                                                                Line2 = "",
                                                                Line3 = "",
                                                            },
                                                            StartsOnPage = 1,
                                                            TotalPages =  67,
                                                            EndsOnpage = 67
                                                        }
                                                 }, 67, 67, false, true);
                                
                            
                            
                                    private async Task PostDocument(byte[] byteData, string base64Data, List recipients,
                                        int totalPages, int pagesPerDocument, bool multiplePages, bool documentsAligned)
                                    {
                                        var data = new UploadDocumentModel
                                        {
                                            Document = new CreateDocumentModel
                                            {
                                                Data = byteData,
                                                Base64Data = base64Data,
                                                Name = "Foo",
                                                Pages = totalPages,
                                                ContainsMultipleDocuments = multiplePages,
                                                PagesPerDocument = pagesPerDocument,
                                                PagesPerDocumentAligned = documentsAligned,
                                                RegisteredMail = false,
                                                Recipients = recipients,
                                                PrintSettings = new CreatePrintSettingsModel()
                                                {
                                                    Color = false,
                                                    Copies = 1,
                                                    Price = 1.23M,
                                                    RectoVerso = false
                                                }
                                            }
                                        };
                                     
                                        var content = new StringContent(JsonConvert.SerializeObject(data), Encoding.Default, "application/json");
                                        var request = new HttpRequestMessage(HttpMethod.Post, "document")
                                        {
                                            Content = content
                                        };
                                     
                                        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", await GetAuthorizationToken());
                                        return await HttpClient.SendAsync(request);
                                    }
                                
                            
3.4.3.2 1 document and N recipients

This is when you want to send 1 document to multiple recipients.

3.4.3.3 N documents and N recipients

This is when you want to send multiple documents to multiple recipients.

3.4.3.4 Rules and validations

This is when you want to send multiple documents to multiple recipients.

3.4.3.4.1 Pages aligned

pages aligned (every pdf for every recipient contains the same amount of pages)

3.4.3.4.2 Pages not aligned

Pages not aligned (the amount of pages is different for each person), this must be set in the recipient data

3.4.3.4.3 Model contains address information

Model contains address data, this data must be structured address data (PUT address/parse can be used to validate address data) , important if your address data is not in the correct zone, a divider page + cost is added

use address lines to input unstructured address info (server will parse it to a structured address)

use Address / Person property when you have a structure address

3.4.3.4.4 Returning a 301

Return a 301 with a location header, here you can find the id of your document

3.4.3.4.5 Validate

This will validate a certain document (you can use the GetDocument with UnverifiedDocumentsOnly=true option to get your unvalidated documents) (PUT /document/{id}/validate)

Send

This will send a 'validated' document to be processed for sending (you can use the GetDocument with UnsendDocumentsOnly=true option to get your unsend documents) => this will also check if you have sufficient balance ! (PUT /document/{id}/send)

3.5 Receiving all documents

Document/all (with GetDocumentsModel in uri parameters).

                            
                                    private async Task> GetDocuments(string query)
                                    {
                                        var result = await HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Get, $"document/all?{query}")
                                        {
                                            Headers = { { "Authorization", $"Bearer {await GetAuthorizationToken()}" } }
                                        });

                                        var responseString = await result.Content.ReadAsStringAsync();
                                        var documents = JsonConvert.DeserializeObject>(responseString).Items;

                                        Assert.IsTrue(result.StatusCode == HttpStatusCode.OK);

                                        return documents;
                                    }
                                
                            

3.6 Receiving a document

GET document/{id} → raw data.

GET document/{id}/pdf → original pdf.

GET document/{id}/pdf/altered → pdf after validation (can contain a divider page, is responsible for b/w converting).

3.7 Removing a document

DELETE document/{id}.

3.8 Calculating the cost

PUT price/simulate (+model) (you can calculate the cost of your document processing)

                            
                                    var result = await HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Get, $"price/packs/{path}")
                                    {
                                    });
                                     
                                    var responseString = await result.Content.ReadAsStringAsync();
                                    var packs = JsonConvert.DeserializeObject>(responseString);

                                    Assert.IsTrue(result.StatusCode == HttpStatusCode.OK);
                                    Assert.Equals(packs.Count(), 3);