openapi: 3.0.3
info:
  title: YAYATO Delivery Cloud API
  description: >
    API d'orchestration logistique. Authentification par clé (Bearer).
    Les endpoints d'écriture acceptent l'en-tête `Idempotency-Key`.
    Chaque réponse porte un `X-Request-Id` (corrélation).
  version: "1.0.0"

servers:
  - url: http://127.0.0.1:8000/api/v1
    description: Développement local
  - url: https://api.yayato.fr/api/v1
    description: Production (à venir)

security:
  - ApiKeyAuth: []

tags:
  - name: Devis
  - name: Livraisons
  - name: Suivi
  - name: Paiements

paths:
  /quotes/auto:
    post:
      tags: [Devis]
      summary: YAYATO calcule le meilleur transporteur
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profile, distance]
              properties:
                profile: { type: string, example: standard }
                distance: { type: number, example: 10 }
                express: { type: boolean }
                relay: { type: boolean }
                weather: { type: string, example: rain }
      responses:
        "200":
          description: Meilleure offre + classement
        "401": { description: Clé API manquante ou invalide }
        "422": { description: Aucune offre éligible }

  /quotes/options:
    post:
      tags: [Devis]
      summary: Options de livraison (express / standard / relais)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [distance]
              properties:
                distance: { type: number, example: 10 }
                weather: { type: string }
      responses:
        "200": { description: Une meilleure offre par service }

  /deliveries:
    get:
      tags: [Livraisons]
      summary: Liste paginée des livraisons
      parameters:
        - { name: status, in: query, schema: { type: string } }
        - { name: per_page, in: query, schema: { type: integer, default: 15 } }
      responses:
        "200": { description: Liste paginée }
    post:
      tags: [Livraisons]
      summary: Crée une livraison (choix auto du transporteur)
      parameters:
        - name: Idempotency-Key
          in: header
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryRequest'
      responses:
        "201": { description: Livraison créée }
        "422": { description: Aucun transporteur éligible / accepté }

  /deliveries/multi:
    post:
      tags: [Livraisons]
      summary: Commande multi-vendeur (une livraison par vendeur)
      parameters:
        - name: Idempotency-Key
          in: header
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customer_name, dropoff_address, dropoff_postcode, dropoff_city, vendors]
              properties:
                customer_name: { type: string }
                dropoff_address: { type: string }
                dropoff_postcode: { type: string }
                dropoff_city: { type: string }
                vendors:
                  type: array
                  items:
                    type: object
                    required: [store_id, distance, pickup_address, pickup_postcode, pickup_city]
                    properties:
                      store_id: { type: integer }
                      distance: { type: number }
                      order_total: { type: number }
                      pickup_address: { type: string }
                      pickup_postcode: { type: string }
                      pickup_city: { type: string }
      responses:
        "201": { description: Livraisons créées, regroupées }

  /deliveries/{uuid}:
    get:
      tags: [Livraisons]
      summary: Détail d'une livraison
      parameters:
        - { name: uuid, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Détail }
        "404": { description: Introuvable }

  /deliveries/{uuid}/cancel:
    post:
      tags: [Livraisons]
      summary: Annule une livraison
      parameters:
        - { name: uuid, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Annulée }
        "422": { description: Non annulable }

  /tracking/{tracking}:
    get:
      tags: [Suivi]
      summary: Suivi unifié d'une livraison
      parameters:
        - { name: tracking, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: Statut + historique }
        "404": { description: Introuvable }

  /payments/split:
    post:
      tags: [Paiements]
      summary: Répartition d'un paiement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [total, delivery_cost]
              properties:
                total: { type: number, example: 50 }
                delivery_cost: { type: number, example: 8 }
                marketplace_id: { type: integer }
      responses:
        "200": { description: Parts calculées }

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer

  schemas:
    DeliveryRequest:
      type: object
      required: [store_id, customer_name, profile, pickup_name, pickup_address, pickup_postcode, pickup_city, pickup_country, dropoff_name, dropoff_address, dropoff_postcode, dropoff_city, dropoff_country, quotes]
      properties:
        store_id: { type: integer }
        customer_name: { type: string }
        profile: { type: string }
        express: { type: boolean }
        relay: { type: boolean }
        weather: { type: string }
        pickup_name: { type: string }
        pickup_address: { type: string }
        pickup_postcode: { type: string }
        pickup_city: { type: string }
        pickup_country: { type: string, example: FR }
        dropoff_name: { type: string }
        dropoff_address: { type: string }
        dropoff_postcode: { type: string }
        dropoff_city: { type: string }
        dropoff_country: { type: string, example: FR }
        quotes:
          type: array
          items:
            $ref: '#/components/schemas/Quote'
    Quote:
      type: object
      required: [carrier, price, minutes]
      properties:
        carrier: { type: string, example: stuart }
        price: { type: number, example: 8.5 }
        minutes: { type: integer, example: 25 }
        available: { type: boolean }
        vehicle: { type: string, example: bike }
