The Fakturia API is an open interface using the REST standard. It allows developers to directly interact with our application via HTTPS exchanging data in the JSON format.
Endpoint for all API calls: https://api.fakturia.de/v1/
Prerequisites
The API can only be accessed if the following conditions are true:
- Your Fakturia plan includes API access
- The API is activated in the backend for at least one project
- An API-Key has been generated in the backend
- The IP address of your client has been added to the IP whitelist for the project
Authorization
Include the following HTTP-Header variables in every request to authorize against our service:
| Header variable name | value |
|---|---|
| api-key | {your api key - see project settings in the backoffice} |
Resources Overview
| URL | GET | POST | PUT | PATCH | DELETE | Status |
|---|---|---|---|---|---|---|
| /Customers | retrieve all customers | create a new customer |  | |||
| /Customers/:CustomerNumber | retrieve one customer | udpate existing customer  | | |||
| /Customers/:CustomerNumber/Contracts | get all contracts for a customer | | ||||
| /Contracts | get all contracts | create a new contract |
| |||
| /Contracts/:ContractNumber | retrieve one contract | update existing contract | | |||
| /Contracts/:ContractNumber/Activities | get all activities for a given contract | create a new activity record for a contract | | |||
| /Contracts/:ContractNumber/Subscription | get the subscription for a contract | create a new subscription for a contract | | |||
| /Invoices | retrieve all invoices | | ||||
| /Projects | retrieve all projects | |
Errors
The API returns standard HTTP status codes to indicate that something went wrong.
| Status code | Possible reasons |
|---|---|
| 400 Bad Request | You have sent an invalid JSON format or invalid data. Validation errors will be printed into the body of the response. |
| 404 Not Found | The request resource could not be found |
| 500 Internal Server Error | We got the correct data but the server got an unknown error while processing your request. You will find detailed information about the error in the body of the response. |
Example error result:
{"errorKey":"INCORRECT_INPUT_DATA","errorMessage":"invalid item number: xd004"}
ENum Values
All possible values of our Enum types are described here.
| Enum | Values | Usage example |
|---|---|---|
| TimeUnit | DAY | Due period for customer |
| Salutation | MR MRS COMPANY | Salutation of customer |
| PaymentMethod | BANKTRANSFER PAYPAL MONEYBOOKERS SOFORTUEBERWEISUNG SEPA_DEBIT | Type of payment for customer or contract |
| ItemUnit | PIECE DAY WEEK MONTH YEAR | unit of a item, e.g. fee per MONTH |
Resource Reference
POST /Customers
Create a new customer.
Example request:
{
"salutation": "MR",
"firstName": "John",
"lastName": "Doe",
"companyName": "MegaCorp",
"locale": "de_DE",
"websiteUri": "",
"phone1": "+49 89 224433",
"phone2": "",
"telefax": "",
"mobile": "",
"email": "info@megacorp.com",
"birthdate": "1980-11-02",
"euTaxId": "",
"taxNumber": "",
"noteText": null,
"postalAddress": null,
"billingAddress": {
"addressLine1": "Arlington Road 1",
"addressLine2": "",
"addressLine3": "",
"zipCode": "80333",
"cityName": "Example Town",
"state": "",
"country": "DE"
},
"paymentMethod": null,
"emailInvoice": "",
"taxRegion": "NATIONAL",
"duePeriod": "0",
"dueUnit": "DAY"
}
POST /Contracts
Create a new contract for a customer. Adding a subscription is optional.
accountNumber only required if multiple accounts for customer exist.
Example request with subscription:
{
"accountNumber": 2,
"customerNumber": "CUST1001",
"projectName": "Projekt1",
"subscription": {
"termPeriod": 1,
"termUnit": "MONTH",
"noticePeriod": 4,
"noticeUnit": "WEEK",
"continuePeriod": 1,
"continueUnit": "MONTH",
"billedInAdvance": true,
"subscriptionItems": [{
"quantity": 1,
"extraDescription": "",
"itemNumber": "item001"
}
]
},
"issueDate": "2016-11-14",
"recur": 6,
"recurUnit": "MONTH",
"duePeriod": null,
"dueUnit": null,
"paymentMethod": null
}