The Profifact service provides automated access to a subset of the data and operations provided
by the Profifact application. Access is granted on a per user account basis and only if
explicitly requested by the user. This document describes the structure of the Profifact service
and how users may implement a client to take advantage of its features.
Access to the Profifact service can be requested by calling the Profifact support desk or by
sending an email to info@profifact.nl from a known email
address such as the client's username. A fee may be required for access to the Profifact
service.
Profifact reserves the right to deny any request for access to its services without explanation.
Access may be revoked at any time if so decided by Profifact. On revocation the client is
notified.
Service implementation
The Profifact service is accessible at https://api.profifact.nl/ over HTTPS only. Resources
are accessible by appending the names of the resources to that URL. HTTP headers and status
codes are used to communicate metadata such as authentication information, supported content
types and operation result types. Data is returned in response bodies and request parameters may
be appended to request URLs for modifying result sets. Each resource may implement HTTP GET,
POST, PUT and DELETE requests where such request methods are permitted and useful to clients.
Request methods
The operation performed by the Profifact service depends on the HTTP request method specified by
a client. The following table lists possible request methods and their associated operations:
HTTP request method
Relative URL
Description
GET
/resource
Retrieves the set of all instances of the specified resource accessible to the
client. The set of properties returned for each instance may differ from the set of
properties returned when retrieving an individual instance. The Profifact service
usually returns only those properties that may be useful when results are shown in
table form. Request parameters may be provided to filter and sort the result set.
GET
/resource/id
Retrieves the single resource identified by the specified ID. The set of properties
returned is intended to provide a full view of the instance and may include
instances of other resource types (e.g. retrieving a single invoice also returns all
payments added for that invoice).
POST
/resource
Creates a new instance of the specified resource type and returns it. POST requests
are not idempotent, meaning that each POST request creates a new instance.
Property values for the new instance must be provided in the request body.
Properties with meaningful default values are optional.
PUT
/resource/id
Updates the properties of the resource identified by the specified ID and returns
it. PUT requests are idempotent, meaning that multiple identical requests do not
change the state of the resource beyond the initial change.
Updated values for the properties of the identified instance must be provided in the
request body. Only those properties of the instance for which values are provided by
the client are updated (e.g. to change the status of an invoice, only the new status
has to be provided and all other values may be omitted).
DELETE
/resource/id
Deletes the resource identified by the specified ID. Like PUT requests, DELETE
requests are idempotent. Multiple identical DELETE requests have exactly the same
effect. As such, deleting a non-existing resource is always successful.
Not every request method is implemented for every resource, because the associated operations may
not be permitted or useful to clients. The vatrates resource, for example, implements
only GET /vatrates and returns HTTP status 405 Method Not Allowed for all
other request methods. VAT rates are controlled by Profifact and should be considered read only by
clients. In other cases, request methods may simply not be implemented yet. Some request methods may
never be implemented, because they are usually modified manually using the Profifact application
(e.g. billing settings and templates).
Request headers
There are several HTTP request headers with a special purpose.
Name
Description
Accept
As defined in RFC 7231 section 5.3.2,
notifies the server of the media types accepted by the client. The Profifact service
ignores quality parameters and assumes the specified media types are in order of
importance. If no Accept header is present, the service assumes the client accepts
the default media type for the requested operation (usually application/json). If
the client provides an Accept header the service cannot satisfy HTTP status code
406 Not Acceptable is returned.
This header is important when the client is trying to retrieve data in formats other
than the default. E.g. /invoices/77 returns a PDF representation of invoice
77 instead the default JSON representation if the client provides an Accept header
specifying application/pdf.
Authorization
As defined in RFC 7235 section 4.2,
provides authentication information for the request. The Profifact service supports
only basic authentication.
The use of the Authorization header is described in the section on
authentication.
Content-Type
As defined in RFC 7231 section 3.1.1.5,
provides the media type of the content sent by the client. This header must be
present when the client is sending content to the Profifact service (e.g. in a POST
or PUT request). If the media type specified is not supported by the service, HTTP
status code 415 Unsupported Media Type is returned. Currently only
application/json is supported for content sent by clients.
X-Profifact-Euid
An optional header that allows Profifact providers and resellers to make
calls to the Profifact service on behalf of their users. The header
specifies the unique ID of the user on whose behalf the caller performs the
current request (i.e. the effective user Id or EUID). When specified by a
client that has authenticated itself as a provider or reseller, the request
is handled exactly as if it were made by the user whose ID is specified by
the header.
If a provider or reseller client sets the X-Profifact-Euid header
to a value that is not a positive integer or if the client has insufficient
permissions to make requests on behalf of the user with the specified ID,
the service returns HTTP status 403 Unauthorized.
X-Profifact-Version
Used by the service and its clients to indicate the version of the Profifact
API they are using for communication. The Profifact will try to adapt to the
version indicated by the client. If the client sends a request with a
version that is not supported by the specified resource or if the client
does not send a version number, the service returns HTTP status
403 Unauthorized.
The X-Profifact-Version header is required for all request methods
and all resources except for HTTP GET requests to the
/support resource. Support information is
publicly available and only the current version is documented. The current
version of the Profifact API is 1.6.0. See
the section on versioning for more information.
X-Profifact-Token
A custom header defined by the Profifact service. When specified by clients, the
value of this header must be the token the client was provided with in a preceeding
request. The X-Profifact-Token header may be used instead of the Authorization
header to improve performance. More information on the use of this header is
available in the section on authentication.
Response headers
There are several HTTP response headers with a special purpose.
Name
Description
Content-Disposition
As defined in RFC 6266,
specifies how the data returned by the Profifact service should be handled by the
client. This header is returned only when the client retrieves content that may be
a file (e.g. an invoice in PDF format).
Content-Type
As defined in RFC 7231 section 3.1.1.5,
provides the media type of the content sent by the service. This header is sent
always and its value is made to match any of the media types provided by the client
in the request Accept header.
Date
As defined in RFC 7231 section 7.1.1.2,
provides the client with the date and time the response of the service was created.
In combination with the X-Profifact-Token-Expires header the Date header may be used
to determine the remaining time until the token provided by the service expires.
X-Profifact-Token
A custom header defined by the Profifact service. After a client has authenticated
succesfully using the Authorization header, the client is provided with a token that
can be used for authentication in consecutive requests. That token is the value of
the X-Profifact-Token header. More information on the use of this header is
available in the section on authentication.
X-Profifact-Token-Expires
A custom header defined by the Profifact service. The X-Profifact-Token-Expires
header is sent to the client whenever the X-Profifact-Token is sent. It provides the
date and time at which the authentication token expires. If a client provides the
server with an expired token HTTP status code 419 Authentication Timeout is
returned. Token authentication has better performance than basic authentication and
is explained in the section on authentication. The
value of this header must adhere to the same rules as the value of the Date header.
Response status codes
HTTP status codes are defined in
RFC 7231 section 6.
The Profifact service uses a limited number of those status codes to indicate the result
of the operation requested by the client. Returned status codes include:
HTTP status code
Description
200 OK
The request has succeeded, requested data is in the response body.
201 Created
The request has succeeded and a new resource has been created. Data is in the
response body. This status code is returned for successful POST and PUT requests
only if a new resource was created. For a PUT request that updates an existing
resource the returned status code is 200, thereby allowing the client to distinguish
between whether a PUT request created or updated a resource.
204 No Content
The request has succeeded and the specified resource is removed. This status code is
returned only for successful DELETE requests.
400 Bad Request
The service has encountered errors while parsing the request. This may be due to a
request with an invalid resource resource ID, invalid request parameters, invalid
headers or invalid data. Error information may be provided in the response body.
401 Unauthorized
Authentication failed. The credentials provided by the client are invalid and the
service will not handle the request until valid credentials are provided.
403 Forbidden
Access to the requested resource is restricted to the client.
404 Not Found
The resource requested by the client was not found or the client has no permission
to access that resource. A 404 status code may indicate that the resource does not
exist or that it does not belong to the client. The Profifact service usually makes
no distinction between the two. Where is does, it returns status code 403 for the
latter case.
405 Method Not Allowed
The type of the request is not
permitted to the client. This may indicate that the request method is not
implemented or that the client is restricted from using it.
406 Not Acceptable
None of the media types provided by the client in the Accept header were acceptable
to the service. In other words, the server cannot return media of the type requested
by the client.
409 Conflict
Status 409 Conflict is returned for POST, PUT and DELETE requests if the current
state of client's data does not allow the operation. For example, trying to
delete a customer that is referenced by one or more invoices is not allowed. As
such, there is a conflict between the delete request of the client and the current
state of the client's data. The server denies the request (usually with an
explanation in the response body) and the client should change its behavior
accordingly.
413 Request Entity Too Large
Data was sent by the client in the request body but the request method (e.g. GET)
does not support content. If this status is returned for request methods that do
allow content in the request body (POST and PUT), the size of the content exceeds
the maximum accepted by the server.
415 Unsupported Media Type
Content of the media type provided by the client and specified in the Content-Type
header is not supported by the service. The client may retry the request providing
its content with a different media type.
419 Authentication Timeout
The client's authentication token has expired. The client should retry the request
using basic authentication. In the response to the retry the client will be provided
with a new token. Clients can prevent this response code by examining the values of
the Date and X-Profifact-Token-Expires headers and using basic
authentication whenever the active token is about to expire.
500 Internal Server Error
An error occurred while the server was handling the request. Error information may
be provided in the response body. Internal server errors may be caused by mistakes
in the server configuration or in the application source code. Any information on
the error and how it can be (re)produced is greatly welcomed by the Profifact
development team. Please send your report to
info@profifact.nl.
Authentication
Like the Profifact application, users of the Profifact service must provide a username and a
password when making requests. Contrary to the Profifact application however, the Profifact
service does not support sessions which means that clients must provide authentication
information on every request.
When access to the Profifact service is granted, the client is sent a new password specifically
for use with the service. The username is the same for the Profifact service and
the Profifact application, but the passwords are different.
Basic authentication
The primary method for authentication is the use of the Authorization header. Though that header
supports multiple authentication schemes, the Profifact service only supports
basic authentication.
The client must generate the value for the Authorization header by appending the username and
password received from Profifact separating them by a colon (':'). The result must be base64
encoded and appended to the string "Basic ". In pseudocode:
auth_header = "Authorization: Basic " + base64(USERNAME + ":" + PASSWORD)
The Profifact service inspects the value of the Authorization header sent by the client
and checks whether a user exists with the specified username. If the user is found and the
specified service password matches the password stored by Profifact, the request continues. If
the user is not found, or if the password does not match, the service returns HTTP status
401 Unauthorized.
Most, if not all, web browsers support basic authentication and can therefore easily be used to
verify user credentials. By opening a Profifact resource URL
(e.g. https://api.profifact.nl/invoices) in a web browser the user is shown an
authentication dialog in which the user's credentials can be entered. If the credentials are
correct, the browser shows the results returned by the Profifact service. If the credentials are
incorrect the browser shows the authentication dialog again.
Token authentication
In order for passwords to be stored securely and to prevent brute force attacks in the case of a
databreach, passwords are passed through a one way hashing algorithm before being stored. The
result is a password hash from which the original password cannot easily be recovered. Brute
force attacks become impractical by using a sufficiently slow hashing algorithm. This also means
that Profifact does not have access to client passwords, but only to client password hashes.
Profifact does not know your password and will NEVER ask for it. You should take
care to keep your passwords secure.
The disadvantage of a slow hashing algorithm is the fact that the time it takes to hash a
password is a signicant part of the time it takes to process a request. In other words, a slow
hashing algorithm causes slow responses from the Profifact service. In practice requests may
take upto 100 milliseconds longer.
Clients are free to take the poor response time for granted and use basic authentication for
every request, but there is an alternative. In response to a succesfully authenticated request
that used basic authentication the Profifact service returns a token that can be used instead of
the Authorization header. The token is returned in the X-Profifact-Token header and is valid for
a limited amount of time. The client may specify the token in subsequent requests by setting the
X-Profifact-Token header to the value of the token. Since token validation is relatively fast
compared to generating a hash value, performance on subsequent requests will be much improved.
The lifetime of a token is very short. Currently it is set to 10 minutes. The expiration time of
the token is sent to the client in the X-Profifact-Token-Expires header. If a clients uses the
token after its expiration time, the Profifact service returns HTTP status code
419 Authentication Timeout. The client should then retry the request with basic
authentication whereby it receives a new token. Instead of handling the 419 error code the
client may also inspect the token expiration time and use basic authentication whenever the
token is about to expire. In summary:
The client sends a request using basic authentication by setting the Authorization
header.
The service returns the response and includes the X-Profifact-Token and
X-Profifact-Token-Expires headers.
The client keeps track of the token and its expiration time for later use.
Before subsequent requests the client checks whether the token has expired.
If the token has expired, goto step 1.
Otherwise use token authentication by setting the X-Profifact-Token header.
Goto step 4.
Resources
Overview of the Profifact models and their relations
The data and operations that are part of the Profifact application are made available by the
Profifact service as resources. Resources are uniquely identifiable through resource URLs. Depending
on the resource operations for creation, reading/retrieval, updating and deletion may be provided
(see Wikipedia for more on CRUD).
These operations match the request methods explained in the subsection on
request methods. This
section gives a list of the available resources with short descriptions and links to more extensive
technical descriptions.
Customers
Before creating invoices and offers, Profifact users must first create one or more customers to whom
the invoices or offers are sent. Using the Profifact service, users can create, retrieve, update and
delete customers. Deleting a customer is only possible if the customer is not referenced by any
invoices and offers.
Profifact tracks the changes made to customer details in customer address records. If the details of
a customer are changed, a new address record may be created for the customer so that the original
details can be kept for previously created invoices and offers. Only invoices and offers with status
CONCEPT are set to reference the new customer address record. Invoices and offers with all
other statuses keep their references to the old customer address record. This setup ensures that
invoices and offers never change after having been set to status UNSETTLED.
For an extensive technical treatment of the customers resource see
/support/customers.
Customers Groups
Customer groups provide a method for grouping customers. A customer always belongs to exactly one
cusotmer group. Clients can create new customer groups and assign customers to customer groups.
There are three types of customer groups and every client has at least one customer group named
"Klanten" (with type SYSTEM_CUSTOMERS) and one customer group named "Gearchiveerd" (with
type SYSTEM_ARCHIVED). New customer groups created by a client are given the type
CUSTOM.
When adding a new customer, clients may provide a customer group ID to indicate the group a
customer should be assigned to. If no customer group ID is supplied the new customer is added to
the group with type SYSTEM_CUSTOMERS (i.e. "Klanten"). Customers assigned to the group with
type SYSTEM_ARCHIVE are considered archived customers and do not show up when selecting a
customer for a new invoice or offer.
For an extensive technical treatment of the customer groups resource see
/support/customergroups.
Invoices
Invoices form the centerpiece of the Profifact application which is expressed in the fact that the
invoices resource provides the most extensive functionality of all resources. Clients can retrieve
the collection of previously created invoices with either summarized (for being shown in a table) or
full information. Individual invoices can be retrieved in JSON and PDF formats. Clients can create
new invoices, invoices based on offers, invoice reversals and copies of existing invoices. Invoices
with status CONCEPT can be updated and deleted.
For an extensive technical treatment of the invoices resource see
/support/invoices.
Invoicemails
Profifact allows clients to send invoices by email. Each time an invoice is sent, a registration of
that operation is stored as an InvoiceMail object for later reference. E.g. it may be useful to
check when a particular invoice was sent to a customer. The invoice mails resource provides access
to the collection of previously sent invoice emails and allows the client to send new messages.
Invoices can be sent to upto five recipients and the client can either provide a message text or
use a predefined message text configured in Profifact.
For an extensive technical treatment of the invoicemails resource see
/support/invoicemails.
Offers
Support for offers in the Profifact service is currently limited compared to support for invoices.
Clients can retrieve summarized information for the collection of previously created offers and
retrieve full information for individual invoices. Support for other operations such as adding,
updating and deleting offers not yet provided.
For an extensive technical treatment of the offers resource see
/support/offers.
Offermails
Profifact allows clients to send offers by email. Each time an offer is sent, a registration of
that operation is stored as an OfferMail object for later reference. E.g. it may be useful to
check when a particular offer was sent to a customer. The offer mails resource provides access
to the collection of previously sent offer emails and allows the client to send new messages.
Offers can be sent to upto five recipients and the client can either provide a message text or
use a predefined message text configured in Profifact.
For an extensive technical treatment of the offermails resource see
/support/offermails.
Payments
Once an invoice is made definitive by setting its status to UNSETTLED, payments may be
received for it. The payments resource provides a way for clients to add payments to invoices.
Payments can be added to all invoices with statuses other than CONCEPT. If the total amount
paid for a particular invoice is exactly the total amount due, the status of the invoice is
automatically changed to PAID. Adding payments to an invoice with status PAID
reverts the status of the invoice to its previous value.
For an extensive technical treatment of the payments resource see
/support/payments.
Reminders
If a customer neglects an invoice by not settling the associated debt one or more reminders of the
outstanding debt may be sent. Profifact supports three types of reminders with increasing gravity:
informal notices, formal notices and notices of default. The reminders resource provides clients the
ability to create a reminder for one or more invoices and provides information about previously
created reminders. Once created, the remindermails resource can be used to send the reminder to the
customer. Alterntatively the PDF version of a reminder can be retrieved so that the client can send
or print the reminder as desired.
For an extensive technical treatment of the reminders resource see
/support/reminders.
Remindermails
Profifact allows clients to send reminders by email. Each time a reminder is sent, a registration of
that operation is stored as a ReminderMail object for later reference. E.g. it may be useful to
check when a particular reminder was sent to a customer and what the outstanding amount was at that
time. The reminder mails resource provides access to the collection of previously sent reminder
emails and allows the client to send new messages.
Reminders can be sent to upto five recipients and the client can either provide a message text or
use a predefined message text configured in Profifact.
For an extensive technical treatment of the remindermails resource see
/support/remindermails.
Settings
Clients can make a number of customizations to tune Profifact to their workflows. The settings for
those customizations and their custom values are available through the settings resource.
The values stored under the settings resource may be useful when adding invoices and customers to
provide default values for properties such as customer and invoice payment periods, invoice price
types (including or excluding VAT) and VAT rates.
For an extensive technical treatment of the settings resource see
/support/settings.
Support
The support resource, of which the current document is a part, provides support documentation for
the Profifact service. It supports only HTTP GET requests and it is publicly available. It always
returns HTML content. If the client indicates it does not accept HTML (through the HTTP Accept
header) HTTP status 406 Not Acceptable is returned.
Templates
Profifact uses templates for rendering PDF versions of invoices and offers. Clients can create and
modify templates using the Profifact application, but the Profifact service also provides methods
for retrieving, creating and updating templates. Clients have at least two templates, one with type
INVOICE and one with type OFFER. For each template type there a client has exactly
one template that is marked as the default template for that type. A client can have more templates
of any type, but those must be specified explicitly when creating an invoice or offer.
For an extensive technical treatment of the templates resource see
/support/templates.
VAT rates
VAT rates are defined by the Dutch government and apply to all deliveries of services and goods. The
vatrates resource provides clients with a list of all VAT rates accepted by Profifact along with
information about their validity. Only VAT rates valid at the date of an invoice are accepted as
valid for an invoice line when creating an invoice. It is therefore essential for clients to obtain
a list of valid VAT rates using this resource.
For an extensive technical treatment of the VAT rates resource see
/support/vatrates.
Data types
Data types are defined for all resouce properties. The data type of a particular property
can be found in the technical description of each resource. Only if a data type is directly
followed by a question mark is null an acceptable value for that data type. E.g.:
null is a valid value for int? but not for int. The following
table shows the data types used by the Profifact service:
Data type
Description
bool
A bit value which may be 0 or false for false and 1 or
true for true.
int
A signed or an unsigned integer.
string
A variable length string.
date
A string representation of a date formatted according to
ISO 8601 (i.e.
YYYY-MM-DD). E.g.: "2015-12-17". The timezone of date values
is always Europe/Amsterdam which is +01:00 during standard
time and +02:00 during day light savings time. Clients in other
timezones must convert datetime values to timezone Europe/Amsterdam
before submitting them and from Europe/Amsterdam after receiving them.
datetime
A string representation of a date and a time formatted according to
ISO 8601 without a
timezone (i.e. YYYY-MM-DDTHH:II:SS. E.g.:
"2015-12-17T16:38:17". The timezone of datetime values is always
Europe/Amsterdam which is +01:00 during standard time and
+02:00 during day light savings time. Clients in other timezones must
convert datetime values to timezone Europe/Amsterdam before submitting
them and from Europe/Amsterdam after receiving them.
decimal
A string representation of a decimal value formatted with an optional leading minus
sign and an optional decimal fraction (indicated by a single dot). E.g.:
"3", "3.14159" or "-3.14159".
array
An array of zero or more objects with the same properties.
Objects are not explicitly typed in the documentation. Objects represent models of the
Profifact application such as invoices, customers, VAT rates etc. Their representations
depend on the programming language used by the client and the encoding used in HTTP
requests. E.g. a customer group object can represented in JSON as:
{ "id": 1, "name": "My Customers", "type": "CUSTOM" }
In object oriented programming languages the same object may be represented by an instance
of a class:
class CustomerGroup
{
int id;
string name;
string type;
}
CustomerGroup instance = new CustomerGroup { id = 1, name = "My Customers", type = "CUSTOM" };
Versioning scheme and version history
Information about the versioning scheme and a full version history of the Profifact API can
be found in the article on profifact versions.
Client implementations
An client implementation example in PHP and information about contributing your own clients
are available in the article on client implementations.
Terms
Client
In this documentation, the term client is used to indicate an organization that
uses Profifact for its invoicing. With regard to the Profifact service the term
client might also be understood to indicate the software that connects to the
Profifact service (i.e. the client software). The term client is unambigiuos, because
currently only client organizations can connect to the Profifact service using client
software. The term refers to both the client organization and the client software and it is
not used to indicate a customer (see Customer).
Customer
A customer in Profifact is a potential debtor of a Profifact client organization
(see Client). Customers belong to customer groups and can be targeted by invoices,
offers and reminders.
Customer information belongs to the client organization that entered it into Profifact
either directly using the UI or through the Profifact service.
Reseller
A reseller is a Profifact user that has access to one or more client (see
Client) accounts. Resellers may provide additional services and support to their
clients either through Profifact or separate from Profifact. Clients can be considered
customers of a reselller, but this support documentation reserves that term for customers of
a client in order to avoid confusion (see Customer).
Profifact application
The components of the Profifact application
The whole of the services provided by Profifact and the software that underlies it. This
includes the Profifact service and the Profifact UI.
Profifact API
The part of the Profifact service (see Profifact service) that is accessible to
clients (see Client). A well documented
API allows developers to
build tools that take advantage of the functionalities provided through the API. The
Profifact API hides some of the complexities and business logic that are part of the
Profifact application. By providing an easy to understand interface, clients can handle
their sales administration in an automated manner without worrying about how customer
information, invoices, reminders etc. are stored, validated and manipulated.
Profifact service
The webservice provided by Profifact as part of the Profifact application that allows
clients to automate important parts of the invoicing process. The API of the Profifact
service is described by this documentation.
Profifact UI
The Profifact user interface is the main portal for non-automated access. The
Profifact UI is part of the Profifact application and is available to registered users at
profifact.nl. Being targeted at regular internet users
instead of computer programs, the functionality provided by the Profifact UI is easy to
understand and tailored to current user interface standards.
