Clients

Les outils clients permettent de gérer vos contacts (particuliers) et organisations (entreprises). Ces clients sont ensuite utilisables dans la facturation.

Abby distingue deux types de clients :

• Contacts — clients particuliers (personnes physiques)

• Organisations — clients professionnels (entreprises, associations, etc.)

Les organisations peuvent avoir plusieurs contacts associés.

Lecture

get-contacts

Récupère les contacts avec pagination et recherche.

Paramètres

Paramètre	Type	Requis	Description
page	number	Non	Numéro de page (défaut : 1)
limit	number	Non	Résultats par page, max 100 (défaut : 50)
search	string	Non	Recherche par prénom ou nom
archived	boolean	Non	Filtrer par statut d'archivage

Réponse

{
  "success": true,
  "total": 15,
  "page": 1,
  "contacts": [
    {
      "id": "string",
      "firstname": "Jean",
      "lastname": "Dupont",
      "emails": ["[email protected]"],
      "phone": "[phone]",
      "jobTitle": "Directeur technique",
      "organizationId": "string",
      "organizationName": "Dupont SARL",
      "notes": "",
      "addresses": [...],
      "archivedAt": null,
      "hasBillings": true,
      "createdAt": "2025-01-15T00:00:00.000Z"
    }
  ]
}

---

get-contact-by-id

Récupère un contact par son identifiant. Retourne les détails incluant nom, email, téléphone, poste, organisation et adresses.

Paramètres

Paramètre	Type	Requis	Description
contactId	string	Oui	Identifiant du contact

---

get-organizations

Récupère les organisations avec pagination et recherche.

Paramètres

Paramètre	Type	Requis	Description
page	number	Non	Numéro de page (défaut : 1)
limit	number	Non	Résultats par page, max 100 (défaut : 50)
search	string	Non	Recherche par nom
archived	boolean	Non	Filtrer par statut d'archivage

Réponse

{
  "success": true,
  "total": 8,
  "organizations": [
    {
      "id": "string",
      "name": "Dupont SARL",
      "commercialName": "Dupont & Fils",
      "emails": ["[email protected]"],
      "siret": "12345678901234",
      "vatNumber": "FR12345678901",
      "countContacts": 3,
      "notes": "",
      "addresses": [...],
      "archivedAt": null,
      "hasBillings": true,
      "createdAt": "2025-01-15T00:00:00.000Z"
    }
  ]
}

---

get-organization-by-id

Récupère une organisation par son identifiant. Retourne les détails incluant nom, SIRET, TVA, nombre de contacts et adresses.

Paramètres

Paramètre	Type	Requis	Description
organizationId	string	Oui	Identifiant de l'organisation

---

get-organization-contacts

Récupère tous les contacts associés à une organisation.

Paramètres

Paramètre	Type	Requis	Description
organizationId	string	Oui	Identifiant de l'organisation

Réponse

{
  "success": true,
  "total": 3,
  "organizationId": "string",
  "contacts": [
    {
      "id": "string",
      "firstname": "Marie",
      "lastname": "Martin",
      "emails": ["[email protected]"],
      "jobTitle": "Comptable",
      "defaultContact": true
    }
  ]
}

---

Création

create-contact

Crée un nouveau contact (client particulier). Nécessite au minimum un prénom et un nom.

Paramètres

Paramètre	Type	Requis	Description
firstname	string	Oui	Prénom
lastname	string	Oui	Nom de famille
emails	string[]	Non	Adresses email
phone	string	Non	Numéro de téléphone
jobTitle	string	Non	Poste / fonction
notes	string	Non	Notes libres
billingAddress	object	Non	Adresse de facturation
billingAddress.address	string	Oui	Rue
billingAddress.complement	string	Non	Complément (bâtiment, étage, etc.)
billingAddress.city	string	Oui	Ville
billingAddress.zipCode	string	Oui	Code postal
billingAddress.country	string	Oui	Code pays ISO 3166-1 alpha-2 (ex : FR)
deliveryAddress	object	Non	Adresse de livraison (même structure)

---

create-organization

Crée une nouvelle organisation (client professionnel). Nécessite au minimum un nom.

Paramètres

Paramètre	Type	Requis	Description
name	string	Oui	Raison sociale
commercialName	string	Non	Nom commercial
emails	string[]	Non	Adresses email
siret	string	Non	Numéro SIRET
vatNumber	string	Non	Numéro de TVA intracommunautaire
notes	string	Non	Notes libres
billingAddress	object	Non	Adresse de facturation (même structure que create-contact)
deliveryAddress	object	Non	Adresse de livraison (même structure)

---

Modification

update-contact

Met à jour un contact existant. Charge les données existantes avant la mise à jour pour préserver les informations non exposées (coordonnées bancaires, préférences).

Paramètres

Paramètre	Type	Requis	Description
contactId	string	Oui	Identifiant du contact
firstname	string	Non	Prénom
lastname	string	Non	Nom de famille
emails	string[]	Non	Adresses email
phone	string	Non	Numéro de téléphone
jobTitle	string	Non	Poste / fonction
billingAddress	object	Non	Adresse de facturation
deliveryAddress	object	Non	Adresse de livraison

Les notes sont gérées séparément via update-contact-notes pour éviter tout écrasement accidentel.

---

update-organization

Met à jour une organisation existante. Préserve les coordonnées bancaires et préférences existantes.

Paramètres

Paramètre	Type	Requis	Description
organizationId	string	Oui	Identifiant de l'organisation
name	string	Non	Raison sociale
commercialName	string	Non	Nom commercial
emails	string[]	Non	Adresses email
siret	string	Non	Numéro SIRET
vatNumber	string	Non	Numéro de TVA
billingAddress	object	Non	Adresse de facturation
deliveryAddress	object	Non	Adresse de livraison

---

update-contact-notes

Met à jour les notes d'un contact via un use case dédié.

Paramètres

Paramètre	Type	Requis	Description
contactId	string	Oui	Identifiant du contact
notes	string	Oui	Nouvelles notes

---

update-organization-notes

Met à jour les notes d'une organisation via un use case dédié.

Paramètres

Paramètre	Type	Requis	Description
organizationId	string	Oui	Identifiant de l'organisation
notes	string	Oui	Nouvelles notes

---

Suppression et archivage

delete-contact

Supprime définitivement un contact. Échoue si le contact a des documents de facturation — utilisez archive-contact dans ce cas.

Paramètres

Paramètre	Type	Requis	Description
contactId	string	Oui	Identifiant du contact

---

delete-organization

Supprime définitivement une organisation. Échoue si l'organisation a des contacts ou des documents de facturation — utilisez archive-organization dans ce cas.

Paramètres

Paramètre	Type	Requis	Description
organizationId	string	Oui	Identifiant de l'organisation

---

archive-contact

Archive un contact (suppression douce). Le contact n'apparaît plus dans les listes actives mais ses données sont conservées. Préférez l'archivage à la suppression quand le contact a des documents de facturation.

Paramètres

Paramètre	Type	Requis	Description
contactId	string	Oui	Identifiant du contact

---

archive-organization

Archive une organisation. L'organisation n'apparaît plus dans les listes actives mais ses données sont conservées.

Paramètres

Paramètre	Type	Requis	Description
organizationId	string	Oui	Identifiant de l'organisation

---

Scopes requis

Outil	Scope
get-contacts, get-contact-by-id, get-organizations, get-organization-by-id, get-organization-contacts	client:read
create-contact, create-organization, update-contact, update-organization, update-contact-notes, update-organization-notes, delete-contact, delete-organization, archive-contact, archive-organization	client:write