Aller au contenu
Givre
Se connecter
  • Langue
  • Thème

Documentation de l’API

Obtenir une clé Télécharger le schéma OpenAPI

API client v1

Démarrage rapide

  • URL de base

    https://givre.app/api/v1

  • Authentification

    Envoyez la clé API en clair comme token Bearer ou en-tête X-Api-Key.

    Authorization: Bearer givre_xxx_secret X-Api-Key: givre_xxx_secret Accept: application/json

  • Scopes

    read / write

Obtenir l’accès

L’API est ouverte aux organisations clientes de Givre. Les clés se créent dans l’application, pas sur cette page.

  1. Un administrateur crée la clé
    Dans Givre, menu Intégrations > Clés API, rattachée à une intégration, avec les droits lecture ou écriture.
  2. Copiez-la à la création
    La clé complète n’est affichée qu’une fois. Conservez-la dans le gestionnaire de secrets de votre application.
  3. Envoyez-la à chaque requête
    En jeton Bearer ou dans l’en-tête X-Api-Key. La clé détermine l’organisation et les dossiers accessibles.

Votre organisation n’utilise pas encore Givre ? Contactez l’équipe.

Sandbox

Les clés sandbox (préfixe givretest_) permettent de tester une intégration sans consommer de jetons ni déclencher de vraie certification. Un administrateur les crée comme les autres clés, en cochant « Sandbox ».

  • Même URL de base et mêmes routes qu’en production.
  • Données isolées : les dossiers, documents et certifications créés avec une clé sandbox ne sont visibles que par les clés sandbox, et restent hors de l’application web, des statistiques et de la facturation.
  • Certifications simulées : aucun jeton débité, aucun horodatage, certificat eIDAS ou PDF PAdES réel ; les artefacts sont des fichiers de démonstration.
  • Les callbacks partent vers l’URL de l’intégration avec "sandbox": true dans le corps et l’en-tête X-Givre-Sandbox: 1.
Clé sandbox 
# Requête
GET https://givre.app/api/v1/dossiers
Authorization: Bearer givretest_xxx_secret

# Callback reçu
X-Givre-Sandbox: 1
{ "event": "certification.success", "sandbox": true, … }

Payload de modèle personnalisé

Corps JSON minimum pour POST /templates/custom.

POST /templates/custom 
{
  "name": "Client onboarding checklist",
  "category": "operations",
  "icon": "bi-clipboard2-check",
  "tone": "primary",
  "config": {
    "proof_overlay_images": [
      {
        "id": "f5b74330-c17e-4e61-9d62-a8fb92d8626b",
        "name": "Company logo",
        "path": "templates/geolocation-overlays/template/logo.png",
        "x": 75,
        "y": 75,
        "width": 20,
        "height": 15
      }
    ],
    "steps": [
      {
        "name": "Identity",
        "description": "Collect onboarding evidence.",
        "allowed_roles": ["inspecteur"],
        "proofs": [
          {
            "name": "Signed PDF",
            "required": true,
            "capture_type": "photo",
            "certification_format": "pades",
            "geolocation_required": true,
            "geolocation_options": {
              "logo": {
                "enabled": true,
                "image_id": "f5b74330-c17e-4e61-9d62-a8fb92d8626b"
              }
            }
          }
        ]
      }
    ]
  }
}

Conventions

Pagination
Chaque liste renvoie un tableau dans data et sa position dans meta.pagination (current_page, last_page, per_page, total). Utilisez page et per_page : 25 par défaut, les valeurs hors de 1 à 100 sont ramenées dans cet intervalle.
Limites de débit
120 requêtes par minute et par clé. Au-delà, l'API répond 429 too_many_requests avec un en-tête Retry-After. Les authentifications par clé échouées sont aussi limitées par IP.
Envois idempotents
Envoyez client_capture_id, et si possible client_sha256, avec chaque envoi. Une nouvelle tentative avec le même identifiant renvoie le document enregistré en 200 au lieu d'un doublon. Le même identifiant avec un autre fichier répond 409 capture_id_conflict.
Artefacts payants
POST eidas-certificate et POST sign-pdf débitent un jeton la première fois seulement, puis réutilisent le PDF enregistré. Les routes GET correspondantes ne font que télécharger et ne débitent jamais.
Nouvelles tentatives
Retentez les 429, 502 et 503 après un délai, en suivant Retry-After s'il est présent. Les autres réponses 4xx ne changeront pas tant que la requête ne change pas.
Dates et identifiants
Les dates sont des chaînes ISO 8601 avec leur décalage horaire. Chaque ressource est identifiée par son UUID.

Codes d'erreur

Chaque erreur garde la même enveloppe avec success à false. Basez votre logique sur meta.code plutôt que sur le message, qui est traduit.

Statut meta.code Signification
401 invalid_api_key La clé est absente, mal formée ou inconnue.
401 api_key_not_valid La clé est expirée ou révoquée.
402 insufficient_tokens Le client n'a plus de jeton pour un artefact payant.
403 missing_api_scope La clé n'a pas le scope read ou write de la route.
403 missing_permission L'utilisateur de la clé n'a pas la permission de la route.
403 forbidden L'action est refusée pour cette ressource, par exemple un dossier inactif.
403 step_role_forbidden L'étape est réservée à des rôles (allowed_roles) que l'utilisateur de la clé n'a pas.
404 not_found Ressource inconnue, ou appartenant à un autre client.
404 artifact_not_found L'artefact n'a pas encore été généré : faites d'abord un POST.
409 invalid_state Le statut du dossier ne permet pas cette action.
409 certification_not_ready Le document n'est pas encore certifié.
409 capture_id_conflict Le client_capture_id est déjà lié à un autre fichier.
409 template_snapshot_diverged Les étapes du dossier ne correspondent plus au début du modèle publié : aucune étape n'a été ajoutée.
409 dossier_archived Le dossier est archivé : désarchivez-le d'abord.
409 template_not_published Le modèle du dossier n'est plus publié.
422 validation_failed Données invalides : errors liste les messages par champ.
422 capture_hash_mismatch Le fichier reçu ne correspond pas à client_sha256.
422 document_not_pdf Seuls les documents PDF peuvent être signés.
429 too_many_requests Limite de débit atteinte : attendez le délai Retry-After.
500 server_error Erreur inattendue, déjà signalée à l'équipe.
502 artifact_generation_failed Le prestataire de certification a échoué. Rien n'a été débité ; réessayez plus tard.
503 document_storage_unavailable Le fichier n'a pas pu être enregistré. Réessayez après le délai Retry-After.

Callbacks

Givre envoie en POST un événement JSON signé vers l’URL de callback de l’intégration. Configurez l’URL, le secret et les événements depuis la page de l’intégration.

Événements

  • certification.success
  • certification.failed
  • certification.insufficient_tokens
  • certification.eidas_certificate.generated
  • certification.eidas_certificate.failed
  • certification.pdf_signed
  • certification.pdf_signature_failed

Contrat de livraison

  • Répondez avec un statut 2xx en moins de 10 secondes.
  • Un même événement peut arriver plusieurs fois : utilisez Idempotency-Key pour ignorer les doublons.
  • Un envoi échoué est retenté jusqu'à 5 tentatives au total, espacées de 10, 20, 30 puis 40 minutes. X-Givre-Attempt indique le numéro de la tentative.
  • Vérifiez X-Givre-Signature et rejetez les horodatages de plus de 5 minutes.
En-têtes 
Content-Type: application/json
Idempotency-Key: {delivery uuid}
X-Givre-Delivery: {delivery uuid}
X-Givre-Attempt: 1
X-Givre-Event: certification.success
X-Givre-Signature: t=1760090000,sha256={hmac(timestamp.body)}
X-Givre-Sandbox: 1 (sandbox keys only)
Vérifier la signature — PHP 
$body = file_get_contents('php://input');
preg_match('/^t=(\d+),sha256=([a-f0-9]{64})$/', $_SERVER['HTTP_X_GIVRE_SIGNATURE'] ?? '', $m);

$expected = hash_hmac('sha256', ($m[1] ?? '').'.'.$body, getenv('GIVRE_CALLBACK_SECRET'));

if (! $m || abs(time() - (int) $m[1]) > 300 || ! hash_equals($expected, $m[2])) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true); // Deduplicate on the Idempotency-Key header.
http_response_code(204);
Vérifier la signature — Node.js 
import crypto from 'node:crypto';

// rawBody: the request body as received (Buffer), before any JSON parsing.
export function verifyGivre(rawBody, headers, secret) {
  const match = /^t=(\d+),sha256=([a-f0-9]{64})$/.exec(headers['x-givre-signature'] ?? '');
  if (!match) return false;

  const [, t, sha256] = match;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');

  return Math.abs(Date.now() / 1000 - Number(t)) <= 300
    && crypto.timingSafeEqual(Buffer.from(sha256), Buffer.from(expected));
}

Historique des changements

  • POST /dossiers/{uuid}/complete nécessite la nouvelle permission dossiers.complete au lieu de dossiers.update, et répond 403 forbidden sans elle. Elle a été accordée à tous les rôles qui pouvaient modifier les dossiers : les intégrations existantes continuent de fonctionner tant qu'un admin ne la retire pas d'un rôle.

  • POST /dossiers/{uuid}/reopen repasse un dossier terminé à l'état actif et efface completed_at. Rouvrir un dossier actif le renvoie inchangé ; un dossier archivé doit d'abord être désarchivé.
  • DELETE /dossiers/{uuid} supprime définitivement un dossier avec ses documents, certifications et fichiers, dossiers archivés compris. Nécessite la nouvelle permission dossiers.delete, accordée aux rôles admin et manager.
  • Les dossiers portent une échéance facultative due_at et un horodatage missed_at (ISO 8601). POST /dossiers et PATCH /dossiers/{uuid} acceptent due_at (dans le futur ; null la supprime sur PATCH, où name devient facultatif).
  • Un dossier encore actif à son due_at passe au nouveau statut missed. Il est en lecture seule comme un dossier terminé, et GET /dossiers accepte status=missed.
  • Un dossier missed n'accepte que les envois dont captured_at ne dépasse pas due_at, reçus dans les 24 heures qui suivent due_at. POST /dossiers/{uuid}/reopen rouvre aussi un dossier missed et efface missed_at et due_at.
  • Les dossiers exposent source, leur mode de création : web, mobile, api ou schedule (dossier récurrent). GET /dossiers accepte source, et les callbacks transmettent dossier.source.

  • POST /dossiers/{uuid}/template-sync ajoute à un dossier existant les étapes ajoutées en fin de modèle publié, ainsi que les preuves ajoutées en fin de ses étapes existantes, sans déplacer les preuves ni les documents existants. meta.added_steps et meta.added_proofs les comptent.
  • POST /dossiers/{uuid}/documents accepte aussi les dossiers terminés, pour ajouter un rapport après la fin de l'intervention. Les dossiers archivés répondent toujours 403.
  • Les étapes des modèles et des dossiers portent allowed_roles, les noms des rôles autorisés à ajouter des documents à l'étape ; une liste vide laisse l'étape ouverte à tous les utilisateurs pouvant modifier le dossier. Les modèles personnalisés n'acceptent que les rôles de leur client (422 sinon).
  • Un dépôt sur une étape réservée à des rôles que l'utilisateur de la clé n'a pas répond 403 step_role_forbidden.
  • POST /dossiers/{uuid}/template-sync met aussi à jour les allowed_roles des étapes existantes depuis le modèle publié ; meta.updated_steps compte les étapes modifiées.

  • Les certifications et artefacts sont identifiés par uuid ; les champs entiers id et certification_id disparaissent. GET /certifications/{uuid} remplace la route par identifiant entier.
  • Les transactions de jetons exposent certification_uuid au lieu de certification_id.
  • GET eidas-certificate ne fait que télécharger : il répond 404 artifact_not_found tant qu'un POST n'a pas généré le certificat.
  • Les erreurs d'artefact ont des statuts dédiés : 402 insufficient_tokens, 409 certification_not_ready, 422 document_not_pdf, 502 artifact_generation_failed.
  • Une clé expirée ou révoquée répond 401 api_key_not_valid, et une permission utilisateur manquante 403 missing_permission.
  • Un changement d'état de dossier refusé répond 409 invalid_state au lieu de 422.
  • GET /templates est paginé. GET /dossiers accepte status, template_uuid et search.
  • Les envois acceptent client_capture_id et client_sha256 pour retenter sans risque.
  • Les callbacks ne contiennent plus les champs internes de certification (endpoint, chemins de stockage, réponse brute du fournisseur).
  • Les messages d'erreur du fournisseur de certification sont remplacés par un message générique.

Référence de l’API

Santé

GET Vérification de santé /health
Sans clé

Un appel anonyme ne reçoit que le statut de chaque vérification. Envoyez l'en-tête X-Health-Token avec le jeton opérateur pour obtenir le détail. Limité par IP.

Paramètres

Réponses

  • 200 Réponse réussie
  • 503 Une dépendance est indisponible
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/health"

Compte

GET Contexte de la clé API courante /me
Portée read

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/me"

Modèles

GET Lister les modèles publiés disponibles pour le client /templates
Portée read Permission templates.view

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/templates"
GET Lister les modèles personnalisés du client /templates/custom
Portée read Permission templates.view

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1
Inclure les modèles personnalisés archivés
Filtrer par statut de modèle
Rechercher les modèles personnalisés par nom, description ou catégorie

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/templates/custom"
POST Créer un brouillon de modèle personnalisé /templates/custom
Portée write Permission templates.create

Corps de la requête application/json

Champs
name* string
description string | null
category* string
operations · quality · logistics · other
icon string
image string | null
tone string
primary · success · info · warning · danger · muted
config* object

Réponses

  • 201 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/templates/custom"
GET Afficher un modèle personnalisé /templates/custom/{uuid}
Portée read

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/templates/custom/{uuid}"
PATCH Modifier un brouillon ou les métadonnées d'un modèle personnalisé /templates/custom/{uuid}
Portée write

Paramètres

Corps de la requête application/json

Champs
name string
description string | null
category string
operations · quality · logistics · other
icon string
image string | null
tone string
primary · success · info · warning · danger · muted
config object

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X PATCH "https://givre.app/api/v1/templates/custom/{uuid}"
POST Publier un modèle personnalisé /templates/custom/{uuid}/publish
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/templates/custom/{uuid}/publish"
POST Archiver un modèle personnalisé /templates/custom/{uuid}/archive
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/templates/custom/{uuid}/archive"
POST Désarchiver un modèle personnalisé /templates/custom/{uuid}/unarchive
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/templates/custom/{uuid}/unarchive"
POST Dupliquer un modèle personnalisé en brouillon /templates/custom/{uuid}/duplicate
Portée write

Paramètres

Réponses

  • 201 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/templates/custom/{uuid}/duplicate"

Dossiers

GET Lister les dossiers /dossiers
Portée read

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1
Inclure les dossiers archivés
Filtrer par statut de dossier. archived implique include_archived.
Seulement les dossiers créés à partir de ce modèle
Rechercher les dossiers par nom ou référence
Filtrer par mode de création du dossier

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers"
POST Créer un dossier depuis un modèle /dossiers
Portée write

Fournir un utilisateur assigné nécessite la permission d'assignation des dossiers.

Corps de la requête application/json

Champs
template_uuid* string (uuid)
UUID du modèle renvoyé par GET /templates. Ce n'est pas un UUID de dossier.
name string | null
assigned_user_uuid string (uuid) | null
UUID utilisateur client optionnel à assigner au dossier.
due_at string (date-time) | null
Échéance facultative, dans le futur (ISO 8601). Passé cette date, un dossier encore actif passe au statut missed.

Réponses

  • 201 Réponse réussie
  • 403 L'utilisateur de l'API ne peut pas assigner de dossiers
  • 404 L'utilisateur sélectionné n'est pas disponible pour ce client
  • 422 L'utilisateur sélectionné est inactif ou indisponible
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers"
GET Afficher un dossier /dossiers/{uuid}
Portée read

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}"
PATCH Modifier le nom ou l'échéance du dossier /dossiers/{uuid}
Portée write

Envoyez name, due_at ou les deux. due_at doit être dans le futur ; null supprime l'échéance. Seul un dossier actif peut être modifié.

Paramètres

Corps de la requête application/json

Champs
name string
due_at string (date-time) | null

Réponses

  • 200 Réponse réussie
  • 403 forbidden : l'utilisateur de l'API ne peut pas modifier ce dossier, ou il n'est pas actif
  • 422 validation_failed : ni name ni due_at n'a été envoyé, ou due_at n'est pas dans le futur
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X PATCH "https://givre.app/api/v1/dossiers/{uuid}"
DELETE Supprimer un dossier /dossiers/{uuid}
Portée write

Supprime définitivement le dossier avec ses documents, certifications et fichiers ; cette action est irréversible. Nécessite la permission de suppression des dossiers. Les dossiers actifs, terminés et archivés peuvent être supprimés ; les dossiers archivés ne sont accessibles que si l'utilisateur API peut consulter les archives. Les transactions de jetons sont conservées et une trace d'audit est enregistrée.

Paramètres

Réponses

  • 200 Les identifiants du dossier supprimé
  • 403 forbidden : l'utilisateur API ne peut pas supprimer ce dossier
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X DELETE "https://givre.app/api/v1/dossiers/{uuid}"
POST Assigner un utilisateur à un dossier /dossiers/{uuid}/assignee
Portée write

Nécessite la permission d'assignation et un dossier actif.

Paramètres

Corps de la requête application/json

Champs
user_uuid* string (uuid)
UUID utilisateur client retourné par GET /users.

Réponses

  • 200 Réponse réussie
  • 403 Ce dossier ne peut pas être assigné par cet utilisateur de l'API
  • 404 L'utilisateur sélectionné n'est pas disponible pour ce client
  • 422 L'utilisateur sélectionné est inactif ou indisponible
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/assignee"
DELETE Retirer l'utilisateur assigné au dossier /dossiers/{uuid}/assignee
Portée write

Nécessite la permission d'assignation et un dossier actif.

Paramètres

Réponses

  • 200 Réponse réussie
  • 403 Ce dossier ne peut pas être assigné par cet utilisateur de l'API
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X DELETE "https://givre.app/api/v1/dossiers/{uuid}/assignee"
POST Terminer un dossier /dossiers/{uuid}/complete
Portée write

Nécessite la permission dossiers.complete et un dossier actif. Terminer un dossier déjà terminé le renvoie inchangé.

Paramètres

Réponses

  • 200 Réponse réussie
  • 403 forbidden : l'utilisateur de l'API ne peut pas terminer ce dossier
  • 409 invalid_state : le statut du dossier ne permet pas cette action
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/complete"
POST Rouvrir un dossier terminé ou non fait /dossiers/{uuid}/reopen
Portée write

Repasse un dossier terminé ou non fait à l'état actif et efface completed_at et missed_at, pour que des documents puissent de nouveau être ajoutés depuis tous les canaux. Une échéance déjà passée (toujours le cas d'un dossier non fait) est supprimée : due_at devient null. Rouvrir un dossier actif le renvoie inchangé. Les dossiers archivés doivent d'abord être désarchivés.

Paramètres

Réponses

  • 200 Réponse réussie
  • 403 forbidden : l'utilisateur API ne peut pas modifier ce dossier, ou le dossier est archivé
  • 409 invalid_state : seul un dossier terminé ou non fait peut être rouvert
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/reopen"
POST Archiver un dossier /dossiers/{uuid}/archive
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 409 invalid_state : le statut du dossier ne permet pas cette action
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/archive"
POST Désarchiver un dossier /dossiers/{uuid}/unarchive
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 409 invalid_state : le statut du dossier ne permet pas cette action
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/unarchive"
POST Ajouter les nouvelles étapes du modèle à un dossier /dossiers/{uuid}/template-sync
Portée write

Lorsque les étapes du dossier sont encore le début du modèle publié (même capture_type et certification_format par index de preuve ; les noms ne sont pas comparés, sauf sur une étape qui reçoit des preuves), les étapes finales manquantes sont ajoutées, les preuves ajoutées en fin d'étape existante y sont ajoutées, et les allowed_roles des étapes existantes sont mis à jour depuis le modèle. Les noms, index et documents des étapes et preuves existantes ne changent jamais. Les dossiers terminés sont acceptés ; un nouvel appel renvoie added_steps 0, added_proofs 0 et updated_steps 0.

Paramètres

Réponses

  • 200 Le dossier ; meta.added_steps compte les étapes ajoutées, meta.added_proofs les preuves ajoutées aux étapes existantes et meta.updated_steps les étapes existantes dont les allowed_roles ont changé (0 partout si déjà à jour)
  • 403 forbidden : l'utilisateur de l'API ne peut pas modifier ce dossier
  • 409 template_snapshot_diverged : les étapes du dossier ne correspondent plus au début du modèle ; dossier_archived : désarchivez d'abord le dossier ; template_not_published : le modèle du dossier n'est pas publié. Rien n'a été modifié.
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/template-sync"

Utilisateurs

GET Lister les utilisateurs client /users
Portée read

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1
Filtrer les utilisateurs par statut actif ou inactif
Rechercher les utilisateurs par nom ou e-mail

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/users"
POST Créer un utilisateur client /users
Portée write

Corps de la requête application/json

Champs
first_name* string
last_name string | null
email* string (email)
password string (password)
password_hash string
Empreinte de mot de passe bcrypt/argon facultative, importée telle quelle. À utiliser à la place de password.
role string | null
admin · manager · inspecteur · user · api-consumer
is_owner boolean
is_active boolean

Réponses

  • 201 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/users"
GET Afficher un utilisateur client /users/{uuid}
Portée read

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/users/{uuid}"
PATCH Modifier un utilisateur client /users/{uuid}
Portée write

Paramètres

Corps de la requête application/json

Champs
first_name string
last_name string | null
email string (email)
password string (password)
password_hash string
Empreinte de mot de passe bcrypt/argon facultative, importée telle quelle. À utiliser à la place de password.
role string | null
admin · manager · inspecteur · user · api-consumer
is_owner boolean
is_active boolean

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X PATCH "https://givre.app/api/v1/users/{uuid}"
POST Activer un utilisateur client /users/{uuid}/activate
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/users/{uuid}/activate"
POST Désactiver un utilisateur client /users/{uuid}/deactivate
Portée write

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/users/{uuid}/deactivate"

Documents

GET Lister les documents rattachés à un dossier /dossiers/{uuid}/documents
Portée read

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}/documents"
POST Envoyer un document de preuve et mettre la certification Datasure en file /dossiers/{uuid}/documents
Portée write

Paramètres

Corps de la requête multipart/form-data

Réponses

  • 201 Réponse réussie
  • 200 Déjà envoyé avec ce client_capture_id : le document enregistré
  • 403 forbidden : le dossier est archivé ou non fait, ou l'utilisateur de l'API ne peut pas le modifier ; step_role_forbidden : l'étape est réservée à des rôles que l'utilisateur de l'API ne possède pas. Un dossier non fait accepte encore un document dont captured_at ne dépasse pas due_at, envoyé dans les 24 heures qui suivent due_at.
  • 409 capture_id_conflict : le client_capture_id est déjà lié à un autre fichier
  • 422 validation_failed, ou capture_hash_mismatch : le fichier reçu ne correspond pas à client_sha256
  • 503 document_storage_unavailable : réessayez après le délai Retry-After
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/documents"
POST Envoyer les réponses d'une preuve formulaire /dossiers/{uuid}/forms
Portée write

Les réponses sont contrôlées selon la version du formulaire figée dans le dossier, puis enregistrées en document PDF de la preuve et certifiées comme un envoi de fichier. Un nouvel envoi crée un nouveau document.

Paramètres

Corps de la requête application/json

Champs
step_index* integer
proof_index* integer
form_version_uuid* string (uuid)
form.version_uuid de la preuve dans le dossier.
client_submission_id* string (uuid)
Votre identifiant unique pour cet envoi. Réessayer avec le même identifiant et les mêmes réponses renvoie l'envoi enregistré (200).
answers* object
Réponses organisées comme le schéma du formulaire : une section est un objet, une section répétée une liste d'objets.
captured_at string (date-time) | null
device object

Réponses

  • 201 Réponse réussie
  • 200 Déjà envoyé avec ce client_submission_id et ces réponses : l'envoi enregistré
  • 403 forbidden : le dossier est archivé ou manqué, ou l'utilisateur de l'API ne peut pas le modifier ; step_role_forbidden : l'étape est réservée à des rôles que l'utilisateur de l'API n'a pas.
  • 409 submission_id_conflict : le client_submission_id a déjà été envoyé avec d'autres réponses
  • 422 validation_failed ; proof_not_form : la preuve n'est pas un formulaire ; form_version_mismatch : form_version_uuid n'est pas la version du dossier ; form_invalid : les réponses ont des problèmes, listés dans « issues » à la racine (path, code, message)
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/forms"
GET Afficher les métadonnées, la certification et les artefacts du document /dossiers/{uuid}/documents/{document}
Portée read

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}"
GET Télécharger le document original du dossier /dossiers/{uuid}/documents/{document}/download
Portée read Téléchargement de fichier

Paramètres

Renvoyer l'aperçu avec le bandeau de géolocalisation et d'horodatage lorsqu'il est disponible

Réponses

  • 200 Fichier binaire
  • 403 Les téléchargements de documents sont désactivés pour les comptes clients.
  • 404 Le document original est introuvable
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/download"
GET Lister les artefacts générés pour un document /dossiers/{uuid}/documents/{document}/artifacts
Portée read

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/artifacts"

Certifications

GET Lister les certifications Datasure /certifications
Portée read Permission dossiers.view | dossiers.view_all

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1
Filtrer par statut de certification

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/certifications"
GET Afficher une certification /certifications/{certification}
Portée read Permission dossiers.view | dossiers.view_all

Paramètres

UUID de la certification.

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/certifications/{certification}"
POST Mettre en file la certification d'un document existant /dossiers/{uuid}/documents/{document}/certifications
Portée write

Relance la certification d'un document qui n'est pas encore valide ; un document valide est renvoyé tel quel. Les dossiers archivés répondent 404.

Paramètres

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/certifications"
GET Télécharger le PDF de certificat eIDAS Datasure stocké /dossiers/{uuid}/documents/{document}/eidas-certificate
Portée read Téléchargement de fichier

Ne génère et ne facture jamais : appelez d'abord POST sur la même URL.

Paramètres

Réponses

  • 200 Fichier PDF
  • 403 Les téléchargements de documents sont désactivés pour les comptes clients.
  • 404 artifact_not_found : aucun certificat eIDAS n'a encore été généré
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/eidas-certificate"
POST Générer ou réutiliser le PDF de certificat eIDAS Datasure stocké /dossiers/{uuid}/documents/{document}/eidas-certificate
Portée write

La première génération réussie coûte un jeton ; les appels suivants réutilisent gratuitement le PDF enregistré.

Paramètres

Réponses

  • 200 Réponse réussie
  • 402 insufficient_tokens : le client n'a plus de jeton
  • 403 missing_permission : l'utilisateur API ne peut pas générer d'artefacts
  • 409 certification_not_ready : le document n'est pas encore certifié
  • 502 artifact_generation_failed : le prestataire a échoué, rien n'a été débité
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/eidas-certificate"
POST Générer ou réutiliser le PDF signé PAdES stocké pour un document PDF certifié /dossiers/{uuid}/documents/{document}/sign-pdf
Portée write

La première génération réussie coûte un jeton ; les appels suivants réutilisent gratuitement le PDF enregistré.

Paramètres

Réponses

  • 200 Réponse réussie
  • 402 insufficient_tokens : le client n'a plus de jeton
  • 403 missing_permission : l'utilisateur API ne peut pas générer d'artefacts
  • 409 certification_not_ready : le document n'est pas encore certifié
  • 422 document_not_pdf : seuls les documents PDF peuvent être signés
  • 502 artifact_generation_failed : le prestataire a échoué, rien n'a été débité
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 404 not_found : ressource inconnue ou appartenant à un autre client
  • 429 too_many_requests : attendez le délai Retry-After
curl -X POST "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/sign-pdf"
GET Télécharger le PDF signé PAdES stocké /dossiers/{uuid}/documents/{document}/signed-pdf
Portée read Téléchargement de fichier

Paramètres

Réponses

  • 200 Fichier PDF
  • 403 Les téléchargements de documents sont désactivés pour les comptes clients.
  • 404 Aucun PDF signé stocké n'a été trouvé
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/dossiers/{uuid}/documents/{document}/signed-pdf"

Jetons

GET Lire le solde de jetons client /tokens/balance
Portée read Permission dashboard.costs

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/tokens/balance"
GET Lister l'historique des transactions de jetons /tokens/transactions
Portée read Permission dashboard.costs

Paramètres

Éléments par page, 25 par défaut. Les valeurs hors de 1 à 100 sont ramenées dans cet intervalle, pas refusées.
Numéro de page, à partir de 1

Réponses

  • 200 Réponse réussie
  • 401 invalid_api_key ou api_key_not_valid (expirée ou révoquée)
  • 403 missing_api_scope ou missing_permission
  • 422 validation_failed : voir errors
  • 429 too_many_requests : attendez le délai Retry-After
curl -X GET "https://givre.app/api/v1/tokens/transactions"