> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/documentations/efalia-process/vue-ensemble-api/documentation-api-rest.md).

# Documentation API REST

Efalia Process expose une **API REST complète** permettant d'interagir programmatiquement avec tous les aspects de la plateforme : documents, workflows, utilisateurs, rôles, et données.

***

## Accès à la Documentation

### Swagger UI

La documentation interactive de l'API est accessible directement sur votre instance Efalia Process via **Swagger UI** :

```
https://<votre-serveur>/workey/swagger-ui.html
```

Swagger UI permet de :

* Consulter tous les endpoints disponibles
* Tester les appels directement depuis le navigateur
* Visualiser les modèles de données (schémas JSON)
* Exporter la spécification OpenAPI

📸 **CAPTURE : api-rest-01-swagger-ui.png**

> Interface Swagger UI avec la liste des endpoints disponibles et un exemple d'appel

***

## Authentification

L'API REST utilise une authentification **HTTP Basic** (identifiant + mot de passe) :

```bash
curl -u login:password \
  https://process.example.com/workey/api/documents
```

Pour les intégrations en production, utilisez un **compte de service** dédié avec les droits strictement nécessaires.

***

## Ressources Principales

### Documents

Les documents sont les instances de workflow dans Efalia Process.

| Méthode  | Endpoint                     | Description           |
| -------- | ---------------------------- | --------------------- |
| `GET`    | `/api/documents`             | Lister les documents  |
| `POST`   | `/api/documents`             | Créer un document     |
| `GET`    | `/api/documents/{id}`        | Récupérer un document |
| `PUT`    | `/api/documents/{id}`        | Modifier un document  |
| `DELETE` | `/api/documents/{id}`        | Supprimer un document |
| `GET`    | `/api/documents/{id}/fields` | Récupérer les champs  |
| `PUT`    | `/api/documents/{id}/fields` | Modifier les champs   |

**Créer un document :**

```json
{
  "processName": "Validation_Facture",
  "documentType": "Facture",
  "state": "Saisie",
  "role": "Comptable",
  "fields": {
    "Montant": "1250.00",
    "Fournisseur": "Société ABC",
    "Numero_Facture": "FAC-2024-0123"
  }
}
```

### Opérations

| Méthode | Endpoint                                | Description                       |
| ------- | --------------------------------------- | --------------------------------- |
| `GET`   | `/api/documents/{id}/operations`        | Lister les opérations disponibles |
| `POST`  | `/api/documents/{id}/operations/{name}` | Déclencher une opération          |

**Déclencher une opération :**

```bash
curl -X POST -u login:password \
  https://process.example.com/workey/api/documents/uuid/operations/Valider
```

### Pièces Jointes

| Méthode  | Endpoint                          | Description                  |
| -------- | --------------------------------- | ---------------------------- |
| `GET`    | `/api/documents/{id}/attachments` | Lister les pièces jointes    |
| `POST`   | `/api/documents/{id}/attachments` | Ajouter une pièce jointe     |
| `GET`    | `/api/attachments/{uuid}`         | Télécharger une pièce jointe |
| `DELETE` | `/api/attachments/{uuid}`         | Supprimer une pièce jointe   |

**Uploader une pièce jointe :**

```bash
curl -X POST -u login:password \
  -F "file=@facture.pdf" \
  -F "fieldName=PJ_Facture" \
  https://process.example.com/workey/api/documents/uuid/attachments
```

### Utilisateurs

| Méthode | Endpoint          | Description              |
| ------- | ----------------- | ------------------------ |
| `GET`   | `/api/users`      | Lister les utilisateurs  |
| `POST`  | `/api/users`      | Créer un utilisateur     |
| `GET`   | `/api/users/{id}` | Récupérer un utilisateur |
| `PUT`   | `/api/users/{id}` | Modifier un utilisateur  |

### Rôles

| Méthode | Endpoint                               | Description                       |
| ------- | -------------------------------------- | --------------------------------- |
| `GET`   | `/api/roles`                           | Lister les rôles                  |
| `GET`   | `/api/documents/{id}/roles`            | Rôles d'un document               |
| `PUT`   | `/api/documents/{id}/roles/{roleName}` | Assigner un utilisateur à un rôle |

***

## Recherche et Filtrage

L'API propose des capacités de recherche avancée sur les documents :

```bash
GET /api/documents?processName=Validation_Facture&state=Validée&page=0&size=20
```

**Paramètres de recherche courants :**

| Paramètre      | Description                               |
| -------------- | ----------------------------------------- |
| `processName`  | Filtre par nom de processus               |
| `documentType` | Filtre par type de document               |
| `state`        | Filtre par état                           |
| `author`       | Filtre par auteur                         |
| `createdAfter` | Documents créés après une date (ISO-8601) |
| `page`         | Numéro de page (0-indexed)                |
| `size`         | Taille de la page (défaut : 20)           |

***

## Codes de Réponse HTTP

| Code                        | Signification                                                 |
| --------------------------- | ------------------------------------------------------------- |
| `200 OK`                    | Succès — données retournées                                   |
| `201 Created`               | Document/ressource créé(e)                                    |
| `204 No Content`            | Succès sans données retournées                                |
| `400 Bad Request`           | Requête invalide (paramètre manquant, format incorrect)       |
| `401 Unauthorized`          | Authentification requise ou invalide                          |
| `403 Forbidden`             | Droits insuffisants                                           |
| `404 Not Found`             | Ressource introuvable                                         |
| `409 Conflict`              | Conflit (ex : état de document incompatible avec l'opération) |
| `500 Internal Server Error` | Erreur serveur — consulter les logs                           |

***

## Exemples d'Intégration

### Créer et piloter un workflow depuis Python

```python
import requests
from requests.auth import HTTPBasicAuth

BASE_URL = "https://process.example.com/workey/api"
AUTH = HTTPBasicAuth("service_account", "password")

# Créer un document
def create_document(data):
    response = requests.post(
        f"{BASE_URL}/documents",
        json={
            "processName": "Validation_Facture",
            "documentType": "Facture",
            "state": "Saisie",
            "role": "Comptable",
            "fields": data
        },
        auth=AUTH
    )
    response.raise_for_status()
    return response.json()["id"]

# Déclencher une opération
def trigger_operation(doc_id, operation):
    response = requests.post(
        f"{BASE_URL}/documents/{doc_id}/operations/{operation}",
        auth=AUTH
    )
    response.raise_for_status()
```

***

## Limites et Bonnes Pratiques

{% hint style="success" %}
**Recommandations**

* Utilisez la pagination pour les requêtes retournant de nombreux résultats
* Gérez les erreurs HTTP avec des mécanismes de retry pour les erreurs 5xx
* Stockez les identifiants dans des variables d'environnement, pas dans le code
* Testez sur un environnement de recette avant la production
  {% endhint %}

***

Pour aller plus loin :

* [Vue d'Ensemble API](/documentations/efalia-process/vue-ensemble-api.md)
* [Connecteur API REST](/documentations/efalia-process/vue-ensemble-api/connecteur-api-rest.md)
* [Webhooks et Événements](/documentations/efalia-process/vue-ensemble-api/webhooks-evenements.md)


---

# 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://documentation.efalia.com/documentations/efalia-process/vue-ensemble-api/documentation-api-rest.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.