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.
Info |
---|
Endpoint for all API calls: https://api.fakturia.de/v1/ Timestamps are handled in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ssXXX in Java) |
...
Include the following HTTP -Header variables headers 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 |
---|---|---|---|---|---|
/Customers | retrieve all customers Filter parameters:
Filter example: /Customers?email=info@customer.com | create a new customer |
/Customers/:CustomerNumber |
retrieve one customer |
update existing customer |
/Customers/:CustomerNumber/Contracts |
retrieve all contracts for a customer |
/Contracts |
retrieve all contracts | create a new contract |
/Contracts/:ContractNumber | retrieve one contract |
update existing contract |
/Contracts/:ContractNumber/Activities |
retrieve all activities for a given contract | create a new activity record for a contract |
/Contracts/:ContractNumber/Subscription |
retrieve the subscription for a contract | create a new subscription for a contract |
/Invoices |
retrieve all invoices |
/Invoices/:InvoiceNumber |
retrieve a single invoice |
/Invoices/:InvoiceNumber/Document |
retrieve the invoice PDF document ( |
Base64 encoded binary) |
/ |
InvoiceCorrections | retrieve all |
invoice corrections | |||||
/InvoiceCorrections/:InvoiceCorrectionNumber | retrieve a single invoice correction | ||||
/InvoiceCorrections/:InvoiceCorrectionNumber/Document | retrieve the invoice correction PDF document (Base64 encoded) | ||||
/Projects | retrieve all projects |
available
in development
not available ist verfügbar In Planung / Entwicklung
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:
Code Block |
---|
{"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
...
Code Block |
---|
{ "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.
Info |
---|
accountNumber only required if multiple accounts for customer exist. |
Example request with subscription:
...
Info |
---|
if you want to override the system price set a value for 'individualPrice' |
Example request:
Code Block |
---|
{ "itemNumber": "item002", "quantity": 1, "individualPrice": null, "description": "additional information", "performanceDateStart": "2016-11-16T00:00:00Z", "performanceDateEnd": null } |
...
Code Block |
---|
{ "termPeriod": 1, "termUnit": "MONTH", "noticePeriod": 4, "noticeUnit": "WEEK", "continuePeriod": 1, "continueUnit": "MONTH", "billedInAdvance": true, "subscriptionItems": [{ "quantity": 1, "extraDescription": "", "itemNumber": "item001" } ] } |
...