Documentation Skalin

Opportunités

API de gestion des opportunités

Cette API permet l'administration des opportunités : les affaires d'expansion, d'upsell et de renouvellement ouvertes sur un compte client.

Toute propriété ou méthode non documentée peut être modifiée ou supprimée sans préavis.

Info

L'appel de la liste des opportunités est toujours paginée. Référez-vous à la section pagination pour plus de détails.

# Chemin au singulier

Attention : la ressource est exposée au singulier, /opportunity, et non /opportunities. Les pipelines, eux, sont au pluriel : /opportunity-pipelines.

# Pipelines et étapes

Une opportunité avance dans les étapes d'un pipeline. Un workspace peut en définir plusieurs, par exemple un pour les renouvellements et un pour les upsells.

Chaque étape porte sa propre probabilité de succès, recopiée sur les opportunités qui s'y trouvent dans les champs probability et stageLabel. Ces deux champs sont en lecture seule : ils suivent l'étape, on ne les écrit pas directement.

Un pipeline doit au minimum proposer les étapes open, won et lost.

# Clôture automatique

won et lost sont les étapes terminales. Y faire passer une opportunité renseigne automatiquement endAt avec la date du jour ; la ramener vers une autre étape efface endAt.

Le champ endAt est géré par Skalin et ignoré s'il est envoyé dans le corps de la requête.

# Identifier le compte client

À la création, le compte peut être désigné de deux façons :

  • avec customerId, l'identifiant Skalin du compte ;
  • avec customer, un terme comparé — sans tenir compte de la casse — au domaine, au refId ou au nom du compte.

Si customer ne correspond à aucun compte, l'appel renvoie une erreur 400.

# userId et teamId

Deux mots-clés évitent d'avoir à résoudre un identifiant :

  • dans userId, OWNER assigne l'opportunité au propriétaire du compte client ;
  • dans teamId, CUSTOMER_TEAM assigne l'opportunité à toute l'équipe du compte client.

# users

Le champ users accepte, comme pour les tâches, des désignations plutôt que de simples identifiants :

[{ "value": "id", "type": "USER" }]
1
[{ "value": "id du champ", "type": "CUSTOM" }]
1

Attention : seuls les champs personnalisables de type USER peuvent être utilisés.

[{ "value": "OWNER", "type": "SYSTEM" }]
1

En lecture, l'API renvoie simplement la liste des identifiants des utilisateurs.

# swagger

Contributeurs: Julien