{
  "openapi": "3.0.3",
  "info": {
    "title": "ControlRoll · API de solicitudes de versiones",
    "version": "1.0.0",
    "description": "Recepción y seguimiento en una aplicación independiente. No ejecuta aprovisionamiento ni activa usuarios en esta etapa. Testing bajo demanda. Piloto de validación tributaria: Chile. Los países requieren autorización. Las comunas se consultan en la plantilla existente del país mediante conexiones privadas de solo lectura. Inactivación de versiones autorizadas mediante POST con JSON; conserva reactivación del ERP."
  },
  "servers": [
    {
      "url": "/",
      "description": "Mismo origen de la instalación; api.controlroll.com aún es una dirección propuesta."
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/versiones": {
      "post": {
        "operationId": "CrearSolicitud",
        "summary": "Registrar una solicitud idempotente.",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 100,
              "pattern": "^[A-Za-z0-9._:-]{8,100}$"
            },
            "description": "Conservar ante timeout. La misma clave con otros datos produce 409."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionInput"
              },
              "example": {
                "pais": "CL",
                "identificacionTributaria": "11111111-1",
                "razonSocial": "Empresa de Ejemplo SpA",
                "direccion": "Avenida de Ejemplo 123",
                "codigoComuna": "<CODIGO_DEL_CATALOGO>",
                "emailAdministrador": "admin@example.com"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Solicitud recibida, aún sin aprovisionar.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Accepted"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string"
                },
                "description": "Ruta de consulta de estado."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Segundos antes de consultar, actualmente 30."
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "País no habilitado o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Solicitud inexistente o ajena.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/solicitudes": {
      "get": {
        "operationId": "ListarSolicitudes",
        "summary": "Solicitudes de la integración autenticada.",
        "parameters": [
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bloque de solicitudes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "solicitudes",
                    "offset",
                    "limit",
                    "hasMore"
                  ],
                  "properties": {
                    "solicitudes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "solicitudId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "razonSocial": {
                            "type": "string"
                          },
                          "pais": {
                            "type": "string"
                          },
                          "estado": {
                            "type": "string",
                            "enum": [
                              "pendiente_aprovisionamiento"
                            ]
                          },
                          "testing": {
                            "type": "string",
                            "enum": [
                              "sin_crear"
                            ]
                          },
                          "recibidaEnUtc": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "País no habilitado o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Solicitud inexistente o ajena.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/solicitudes/{solicitudId}": {
      "get": {
        "operationId": "ConsultarSolicitud",
        "summary": "Detalle y eventos de una solicitud propia.",
        "parameters": [
          {
            "in": "path",
            "name": "solicitudId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Solicitud propia.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "solicitudId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "razonSocial": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 60
                    },
                    "pais": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 2,
                      "example": "CL"
                    },
                    "estado": {
                      "type": "string",
                      "enum": [
                        "pendiente_aprovisionamiento"
                      ]
                    },
                    "testing": {
                      "type": "string",
                      "enum": [
                        "sin_crear"
                      ]
                    },
                    "recibidaEnUtc": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "identificacionTributaria": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 20
                    },
                    "direccion": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "codigoComuna": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 20,
                      "description": "Código de texto obtenido del catálogo de comunas; no enviar un número JSON."
                    },
                    "emailAdministrador": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 60,
                      "format": "email"
                    },
                    "nombreComercial": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50,
                      "description": "Opcional; por defecto, hasta 50 caracteres de razonSocial."
                    },
                    "referenciaComercial": {
                      "type": "string"
                    },
                    "eventos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "codigo": {
                            "type": "string"
                          },
                          "mensaje": {
                            "type": "string"
                          },
                          "fechaUtc": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "País no habilitado o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Solicitud inexistente o ajena.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/catalogos/paises": {
      "get": {
        "operationId": "ListarPaises",
        "summary": "Países habilitados para la integración.",
        "responses": {
          "200": {
            "description": "Países disponibles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "paises": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "codigo",
                          "nombre",
                          "validacion",
                          "permiteSolicitarVersion"
                        ],
                        "properties": {
                          "codigo": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                          },
                          "nombre": {
                            "type": "string"
                          },
                          "validacion": {
                            "type": "string",
                            "enum": [
                              "cl_mod11"
                            ]
                          },
                          "permiteSolicitarVersion": {
                            "type": "boolean",
                            "description": "Autoriza altas además de consultar el catálogo."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "País no habilitado o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Solicitud inexistente o ajena.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Países autorizados para catálogo. permiteSolicitarVersion indica si además admiten solicitudes de alta; los demás continúan disponibles solo para catálogo."
      }
    },
    "/api/v1/catalogos/comunas": {
      "get": {
        "operationId": "ListarComunas",
        "summary": "Catálogo paginado y búsqueda literal de comunas.",
        "parameters": [
          {
            "in": "query",
            "name": "pais",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            }
          },
          {
            "in": "query",
            "name": "buscar",
            "schema": {
              "type": "string",
              "maxLength": 60
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bloque de comunas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "comunas",
                    "offset",
                    "limit",
                    "hasMore"
                  ],
                  "properties": {
                    "comunas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "codigo": {
                            "type": "string"
                          },
                          "nombre": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "hasMore": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "País no habilitado o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Solicitud inexistente o ajena.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Primero elegir un país autorizado. Consulta directamente su plantilla existente, filtrando también la pertenencia geográfica. No usa un catálogo importado como fallback. Un fallo de fuente produce 503."
      }
    },
    "/api/v1/integracion": {
      "get": {
        "operationId": "ConsultarIntegracion",
        "summary": "Identidad y configuración pública de la credencial.",
        "responses": {
          "200": {
            "description": "Integración autenticada, sin el secreto.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "integracionId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "nombre": {
                      "type": "string"
                    },
                    "referenciaComercial": {
                      "type": "string"
                    },
                    "venceEnUtc": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "solicitudesPorMinuto": {
                      "type": "integer"
                    },
                    "paises": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "codigo",
                          "nombre",
                          "validacion",
                          "permiteSolicitarVersion"
                        ],
                        "properties": {
                          "codigo": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 2
                          },
                          "nombre": {
                            "type": "string"
                          },
                          "validacion": {
                            "type": "string",
                            "enum": [
                              "cl_mod11"
                            ]
                          },
                          "permiteSolicitarVersion": {
                            "type": "boolean",
                            "description": "Autoriza altas además de consultar el catálogo."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "País no habilitado o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Solicitud inexistente o ajena.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/versiones/inactivar": {
      "post": {
        "operationId": "InactivarVersion",
        "summary": "Inactivar una versión expresamente autorizada.",
        "description": "Exige permiso por SSID. No admite parámetros de URL como sustituto del JSON. Conserva la reactivación del ERP. Si ya está inactiva no reemplaza el motivo anterior. Un reintento con la misma clave no vuelve a suspender después de reactivación.",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 100,
              "pattern": "^[A-Za-z0-9._:-]{8,100}$"
            },
            "description": "Conservar ante timeout. La misma clave con otros datos produce 409."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InactivationInput"
              },
              "example": {
                "ssid": "<SSID>",
                "motivo": "Suspensión solicitada por el cliente."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operación confirmada o reintento. estadoActual puede diferir del resultado histórico tras una reactivación.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InactivationResult"
                }
              }
            }
          },
          "400": {
            "description": "Validación o JSON no válido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente, vencida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Versión no autorizada o HTTPS requerido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Versión previamente autorizada inexistente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Método no admitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key ya utilizada con otro contenido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Más de 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Se requiere application/json UTF-8.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Límite por minuto alcanzado; respete Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Servicio no disponible; reintente con la misma clave.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Secreto opaco de 256 bits (43 caracteres base64url); no es un JWT. Solo desde servidor sobre HTTPS."
      }
    },
    "schemas": {
      "VersionInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "pais",
          "identificacionTributaria",
          "razonSocial",
          "direccion",
          "codigoComuna",
          "emailAdministrador"
        ],
        "properties": {
          "pais": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2,
            "example": "CL"
          },
          "identificacionTributaria": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20
          },
          "razonSocial": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "direccion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "codigoComuna": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "description": "Código de texto obtenido del catálogo de comunas; no enviar un número JSON."
          },
          "emailAdministrador": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60,
            "format": "email"
          },
          "nombreComercial": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "Opcional; por defecto, hasta 50 caracteres de razonSocial."
          }
        }
      },
      "Accepted": {
        "type": "object",
        "required": [
          "solicitudId",
          "estado",
          "testing",
          "recibidaEnUtc",
          "repetida",
          "estadoUrl",
          "mensaje"
        ],
        "properties": {
          "solicitudId": {
            "type": "string",
            "format": "uuid"
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente_aprovisionamiento"
            ]
          },
          "testing": {
            "type": "string",
            "enum": [
              "sin_crear"
            ]
          },
          "recibidaEnUtc": {
            "type": "string",
            "format": "date-time"
          },
          "repetida": {
            "type": "boolean"
          },
          "estadoUrl": {
            "type": "string"
          },
          "mensaje": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "codigo",
              "mensaje",
              "seguimientoId"
            ],
            "properties": {
              "codigo": {
                "type": "string"
              },
              "mensaje": {
                "type": "string"
              },
              "campo": {
                "type": "string",
                "nullable": true
              },
              "seguimientoId": {
                "type": "string",
                "format": "uuid"
              }
            }
          }
        }
      },
      "InactivationInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ssid",
          "motivo"
        ],
        "properties": {
          "ssid": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9._-]{1,20}$"
          },
          "motivo": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Texto sin controles, representable en OBS_ESTADO varchar(500). No admite INAC_POR_PAGO."
          }
        }
      },
      "InactivationResult": {
        "type": "object",
        "required": [
          "operacionId",
          "ssid",
          "resultado",
          "estadoActual",
          "motivoAplicado",
          "fechaUtc",
          "repetida"
        ],
        "properties": {
          "operacionId": {
            "type": "string",
            "format": "uuid"
          },
          "ssid": {
            "type": "string"
          },
          "resultado": {
            "type": "string",
            "enum": [
              "inactivada",
              "ya_inactiva"
            ]
          },
          "estadoActual": {
            "type": "string",
            "enum": [
              "activa",
              "inactiva"
            ]
          },
          "motivoAplicado": {
            "type": "string",
            "nullable": true
          },
          "fechaUtc": {
            "type": "string",
            "format": "date-time"
          },
          "repetida": {
            "type": "boolean"
          }
        }
      }
    }
  }
}