FastBill API

The interface for your projects and apps!

Fundamentals

Introduction

The FastBill API was created as an XML/JSON Web Service. All of its resources are operated by a central URL. All API requests are sent as POST requests with either an XML- or JSON-formatted Body to the Service-URL. These documents describe the communication in XML Format.

General Service-URL:

https://my.fastbill.com/api/1.0/api.php

Every request is encrypted with SSL when it is transmitted.


Authentication

Login to own acccount

The Standard-Authentication occurs through the existing FastBill User (E-Mail Address) und the API-Key of the respective FastBill Account. In this way, users have simple access to their own account.

API-Accesses are stateless; that means no sessions are saved. The email address and API-Key must be submitted for every request.

The authentication is conducted using HTTP Basic Authentication:

curl -v -X POST \
–u {E-Mail-Adresse}:{API-Key} \
-H 'Content-Type: application/xml' \
-d '{xml body}' \
https://my.fastbill.com/api/1.0/api.php

Login as a user

For providers of Add-ons or Mobile Apps, it is possible to conduct authentication using the email address and password of a current user. These external tools accept separate “Add-On Access Information” (their own E-Mail Address and API-Key). However, in order to authenticate the service, the users’ access information must be submitted separately.

API-Accesses are stateless; that means no sessions are saved. The access information for the Add-On, as well as the access information of the user, must be submitted for every request.

The Authentication is conducted using HTTP Basic Authentication, as well as additional HTTP Header-Data:

curl -v -X POST \
-u {E-Mail-Adresse}:{API-Key} \
-H 'X-Username: {E-Mail Adresse des Benutzers}'\
-H 'X-Password: {Passwort des Benutzers}' \
-H 'Content-Type: application/xml' \
-d '{xml body}' \
https://my.fastbill.com/api/1.0/api.php


Request structure

The header always inconcludes:

  • HTTP-Verb
  • Authentication
  • Content-Type

Example:

curl -v -X POST \
-u {E-Mail-Adresse}:{API-Key} \
-H 'Content-Type: application/xml' \
-d '{xml body}' \
https://my.fastbill.com/api/1.0/api.php

The body of a request / a response always follows the same pattern. The following compo-nents constitute the frameworks:

  • FBAPI: Main node, constitutes all XML-data (not necessary in JSON Format!)
  • SERVICE: The username that should be addressed on the Server
  • LIMIT: Parameter concerning the limit on the number of elements in the query of a list (Standard 10)
  • OFFSET: Parameter concerning the specification of the first element in the query of a list
  • FILTER: Parameter concerning the addressing/filtering of the respective resources
  • DATA: Data, that should be submitted for the designated action
  • REQUEST: returned, repeated input data
  • RESPONSE: returned resource data
  • ERRORS: returned errors

Example of a successful retrieval of data for a client:

Request

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
         <SERVICE>customer.get</SERVICE>
         <FILTER>
            <CUSTOMER_ID>5376</CUSTOMER_ID>
         </FILTER>
    </FBAPI>
                

Response

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
        <REQUEST>
            <SERVICE>customer.get</SERVICE>
            <FILTER>
               <CUSTOMER_ID>5376</CUSTOMER_ID>
            </FILTER>
        </REQUEST>
        <RESPONSE>
            <CUSTOMERS>
                <CUSTOMER>
                    ...
                </CUSTOMER>
            </CUSTOMERS>
        </RESPONSE>
    </FBAPI>
                

Example of a wrong declaration to create a new customer:

Request

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
         <SERVICE>customer.create</SERVICE>
         <DATA>
            ...
         </DATA>
    </FBAPI>
                

Response

    <?xml version="1.0" encoding="utf-8"?>
    <FBAPI>
        <REQUEST>
            <SERVICE>customer.create</SERVICE>
            <DATA>
               ...
            </DATA>
        </REQUEST>
        <RESPONSE>
            <ERRORS>
                <ERROR> ... </ERROR>
            </ERRORS>
        </RESPONSE>
    </FBAPI>
                

Further comments:

  • SERVICE: The username(e.g. customer, user, invoice, product)is written in lowercase letters, followed by a period and the method name (get, create, update, delete).
  • For the response, all information in the request (LIMIT,OFFSET,FILTER, DATA) will continue to be carried and expanded using the returns (RESPONSE, ERRORS)

Limitations

For security in case of unplanned peak demands or unintended infinite loops, the number of API-Accesses per user will be limited to 1000 per minute.

The maximum number of calls depends on your subscription - 100 calls/h (Starter), 1000 calls/h (Pro), 2500 calls/h (ProMax).

However, the maximum number of elements for the retrieval is 100.

support@fastbill.com
© 2016 FastBill GmbH