> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami.md).

# RestApi - Integrations with external systems

{% hint style="warning" %}
Functionality available from platform version: 2.2924.0

The functionality is active for all customers. It does not require any activation flag.
{% endhint %}

{% hint style="warning" %}
API change

Calling via context.api() has been replaced **api.rest.v1**. It is the only correct way to make requests.
{% endhint %}

{% hint style="info" %}
The functionality for calling external REST services is available for scripts (scriptService), script tasks (scriptTask), and script validators (validationScript).
{% endhint %}

## Integration with external services via REST API

### What is REST?

**REST (Representational State Transfer)** is an architectural style of communication between IT systems that is based on the standard protocol **HTTP**.\
It enables data exchange between the client (e.g. an application) and the server (e.g. an external service) in a **lightweight, simple, and scalable**.

Each resource (e.g. user, order, document) is identified by a unique **URL**, and operations on it are performed using standard HTTP methods:

| The method      | Description                    |
| --------------- | ------------------------------ |
| `GET`           | Retrieves data from the server |
| `POST`          | Creates a new resource         |
| `PUT` / `PATCH` | Updates an existing resource   |
| `DELETE`        | Deletes a resource             |

***

### Data format

Information exchange in REST API most often takes place in the format of **JSON** (less often XML).\
JSON is human-readable, easy to process, and natively supported by most programming languages.

***

### Authorization and security

Access to external services usually requires **authorization**, which ensures that only authorized applications or users can use the API.

The most common mechanisms are:

* **API Key** – a simple identification key added to the header or request parameter;
* **Bearer Token (OAuth 2.0)** – a modern standard based on access tokens;
* **Basic Auth** – login and password encoded in the header (currently used less often, mainly in test environments).

> 🔒 When integrating with external services, HTTPS should always be used **HTTPS**, to ensure communication encryption.

***

### Response statuses (HTTP status codes)

The server returns in response to a request **HTTP status code**, which informs about the result of the operation:

| Code                        | Meaning                                |
| --------------------------- | -------------------------------------- |
| `200 OK`                    | Operation completed successfully       |
| `201 Created`               | New resource created                   |
| `400 Bad Request`           | Bad request (e.g. invalid input data)  |
| `401 Unauthorized`          | Missing authorization or invalid token |
| `404 Not Found`             | Resource does not exist                |
| `500 Internal Server Error` | Server-side error                      |

***

## Typical REST integration flow

1. **Building the request** – preparing the URL, headers (e.g. authorization, data type) and optional body (for `POST` / `PUT`).
2. **Sending the request** – communication with the external API via HTTP.
3. **Receiving the response** – processing the data returned in JSON format.
4. **Error handling** – interpreting status codes and error messages.
5. **Data mapping** – saving or using the received data in the local system.

***

## Advantages of REST

* **Simplicity** – easy to understand and implement.
* **Scalability** – works well in distributed environments.
* **Independence** – client and server can be implemented in any technologies.
* **Popularity** – broad support in libraries and development tools.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.