APIMis à jour le 18 juin 2026

Opportunités

Lister, lire, créer, modifier et supprimer des opportunités via l'API. Champs renvoyés, statuts et corps de création.

La ressource opportunities permet de gérer votre pipeline commercial. L'enveloppe (authentification, pagination, format des réponses) est identique aux autres ressources.

Endpoints

Méthode	Chemin	Scope
`GET`	`/api/v1/opportunities`	`read:opportunities`
`POST`	`/api/v1/opportunities`	`write:opportunities`
`GET`	`/api/v1/opportunities/{id}`	`read:opportunities`
`PATCH`	`/api/v1/opportunities/{id}`	`write:opportunities`
`DELETE`	`/api/v1/opportunities/{id}`	`write:opportunities`

Les statuts

Une opportunité a l'un de ces statuts :

Statut	Sens
`DRAFT`	Brouillon (par défaut)
`QUOTE_SENT`	Devis envoyé
`WAITING_REPLY`	En attente de réponse
`REPLIED`	Le contact a répondu
`HOT`	Chaude
`WON`	Gagnée
`LOST`	Perdue

Lister les opportunités

Paramètres de requête : limit, offset (voir Pagination) et status.

Champs renvoyés

id, title, status, amount, priority, contactEmail, companyId, company (objet { id, name } ou null), lastContactAt, nextFollowUpAt, wonAt, createdAt.

GET /api/v1/opportunities/{id} ajoute quoteSentAt.

Créer une opportunité

Champ	Type	Requis	Notes
`title`	texte, 1 à 200 caractères	Oui
`amount`	nombre, 0 ou plus	Non
`contactId`	texte	Non	Rattacher à un contact
`companyId`	texte	Non	Rattacher à une entreprise
`status`	statut (voir ci-dessus)	Non	`DRAFT` par défaut

La réponse contient l'opportunité créée : id, title, status, amount, contactEmail, companyId, createdAt.

Le champ contactId n'est pas conservé

contactId est accepté en entrée mais n'est pas persisté : il sert uniquement à dériver le contactEmail renvoyé. La réponse ne contient donc pas de contactId. Pour relier durablement un contact, renseignez plutôt companyId et contactEmail.

Exemple

curl -X POST "https://app.naskel.io/api/v1/opportunities" \
  -H "Authorization: Bearer nsk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Refonte site ACME", "amount": 8000, "status": "QUOTE_SENT" }'

Modifier une opportunité

PATCH /api/v1/opportunities/{id} met à jour une opportunité, quel que soit son statut. Tous les champs sont optionnels.

Champ	Type	Notes
`title`	texte, 1 à 200 caractères
`amount`	nombre, 0 ou plus
`status`	statut (voir ci-dessus)	`WON` renseigne automatiquement `wonAt`
`priority`	nombre, 0 à 10
`contactEmail`	email
`companyId`	texte	Rattacher à une entreprise

Supprimer une opportunité

DELETE /api/v1/opportunities/{id} supprime une opportunité, quel que soit son statut. La suppression est douce (soft delete). Réponse : { "ok": true }.