Freemle REST API documentatie

Deze documentatie is bedoeld voor ontwikkelaars van applicaties die met Freemle.com willen koppelen. De REST API is alleen beschikbaar voor klanten met een Pro Wow abonnement. Vooralsnog kan iedereen een koppeling maken, we stellen het wel op prijs als je ons laat weten dat je een koppeling gaat maken. Dan kunnen we je applicatie ook op onze website noemen. Daarnaast is er een test omgeving beschikbaar om de integratie te testen. Wil je toegang tot de testomgeving of heb je andere vragen stuur ons dan een e-mail.

Ontwikkel je een Ruby (on Rails) applicatie? Dan is er naast de REST API is er ook een Ruby gem beschikbaar.
Zie Freemle op Rubygems en Github.

Beschrijving REST API

Autorisatie en authenticatie

De Freemle API is alleen beschikbaar voor klanten met een Pro Wow abonnement. Alle urls voor de Freemle API starten met https://www.freemle.com/api. Bij elk request moet er een Basic Authentication header worden mee gestuurd met daarin de Base64 encoded waarde van de 'applicatie naam:api key' die je kunt aanmaken bij je profiel.

Voorbeeld

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Algemene statuscodes
Status Uitleg
400 Treedt op indien de invoer ongeldig is. Bijvoorbeeld een verplicht veld vergeten, of een veld is in het verkeerde formaat. De response body bevat extra informatie indien mogelijk: {"errors": {"delivery_period": {"code": "invalid"}}}
401 Authenticatie header ontbreekt of api key en app name zijn ongeldig.
403 Gebruiker heeft geen pro wow abonnement.
Operaties

Klanten zoeken

GET /customers
Parameters
Naam Uitleg
query (Gedeelte van de) naam van het bedrijf
Resultaat

Status 200 en een lijst van customers in JSON formaat.

      {"customers": [{"finance_company_name": "Naam",
                      "finance_address_street": "Paleisstraat 1",
                      "finance_address_city": "Amsterdam",
                      "finance_address_postal_code": "1000AA",
                      "finance_address_country_code": "NL",
                      "finance_address_country_name": "Nederland",
                      "finance_attn": "Financiële afdeling",
                      "finance_email": "finance@localhost.local",
                      "finance_extra_information": "Optionele extra informatie voor deze klant",
                      "customer_id": "unique identifier van de klant",
                      "vat_number": "BTW nummer van de klant",
                      "payment_term": 14
                    }]}
                  

Klant aanmaken

POST /customers
De request body dient de volgende JSON data te bevatten
      {"customer": {"company_name": "Bedrijfsnaam, verplicht",
                    "attn": "Ter attentie van, optioneel",
                    "email": "E-mail adres, optioneel",
                    "extra_information": "Extra informatie over de klant, optioneel",
                    "address": {"street": "Straat, verplicht",
                              "postal_code": "Postcode, verplicht",
                              "city": "Plaats, verplicht",
                              "country_code": "Tweecijferige landcode, verplicht"
                              }
                  }}
                  
Resultaat

Statuscode 201 en de ID van de aangemaakte klant.

      {"customer_id": "ID van de aangemaakte klant"}
                  

Factuur aanmaken

POST /invoices
De request body dient de volgende JSON data te bevatten
      {"invoice":
        {
          "customer_id": "ID van de klant aan wie de factuur is gericht, optioneel",
          "delivery_period": "Datumlevering, optioneel, formaat: DD-MM-YYYY",
          "reference": "Referentie, optioneel",
          "line_items": [
            {"vat": "BTW percentage, verplicht, formaat: Getal (voorbeeld: 21)",
             "amount": "Bedrag fatuurregel, verplicht, formaat: Getal (voorbeeld: 1359.50)",
             "quantity": "Aantal, verplicht, formaat: Getal",
             "description": "Beschrijving, verplicht"}
          ]
        }
      }
                  
Resultaat

Statuscode 201 en de ID van de aangemaakte factuur.

      {"invoice_id": "ID van de aangemaakte factuur"}