Skip to main content

Créer une demande de dépôt de garantie

Cette page présente trois requêtes complètes pour créer une demande sans modèle, selon le mode d’intégration choisi : default, integrated ou fully_integrated.

Les exemples créent un dépôt de garantie de 500 €, de type verification. Les montants sont exprimés en euros, pas en centimes. Les dates et coordonnées sont fictives et doivent être adaptées.

Préparer l’appel​

Obtenez un token OAuth2 en suivant la page Introduction, puis définissez ces variables dans votre terminal :

export TYLLT_API_URL='https://api26.tyllt.com'
export TYLLT_ACCESS_TOKEN='VOTRE_ACCESS_TOKEN'
export TYLLT_ORGANISATION_ID='UUID_DE_VOTRE_ORGANISATION'

L’organisation doit être un compte propriétaire accessible au client OAuth2. Chaque exemple utilise le même endpoint :

POST /api/v1/partner/organisations/{organisationId}/request/security_deposit
Content-Type: application/json
Authorization: Bearer VOTRE_ACCESS_TOKEN

Envoyez directement l’objet JSON, sans enveloppe supplémentaire.

1. Mode default​

Le destinataire suit le parcours Tyllt standard. Cette requête contient les champs obligatoires pour créer une demande de dépôt sans modèle : name, description, deposit: true, depositAmount et depositType. Elle inclut aussi une période de location, un email, une référence partenaire et le choix du moment d’envoi de l’email. Le mode est explicite, même si default est aussi la valeur par défaut.

curl --request POST \
"${TYLLT_API_URL}/api/v1/partner/organisations/${TYLLT_ORGANISATION_ID}/request/security_deposit" \
--header "Authorization: Bearer ${TYLLT_ACCESS_TOKEN}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"name": "Dépôt de garantie - réservation RES-001",
"description": "Garantie pour la location du logement",
"deposit": true,
"depositAmount": 500,
"depositType": "verification",
"partnerIntegrationType": "default",
"partnerRef": "RES-001",
"startAt": "2027-06-10",
"endAt": "2027-06-17",
"email": "camille.martin@example.com",
"emailSendTiming": "instant"
}'

L’email, les dates et la référence partenaire restent facultatifs à la création dans ce mode. Ici, emailSendTiming: "instant" demande un envoi immédiat à l’adresse fournie. Pour partager vous-même le lien fullLink retourné sans envoyer d’email automatique, choisissez emailSendTiming: "none". Si startAt est absent, le serveur utilise la date courante.

2. Mode integrated​

Ce mode utilise le parcours intégré et fournit les URL de retour vers votre application. partnerReturnSuccessUrl et partnerReturnFailedUrl sont obligatoires et limités à 255 caractères chacun.

L’exemple inclut aussi une période de location, une référence partenaire et un email. Ces champs sont facultatifs dans ce mode. emailSendTiming: "none" permet ici de partager vous-même le lien retourné.

curl --request POST \
"${TYLLT_API_URL}/api/v1/partner/organisations/${TYLLT_ORGANISATION_ID}/request/security_deposit" \
--header "Authorization: Bearer ${TYLLT_ACCESS_TOKEN}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"name": "Dépôt de garantie - réservation RES-002",
"description": "Garantie pour la location du logement",
"deposit": true,
"depositAmount": 500,
"depositType": "verification",
"partnerIntegrationType": "integrated",
"partnerReturnSuccessUrl": "https://partenaire.example/reservations/RES-002/success",
"partnerReturnFailedUrl": "https://partenaire.example/reservations/RES-002/failed",
"partnerRef": "RES-002",
"startAt": "2027-06-10",
"endAt": "2027-06-17",
"email": "camille.martin@example.com",
"emailSendTiming": "none",
"locale": "fr"
}'

Le bloc recipient est réservé au mode fully_integrated. Dans le mode integrated, un éventuel bloc recipientPreFill sert seulement à préremplir les informations ; il ne remplace pas la création d’un destinataire.

3. Mode fully_integrated​

En plus des deux URL de retour, ce mode exige un email valide à la racine de la requête. Le bloc recipient ci-dessous fournit les informations pour créer un compte destinataire particulier :

  • legalType: "particular" et un bloc physicalPerson ;
  • prénom, nom et téléphone ;
  • date de naissance au format YYYY-MM-DD ;
  • adresse de résidence : adresse, code postal, pays et ville ;
  • lieu de naissance : pays et ville.

L’email du compte est celui du champ email à la racine, pas un champ ajouté dans physicalPerson.

curl --request POST \
"${TYLLT_API_URL}/api/v1/partner/organisations/${TYLLT_ORGANISATION_ID}/request/security_deposit" \
--header "Authorization: Bearer ${TYLLT_ACCESS_TOKEN}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"name": "Dépôt de garantie - réservation RES-003",
"description": "Garantie pour la location du logement",
"deposit": true,
"depositAmount": 500,
"depositType": "verification",
"partnerIntegrationType": "fully_integrated",
"partnerReturnSuccessUrl": "https://partenaire.example/reservations/RES-003/success",
"partnerReturnFailedUrl": "https://partenaire.example/reservations/RES-003/failed",
"partnerRef": "RES-003",
"startAt": "2027-06-10",
"endAt": "2027-06-17",
"email": "camille.martin@example.com",
"emailSendTiming": "none",
"locale": "fr",
"recipient": {
"legalType": "particular",
"physicalPerson": {
"firstname": "Camille",
"lastname": "Martin",
"phone": "+33612345678",
"birthday": "1990-05-15",
"address": {
"address": "10 rue de la Paix",
"zipCode": "75002",
"country": "fra",
"city": "Paris"
},
"birthdayAddress": {
"country": "fra",
"city": "Lyon"
}
}
}
}'

Avec un email qui ne correspond à aucun utilisateur existant, le serveur crée le compte destinataire et le rattache à la demande. Le fullLink retourné peut alors contenir un token permettant au destinataire de définir son mot de passe : utilisez ce lien tel quel.

Réponse et champs conditionnels​

Une création réussie renvoie HTTP 201 et la demande créée. Récupérez notamment son id et son fullLink pour poursuivre le parcours.

ChampRègle
name, descriptionObligatoires sans modèle ; 255 caractères maximum chacun.
depositAmount, depositTypeObligatoires lorsque deposit vaut true. Types acceptés : verification, blocked, debit.
partnerReturnSuccessUrl, partnerReturnFailedUrlObligatoires en integrated et fully_integrated.
emailObligatoire en fully_integrated ; doit être valide lorsqu’il est fourni.
recipientÀ fournir pour créer le compte destinataire dans l’exemple fully_integrated.
startAt, endAt, recipient.physicalPerson.birthdayFormat YYYY-MM-DD lorsqu’ils sont fournis.

Les exemples n’utilisent pas de model. Si vous en ajoutez un, les valeurs du modèle peuvent compléter la demande.

Il existe d'avantage de paramètre disponible dans l'API, pour une utilisation plus poussée, consultez la documentation de l’API plsu complète dans la section Endpoints.