API REST SmartDoc (/api/v1/)

L'API REST SmartDoc fournit un acces CRUD complet a toutes les entites de documentation. Tous les endpoints requierent une authentification par cle API.

Authentification

Toutes les requetes doivent inclure la cle API dans l'en-tete Authorization :

curl -H "Authorization: Bearer sk-smartdoc-VOTRE_CLE_ICI" \
  https://smartdoc.mspsmart.ca/api/v1/companies

URL de base

https://smartdoc.mspsmart.ca/api/v1/

Documentation interactive

La documentation Swagger UI est disponible a :

https://smartdoc.mspsmart.ca/api/v1/docs/

Elle permet de visualiser tous les endpoints et de les tester directement depuis le navigateur.

---

Endpoints communs

Chaque entite expose jusqu'a 5 endpoints standards :

Methode	Endpoint	Description	Scope requis
GET	/{entite}	Lister avec pagination	read-only
GET	/{entite}/{id}	Obtenir par ID	read-only
POST	/{entite}	Creer	read-write
PATCH	/{entite}/{id}	Modifier	read-write
DELETE	/{entite}/{id}	Supprimer	full-access

Endpoints speciaux

Methode	Endpoint	Description
GET	/search?q=keyword	Recherche cross-entites
GET	/whoami	Informations sur la cle API

---

Parametres de liste (GET)

Tous les endpoints de liste acceptent les parametres suivants :

Parametre	Type	Defaut	Description
page	number	1	Numero de page
limit	number	25	Elements par page (max: 100)
sort_by	string	varie	Colonne de tri
sort_order	asc | desc	desc	Ordre de tri
search	string	—	Recherche textuelle (ILIKE)
company_id	UUID	—	Filtrer par compagnie
status	string	—	Filtrer par statut

Exemple

curl -H "Authorization: Bearer sk-smartdoc-..." \
  "https://smartdoc.mspsmart.ca/api/v1/assets?page=1&limit=10&search=server&sort_by=name&sort_order=asc"

---

Format de reponse

Liste

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "...",
      "name": "Serveur principal",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "totalPages": 6
  }
}

Element unique

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenantId": "...",
    "name": "Serveur principal",
    "hostname": "SRV-PROD-01",
    "status": "active"
  }
}

Erreur

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

---

Reference des entites

Contenu

Documents (/api/v1/documents)

Gestion des documents de documentation client.

Champ	Type	Description
id	UUID	Identifiant unique
companyId	UUID	Compagnie associee
title	string	Titre du document
description	string	Description
content	string	Contenu HTML
status	string	Statut (draft, published, archived)
accessLevel	string	Niveau d'acces
documentTypeId	UUID	Type de document
folderId	UUID	Dossier parent
tags	string[]	Tags associes
viewCount	number	Nombre de consultations
createdAt	datetime	Date de creation

Tri possible : title, created_at, updated_at, status Recherche : title, description

Types de documents (/api/v1/document-types)

Definitions des categories de documents.

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom du type
slug	string	Identifiant URL
category	string	Categorie
icon	string	Icone
color	string	Couleur
sortOrder	number	Ordre d'affichage

Articles KB (/api/v1/kb-articles)

Articles de la base de connaissances.

Champ	Type	Description
id	UUID	Identifiant unique
companyId	UUID	Compagnie
title	string	Titre de l'article
content	string	Contenu HTML
status	string	Statut
categoryId	UUID	Categorie KB
isPublic	boolean	Visible publiquement
isFeatured	boolean	Mis en avant

Categories KB (/api/v1/kb-categories)

Categories de la base de connaissances.

Changelogs (/api/v1/changelogs)

Historique des modifications d'infrastructure.

---

Securite

Identifiants (/api/v1/credentials)

Coffre-fort d'identifiants. Les champs sensibles (password_encrypted, notes_encrypted, etc.) ne sont jamais exposes via l'API.

Champ	Type	Description
id	UUID	Identifiant unique
companyId	UUID	Compagnie
name	string	Nom de l'identifiant
credentialType	string	Type (password, api_key, ssh_key, etc.)
username	string	Nom d'utilisateur
url	string	URL de connexion
status	string	Statut (active, expired, revoked)
passwordStrength	string	Force du mot de passe
accessCount	number	Nombre d'acces

Champs chiffres exclus

Les champs contenant des secrets chiffres (password_encrypted, notes_encrypted, totp_secret_encrypted, etc.) ne sont jamais retournes par l'API pour des raisons de securite.

VPN (/api/v1/vpn)

Configurations VPN (sans mots de passe/PSK chiffres).

WiFi (/api/v1/wifi)

Reseaux WiFi (sans mots de passe chiffres).

---

IT Assets

Actifs (/api/v1/assets)

Inventaire complet des actifs IT.

Champ	Type	Description
id	UUID	Identifiant unique
companyId	UUID	Compagnie
name	string	Nom de l'actif
hostname	string	Nom d'hote
serialNumber	string	Numero de serie
assetTag	string	Etiquette d'actif
status	string	Statut
location	string	Emplacement
ipAddresses	string[]	Adresses IP
macAddresses	string[]	Adresses MAC
specs	object	Specifications materielles
warrantyExpiry	date	Expiration de garantie

Tri : name, hostname, created_at, updated_at, status Recherche : name, hostname, serial_number, asset_tag

Types d'actifs (/api/v1/asset-types)

Definitions des categories d'actifs.

Certificats (/api/v1/certificates)

Certificats SSL/TLS (sans cles privees chiffrees).

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom
domain	string	Domaine
commonName	string	CN du certificat
issuer	string	Autorite de certification
validFrom	date	Date de debut
validUntil	date	Date d'expiration

Applications (/api/v1/applications)

Licences logicielles (sans cles de licence chiffrees).

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom du logiciel
vendor	string	Editeur
version	string	Version
licenseSeats	number	Nombre de licences
licenseSeatsUsed	number	Licences utilisees
expiryDate	date	Date d'expiration
cost	number	Cout

Numeros de serie (/api/v1/serials)

Garanties et suivi materiel (sans numeros de serie chiffres).

Racks (/api/v1/racks)

Disposition physique des equipements serveur.

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom du rack
locationName	string	Emplacement
totalUnits	number	Unites totales
usedUnitsFront	number	Unites utilisees (avant)
usedUnitsRear	number	Unites utilisees (arriere)
powerCapacityWatts	number	Capacite electrique

---

Reseau

Diagrammes reseau (/api/v1/network-diagrams)

Topologies et schemas visuels.

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom du diagramme
diagramType	string	Type de diagramme
engineType	string	Moteur de rendu
thumbnailUrl	string	Miniature

---

Organisation

Compagnies (/api/v1/companies)

Gestion des compagnies clientes.

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom de la compagnie
identifier	string	Identifiant interne
status	string	Statut
phone	string	Telephone
website	string	Site web
city	string	Ville

Tri : name, created_at, updated_at, status Recherche : name, identifier

Tags (/api/v1/tags)

Systeme de tags transversal.

Dossiers (/api/v1/folders)

Arborescence de dossiers pour organiser les entites.

Liens d'entites (/api/v1/entity-links)

Relations entre entites (ex : un document lie a un actif).

Accords (/api/v1/agreements)

Contrats de service et ententes.

---

Processus et monitoring

Processus (/api/v1/processes)

Procedures et listes de taches.

Sites web (/api/v1/websites)

Monitoring de sites web.

Champ	Type	Description
id	UUID	Identifiant unique
name	string	Nom
url	string	URL a surveiller
isMonitored	boolean	Surveillance active
isUp	boolean	Etat actuel
httpStatus	number	Code HTTP
responseTimeMs	number	Temps de reponse (ms)
sslValidTo	date	Expiration SSL
domainExpiresAt	date	Expiration du domaine

Photos (/api/v1/photos)

Bibliotheque de medias.

---

Recherche globale

L'endpoint de recherche permet de chercher simultanement dans plusieurs types d'entites :

curl -H "Authorization: Bearer sk-smartdoc-..." \
  "https://smartdoc.mspsmart.ca/api/v1/search?q=firewall&entity_types=assets,documents"

Parametres

Parametre	Type	Description
q	string	Terme de recherche (obligatoire)
entity_types	string	Types d'entites (separes par virgule). Defaut : tous
limit	number	Max resultats par type (defaut : 10, max : 50)

Types recherchables

documents, kb-articles, assets, credentials, companies, certificates, websites

Reponse

{
  "data": [
    { "type": "assets", "id": "...", "name": "Firewall Fortinet", "createdAt": "..." },
    { "type": "documents", "id": "...", "name": "Guide Firewall", "createdAt": "..." }
  ],
  "total": 5
}

---

Endpoint Whoami

Verifie les informations associees a votre cle API :

curl -H "Authorization: Bearer sk-smartdoc-..." \
  https://smartdoc.mspsmart.ca/api/v1/whoami

{
  "data": {
    "tenantId": "550e8400-...",
    "scope": "read-write",
    "companyFilter": { "mode": "all", "companyIds": [] },
    "entities": ["companies", "documents", "assets", "..."]
  }
}

---

Codes d'erreur

Code HTTP	Signification
200	Succes
201	Creation reussie
204	Suppression reussie
400	Requete invalide (validation Zod)
401	Cle API manquante ou invalide
403	Portee insuffisante (ex : read-only essaie de creer)
404	Ressource non trouvee
429	Limite de requetes depassee
500	Erreur serveur

---

Exemples complets

Lister les actifs d'une compagnie

curl -H "Authorization: Bearer sk-smartdoc-..." \
  "https://smartdoc.mspsmart.ca/api/v1/assets?company_id=UUID&limit=50&sort_by=name&sort_order=asc"

Creer un document

curl -X POST \
  -H "Authorization: Bearer sk-smartdoc-..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "550e8400-...",
    "title": "Guide de deploiement",
    "content": "<h1>Deploiement</h1><p>Etapes...</p>",
    "status": "draft"
  }' \
  https://smartdoc.mspsmart.ca/api/v1/documents

Modifier un actif

curl -X PATCH \
  -H "Authorization: Bearer sk-smartdoc-..." \
  -H "Content-Type: application/json" \
  -d '{"status": "retired", "location": "Depot"}' \
  https://smartdoc.mspsmart.ca/api/v1/assets/550e8400-...

Supprimer un tag

curl -X DELETE \
  -H "Authorization: Bearer sk-smartdoc-..." \
  https://smartdoc.mspsmart.ca/api/v1/tags/550e8400-...