{
  "openapi": "3.0.3",
  "info": {
    "title": "WapiWay API",
    "version": "1.0.0",
    "description": "API REST pour automatiser WhatsApp Business : envoi de messages, gestion de sessions, contacts, conversations et webhooks en temps réel.",
    "contact": {
      "name": "Support WapiWay",
      "email": "support@wapiway.tech",
      "url": "https://wapiway.tech/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://wapiway.tech/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.wapiway.tech/api",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Sessions",
      "description": "Gestion des sessions WhatsApp connectées"
    },
    {
      "name": "Messages",
      "description": "Envoi et suivi de messages WhatsApp"
    },
    {
      "name": "Conversations",
      "description": "Gestion des conversations avec vos contacts"
    },
    {
      "name": "Contacts",
      "description": "Gestion de votre carnet de contacts"
    },
    {
      "name": "Groups",
      "description": "Gestion des groupes WhatsApp"
    },
    {
      "name": "Profile",
      "description": "Gestion du profil WhatsApp Business"
    },
    {
      "name": "Webhooks",
      "description": "Configuration et événements webhooks"
    },
    {
      "name": "Developer",
      "description": "Informations API et limites"
    }
  ],
  "paths": {
    "/public/sessions": {
      "get": {
        "tags": ["Sessions"],
        "summary": "Liste toutes les sessions",
        "description": "Récupère la liste paginée de toutes les sessions WhatsApp du workspace.",
        "operationId": "listSessions",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Numéro de page",
            "schema": {"type": "integer", "default": 1, "minimum": 1}
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Éléments par page",
            "schema": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100}
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des sessions",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/SessionsList"}
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "429": {"$ref": "#/components/responses/RateLimited"}
        }
      }
    },
    "/public/sessions/{id}": {
      "get": {
        "tags": ["Sessions"],
        "summary": "Détails d'une session",
        "description": "Récupère les informations détaillées d'une session spécifique.",
        "operationId": "getSession",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID de la session",
            "schema": {"type": "string", "format": "uuid"}
          }
        ],
        "responses": {
          "200": {
            "description": "Détails de la session",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Session"}
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"}
        }
      }
    },
    "/public/messages/send-text": {
      "post": {
        "tags": ["Messages"],
        "summary": "Envoyer un message texte",
        "description": "Envoie un message texte via une session WhatsApp connectée.",
        "operationId": "sendTextMessage",
        "security": [{"bearerAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/SendTextRequest"}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message envoyé avec succès",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/MessageResponse"}
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/UnprocessableEntity"}
        }
      }
    },
    "/public/messages/send-media": {
      "post": {
        "tags": ["Messages"],
        "summary": "Envoyer un message média",
        "description": "Envoie un message avec média (image, vidéo, document, audio).",
        "operationId": "sendMediaMessage",
        "security": [{"bearerAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/SendMediaRequest"}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message média envoyé",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/MessageResponse"}
              }
            }
          }
        }
      }
    },
    "/public/messages/{id}": {
      "get": {
        "tags": ["Messages"],
        "summary": "Détails d'un message",
        "description": "Récupère les détails et le statut d'un message.",
        "operationId": "getMessage",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {"type": "string", "format": "uuid"}
          }
        ],
        "responses": {
          "200": {
            "description": "Détails du message",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Message"}
              }
            }
          }
        }
      }
    },
    "/public/messages/{id}/events": {
      "get": {
        "tags": ["Messages"],
        "summary": "Historique des événements",
        "description": "Récupère l'historique complet des événements d'un message.",
        "operationId": "getMessageEvents",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {"type": "string", "format": "uuid"}
          }
        ],
        "responses": {
          "200": {
            "description": "Événements du message",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/MessageEvents"}
              }
            }
          }
        }
      }
    },
    "/public/conversations": {
      "get": {
        "tags": ["Conversations"],
        "summary": "Liste des conversations",
        "operationId": "listConversations",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 20, "maximum": 100}},
          {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["active", "archived"]}}
        ],
        "responses": {
          "200": {
            "description": "Liste des conversations",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ConversationsList"}
              }
            }
          }
        }
      }
    },
    "/public/contacts": {
      "get": {
        "tags": ["Contacts"],
        "summary": "Liste des contacts",
        "operationId": "listContacts",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {"name": "page", "in": "query", "schema": {"type": "integer", "default": 1}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 20}},
          {"name": "search", "in": "query", "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "Liste des contacts",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/ContactsList"}
              }
            }
          }
        }
      }
    },
    "/sessions/{id}/groups": {
      "get": {
        "tags": ["Groups"],
        "summary": "Liste des groupes WhatsApp",
        "operationId": "listGroups",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}
        ],
        "responses": {
          "200": {
            "description": "Liste des groupes",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/GroupsList"}
              }
            }
          }
        }
      }
    },
    "/sessions/{id}/profile": {
      "get": {
        "tags": ["Profile"],
        "summary": "Récupérer le profil Business",
        "operationId": "getProfile",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}
        ],
        "responses": {
          "200": {
            "description": "Profil WhatsApp Business",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/BusinessProfile"}
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["Profile"],
        "summary": "Mettre à jour le profil",
        "operationId": "updateProfile",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/UpdateProfileRequest"}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profil mis à jour",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/UpdateProfileResponse"}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Clé API au format: Bearer sk_live_xxxxxxxxxxxx"
      }
    },
    "schemas": {
      "Session": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "name": {"type": "string"},
          "status": {"type": "string", "enum": ["connected", "disconnected", "connecting", "failed"]},
          "phone_number": {"type": "string"},
          "connected_at": {"type": "string", "format": "date-time"},
          "last_active_at": {"type": "string", "format": "date-time"},
          "created_at": {"type": "string", "format": "date-time"}
        }
      },
      "SessionsList": {
        "type": "object",
        "properties": {
          "data": {"type": "array", "items": {"$ref": "#/components/schemas/Session"}},
          "total": {"type": "integer"},
          "page": {"type": "integer"},
          "limit": {"type": "integer"}
        }
      },
      "SendTextRequest": {
        "type": "object",
        "required": ["phone_number", "content"],
        "properties": {
          "session_id": {"type": "string", "format": "uuid", "description": "ID de la session (optionnel)"},
          "session_name": {"type": "string", "description": "Nom de la session (alias)"},
          "phone_number": {"type": "string", "description": "Numéro au format international sans + (ex: 33612345678) ou LID (ex: 12345@lid)"},
          "content": {"type": "string", "maxLength": 4096, "description": "Contenu du message"}
        }
      },
      "SendMediaRequest": {
        "type": "object",
        "required": ["phone_number", "type", "media_url"],
        "properties": {
          "session_id": {"type": "string", "format": "uuid"},
          "session_name": {"type": "string"},
          "phone_number": {"type": "string"},
          "type": {"type": "string", "enum": ["image", "video", "document", "audio"]},
          "media_url": {"type": "string", "format": "uri"},
          "caption": {"type": "string"}
        }
      },
      "MessageResponse": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "status": {"type": "string", "enum": ["queued", "sent", "delivered", "read", "failed"]},
          "request_id": {"type": "string"}
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "status": {"type": "string"},
          "direction": {"type": "string", "enum": ["inbound", "outbound"]},
          "content": {"type": "string"},
          "phone_number": {"type": "string"},
          "sent_at": {"type": "string", "format": "date-time"},
          "delivered_at": {"type": "string", "format": "date-time"}
        }
      },
      "MessageEvents": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {"type": "string"},
                "timestamp": {"type": "string", "format": "date-time"}
              }
            }
          }
        }
      },
      "ConversationsList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/Conversation"}
          },
          "total": {"type": "integer"},
          "page": {"type": "integer"}
        }
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "contact": {"$ref": "#/components/schemas/Contact"},
          "last_message_at": {"type": "string", "format": "date-time"},
          "unread_count": {"type": "integer"},
          "status": {"type": "string"}
        }
      },
      "ContactsList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/Contact"}
          },
          "total": {"type": "integer"}
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "phone_number": {"type": "string"},
          "display_name": {"type": "string"},
          "first_name": {"type": "string"},
          "last_name": {"type": "string"},
          "tags": {"type": "array", "items": {"type": "string"}},
          "created_at": {"type": "string", "format": "date-time"}
        }
      },
      "GroupsList": {
        "type": "object",
        "properties": {
          "groups": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/Group"}
          },
          "total": {"type": "integer"}
        }
      },
      "Group": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "size": {"type": "integer"},
          "creation": {"type": "integer"}
        }
      },
      "BusinessProfile": {
        "type": "object",
        "properties": {
          "displayName": {"type": "string"},
          "status": {"type": "string"},
          "profilePictureUrl": {"type": "string", "format": "uri"}
        }
      },
      "UpdateProfileRequest": {
        "type": "object",
        "properties": {
          "displayName": {"type": "string", "maxLength": 25},
          "status": {"type": "string", "maxLength": 139},
          "profilePictureUrl": {"type": "string", "format": "uri"}
        }
      },
      "UpdateProfileResponse": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "updated": {"type": "array", "items": {"type": "string"}}
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {"type": "string"},
          "message": {"type": "string"},
          "code": {"type": "string"}
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Clé API invalide ou manquante",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/Error"}
          }
        }
      },
      "BadRequest": {
        "description": "Paramètres invalides",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/Error"}
          }
        }
      },
      "NotFound": {
        "description": "Ressource introuvable",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/Error"}
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Session non connectée ou autre erreur métier",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/Error"}
          }
        }
      },
      "RateLimited": {
        "description": "Limite de taux dépassée",
        "content": {
          "application/json": {
            "schema": {"$ref": "#/components/schemas/Error"}
          }
        },
        "headers": {
          "X-RateLimit-Limit": {"schema": {"type": "integer"}},
          "X-RateLimit-Remaining": {"schema": {"type": "integer"}},
          "X-RateLimit-Reset": {"schema": {"type": "integer"}}
        }
      }
    }
  },
  "x-webhooks": {
    "message.inbound.received": {
      "post": {
        "summary": "Message entrant reçu",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {"type": "string", "example": "message.inbound.received"},
                  "timestamp": {"type": "string", "format": "date-time"},
                  "data": {
                    "type": "object",
                    "properties": {
                      "message_id": {"type": "string"},
                      "session_id": {"type": "string"},
                      "from": {"type": "string"},
                      "content": {"type": "string"},
                      "type": {"type": "string"}
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {"description": "Webhook reçu"}
        }
      }
    }
  }
}