{
  "openapi": "3.0.3",
  "info": {
    "title": "WhatsApi REST API · Cliente",
    "version": "1.0.0",
    "description": "Specifica dei soli endpoint cliente implementati nel portale. WhatsApi utilizza Baileys 7.0.0-rc14 come motore; le API avanzate di media, ricevute, presenza e gruppi non sono ancora esposte e non sono incluse in questo contratto. La risposta HTTP 202 indica accettazione, NON consegna."
  },
  "servers": [
    {
      "url": "https://whatsapi.it/api/v1",
      "description": "Dominio principale (richiede certificato HTTPS attivo)"
    },
    {
      "url": "https://mcp-whatsapp.helloguest.si/wa-platform/api/v1",
      "description": "Endpoint HTTPS tecnico temporaneo"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Account"
    },
    {
      "name": "Istanze"
    },
    {
      "name": "Messaggi"
    },
    {
      "name": "Eventi"
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Profilo e limiti account",
        "responses": {
          "200": {
            "description": "Profilo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          }
        }
      }
    },
    "/instances": {
      "get": {
        "tags": [
          "Istanze"
        ],
        "summary": "Elenco delle istanze dell'account",
        "responses": {
          "200": {
            "description": "Lista e limite",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "instances",
                    "max"
                  ],
                  "properties": {
                    "instances": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Instance"
                      }
                    },
                    "max": {
                      "type": "integer",
                      "minimum": 1
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          }
        }
      }
    },
    "/instances/{id}": {
      "get": {
        "tags": [
          "Istanze"
        ],
        "summary": "Dettaglio e stato dell'istanza",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID dell'istanza di proprietà dell'account",
            "schema": {
              "type": "string",
              "pattern": "^wa_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stato istanza",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Instance"
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          },
          "404": {
            "description": "Istanza non trovata o non assegnata all'utente"
          }
        }
      }
    },
    "/instances/{id}/start": {
      "post": {
        "tags": [
          "Istanze"
        ],
        "summary": "Avvio o riconnessione",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID dell'istanza di proprietà dell'account",
            "schema": {
              "type": "string",
              "pattern": "^wa_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Avvio accettato",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Instance"
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          },
          "404": {
            "description": "Istanza non trovata o non assegnata all'utente"
          }
        }
      }
    },
    "/instances/{id}/pause": {
      "post": {
        "tags": [
          "Istanze"
        ],
        "summary": "Pausa mantenendo credenziali WhatsApp",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID dell'istanza di proprietà dell'account",
            "schema": {
              "type": "string",
              "pattern": "^wa_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sessione messa in pausa",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          },
          "404": {
            "description": "Istanza non trovata o non assegnata all'utente"
          }
        }
      }
    },
    "/instances/{id}/qr": {
      "get": {
        "tags": [
          "Istanze"
        ],
        "summary": "QR di collegamento",
        "description": "Disponibile soltanto se un QR è stato generato; 404 anche se il QR non è disponibile.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID dell'istanza di proprietà dell'account",
            "schema": {
              "type": "string",
              "pattern": "^wa_[0-9a-f]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "QR disponibile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "qrDataUrl": {
                      "type": "string",
                      "description": "PNG in data URI Base64"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          },
          "404": {
            "description": "Istanza o QR non disponibili"
          }
        }
      }
    },
    "/instances/{id}/messages": {
      "post": {
        "tags": [
          "Messaggi"
        ],
        "summary": "Invio testo con chiave di idempotenza",
        "description": "Non supporta ancora media tramite API pubblica. Una 202 non equivale a consegna.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID dell'istanza di proprietà dell'account",
            "schema": {
              "type": "string",
              "pattern": "^wa_[0-9a-f]{24}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Univoca per ciascun invio logico e stabile tra retry",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[a-zA-Z0-9_-]{8,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TextMessage"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Invio accettato, consegna non garantita",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "nullable": true
                    },
                    "sessionId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "example": "accepted"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Destinatario, testo o chiave idempotenza non validi"
          },
          "401": {
            "description": "Token invalido o assente"
          },
          "404": {
            "description": "Istanza non trovata o non assegnata all'utente"
          },
          "409": {
            "description": "Conflitto sessione o idempotenza"
          },
          "502": {
            "description": "Esito invio incerto: non inviare una nuova chiave di retry alla cieca"
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": [
          "Eventi"
        ],
        "summary": "Elenco messaggi ricevuti, polling",
        "description": "Fino a 500 eventi conservati per utente per massimo 7 giorni, salvo eventuali cancellazioni. Niente download media da API pubbliche.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Eventi ricevuti",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token invalido o assente"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token WhatsApi personale wa_... ricevuto alla creazione account. Non usare l'API key interna del gateway."
      }
    },
    "schemas": {
      "Instance": {
        "type": "object",
        "required": [
          "id",
          "status",
          "hasQr"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "wa_0123456789abcdef01234567"
          },
          "status": {
            "type": "string",
            "example": "connected",
            "description": "not_started, connecting, qr_ready, connected, paused, reconnecting e altri stati transitori"
          },
          "hasQr": {
            "type": "boolean"
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "TextMessage": {
        "type": "object",
        "required": [
          "to",
          "text"
        ],
        "properties": {
          "to": {
            "type": "string",
            "pattern": "^[0-9]{8,15}$",
            "example": "393271234567"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "example": "Ciao da WhatsApi!"
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "sessionId": {
            "type": "string"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "type": {
            "type": "string",
            "example": "text"
          },
          "from": {
            "type": "string",
            "nullable": true
          },
          "text": {
            "type": "string"
          },
          "messageId": {
            "type": "string",
            "nullable": true
          },
          "hasMedia": {
            "type": "boolean"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}