Internal Funnels API - Closelly (auto-sync)

internal-funnels-api-docs.json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Internal Funnels API - Closelly",
    "description": "API interna para obtener datos de funnels de negocio. Cada funnel agrupa información relacionada (leads, businesses, implementaciones SENCE, pagos) según el tipo de funnel solicitado.\n\n**Autenticación:** Header `token` con credencial interna.\n\n**Funnels disponibles:**\n- `sence_leads`: Devuelve BusinessLeads con su Business asociado (si existe), SenceImplementations y Payments del business. Orden por id desc, filtrable por name, contact_name, contact_email (ILIKE), paginado estándar.",
    "contact": {
      "name": "Closelly website",
      "url": "http://closelly.com/",
      "email": "soporte@closelly.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.closelly.com",
      "description": "Production Server"
    },
    {
      "url": "https://staging-api.closelly.com",
      "description": "Staging Server"
    }
  ],
  "security": [
    {
      "InternalTokenAuth": []
    }
  ],
  "paths": {
    "/api/internal/funnels/{funnel}": {
      "get": {
        "tags": ["Internal Funnels"],
        "summary": "Obtener funnel",
        "description": "Obtiene los datos del funnel especificado. El primer funnel disponible es `sence_leads`, que devuelve items con estructura: one (BusinessLead), two (Business o {}), three (SenceImplementation[]), four (Payment[]).",
        "parameters": [
          {
            "name": "funnel",
            "in": "path",
            "description": "Nombre del funnel a consultar (ej: sence_leads)",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["sence_leads"]
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Filtrar por nombre del BusinessLead (ILIKE)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact_name",
            "in": "query",
            "description": "Filtrar por contact_name del BusinessLead (ILIKE)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact_email",
            "in": "query",
            "description": "Filtrar por contact_email del BusinessLead (ILIKE)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "email"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Número de página. Default: 1",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "description": "Resultados por página. Default: 10",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de items del funnel",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FunnelItem"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "description": "Funnel no encontrado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Funnel not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "InternalTokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "token",
        "description": "Token de autenticación para APIs internas."
      }
    },
    "schemas": {
      "FunnelItem": {
        "type": "object",
        "description": "Item del funnel sence_leads. Cada item representa un BusinessLead con sus datos asociados.",
        "properties": {
          "one": {
            "$ref": "#/components/schemas/BusinessLead"
          },
          "two": {
            "oneOf": [
              { "$ref": "#/components/schemas/Business" },
              { "type": "object", "description": "Objeto vacío {} si no hay business asociado" }
            ]
          },
          "three": {
            "type": "array",
            "description": "SenceImplementations del business. Array vacío si no hay business.",
            "items": {
              "$ref": "#/components/schemas/SenceImplementation"
            }
          },
          "four": {
            "type": "array",
            "description": "Payments del business. Array vacío si no hay business.",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          }
        }
      },
      "BusinessLead": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "contact_name": { "type": "string" },
          "contact_lastname": { "type": "string" },
          "contact_email": { "type": "string", "format": "email" },
          "position": { "type": "string" },
          "validation_hash": { "type": "string" },
          "is_validated": { "type": "boolean" },
          "validated_at": { "type": "string", "format": "date-time", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Business": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "cif": { "type": "string" },
          "phone": { "type": "string" },
          "business_lead_id": { "type": "integer", "nullable": true },
          "active": { "type": "boolean", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "SenceImplementation": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "code": { "type": "string" },
          "business_id": { "type": "integer" },
          "course_name": { "type": "string" },
          "course_code": { "type": "string" },
          "company_name": { "type": "string" },
          "status": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "business_id": { "type": "integer" },
          "amount": { "type": "number" },
          "currency": { "type": "string" },
          "status": { "type": "string" },
          "title": { "type": "string" },
          "quantity": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "No autorizado - Token inválido o faltante",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "example": "credential token not found"
                }
              }
            }
          }
        }
      }
    }
  }
}