{
  "openapi": "3.1.0",
  "info": {
    "title": "IDTAP365 Frontend-Observed API Contract",
    "version": "2026-07-07",
    "description": "OpenAPI description generated from the local static frontend. It documents endpoints called by the frontend and should be verified against the live backend before integration. Verified against guardar.php source on 2026-07-07: the 'aprobado' field is strictly required and must be boolean true."
  },
  "servers": [
    {
      "url": "https://api.idtap365.com",
      "description": "Public API host referenced by the frontend"
    }
  ],
  "tags": [
    {
      "name": "Checkout",
      "description": "Payment intent creation for the Stripe checkout flow"
    },
    {
      "name": "Personalization",
      "description": "Token-based NFC card personalization flow"
    },
    {
      "name": "Formulario",
      "description": "DEPRECATED legacy order form endpoint. No confirmed real traffic since 2026-04-15."
    }
  ],
  "paths": {
    "/stripe/checkout.php": {
      "post": {
        "tags": [
          "Checkout"
        ],
        "summary": "Create Stripe checkout/payment session data",
        "description": "Called by checkout.html before Stripe confirmation. Exact backend response should be verified live.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout initialization response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid checkout request"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/personalizacion/init.php": {
      "get": {
        "tags": [
          "Personalization"
        ],
        "summary": "Initialize personalization form by token",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Secure personalization token"
          }
        ],
        "responses": {
          "200": {
            "description": "Personalization data for the token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonalizationInitResponse"
                }
              }
            }
          },
          "404": {
            "description": "Token not found or expired"
          }
        }
      }
    },
    "/personalizacion/subir_archivo.php": {
      "post": {
        "tags": [
          "Personalization"
        ],
        "summary": "Upload an image/file for personalization",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid upload"
          }
        }
      }
    },
    "/personalizacion/guardar.php": {
      "post": {
        "tags": [
          "Personalization"
        ],
        "summary": "Save personalization payload",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonalizationSaveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Personalization saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Invalid payload"
          }
        }
      }
    },
    "/api/procesar_formulario.php": {
      "post": {
        "tags": [
          "Formulario"
        ],
        "summary": "Submit configurator/order form",
        "description": "Called by js/configurador.js using FormData. The frontend also supports action routing by query parameter in backend project guidance. DEPRECATED as of 2026-07-07: nginx access logs show no legitimate traffic since 2026-04-15, predating the June 2026 architecture overhaul to the buy-pay-token-personalize flow. The last hit (2026-05-30) had no referer and matches bot-scan behavior, not a real submission. Use /stripe/checkout.php and the /personalizacion/* endpoints instead. This entry is kept for historical reference only.",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "procesar"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/FormularioProcesarRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Form submission result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          }
        },
        "deprecated": true
      },
      "get": {
        "tags": [
          "Formulario"
        ],
        "summary": "Consult order by id",
        "description": "Backend project guidance describes this route as GET ?action=consultar&id=N. Verify live before using. DEPRECATED as of 2026-07-07: nginx access logs show no legitimate traffic since 2026-04-15, predating the June 2026 architecture overhaul to the buy-pay-token-personalize flow. The last hit (2026-05-30) had no referer and matches bot-scan behavior, not a real submission. Use /stripe/checkout.php and the /personalizacion/* endpoints instead. This entry is kept for historical reference only.",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "const": "consultar"
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order data"
          },
          "404": {
            "description": "Order not found"
          }
        },
        "deprecated": true
      }
    }
  },
  "components": {
    "schemas": {
      "CheckoutRequest": {
        "type": "object",
        "required": [
          "plan",
          "nombre",
          "email",
          "whatsapp",
          "cantidad",
          "direccion"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "basic",
              "start",
              "pro"
            ]
          },
          "modalidad": {
            "type": "string",
            "enum": [
              "perfil",
              "resena"
            ]
          },
          "nombre": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "whatsapp": {
            "type": "string"
          },
          "cantidad": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
          },
          "direccion": {
            "$ref": "#/components/schemas/Direccion"
          }
        }
      },
      "Direccion": {
        "type": "object",
        "required": [
          "calle",
          "colonia",
          "cp",
          "ciudad",
          "estado"
        ],
        "properties": {
          "calle": {
            "type": "string"
          },
          "colonia": {
            "type": "string"
          },
          "cp": {
            "type": "string"
          },
          "ciudad": {
            "type": "string"
          },
          "estado": {
            "type": "string"
          },
          "referencias": {
            "type": "string"
          }
        }
      },
      "CheckoutResponse": {
        "type": "object",
        "properties": {
          "client_secret": {
            "type": "string",
            "description": "Stripe PaymentIntent client secret"
          },
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "PersonalizationInitResponse": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          },
          "modalidad": {
            "type": "string"
          },
          "nombre": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "FileUploadRequest": {
        "type": "object",
        "required": [
          "token",
          "tipo",
          "archivo"
        ],
        "properties": {
          "token": {
            "type": "string"
          },
          "tipo": {
            "type": "string"
          },
          "archivo": {
            "type": "string",
            "format": "binary"
          }
        }
      },
      "FileUploadResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "PersonalizationSaveRequest": {
        "type": "object",
        "required": [
          "token",
          "aprobado"
        ],
        "properties": {
          "token": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          },
          "modalidad": {
            "type": "string"
          },
          "template": {
            "type": "string"
          },
          "nombre": {
            "type": "string"
          },
          "profesion": {
            "type": "string"
          },
          "organizacion": {
            "type": "string"
          },
          "whatsapp": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "redes": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "servicios": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "aprobado": {
            "type": "boolean",
            "const": true,
            "description": "Confirmation checkbox. The backend rejects the request with HTTP 400 ('Debes confirmar el checkbox de aprobacion') unless this is exactly boolean true."
          }
        },
        "additionalProperties": true
      },
      "FormularioProcesarRequest": {
        "type": "object",
        "required": [
          "plan",
          "nombre_completo",
          "profesion_cargo",
          "whatsapp_principal",
          "correo_electronico",
          "url_principal"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "basic",
              "start",
              "pro"
            ]
          },
          "nombre_completo": {
            "type": "string"
          },
          "profesion_cargo": {
            "type": "string"
          },
          "whatsapp_principal": {
            "type": "string"
          },
          "correo_electronico": {
            "type": "string",
            "format": "email"
          },
          "url_principal": {
            "type": "string"
          },
          "imagen_perfil": {
            "type": "string",
            "format": "binary"
          }
        },
        "additionalProperties": true
      },
      "GenericSuccess": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  }
}