Aller au contenu principal
HeartCoHeartCo/Guide utilisateur
Retour au site
Dernière mise à jour : 2026-03-14·Plan BUSINESS+

API REST HeartCo

Intègre HeartCo dans tes outils et automatise tes flux métier grâce à l'API REST. L'API utilise JSON et l'authentification par Bearer token.

Plan BUSINESS

Accès anticipé

La documentation API complète sera disponible à partir du T2 2026. En attendant, contacte-nous à support@heartco.fr pour un accès anticipé.

URL de base

https://app.heartco.fr/api/v1

Authentification

Toutes les requêtes doivent inclure ta clé API dans le header Authorization :

Authorization: Bearer hco_live_xxxxxxxxxxxx

Génère tes clés API depuis Réglages → Paramètres.

Sécurité des clés

Ne partage jamais ta clé API. Ne la commite pas dans ton code source. Utilise des variables d'environnement pour la stocker.

Endpoints disponibles

Clients

GET/api/v1/clients

Lister tous les clients de l'organisation. Supporte la pagination et la recherche par nom.

POST/api/v1/clients

Créer un nouveau client. Champs requis : name. Optionnels : email, phone, address, siret, vatNumber.

Factures

GET/api/v1/invoices

Lister les factures. Filtres disponibles : status (DRAFT, SENT, PAID, OVERDUE), dateRange.

POST/api/v1/invoices

Créer et émettre une facture. Requiert un clientId et au moins une ligne (description, quantity, unitPrice, vatRate).

Devis

GET/api/v1/quotes

Lister les devis de l'organisation. Filtres : status (DRAFT, SENT, ACCEPTED, REJECTED, EXPIRED).

Webhooks

POST/api/v1/webhooks

Enregistrer une URL de webhook pour recevoir des événements en temps réel.

Format des réponses

Toutes les réponses sont au format JSON avec la structure suivante :

{
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 142
  }
}

En cas d'erreur :

{
  "error": {
    "code": "NOT_FOUND",
    "message": "La ressource demandée n'existe pas."
  }
}

Webhooks

HeartCo envoie des événements en temps réel vers ton endpoint lors des actions importantes.

Événements disponibles

ÉvénementDéclencheur
invoice.createdNouvelle facture créée
invoice.paidFacture marquée comme payée
quote.sentDevis envoyé au client
quote.acceptedDevis accepté par le client
client.createdNouveau client ajouté
member.invitedNouveau membre invité

Vérification de signature

Chaque requête webhook inclut un en-tête X-HeartCo-Signature contenant un hash HMAC-SHA256 du body.

Pour vérifier la signature :

const crypto = require("crypto");
 
function verifySignature(body, signature, secret) {
  const computed =
    "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex");
 
  return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(signature));
}

Sécurité HMAC

Utilise toujours timingSafeEqual pour comparer les signatures. Ne compare jamais avec === — cela expose ton endpoint à des attaques par timing.

En-têtes webhook

En-têteDescription
X-HeartCo-Signaturesha256=<hex> — signature HMAC-SHA256
X-HeartCo-EventType d'événement (ex : invoice.paid)
Content-Typeapplication/json

Tester un webhook

Depuis Réglages → Webhooks, clique sur Tester pour envoyer un payload de test à ton endpoint. HeartCo enregistre le code HTTP de réponse et la durée de la requête.

Rate limiting

L'API est limitée à 100 requêtes par minute par clé API. En cas de dépassement, tu reçois une réponse 429 Too Many Requests avec un en-tête Retry-After.

Questions fréquentes

Comment obtenir une clé API ?

Depuis Réglages → Paramètres, génère une clé API. Tu peux créer plusieurs clés (production, test) et les révoquer individuellement.

L'API est-elle disponible sur tous les plans ?

L'API REST est disponible à partir du plan Battement (Business). Les webhooks sortants sont disponibles dès le plan Pulsation (Starter).

Puis-je utiliser l'API en sandbox ?

Contacte support@heartco.fr pour obtenir un accès sandbox avec des données de test. La documentation complète avec sandbox sera disponible au T2 2026.

Voir aussi