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 blocphysicalPerson;- 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.
| Champ | Règle |
|---|---|
name, description | Obligatoires sans modèle ; 255 caractères maximum chacun. |
depositAmount, depositType | Obligatoires lorsque deposit vaut true. Types acceptés : verification, blocked, debit. |
partnerReturnSuccessUrl, partnerReturnFailedUrl | Obligatoires en integrated et fully_integrated. |
email | Obligatoire 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.birthday | Format 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.