Artesa API

Appearance

Getting Started with Artesa API ​

Artesa provides a powerful API that allows you to interact with your data in a flexible and efficient way. This documentation will guide you through the process of getting started with the Artesa API, including authentication, making requests, and handling responses.

Getting Started ​

To get started with the Artesa API, follow these steps:

  1. Login: If you're an admin, sign in. If you don't have an account yet, you can sign up for a free trial.
  2. Settings: Go to the settings page and create a new API key or copy an existing one. This key will be used to authenticate your requests.
  3. API Documentation: Familiarize yourself with the API documentation. The documentation is organized by version and includes detailed information about each endpoint, including request and response formats.
  4. Make Requests: Use your API key to make requests to the API. You can use tools like Postman or curl to test the endpoints.
  5. Handle Responses: The API will return responses in JSON format. Make sure to handle these responses appropriately in your application.
  6. Explore the API: The API is designed to be flexible and powerful. Explore the different endpoints and see how they can be used to interact with your data.

Base URL ​

All endpoints are served under:

https://api.artesa.de

Every endpoint is versioned in its path, for example https://api.artesa.de/v1/customers.

A staging environment is available at https://api-staging.artesa.dev. Its data may be out of date and it can contain unreleased changes — use it for testing only.

Localization ​

🇩🇪 Deutschland ​

  • assignments: Auftrag
  • assignment-types: Auftragstyp
  • assignment-events: Arbeitsschritt
  • assignment-event-groups: Arbeitsschrittgruppe
  • assignment-status-types: Auftragsstatus
  • customers: Kunde
  • roles: Benutzerrolle
  • users: Benutzer/Mitarbeiter

🇮🇹 Italia ​

  • assignments: Ordine
  • assignment-types: Tipo ordine
  • assignment-events: Fase di lavoro
  • assignment-event-groups: Gruppo
  • assignment-status-types: Stato ordine
  • customers: Cliente
  • roles: Ruolo utente
  • users: Dipendente

Authorization ​

To access the Artesa API, you need to include your API key in the Authorization header of your requests. The format should be:

Authorization: Bearer YOUR_API_KEY

Check the Samples on each endpoints documentation page for examples of how to include the API key in your requests.

Pagination ​

List endpoints are paginated. Two query parameters control the page:

  • page — zero-based page index (default 0).
  • size — number of items per page (default 10, maximum 20).

For example, GET /v1/customers?page=2&size=20 returns the third page of 20 customers.

Every list response is wrapped in a pagination envelope:

json
{
  "page": 0,
  "pages": 5,
  "size": 10,
  "items": [
    /* ... */
  ]
}
  • page — the current page index.
  • pages — the total number of pages available.
  • size — the page size used.
  • items — the array of results for this page.

Errors ​

The API uses standard HTTP status codes. On error, the response body is JSON with a consistent shape:

json
{
  "name": "BadRequest",
  "message": "Invalid query: \"createdAt\": Expected a valid ISO 8601 date-time string",
  "code": 400
}
  • name — a short error identifier (e.g. BadRequest, NotAuthenticated, NotFound).
  • message — a human-readable description of what went wrong.
  • code — the HTTP status code.

The most common status codes are:

  • 400 Bad Request — the request body or query parameters are invalid. For validation errors, the offending fields are listed under data.validationErrors.
  • 401 Unauthorized — the API key is missing or invalid (see Authorization).
  • 404 Not Found — the requested resource does not exist, or is not visible to your company.

Versioning ​

The Artesa API follows a versioning scheme to ensure backward compatibility. Every endpoint has its own version, which is reflected in the URL. When we introduce breaking changes, we will increment the major version number. For example, if the current version is v1, the next breaking change will be v2. We'll inform you about these changes in the changelog and per announcements. We detect who is using which version of the API, so you can continue using the old version until you are ready to upgrade.

Support ​

If you have any questions or need assistance, please refer to www.artesa.de or contact our support team.

Copyright © Artesa GmbH