{ "openapi": "3.0.3", "info": { "title": "OTP Login API Frontend", "description": "API JSON per il frontend (mockup / mockupfe).\n\nURL reale: POST /?action=\n(index.php e front controller; DirectoryIndex/rewrite).\n\nConvenzioni:\n- Content-Type: application/json\n- Risposta base: { \"success\": true|false, \"error\": \"...\", \"data\": { ... } }\n- data.otp / otp.otp in chiaro solo se config.otp.debug = true\n- In debug (config.debug): piano_debug / debug[] sulle orchestrazioni QN*\n\nNota Postman: i path /ACTION nella spec corrispondono a POST /?action=ACTION.\nUsa anche openapi.json oppure postman_collection.json per l'import.\n", "version": "1.0.0", "contact": { "name": "QN Media / Helios" } }, "servers": [ { "url": "https://testgm.quotidiano.net", "description": "Ambiente test" }, { "url": "http://localhost", "description": "Locale (se applicabile)" } ], "tags": [ { "name": "QN", "description": "API ottimizzate FE (meno round-trip)" }, { "name": "OTP", "description": "OTP locale (DB + email/SMS)" }, { "name": "Piano", "description": "Identity, profilo, token" }, { "name": "Newsletter", "description": "Piano ESP + feed Quotidiano" }, { "name": "Recommendations", "description": "Contenuti suggeriti Cxense / Piano" }, { "name": "Debug", "description": "Test SMTP / SMS" } ], "paths": { "/QNLogin": { "post": { "tags": [ "QN" ], "summary": "QNLogin", "description": "Da email/telefono fino a step OTP telefono (#14), OTP email (#33) o password (#60).\nURL reale: `POST /?action=QNLogin`\n", "operationId": "QNLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QNLoginRequest" }, "examples": { "phone": { "value": { "identifier": "3331234567" } }, "email": { "value": { "identifier": "user@example.com" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/QNVerifyOtp": { "post": { "tags": [ "QN" ], "summary": "QNVerifyOtp", "description": "Verifica OTP. Login completo ÔåÆ `next_step: 90` + token.\nPer `flow: phone_register` conferma anche DOI Piano.\nURL reale: `POST /?action=QNVerifyOtp`\n", "operationId": "QNVerifyOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QNVerifyOtpRequest" }, "example": { "otp_code": "123456", "flow": "phone", "phone": "3331234567", "email": "user@example.com", "uid": "", "stay_logged_in": true } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/QNRegister": { "post": { "tags": [ "QN" ], "summary": "QNRegister", "description": "Register + eventuale OTP email. `otp: true|false` controlla lÔÇÖinvio.\nURL reale: `POST /?action=QNRegister`\n", "operationId": "QNRegister", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QNRegisterRequest" }, "example": { "email": "new@mail.it", "phone": "3331234567", "consents": { "terms_conditions": true }, "otp": true, "flow": "phone_register", "is_magic_link_sent": true } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/QNAddPhone": { "post": { "tags": [ "QN" ], "summary": "QNAddPhone", "description": "Step #61ÔÇô#62: unicit├á telefono + OTP SMS.\nErrore `phone_taken` se gi├á registrato.\nURL reale: `POST /?action=QNAddPhone`\n", "operationId": "QNAddPhone", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QNAddPhoneRequest" }, "example": { "phone": "3331234567", "uid": "PNI...", "email": "user@mail.it", "flow": "email_add_phone" } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/QNUpdateProfile": { "post": { "tags": [ "QN" ], "summary": "QNUpdateProfile", "description": "update_profile + access_token. Imposta cookie `__utp`.\nCheck unicit├á `otp_phone` prima del save.\nURL reale: `POST /?action=QNUpdateProfile`\n", "operationId": "QNUpdateProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QNUpdateProfileRequest" }, "example": { "uid": "PNI...", "first_name": "Luca", "last_name": "Rossi", "birth_date": "1990-01-15", "city": "Milano", "otp_phone": "3331234567", "stay_logged_in": true } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/otp_generate": { "post": { "tags": [ "OTP" ], "summary": "otp_generate", "description": "Genera e invia OTP (email e/o SMS). Cooldown `resend_cooldown_seconds`.\nURL reale: `POST /?action=otp_generate`\n", "operationId": "otp_generate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpGenerateRequest" }, "examples": { "smsOnly": { "value": { "uid": "3331234567", "phone": "3331234567" } }, "smsEmail": { "value": { "uid": "3331234567", "phone": "3331234567", "notify_email": "user@example.com" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/verify_otp": { "post": { "tags": [ "OTP" ], "summary": "verify_otp", "description": "Verifica OTP locale. Con `is_registration` + `uid` conferma DOI Piano.\nURL reale: `POST /?action=verify_otp`\n", "operationId": "verify_otp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpRequest" }, "example": { "email": "3331234567", "otp_code": "123456", "is_registration": false, "uid": "PNIxxxx", "stay_logged_in": false } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/otp_verify_local": { "post": { "tags": [ "OTP" ], "summary": "otp_verify_local", "description": "Solo test: verifica OTP in DB senza DOI/sessione.\nURL reale: `POST /?action=otp_verify_local`\n", "operationId": "otp_verify_local", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uid", "otp_code" ], "properties": { "uid": { "type": "string" }, "otp_code": { "type": "string" } } }, "example": { "uid": "3331234567", "otp_code": "123456" } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/search_user": { "post": { "tags": [ "Piano" ], "summary": "search_user", "description": "Cerca utente per telefono (`otp_phone`). URL reale: `POST /?action=search_user`", "operationId": "search_user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "example": "3331234567" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/get_user_email": { "post": { "tags": [ "Piano" ], "summary": "get_user_email", "description": "Lookup utente per email. URL reale: `POST /?action=get_user_email`", "operationId": "get_user_email", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/get_user": { "post": { "tags": [ "Piano" ], "summary": "get_user", "description": "Profilo ridotto per uid. URL reale: `POST /?action=get_user`", "operationId": "get_user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "example": "PNIxxxx" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/login": { "post": { "tags": [ "Piano" ], "summary": "login", "description": "Login Piano. Senza password = passwordless; con password = ramo email.\nURL reale: `POST /?action=login`\n", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "examples": { "passwordless": { "value": { "email": "user@example.com", "stay_logged_in": false } }, "withPassword": { "value": { "email": "user@example.com", "password": "secret", "stay_logged_in": true } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/register": { "post": { "tags": [ "Piano" ], "summary": "register", "description": "Registrazione passwordless. `send_otp: false` salta lÔÇÖOTP.\nURL reale: `POST /?action=register`\n", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" }, "example": { "email": "user@example.com", "phone": "3331234567", "consents": { "terms_conditions": true }, "is_magic_link_sent": true, "send_otp": true } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/update_profile": { "post": { "tags": [ "Piano" ], "summary": "update_profile", "description": "Aggiorna identity e/o custom fields. Check `phone_taken` su `otp_phone`.\nURL reale: `POST /?action=update_profile`\n", "operationId": "update_profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" }, "example": { "uid": "PNIxxxx", "email": "user@example.com", "first_name": "Luca", "last_name": "Rossi", "otp_phone": "331222222", "city": "Roma", "birth_date": "1973-07-21" } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/doi_confirm": { "post": { "tags": [ "Piano" ], "summary": "doi_confirm", "description": "Imposta DOI email CONFIRMED. URL reale: `POST /?action=doi_confirm`", "operationId": "doi_confirm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/access_token": { "post": { "tags": [ "Piano" ], "summary": "access_token", "description": "Emette access token Piano e cookie `__utp`.\nURL reale: `POST /?action=access_token`\n", "operationId": "access_token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string" }, "stay_logged_in": { "type": "boolean", "default": true }, "body": { "type": "object", "nullable": true } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/refresh_token": { "post": { "tags": [ "Piano" ], "summary": "refresh_token", "description": "Refresh OAuth via Piano identity/token (`grant_type=refresh_token`).\nURL reale: `POST /?action=refresh_token`\n", "operationId": "refresh_token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" }, "stay_logged_in": { "type": "boolean" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/user_access_list": { "post": { "tags": [ "Piano" ], "summary": "user_access_list", "description": "Lista risorse accessibili (Piano user/access/list).\nToken da body, cookie `__utp` o header Bearer.\nURL reale: `POST /?action=user_access_list`\n", "operationId": "user_access_list", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/newsletter_subscribe": { "post": { "tags": [ "Newsletter" ], "summary": "newsletter_subscribe", "description": "Iscrizione ESP. Preferito `selections[]` multi-testata.\nURL reale: `POST /?action=newsletter_subscribe`\n", "operationId": "newsletter_subscribe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscribeRequest" }, "examples": { "batch": { "value": { "email": "user@mail.it", "selections": [ { "feed": "ilresto", "mlid": "6521" }, { "feed": "qn", "mlid": "3832" } ] } }, "single": { "value": { "email": "user@mail.it", "testata": "rdc", "mlids": "6521" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/newsletter_feed": { "post": { "tags": [ "Newsletter" ], "summary": "newsletter_feed", "description": "Feed newsletter. `all: true` (o senza feed) ÔåÆ 4 feed + `items[]`.\nURL reale: `POST /?action=newsletter_feed`\n", "operationId": "newsletter_feed", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "all": { "type": "boolean" }, "feed": { "type": "string", "enum": [ "qn", "ilresto", "ilgiorno", "lanazione" ] } } }, "examples": { "all": { "value": { "all": true } }, "one": { "value": { "feed": "ilresto" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/recommendations": { "post": { "tags": [ "Recommendations" ], "summary": "recommendations", "description": "Contenuti suggeriti Cxense.\n- `url` opzionale: assente ÔåÆ home, presente ÔåÆ article\n- `toptrend` opzionale (default false)\n- widget selezionato: home | article | home_toptrend | article_toptrend\nURL reale: `POST /?action=recommendations`\n", "operationId": "recommendations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true }, "udi": { "type": "string", "nullable": true }, "toptrend": { "type": "boolean", "default": false }, "widget_id": { "type": "string", "nullable": true, "description": "Override selezione automatica" } } }, "examples": { "home": { "value": { "toptrend": false } }, "article": { "value": { "url": "https://www.quotidiano.net/cronaca/articolo", "udi": "PNI...", "toptrend": false } }, "articleToptrend": { "value": { "url": "https://www.quotidiano.net/cronaca/articolo", "toptrend": true } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/test_mail": { "post": { "tags": [ "Debug" ], "summary": "test_mail", "description": "Test SMTP diagnostico. URL reale: `POST /?action=test_mail`", "operationId": "test_mail", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } }, "/test_sms": { "post": { "tags": [ "Debug" ], "summary": "test_sms", "description": "Test gateway SMS. URL reale: `POST /?action=test_sms`", "operationId": "test_sms", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "$ref": "#/components/responses/ApiSuccess" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Access token Piano (anche cookie `__utp`)" } }, "responses": { "ApiSuccess": { "description": "Risposta JSON standard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "schemas": { "ApiResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "data": { "type": "object", "additionalProperties": true, "nullable": true }, "piano_debug": { "type": "object", "additionalProperties": true, "description": "Solo se config.debug" }, "debug": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Trace orchestratore QN* (solo debug)" } } }, "QNLoginRequest": { "type": "object", "required": [ "identifier" ], "properties": { "identifier": { "type": "string", "description": "Email o telefono" } } }, "QNVerifyOtpRequest": { "type": "object", "required": [ "otp_code", "flow" ], "properties": { "otp_code": { "type": "string" }, "flow": { "type": "string", "enum": [ "phone", "email_with_phone", "email", "phone_register", "email_register", "email_add_phone", "email_register_phone" ] }, "phone": { "type": "string" }, "email": { "type": "string" }, "uid": { "type": "string" }, "stay_logged_in": { "type": "boolean" } } }, "QNRegisterRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "consents": { "type": "object", "additionalProperties": true }, "otp": { "type": "boolean", "description": "true = invia OTP email" }, "flow": { "type": "string" }, "is_magic_link_sent": { "type": "boolean" } } }, "QNAddPhoneRequest": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" }, "uid": { "type": "string" }, "email": { "type": "string" }, "flow": { "type": "string", "enum": [ "email_add_phone", "email_register_phone" ] } } }, "QNUpdateProfileRequest": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "birth_date": { "type": "string", "format": "date" }, "city": { "type": "string" }, "otp_phone": { "type": "string" }, "email": { "type": "string" }, "stay_logged_in": { "type": "boolean" } } }, "OtpGenerateRequest": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "Chiave OTP in DB" }, "phone": { "type": "string" }, "notify_email": { "type": "string", "format": "email" }, "email": { "type": "string", "description": "Retrocompat notify" } } }, "VerifyOtpRequest": { "type": "object", "required": [ "otp_code" ], "properties": { "email": { "type": "string", "description": "uid OTP (telefono o email)" }, "otp_code": { "type": "string" }, "is_registration": { "type": "boolean" }, "uid": { "type": "string" }, "access_token": { "type": "string" }, "stay_logged_in": { "type": "boolean" } } }, "LoginRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "stay_logged_in": { "type": "boolean" } } }, "RegisterRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "consents": { "type": "object", "additionalProperties": true }, "is_magic_link_sent": { "type": "boolean" }, "send_otp": { "type": "boolean" } } }, "UpdateProfileRequest": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "otp_phone": { "type": "string" }, "city": { "type": "string" }, "birth_date": { "type": "string", "format": "date" } } }, "NewsletterSubscribeRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "selections": { "type": "array", "items": { "type": "object", "properties": { "feed": { "type": "string" }, "testata": { "type": "string" }, "mlid": { "type": "string" } } } }, "testata": { "type": "string" }, "mlids": { "type": "string" } } } } } }