{"openapi":"3.1.0","info":{"title":"WellSim — pozo virtual","description":"Un pozo virtual con las tres salidas que tendría un pozo real: panel, API HTTP y RTU Modbus TCP. Todo sale del mismo motor físico; el switch de levantamiento cambia qué instrumentos lo miran.","version":"2.6.5"},"paths":{"/api/salud":{"get":{"tags":["Catálogos"],"summary":"Salud del servicio","description":"Versión, pozos vivos y puertos RTU.\n\n`rtu_interno` es donde ESCUCHA el proceso; `rtu_publicado`, donde se le habla\ndesde fuera. Desde F18-002 no coinciden: el contenedor corre sin privilegios y\nno puede tomar el 502, así que escucha en 5020 y el compose publica\n127.0.0.1:502→5020. Quien se conecta usa `rtu_publicado`.\n\n`rtu` se mantiene como alias de `rtu_interno` para no romper a quien ya lo lee.","operationId":"salud_api_salud_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Salud Api Salud Get"}}}}}}},"/api/pozos":{"get":{"tags":["Catálogos"],"summary":"Pozos virtuales","description":"`pozo-demo-01` es conmutable entre los seis levantamientos; `pozo-demo-02` es gas lift fijo.","operationId":"pozos_api_pozos_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"type":"object"},"type":"array","title":"Response Pozos Api Pozos Get"}}}}}}},"/api/levantamientos":{"get":{"tags":["Catálogos"],"summary":"Sistemas de levantamiento","description":"Los seis levantamientos con su mecanismo, sus tags (orden = mapa Modbus) y su falla típica.","operationId":"levantamientos_api_levantamientos_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"type":"object"},"type":"array","title":"Response Levantamientos Api Levantamientos Get"}}}}}}},"/api/catalogo":{"get":{"tags":["Catálogos"],"summary":"Catálogo de variables","description":"Copia fiel de la tabla `variables` de Oilboards: código, unidad canónica, tipo de entidad y rango válido.","operationId":"catalogo_api_catalogo_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"type":"object"},"type":"array","title":"Response Catalogo Api Catalogo Get"}}}}}}},"/api/lecturas":{"get":{"tags":["Lecturas"],"summary":"Lecturas del instante (contrato del Conector de Campo)","description":"Devuelve `{well, lift_type, measured_at, readings:{TAG:{value, unit, quality}}}`. Las presiones vienen en **kg/cm²**, como las reporta un SCADA de campo mexicano; la ingesta de Oilboards convierte.","operationId":"lecturas_api_lecturas_get","parameters":[{"name":"pozo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Lecturas Api Lecturas Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/estado":{"get":{"tags":["Estado"],"summary":"Estado completo del pozo","description":"Foto completa: lecturas crudas y canónicas, escenario, consignas, geometría, yacimiento, internos de la física (Pwf, gasto por fase, nivel de fluido, carta dinamométrica o curva de bomba), mapa Modbus y estado del conector.","operationId":"estado_api_estado_get","parameters":[{"name":"pozo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Estado Api Estado Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/historial":{"get":{"tags":["Estado"],"summary":"Historial reciente","description":"Últimos `n` ticks (1 por segundo) de todas las variables, en unidad canónica. Para tendencias.","operationId":"historial_api_historial_get","parameters":[{"name":"pozo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}},{"name":"n","in":"query","required":false,"schema":{"type":"integer","maximum":1800,"minimum":1,"default":300,"title":"N"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Historial Api Historial Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/stream":{"get":{"tags":["Estado"],"summary":"Stream en vivo (SSE, 1 Hz)","description":"`text/event-stream`. Cada evento trae lecturas crudas y canónicas, internos y estado del conector. Es lo que consume el panel.","operationId":"stream_api_stream_get","parameters":[{"name":"pozo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/levantamiento":{"post":{"tags":["Control"],"summary":"Conmutar el levantamiento","description":"`tipo` ∈ NAT · GL · BEC · BM · PCP · BH. No reinicia la historia del pozo: cambia el equipo y qué instrumentos lo miran. Solo `pozo-demo-01`.","operationId":"levantamiento_api_levantamiento_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiftIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Levantamiento Api Levantamiento Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/escenario":{"post":{"tags":["Control"],"summary":"Cambiar el escenario","description":"`normal`, la falla típica del levantamiento activo (`gas-lock`, `pump-off`, `perdida-inyeccion`, `solidos-desgaste`, `cavitacion-jet`, `carga-liquido`) o `paro`. La severidad rampa en minutos.","operationId":"escenario_api_escenario_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScenarioIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Escenario Api Escenario Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/consigna":{"post":{"tags":["Control"],"summary":"Ajustar una consigna del operador","description":"Frecuencia (BEC), carreras (BM), rpm (PCP), inyección (GL), presión y caudal motriz (BH), estrangulador. Acotada a límites físicos.","operationId":"consigna_api_consigna_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetpointIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Consigna Api Consigna Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/conector":{"get":{"tags":["Conector"],"summary":"Estado del conector","description":"Si está activo y desde cuándo, el destino, el token enmascarado (primeros 6 y últimos 4) y la última respuesta de Oilboards.","operationId":"conector_estado_api_conector_get","parameters":[{"name":"pozo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Conector Estado Api Conector Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Conector"],"summary":"Activar o detener el conector","description":"Con `activar: true` manda un lote cada `intervalo_s` segundos al `POST /api/v1/ingest` indicado. El token vive solo en memoria; con `activar: false` se olvida. Destinos acotados al ecosistema.","operationId":"conector_api_conector_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Conector Api Conector Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/conector/enviar":{"post":{"tags":["Conector"],"summary":"Enviar un solo lote de prueba","description":"Mismo lote que el conector, una sola vez, sin dejarlo activo. Devuelve la respuesta de Oilboards tal cual.","operationId":"conector_enviar_api_conector_enviar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Conector Enviar Api Conector Enviar Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/modbus/mapa":{"get":{"tags":["RTU"],"summary":"Mapa de registros Modbus","description":"Texto plano en el formato del manual del Conector: `tag, dirección, tipo, escala, unidad`. Holding registers, float32 big-endian, 2 registros por variable, unit ID 1, solo lectura.","operationId":"modbus_mapa_api_modbus_mapa_get","parameters":[{"name":"pozo","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}}],"responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConnectorIn":{"properties":{"activar":{"type":"boolean","title":"Activar"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"entidad":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entidad"},"intervalo_s":{"type":"integer","title":"Intervalo S","default":10},"pozo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}},"type":"object","required":["activar"],"title":"ConnectorIn"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LiftIn":{"properties":{"tipo":{"type":"string","title":"Tipo"},"pozo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}},"type":"object","required":["tipo"],"title":"LiftIn"},"ScenarioIn":{"properties":{"escenario":{"type":"string","title":"Escenario"},"pozo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}},"type":"object","required":["escenario"],"title":"ScenarioIn"},"SetpointIn":{"properties":{"clave":{"type":"string","title":"Clave"},"valor":{"type":"number","title":"Valor"},"pozo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pozo"}},"type":"object","required":["clave","valor"],"title":"SetpointIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"Lecturas","description":"Lo que un SCADA o el Conector de Campo leerían del pozo."},{"name":"Estado","description":"Estado completo del motor, historial y stream para paneles."},{"name":"Control","description":"Conmutar levantamiento, escenario y consignas del operador. Es un pozo de práctica: se acciona sin credencial."},{"name":"Conector","description":"Enviar las lecturas al `POST /api/v1/ingest` de Oilboards desde este servidor. La credencial es el token de fuente de Oilboards: sin uno válido, Oilboards rechaza el lote."},{"name":"RTU","description":"Mapa de registros del RTU Modbus TCP (puertos 502 y 503)."},{"name":"Catálogos","description":"Pozos, levantamientos y catálogo de variables."}]}