openapi: 3.1.0 info: title: API Ti Course pour les partenaires version: "1.0" summary: Créer et suivre des courses de retrait de commande (click & collect) livrées par Ti Course. description: | Un commerce partenaire qui propose le click & collect crée lui-même la course de livraison depuis son propre système (site de vente, caisse) : Ti Course envoie un coursier retirer la commande au commerce et la livre au client. - **Authentification** : clé d'API dans l'en-tête `Authorization: Bearer tc_…`. Les clés se créent dans l'espace partenaire (« API et intégration »), une fois l'accès ouvert par Ti Course. Une clé n'est montrée qu'une fois, à sa création. - **Paiement** : chaque course est payée sur le solde prépayé du commerce (réservée à la création, rendue si la course est annulée, versée au coursier à la clôture). Le solde se recharge par carte depuis l'espace partenaire. - **Point de retrait** : l'adresse du commerce, telle qu'elle est renseignée dans son espace partenaire. - **Code de livraison** : chaque course a un code à 4 chiffres, que le coursier demande au client à la remise. Transmettez-le à votre client. - **Limite** : 120 appels par minute et par clé. contact: name: Ti Course servers: - url: https://api.ticourseconnect.fr/api/v1 description: "Production, clés « tc_live_… ». Le bac à sable (clés « tc_test_… », données d'essai, aucun paiement réel) s'ouvre sur demande ; son adresse est affichée dans l'espace partenaire, rubrique « API et intégration »." security: - cleApi: [] tags: - name: Compte description: La clé utilisée et le solde prépayé. - name: Courses description: Devis, création, suivi, préparation et annulation des courses. paths: /ping: get: tags: [Compte] summary: Vérifier une clé operationId: ping responses: "200": description: La clé est valide ; le compte et la clé utilisés. content: application/json: schema: type: object properties: partenaire: type: object properties: id: { type: integer } nom: { type: string } cle: type: object properties: nom: { type: string } apercu: { type: string, example: "tc_test_AbCd…wxyz" } environnement: { type: string, enum: [test, live] } heure: { type: string, format: date-time } "401": { $ref: "#/components/responses/NonAuthentifie" } "403": { $ref: "#/components/responses/Interdit" } "429": { $ref: "#/components/responses/TropDeRequetes" } /solde: get: tags: [Compte] summary: Solde prépayé operationId: solde responses: "200": description: Solde disponible et montant réservé sur les courses en cours. content: application/json: schema: type: object properties: solde: { $ref: "#/components/schemas/Montant" } reserve: { $ref: "#/components/schemas/Montant" } "401": { $ref: "#/components/responses/NonAuthentifie" } "403": { $ref: "#/components/responses/Interdit" } /devis: post: tags: [Courses] summary: Prix d'une course, sans rien créer operationId: devis requestBody: required: true content: application/json: schema: type: object required: [taille, livraison] properties: taille: { $ref: "#/components/schemas/Taille" } livraison: { $ref: "#/components/schemas/AdresseLivraisonDemandee" } responses: "200": description: Prix et distance pour cette adresse et cette taille. content: application/json: schema: type: object properties: taille: { $ref: "#/components/schemas/Taille" } prix: { $ref: "#/components/schemas/Montant" } distance_km: { type: number, example: 4.2 } livraison: type: object properties: adresse: { type: string } latitude: { type: number } longitude: { type: number } creable: type: boolean description: Faux si le prix dépasse le plafond d'une course (200 €). "401": { $ref: "#/components/responses/NonAuthentifie" } "403": { $ref: "#/components/responses/Interdit" } "409": { $ref: "#/components/responses/Conflit" } "422": { $ref: "#/components/responses/Invalide" } /courses: post: tags: [Courses] summary: Créer une course operationId: creerCourse description: | Crée la course et réserve son prix sur le solde. Avec `prete: true` (par défaut), elle est proposée aux coursiers tout de suite ; avec `prete: false`, elle reste « en préparation » jusqu'à `POST /courses/{id}/prete`. Une seule course en cours par `reference_commande` (annulez-la pour en créer une autre). Envoyez un en-tête `Idempotency-Key` : un nouvel envoi avec la même clé rend la course déjà créée (statut 200, en-tête `Idempotent-Replayed: true`), sans nouveau débit. parameters: - name: Idempotency-Key in: header required: false description: 8 à 64 caractères parmi lettres, chiffres, « - » et « _ ». Une valeur par commande et par tentative logique. schema: { type: string, pattern: "^[A-Za-z0-9_-]{8,64}$" } requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/CourseDemandee" } example: reference_commande: CMD-1042 taille: M destinataire: { nom: Marie Hoarau, telephone: "+262 692 12 34 56" } livraison: { adresse: "5 rue Jean Chatel, 97400 Saint-Denis", precisions: "Bât. B, code 1234" } retrait: { nom_sur_commande: Hoarau, plage: "dès 14 h" } instructions: Sac isotherme. responses: "201": description: Course créée. content: application/json: schema: type: object properties: course: { $ref: "#/components/schemas/Course" } "200": description: Même `Idempotency-Key` qu'une course déjà créée — la voici (aucun nouveau débit). headers: Idempotent-Replayed: { schema: { type: string, enum: ["true"] } } content: application/json: schema: type: object properties: course: { $ref: "#/components/schemas/Course" } "401": { $ref: "#/components/responses/NonAuthentifie" } "402": description: "Solde insuffisant (code `solde_insuffisant`, avec `prix` et `solde`)." content: application/json: schema: { $ref: "#/components/schemas/Erreur" } example: { erreur: { code: solde_insuffisant, message: "Solde prépayé insuffisant pour cette course : rechargez-le depuis l'espace partenaire.", prix: 9.6, solde: 4.0 } } "403": { $ref: "#/components/responses/Interdit" } "409": { $ref: "#/components/responses/Conflit" } "422": { $ref: "#/components/responses/Invalide" } "429": { $ref: "#/components/responses/TropDeRequetes" } get: tags: [Courses] summary: Lister ses courses operationId: listerCourses description: Les courses créées par l'API de ce commerce, les plus récentes d'abord. parameters: - { name: statut, in: query, schema: { $ref: "#/components/schemas/Statut" } } - { name: reference_commande, in: query, schema: { type: string } } - { name: depuis, in: query, description: "Créées depuis ce jour (heure de La Réunion).", schema: { type: string, format: date } } - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } } - { name: par_page, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } } responses: "200": description: Une page de courses. content: application/json: schema: type: object properties: courses: { type: array, items: { $ref: "#/components/schemas/Course" } } pagination: type: object properties: page: { type: integer } par_page: { type: integer } total: { type: integer } pages: { type: integer } "401": { $ref: "#/components/responses/NonAuthentifie" } "422": { $ref: "#/components/responses/Invalide" } /courses/{id}: get: tags: [Courses] summary: Une course operationId: course parameters: [{ $ref: "#/components/parameters/IdCourse" }] responses: "200": description: La course. content: application/json: schema: type: object properties: course: { $ref: "#/components/schemas/Course" } "401": { $ref: "#/components/responses/NonAuthentifie" } "404": { $ref: "#/components/responses/Introuvable" } /courses/{id}/prete: post: tags: [Courses] summary: La commande est prête operationId: coursePrete description: "Pour une course créée avec `prete: false` — elle est alors proposée aux coursiers." parameters: [{ $ref: "#/components/parameters/IdCourse" }] responses: "200": description: La course, désormais en recherche de coursier. content: application/json: schema: type: object properties: course: { $ref: "#/components/schemas/Course" } "404": { $ref: "#/components/responses/Introuvable" } "409": { $ref: "#/components/responses/Conflit" } /courses/{id}/annuler: post: tags: [Courses] summary: Annuler une course operationId: annulerCourse description: | Possible tant que le coursier n'a pas retiré la commande (statuts `en_preparation`, `recherche_coursier`, `coursier_assigne`). Le prix réservé est rendu au solde. Ensuite : code `non_annulable`, voir le support. parameters: [{ $ref: "#/components/parameters/IdCourse" }] requestBody: required: false content: application/json: schema: type: object properties: motif: { type: string, maxLength: 500 } responses: "200": description: La course annulée. content: application/json: schema: type: object properties: course: { $ref: "#/components/schemas/Course" } "404": { $ref: "#/components/responses/Introuvable" } "409": { $ref: "#/components/responses/Conflit" } webhooks: evenementCourse: post: operationId: evenementCourse summary: Événement d'une course description: | Envoyé à l'adresse réglée dans l'espace partenaire, à la création de la course (`course.creee`) puis à chaque changement de statut (`course.`, par exemple `course.coursier_assigne`, `course.livree`, `course.annulee`), et sur demande (`test`). **Signature** : en-tête `Ti-Course-Signature: t=,v1=`, où `signature` = HMAC-SHA256, avec votre secret `whsec_…`, de la chaîne `.`. Recalculez-la sur le corps brut, comparez en temps constant, et refusez un horodatage de plus de 5 minutes. **Réponse attendue** : un code 2xx en moins de 10 secondes. Sinon, nouvelles tentatives après 1 min, 5 min, 30 min, 2 h et 6 h (6 tentatives en tout). Un même événement peut arriver deux fois : ignorez un `id` déjà traité. **Adresse** : https, port 443, nom d'hôte public (adresse IPv4 publique) ; les redirections ne sont pas suivies. parameters: - { name: Ti-Course-Signature, in: header, required: true, schema: { type: string, example: "t=1763371200,v1=5f2b…" } } - { name: Ti-Course-Evenement, in: header, required: true, schema: { type: string, example: course.livree } } requestBody: content: application/json: schema: { $ref: "#/components/schemas/Evenement" } responses: "200": { description: Événement reçu. } components: securitySchemes: cleApi: type: http scheme: bearer description: "Clé d'API « tc_live_… » (production) ou « tc_test_… » (bac à sable)." parameters: IdCourse: name: id in: path required: true schema: { type: integer } schemas: Taille: type: string enum: [S, M, L, XL] description: "S : sac à dos · M : cabas · L : coffre · XL : gros volume." Statut: type: string enum: [en_preparation, recherche_coursier, coursier_assigne, coursier_en_route, coursier_au_commerce, en_livraison, coursier_a_destination, livree, terminee, annulee, litige] description: | en_preparation : la commande n'est pas encore prête · recherche_coursier : proposée aux coursiers · coursier_assigne · coursier_en_route (vers le commerce) · coursier_au_commerce · en_livraison · coursier_a_destination · livree · terminee (24 h après la livraison, le coursier est payé) · annulee · litige (traitée par le support). Montant: type: object properties: montant: { type: number, example: 9.6 } devise: { type: string, enum: [EUR] } AdresseLivraisonDemandee: type: object required: [adresse] properties: adresse: type: string minLength: 6 maxLength: 500 description: Adresse à La Réunion. Sans coordonnées, elle est située par la Base Adresse Nationale (code `adresse_introuvable` si elle ne l'est pas sûrement). latitude: { type: number, minimum: -21.42, maximum: -20.85, description: "Avec longitude ; recommandé si vous les avez." } longitude: { type: number, minimum: 55.20, maximum: 55.85 } precisions: { type: string, maxLength: 500, description: "Bâtiment, digicode, repère, pour le coursier." } CourseDemandee: type: object required: [reference_commande, taille, destinataire, livraison] properties: reference_commande: { type: string, maxLength: 100, description: "Votre numéro de commande : le coursier le présente au retrait." } taille: { $ref: "#/components/schemas/Taille" } destinataire: type: object required: [nom, telephone] properties: nom: { type: string, maxLength: 100 } telephone: { type: string, maxLength: 20, pattern: "^\\+?[0-9 .\\-]{9,20}$" } livraison: { $ref: "#/components/schemas/AdresseLivraisonDemandee" } retrait: type: object properties: nom_sur_commande: { type: string, maxLength: 100 } plage: { type: string, maxLength: 100, description: "Quand la commande peut être retirée (texte libre)." } instructions: { type: string, maxLength: 2000, description: Consignes pour le coursier. } prete: { type: boolean, default: true } creneau: type: object description: Livraison programmée (heure de La Réunion), à venir. required: [date] properties: date: { type: string, format: date } heure: { type: string, pattern: "^\\d{2}:\\d{2}$" } Course: type: object properties: id: { type: integer } reference_commande: { type: string } statut: { $ref: "#/components/schemas/Statut" } statut_libelle: { type: string, example: "Recherche d'un coursier" } taille: { $ref: "#/components/schemas/Taille" } prix: { $ref: "#/components/schemas/Montant" } distance_km: { type: [number, "null"] } retrait: type: object properties: adresse: { type: string } nom_sur_commande: { type: [string, "null"] } plage: { type: [string, "null"] } livraison: type: object properties: adresse: { type: string } latitude: { type: number } longitude: { type: number } precisions: { type: [string, "null"] } destinataire: type: object properties: nom: { type: string } telephone: { type: string } creneau: type: [object, "null"] properties: date: { type: string, format: date } heure: { type: [string, "null"] } instructions: { type: [string, "null"] } code_livraison: { type: string, pattern: "^\\d{4}$", description: À transmettre à votre client. } coursier: type: [object, "null"] properties: nom: { type: string } telephone: { type: string } motif_annulation: { type: [string, "null"] } creee_le: { type: string, format: date-time } mise_a_jour_le: { type: string, format: date-time } livree_le: { type: [string, "null"], format: date-time } Evenement: type: object properties: id: { type: string, example: evt_9fK2mQ7xLpA4sT1vB8nC3dE0 } type: { type: string, example: course.livree } cree_le: { type: string, format: date-time } donnees: type: object properties: course: { $ref: "#/components/schemas/Course" } Erreur: type: object required: [erreur] properties: erreur: type: object required: [code, message] properties: code: type: string enum: [cle_invalide, cle_revoquee, compte_inactif, acces_api_ferme, donnees_invalides, idempotency_key_invalide, creneau_passe, adresse_introuvable, montant_trop_eleve, adresse_commerce_manquante, reference_deja_utilisee, solde_insuffisant, introuvable, deja_prete, non_annulable, transition_refusee, trop_de_requetes] message: { type: string } champs: type: object additionalProperties: { type: array, items: { type: string } } description: "Avec donnees_invalides : les messages par champ (« destinataire.telephone »…)." additionalProperties: true responses: NonAuthentifie: description: "Clé absente ou invalide (`cle_invalide`), ou révoquée (`cle_revoquee`)." content: application/json: schema: { $ref: "#/components/schemas/Erreur" } Interdit: description: "Accès à l'API pas encore ouvert (`acces_api_ferme`) ou compte inactif (`compte_inactif`)." content: application/json: schema: { $ref: "#/components/schemas/Erreur" } Introuvable: description: "Course introuvable, ou pas à vous (`introuvable`)." content: application/json: schema: { $ref: "#/components/schemas/Erreur" } Conflit: description: "`reference_deja_utilisee` (avec `course_id`), `adresse_commerce_manquante`, `deja_prete`, `non_annulable` (avec `statut`), `transition_refusee`." content: application/json: schema: { $ref: "#/components/schemas/Erreur" } Invalide: description: "`donnees_invalides` (avec `champs`), `idempotency_key_invalide`, `creneau_passe`, `adresse_introuvable`, `montant_trop_eleve` (avec `prix`)." content: application/json: schema: { $ref: "#/components/schemas/Erreur" } TropDeRequetes: description: "Plus de 120 appels par minute avec cette clé (`trop_de_requetes`). En-têtes Retry-After et X-RateLimit-*." content: application/json: schema: { $ref: "#/components/schemas/Erreur" }