Page tree
Skip to end of metadata
Go to start of metadata

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:

Timestamps are handled in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ssXXX in Java)

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 headers in every request to authorize against our service:

Header variable namevalue
api-key{your api key - see project settings in the backoffice}

Resources Overview

URLGETPOSTPUTPATCHDELETE
/Customers

(tick) retrieve all customers

Filter parameters:

  • email
  • firstName
  • lastName
  • companyName

Filter example:

/Customers?email=info@customer.com

(tick) create a new customer(minus)(minus)(minus)
/Customers/:CustomerNumber(tick) retrieve one customer(minus)(warning) update existing customer
(warning)
/Customers/:CustomerNumber/Contracts(tick) retrieve all contracts for a customer(minus)(minus)(minus)(minus)
/Contracts(tick) retrieve all contracts(tick) create a new contract


/Contracts/:ContractNumber(tick) retrieve one contract(minus)(warning) update existing contract

/Contracts/:ContractNumber/Activities(tick) retrieve all activities for a given contract(tick) create a new activity record for a contract


/Contracts/:ContractNumber/Subscription(tick) retrieve the subscription for a contract(tick) create a new subscription for a contract


/Invoices(tick) retrieve all invoices(minus)(minus)(minus)(minus)
/Invoices/:InvoiceNumber(tick) retrieve a single invoice(minus)(minus)(minus)(minus)
/Invoices/:InvoiceNumber/Document(tick) retrieve the invoice PDF document (Base64 encoded binary)(minus)(minus)(minus)(minus)
/InvoiceCorrections(tick) retrieve all invoice corrections(minus)(minus)(minus)(minus)
/InvoiceCorrections/:InvoiceCorrectionNumber(tick) retrieve a single invoice correction(minus)(minus)(minus)(minus)
/InvoiceCorrections/:InvoiceCorrectionNumber/Document(tick) retrieve the invoice correction PDF document (Base64 encoded)(minus)(minus)(minus)(minus)
/Projects(tick) retrieve all projects



(tick) available
(warning) in development / planned
(minus) not available

Errors

The API returns standard HTTP status codes to indicate that something went wrong.

Status codePossible reasons
400 Bad RequestYou have sent an invalid JSON format or invalid data. Validation errors will be printed into the body of the response.
404 Not FoundThe request resource could not be found
500 Internal Server ErrorWe 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.

EnumValuesUsage example
TimeUnit

DAY
WEEK
MONTH
YEAR

Due period for customer
SalutationMR
MRS
COMPANY
Salutation of customer
PaymentMethodBANKTRANSFER
PAYPAL
MONEYBOOKERS
SOFORTUEBERWEISUNG
SEPA_DEBIT
CREDITCARD
Type of payment for customer or contract
ItemUnitPIECE
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
    }

POST /Contracts/:ContractNumber/Activities

Create a new activity entry for a given contract.

if you want to override the system price set a value for 'individualPrice'


Example request:

{
        "itemNumber": "item002",
        "quantity": 1,
        "individualPrice": null,
        "description": "additional information",
        "performanceDateStart": "2016-11-16T00:00:00Z",
        "performanceDateEnd": null
    }

POST /Contracts/:ContractNumber/Subscription

Create a new subscription for a existing contract without subscription.

Example request:

{           "termPeriod": 1,
            "termUnit": "MONTH",
            "noticePeriod": 4,
            "noticeUnit": "WEEK",
            "continuePeriod": 1,
            "continueUnit": "MONTH",
            "billedInAdvance": true,
            "subscriptionItems": [{
                    "quantity": 1,
                    "extraDescription": "",
                    "itemNumber": "item001"
                }
            ]
             
}



Write a comment…