Présentation
L’API publique StageReturn est une API de consultation en lecture seule. La clé API détermine automatiquement l’entreprise dont les données peuvent être consultées.
- Format des réponses : JSON
- Protocole : HTTPS
- Authentification : header x-api-key
- Méthode acceptée : GET
- Corps de requête : aucun
- Paramètres : transmis dans la chaîne de requête de l’URL
Cette page documente uniquement les deux endpoints publics réellement disponibles : equipmentStatusApi et missingEquipmentStatusApi.
URL de base
L’URL officielle de l’API StageReturn est :
Base URL
https://api.stagereturn.com
Cette adresse est le point d’entrée officiel de l’API StageReturn. Toutes les requêtes documentées ci-dessous utilisent ce domaine.
Les endpoints publics disponibles sont :
Endpoints
GET /equipmentStatusApi GET /missingEquipmentStatusApi
Format des requêtes
- Utilisez la méthode GET.
- Transmettez les paramètres dans l’URL.
- N’envoyez aucun corps de requête.
- Envoyez la clé dans le header x-api-key.
- Le header Accept: application/json est recommandé.
- Encodez les paramètres avec l’encodage URL.
Exemple HTTP
GET /equipmentStatusApi?serial=SN-123456 HTTP/1.1 Host: api.stagereturn.com x-api-key: VOTRE_CLE_API Accept: application/json
Authentification
Chaque requête doit transmettre une clé API StageReturn valide dans le header HTTP x-api-key.
Header requis
x-api-key: VOTRE_CLE_API
La clé doit être envoyée telle quelle, sans préfixe Bearer.
Obtenir une clé API
Dans StageReturn, ouvrez l’espace d’administration puis la section API. La clé doit être générée et activée par un utilisateur autorisé de l’entreprise.
Conservez la clé côté serveur. Ne l’intégrez pas dans un site public, une application frontend ou un dépôt de code accessible.
Premier appel
Ce premier appel consulte le statut associé au numéro de série SN-123456.
cURL
Bash
curl --request GET \ --url "https://api.stagereturn.com/equipmentStatusApi?serial=SN-123456" \ --header "x-api-key: VOTRE_CLE_API" \ --header "Accept: application/json"
JavaScript / Node.js
JavaScript
const url = new URL(
"https://api.stagereturn.com/equipmentStatusApi"
);
url.searchParams.set("serial", "SN-123456");
const response = await fetch(url, {
method: "GET",
headers: {
"x-api-key": process.env.STAGERETURN_API_KEY,
"Accept": "application/json"
}
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.error || `HTTP ${response.status}`);
}
console.log(data);
PHP
PHP
<?php
$serial = rawurlencode("SN-123456");
$url = "https://api.stagereturn.com/equipmentStatusApi?serial={$serial}";
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"x-api-key: " . getenv("STAGERETURN_API_KEY"),
"Accept: application/json"
],
CURLOPT_TIMEOUT => 15
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($body, true);
if ($status < 200 || $status >= 300) {
throw new Exception($data["error"] ?? "HTTP {$status}");
}
Python
Python
import os
import requests
response = requests.get(
"https://api.stagereturn.com/equipmentStatusApi",
params={"serial": "SN-123456"},
headers={
"x-api-key": os.environ["STAGERETURN_API_KEY"],
"Accept": "application/json",
},
timeout=15,
)
data = response.json()
if not response.ok:
raise RuntimeError(data.get("error", f"HTTP {response.status_code}"))
print(data)
GET
/equipmentStatusApi?serial=XXXX
Consulter le statut d’un équipement sérialisé
Recherche jusqu’à 10 réparations ouvertes de l’entreprise pour le numéro de série fourni. Une réparation est considérée comme ouverte lorsque son statut est todo ou in_progress.
Si plusieurs réparations ouvertes correspondent au même numéro de série, une réparation qui immobilise l’équipement est prioritaire. Si aucune réparation ouverte ne l’immobilise, l’API retourne les informations de la première réparation ouverte trouvée.
Paramètre de requête
| Paramètre | Type | Obligatoire | Traitement exact |
|---|---|---|---|
| serial | string | Oui | La valeur est convertie en chaîne puis les espaces placés au début et à la fin sont supprimés. La recherche restante est exacte et sensible à la casse. Le numéro doit donc correspondre exactement à serialNumber dans StageReturn. |
Réponse lorsqu’une réparation immobilise l’équipement
JSON — HTTP 200
{
"success": true,
"serial": "SN-123456",
"erpImmobilized": true,
"erpImmobilizationEnabled": true,
"erpProvider": "rentman",
"erpSyncStatus": "synced",
"erpStatusReason": "repair_open",
"stockAvailable": false,
"reason": "repair_open",
"repairStatus": "in_progress",
"repairId": "abc123",
"repairTitle": "Projecteur LED",
"problemDescription": "Le projecteur ne s’allume plus.",
"projectId": "project123",
"projectName": "Concert été",
"projectNumber": "PRJ-00124",
"repairCreatedAt": "2026-07-10T09:18:22.000Z",
"repairUpdatedAt": "2026-07-11T14:52:03.000Z",
"updatedAt": "2026-07-12T14:00:00.000Z"
}
Réponse lorsqu’aucune réparation ouverte n’est trouvée
JSON — HTTP 200
{
"success": true,
"serial": "SN-INCONNU",
"erpImmobilized": false,
"erpImmobilizationEnabled": false,
"erpProvider": null,
"erpSyncStatus": null,
"erpStatusReason": "none",
"stockAvailable": true,
"reason": "none",
"repairStatus": null,
"repairId": null,
"repairTitle": null,
"problemDescription": null,
"projectId": null,
"projectName": null,
"projectNumber": null,
"repairCreatedAt": null,
"repairUpdatedAt": null,
"updatedAt": "2026-07-12T14:00:00.000Z"
}
Cet endpoint ne vérifie pas l’existence d’un équipement dans un catalogue. Un numéro sans réparation ouverte retourne donc également HTTP 200 avec stockAvailable: true et les champs de réparation à null.
Champs retournés
| Champ | Type | Valeur exacte |
|---|---|---|
| success | boolean | Toujours true pour une réponse HTTP 200. |
| serial | string | Numéro de série reçu après suppression des espaces de début et de fin. |
| erpImmobilized | boolean | true lorsqu’une réparation ouverte immobilise l’équipement. Les anciennes réparations compatibles peuvent également être prises en compte. |
| erpImmobilizationEnabled | boolean | true si au moins une réparation ouverte active l’immobilisation ERP. Les anciennes réparations compatibles peuvent également être prises en compte. |
| erpProvider | string | null | Fournisseur ERP de la réparation retenue. Si la réparation immobilisée ne contient pas cette valeur, l’API peut conserver celle de la première réparation ouverte trouvée. Le connecteur actuellement produit par StageReturn utilise rentman. |
| erpSyncStatus | string | null | Statut ERP de la réparation retenue. Si la réparation immobilisée ne contient pas cette valeur, l’API peut conserver celle de la première réparation ouverte trouvée. Les valeurs retournées par l’API sont détaillées plus bas. |
| erpStatusReason | string | none, erp_immobilization_disabled_or_pending, ou le motif enregistré sur la réparation immobilisée. La valeur par défaut d’une immobilisation est repair_open. |
| stockAvailable | boolean | false uniquement lorsqu’une réparation ouverte est considérée comme immobilisée ; sinon true. |
| reason | string | none sans réparation ouverte, repair_open pour une réparation ouverte non immobilisée, ou le motif enregistré sur la réparation immobilisée. |
| repairStatus | string | null | todo, in_progress ou null. |
| repairId | string | null | Identifiant de la réparation ouverte sélectionnée. |
| repairTitle | string | null | Première valeur non vide trouvée parmi le titre, le nom ou le nom d’équipement de la réparation retenue. Si la réparation immobilisée ne fournit aucune valeur, l’API peut conserver celle de la première réparation ouverte trouvée. |
| problemDescription | string | null | Première description non vide trouvée parmi les champs de problème, diagnostic, description ou remarque de la réparation retenue. Si la réparation immobilisée ne fournit aucune valeur, l’API peut conserver celle de la première réparation ouverte trouvée. |
| projectId | string | null | Identifiant du projet associé à la réparation retenue lorsqu’il est enregistré. Si la réparation immobilisée ne fournit pas d’identifiant, l’API peut conserver celui de la première réparation ouverte trouvée. |
| projectName | string | null | Nom du projet associé à la réparation retenue lorsqu’il est disponible. Il peut être complété à partir du projet lié ou conservé depuis la première réparation ouverte trouvée. |
| projectNumber | string | null | Numéro du projet associé à la réparation retenue lorsqu’il est disponible. Il peut être complété à partir du projet lié ou conservé depuis la première réparation ouverte trouvée. |
| repairCreatedAt | string | null | Date de création de la réparation retenue convertie au format ISO 8601. Si la réparation immobilisée ne fournit aucune date exploitable, l’API peut conserver celle de la première réparation ouverte trouvée. |
| repairUpdatedAt | string | null | Première date disponible parmi la mise à jour de la réparation retenue, la mise à jour ERP ou la dernière synchronisation ERP, convertie en ISO 8601. Si aucune date n’est disponible sur la réparation immobilisée, l’API peut conserver celle de la première réparation ouverte trouvée. |
| updatedAt | string | Date de génération de la réponse au format ISO 8601. |
GET
/missingEquipmentStatusApi?projectId=…&defectId=…
Consulter un équipement manquant
Retourne la déclaration désignée par un identifiant de projet et un identifiant de défaut, à condition qu’elle appartienne à l’entreprise associée à la clé API.
Paramètres de requête
| Paramètre | Type | Obligatoire | Traitement exact |
|---|---|---|---|
| projectId | string | Oui | Identifiant exact du projet. Les espaces de début et de fin sont supprimés. |
| defectId | string | Oui | Identifiant exact de la déclaration dans le projet. Les espaces de début et de fin sont supprimés. |
Exemple de requête
HTTP
GET /missingEquipmentStatusApi?projectId=project123&defectId=defect456 x-api-key: VOTRE_CLE_API Accept: application/json
Exemple de réponse complète
JSON — HTTP 200
{
"success": true,
"projectId": "project123",
"defectId": "defect456",
"equipmentName": "Câble XLR 10 m",
"isSerialized": false,
"serial": null,
"isMissingEquipment": true,
"missingQuantity": 5,
"returnedQuantity": 2,
"remainingMissingQuantity": 3,
"erpStockSyncEnabled": true,
"erpStockSynced": true,
"erpProvider": "rentman",
"erpConnectionId": "connection123",
"erpMappingId": "mapping123",
"erpItemId": "742",
"erpExternalItemId": "742",
"erpItemName": "Câble XLR 10 m",
"erpSyncStatus": "reintegrated",
"erpLastSyncAt": "2026-07-12T10:30:00.000Z",
"erpLastError": null,
"erpQuantityRemoved": 5,
"erpQuantityReintegrated": 2,
"erpRemainingQuantity": 3,
"projectName": "Festival été",
"projectNumber": "PRJ-00130",
"entrepotId": "warehouse123",
"updatedAt": "2026-07-12T14:00:00.000Z"
}
Champs retournés
| Champ | Type exact | Valeur exacte |
|---|---|---|
| success | boolean | Toujours true pour une réponse HTTP 200. |
| projectId | string | Identifiant du projet reçu après suppression des espaces de début et de fin. |
| defectId | string | Identifiant de déclaration reçu après suppression des espaces de début et de fin. |
| equipmentName | string | null | Nom de l’équipement, ou null s’il est vide. |
| isSerialized | boolean | true si la déclaration contient un numéro de série non vide dans numeroSerie. |
| serial | string | null | Numéro de série de la déclaration, après suppression des espaces de début et de fin, ou null. |
| isMissingEquipment | boolean | true uniquement si equipementManquant vaut strictement true. |
| missingQuantity | integer | Valeur de quantite convertie en nombre entier tronqué. Une valeur absente ou invalide devient 0. |
| returnedQuantity | integer | Valeur de returnedQty convertie en entier tronqué. Une valeur absente ou invalide devient 0. |
| remainingMissingQuantity | integer | max(0, missingQuantity – returnedQuantity). |
| erpStockSyncEnabled | boolean | true uniquement si l’option vaut strictement true. |
| erpStockSynced | boolean | true uniquement si le champ enregistré vaut strictement true. |
| erpProvider | valeur JSON | null | Valeur ERP enregistrée, renvoyée telle quelle, ou null. Dans l’usage StageReturn actuel, cette valeur est normalement une chaîne comme rentman. |
| erpConnectionId | valeur JSON | null | Identifiant de connexion ERP enregistré, renvoyé tel quel, ou null. Dans l’usage StageReturn actuel, cette valeur est normalement une chaîne. |
| erpMappingId | valeur JSON | null | Identifiant de mapping ERP enregistré, renvoyé tel quel, ou null. Dans l’usage StageReturn actuel, cette valeur est normalement une chaîne. |
| erpItemId | string | number | null | erpItemId, sinon erpExternalItemId, sinon null. Le backend ne force pas ce champ en chaîne. |
| erpExternalItemId | string | number | null | erpExternalItemId, sinon erpItemId, sinon null. Le backend ne force pas ce champ en chaîne. |
| erpItemName | valeur JSON | null | Nom d’article ERP enregistré, renvoyé tel quel, ou null. Dans l’usage StageReturn actuel, cette valeur est normalement une chaîne. |
| erpSyncStatus | string | null | Statut ERP enregistré. Les valeurs retournées par l’API sont détaillées plus bas. |
| erpLastSyncAt | string | null | Date convertie au format ISO 8601, ou null. |
| erpLastError | string | null | Dernière erreur ERP enregistrée, ou null. Ce champ peut contenir une erreur technique variable. |
| erpQuantityRemoved | integer | Quantité retirée, convertie en entier tronqué ; valeur invalide ou absente : 0. |
| erpQuantityReintegrated | integer | Quantité réintégrée, convertie en entier tronqué ; valeur invalide ou absente : 0. |
| erpRemainingQuantity | integer | Valeur enregistrée dans erpRemainingQuantity, convertie en entier tronqué ; valeur invalide ou absente : 0. |
| projectName | string | null | Nom du projet, ou null. |
| projectNumber | string | null | Numéro du projet, ou null. |
| entrepotId | string | number | null | Identifiant du dépôt de la déclaration, sinon celui du projet, sinon null. Le backend ne force pas ce champ en chaîne. |
| updatedAt | string | Date de génération de la réponse au format ISO 8601. |
Valeurs retournées par l’API
repairStatus
- todo : réparation ouverte à faire.
- in_progress : réparation ouverte en cours.
- null : aucune réparation ouverte sélectionnée.
erpSyncStatus d’une réparation sérialisée
- syncing
- not_required
- not_configured
- rate_limited
- not_found
- error
- synced
- released
- null
erpSyncStatus d’un équipement manquant
- syncing
- not_configured
- rate_limited
- error
- synced
- reintegrated
- null
Ces listes regroupent les valeurs produites par le fonctionnement actuel de l’API. Une donnée plus ancienne peut exceptionnellement contenir une valeur héritée.
Codes HTTP réellement utilisés
| Code | Endpoint | Cas exact |
|---|---|---|
| 200 | Les deux | Requête traitée avec succès. Pour equipmentStatusApi, HTTP 200 est également retourné lorsqu’aucune réparation ouverte ne correspond au numéro de série. |
| 400 | equipmentStatusApi | Paramètre serial absent ou vide. |
| 400 | missingEquipmentStatusApi | projectId ou defectId absent ou vide. |
| 401 | Les deux | Clé API absente ou invalide. |
| 403 | Les deux | Configuration API trouvée mais désactivée. |
| 404 | missingEquipmentStatusApi | Projet ou déclaration introuvable, ou ressource n’appartenant pas à l’entreprise de la clé API. |
| 405 | Les deux | Méthode HTTP différente de GET. |
| 500 | Les deux | Configuration API invalide ou erreur interne inattendue. |
Réponses d’erreur exactes
Toutes les erreurs de ces deux endpoints sont renvoyées sous cette forme :
JSON
{
"success": false,
"error": "error_code"
}
| Valeur de error | HTTP | Endpoint | Signification |
|---|---|---|---|
| method_not_allowed | 405 | Les deux | La méthode utilisée n’est pas GET. |
| missing_api_key | 401 | Les deux | Le header x-api-key est absent ou vide. |
| invalid_api_key | 401 | Les deux | Aucune configuration API ne correspond à la clé. |
| api_disabled | 403 | Les deux | La clé existe, mais l’accès API n’est pas activé. |
| missing_serial | 400 | equipmentStatusApi | Le paramètre serial est absent ou vide. |
| missing_parameters | 400 | missingEquipmentStatusApi | projectId ou defectId est absent ou vide. |
| project_not_found | 404 | missingEquipmentStatusApi | Le projet n’existe pas ou n’appartient pas à l’entreprise de la clé API. |
| equipment_not_found | 404 | missingEquipmentStatusApi | La déclaration n’existe pas ou n’appartient pas à l’entreprise de la clé API. |
| invalid_enterprise_ref | 500 | Les deux | La configuration API est invalide. Le client doit contacter le support StageReturn. |
| internal_error | 500 | Les deux | Une erreur inattendue est survenue pendant le traitement. |
Règles d’intégration à respecter
Disponibilité sérialisée
Utilisez stockAvailable comme résultat principal. erpImmobilized indique la cause ERP de l’indisponibilité.
Numéro inconnu
equipmentStatusApi ne possède pas de réponse 404. Une réponse disponible ne confirme pas que le numéro existe dans un catalogue.
Identifiants manquants
Pour appeler missingEquipmentStatusApi, l’intégration doit déjà connaître le projectId et le defectId. Aucun endpoint public actuel ne permet de les rechercher ou de les lister.
Valeurs nulles
Traitez tous les champs marqués | null comme réellement facultatifs.
Encodage des paramètres
Encodez toujours les paramètres avec l’encodage URL, notamment les numéros de série contenant des espaces ou des caractères spéciaux.
Gestion des erreurs
Basez la logique sur le code HTTP et la valeur du champ error. Ne tentez pas d’interpréter le texte d’une autre source.
Avec les endpoints publics disponibles, une intégration externe peut consulter un statut par numéro de série et consulter une déclaration connue par ses deux identifiants. Elle ne peut pas lister les projets, rechercher des déclarations, créer un incident ni modifier une donnée.
Checklist avant mise en production
- La clé API est stockée uniquement côté serveur.
- Les paramètres sont encodés dans l’URL.
- Le client traite les codes HTTP avant d’utiliser les données.
- Les champs pouvant valoir null sont gérés.
- Le statut d’un équipement sérialisé repose sur stockAvailable.
- Une réponse HTTP 200 de equipmentStatusApi n’est pas utilisée comme preuve d’existence dans un catalogue.
- Les identifiants projectId et defectId sont conservés lorsque l’intégration doit consulter un équipement manquant.
- Les erreurs 500 sont journalisées sans enregistrer la clé API.
Assistance technique
En cas d’échec, transmettez au support l’endpoint appelé, les paramètres utilisés sans données sensibles, le code HTTP et la valeur du champ error. Ne transmettez jamais votre clé API.
