openapi: 3.0.3

info:
  title: STRATAON miniEnv REST API v1
  version: "1.0.0"
  description: |
    API REST v1 do STRATAON miniEnv.

    Autenticação:
    - Token READ permite operações GET.
    - Token WRITE permite operações GET e POST.
    - Envie o token no cabeçalho: Authorization: Bearer <token>.
    - Quando a API estiver desabilitada, os endpoints protegidos retornam HTTP 403.

    Capacidades do miniEnv:
    - 9 entradas digitais: DI1 a DI9
    - 2 saídas digitais: DO1 a DO2
    - 32 variáveis booleanas: VB1 a VB32
    - 32 variáveis long: VL1 a VL32

servers:
  - url: http://192.168.17.178
    description: miniEnv na rede local — altere o IP conforme necessário

tags:
  - name: System
    description: Estado, identificação e reinicialização
  - name: I/O
    description: Leitura e comando das variáveis
  - name: DateTime
    description: Leitura e ajuste de data e hora

security:
  - BearerAuth: []

paths:
  /api/v1/health:
    get:
      tags: [System]
      summary: Consulta o estado geral
      description: Requer token READ ou WRITE.
      operationId: getHealth
      responses:
        "200":
          description: Estado geral do dispositivo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              example:
                ok: true
                status: ok
                uptime_s: 12345
                epoch: 1785240000
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ApiDisabled"

  /api/v1/info:
    get:
      tags: [System]
      summary: Consulta informações do dispositivo
      description: Requer token READ ou WRITE.
      operationId: getInfo
      responses:
        "200":
          description: Informações do miniEnv
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
              example:
                ok: true
                model: miniEnv
                hardware_revision: "-"
                board_id: "BOARD-ID"
                serial_id: "SERIAL-ID"
                version: "1.0.0"
                language: pt-BR
                media: wired
                mac: "00:11:22:33:44:55"
                ip: "192.168.17.173"
                dns1: "192.168.17.1"
                dns2: "8.8.8.8"
                gateway: "192.168.17.1"
                mask: "255.255.255.0"
                runtime:
                  uptime_s: 12345
                  epoch: 1785240000
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ApiDisabled"

  /api/v1/reboot:
    post:
      tags: [System]
      summary: Reinicia o dispositivo
      description: Requer token WRITE. O reboot ocorre após aproximadamente 500 ms.
      operationId: rebootDevice
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
            example: {}
      responses:
        "200":
          description: Reboot agendado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RebootResponse"
              example:
                ok: true
                message: Reboot agendado.
                delay_ms: 500
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ForbiddenOrDisabled"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/map:
    get:
      tags: [I/O]
      summary: Consulta o mapa das variáveis
      description: Requer token READ ou WRITE.
      operationId: getIoMap
      responses:
        "200":
          description: Identificadores disponíveis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IoMapResponse"
              example:
                ok: true
                di: [DI1, DI2, DI3, DI4, DI5, DI6, DI7, DI8, DI9]
                do: [DO1, DO2]
                vb: [VB1, VB2, VB3, VB4]
                vl: [VL1, VL2, VL3, VL4]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ApiDisabled"

  /api/v1/io:
    get:
      tags: [I/O]
      summary: Consulta todas as variáveis
      description: |
        Retorna um snapshot das 9 entradas, 2 saídas, 32 variáveis BOOL
        e 32 variáveis LONG. Requer token READ ou WRITE.
      operationId: getIoSnapshot
      responses:
        "200":
          description: Snapshot atual
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IoSnapshotResponse"
              example:
                ok: true
                di: [0, 1, 0, 0, 0, 0, 0, 0, 0]
                do: [1, 0]
                vb: [false, true, false]
                vl: [0, 123, -10]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ApiDisabled"

  /api/v1/io/{kind}/{idx}:
    parameters:
      - name: kind
        in: path
        required: true
        description: |
          Tipo da variável:
          - di: entrada digital
          - do: saída digital
          - vb: variável BOOL
          - vl: variável LONG
        schema:
          type: string
          enum: [di, do, vb, vl]
      - name: idx
        in: path
        required: true
        description: |
          Índice iniciado em 1. Faixas:
          DI 1..9, DO 1..2, VB 1..32 e VL 1..32.
        schema:
          type: integer
          minimum: 1
          maximum: 32

    get:
      tags: [I/O]
      summary: Consulta uma variável
      description: Requer token READ ou WRITE.
      operationId: getIoVariable
      responses:
        "200":
          description: Valor atual
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IoValueResponse"
              examples:
                digitalOutput:
                  value:
                    ok: true
                    kind: do
                    idx: 1
                    value: 1
                booleanVariable:
                  value:
                    ok: true
                    kind: vb
                    idx: 1
                    value: true
                longVariable:
                  value:
                    ok: true
                    kind: vl
                    idx: 1
                    value: 123
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ApiDisabled"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      tags: [I/O]
      summary: Comanda uma variável
      description: |
        Requer token WRITE.

        Tipos permitidos para escrita:
        - do: saída digital, índice 1..2
        - vb: variável BOOL, índice 1..32
        - vl: variável LONG, índice 1..32

        Entradas digitais (`di`) são somente leitura e não podem ser usadas neste POST.

        Para `do`, o campo opcional `pulse_ms` aplica imediatamente o valor
        solicitado e, ao final do tempo, muda a saída para o valor oposto.
        O firmware limita `pulse_ms` ao intervalo de 0 a 60000 ms.
      parameters:
        - name: kind
          in: path
          required: true
          description: Tipo gravável da variável.
          schema:
            type: string
            enum: [do, vb, vl]
        - name: idx
          in: path
          required: true
          description: |
            Índice iniciado em 1. Faixas:
            DO 1..2, VB 1..32 e VL 1..32.
          schema:
            type: integer
            minimum: 1
            maximum: 32
      operationId: setIoVariable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IoWriteRequest"
            examples:
              setOutput:
                summary: Liga DO1
                value:
                  value: 1
              pulseOutput:
                summary: Liga DO1 por 500 ms
                value:
                  value: 1
                  pulse_ms: 500
              setBoolean:
                summary: Ajusta VB1
                value:
                  value: true
              setLong:
                summary: Ajusta VL1
                value:
                  value: 123
      responses:
        "200":
          description: Comando executado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IoWriteResponse"
              examples:
                direct:
                  value:
                    ok: true
                    kind: do
                    idx: 1
                    value: 1
                pulse:
                  value:
                    ok: true
                    kind: do
                    idx: 1
                    value: 1
                    pulse_ms: 500
                    during: 1
                    final: 0
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ForbiddenOrDisabled"
        "404":
          $ref: "#/components/responses/NotFound"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"

  /api/v1/get_datetime:
    get:
      tags: [DateTime]
      summary: Consulta data e hora
      description: Requer token READ ou WRITE.
      operationId: getDateTime
      responses:
        "200":
          description: Data e hora locais do dispositivo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DateTimeResponse"
              example:
                ok: true
                datetime: "28/07/2026 10:30:00"
                epoch: 1785245400
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ApiDisabled"

  /api/v1/set_datetime:
    post:
      tags: [DateTime]
      summary: Ajusta data e hora
      description: Requer token WRITE.
      operationId: setDateTime
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DateTimeSetRequest"
            example:
              year: 2026
              mon: 7
              day: 28
              hour: 10
              min: 30
              sec: 0
      responses:
        "200":
          description: Data e hora ajustadas
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DateTimeResponse"
              example:
                ok: true
                datetime: "28/07/2026 10:30:00"
                epoch: 1785245400
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/ForbiddenOrDisabled"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token
      description: Token READ ou WRITE configurado no miniEnv.

  schemas:
    HealthResponse:
      type: object
      required: [ok, status, uptime_s, epoch]
      properties:
        ok:
          type: boolean
        status:
          type: string
          example: ok
        uptime_s:
          type: integer
          format: int64
          minimum: 0
        epoch:
          type: integer
          format: int64

    RuntimeInfo:
      type: object
      required: [uptime_s, epoch]
      properties:
        uptime_s:
          type: integer
          format: int64
          minimum: 0
        epoch:
          type: integer
          format: int64

    InfoResponse:
      type: object
      required:
        - ok
        - model
        - hardware_revision
        - board_id
        - serial_id
        - version
        - language
        - runtime
      properties:
        ok:
          type: boolean
        model:
          type: string
          example: miniEnv
        hardware_revision:
          type: string
        board_id:
          type: string
        serial_id:
          type: string
        version:
          type: string
        language:
          type: string
        media:
          type: string
          enum: [wired, wireless]
        mac:
          type: string
        ip:
          type: string
        dns1:
          type: string
        dns2:
          type: string
        gateway:
          type: string
        mask:
          type: string
        runtime:
          $ref: "#/components/schemas/RuntimeInfo"

    RebootResponse:
      type: object
      required: [ok, message, delay_ms]
      properties:
        ok:
          type: boolean
        message:
          type: string
        delay_ms:
          type: integer
          minimum: 0

    IoMapResponse:
      type: object
      required: [ok, di, do, vb, vl]
      properties:
        ok:
          type: boolean
        di:
          type: array
          minItems: 9
          maxItems: 9
          items:
            type: string
        do:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: string
        vb:
          type: array
          minItems: 32
          maxItems: 32
          items:
            type: string
        vl:
          type: array
          minItems: 32
          maxItems: 32
          items:
            type: string

    IoSnapshotResponse:
      type: object
      required: [ok, di, do, vb, vl]
      properties:
        ok:
          type: boolean
        di:
          type: array
          minItems: 9
          maxItems: 9
          items:
            type: integer
            enum: [0, 1]
        do:
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: integer
            enum: [0, 1]
        vb:
          type: array
          minItems: 32
          maxItems: 32
          items:
            type: boolean
        vl:
          type: array
          minItems: 32
          maxItems: 32
          items:
            type: integer
            format: int32

    IoValueResponse:
      type: object
      required: [ok, kind, idx, value]
      properties:
        ok:
          type: boolean
        kind:
          type: string
          enum: [di, do, vb, vl]
        idx:
          type: integer
          minimum: 1
          maximum: 32
        value:
          oneOf:
            - type: boolean
            - type: integer
              format: int32

    IoWriteRequest:
      type: object
      required: [value]
      properties:
        value:
          oneOf:
            - type: boolean
            - type: number
          description: DO/VB interpretam zero como falso e qualquer valor diferente de zero como verdadeiro. VL é convertido para int32.
        pulse_ms:
          type: integer
          minimum: 0
          maximum: 60000
          description: Opcional e válido apenas para DO.

    IoWriteResponse:
      type: object
      required: [ok, kind, idx, value]
      properties:
        ok:
          type: boolean
        kind:
          type: string
          enum: [do, vb, vl]
        idx:
          type: integer
          minimum: 1
          maximum: 32
        value:
          oneOf:
            - type: boolean
            - type: integer
              format: int32
        pulse_ms:
          type: integer
          minimum: 1
          maximum: 60000
        during:
          type: integer
          enum: [0, 1]
        final:
          type: integer
          enum: [0, 1]

    DateTimeSetRequest:
      type: object
      additionalProperties: false
      required: [year, mon, day, hour, min, sec]
      properties:
        year:
          type: integer
          minimum: 1970
          maximum: 9999
        mon:
          type: integer
          minimum: 1
          maximum: 12
        day:
          type: integer
          minimum: 1
          maximum: 31
        hour:
          type: integer
          minimum: 0
          maximum: 23
        min:
          type: integer
          minimum: 0
          maximum: 59
        sec:
          type: integer
          minimum: 0
          maximum: 59

    DateTimeResponse:
      type: object
      required: [ok, datetime, epoch]
      properties:
        ok:
          type: boolean
        datetime:
          type: string
          description: Data e hora local no formato DD/MM/YYYY HH:MM:SS
          example: "28/07/2026 10:30:00"
        epoch:
          type: integer
          format: int64

    ErrorResponse:
      type: object
      required: [ok, error]
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string

  responses:
    BadRequest:
      description: Requisição inválida
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    Unauthorized:
      description: Token ausente ou inválido
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            ok: false
            error:
              code: unauthorized
              message: Token inválido ou ausente.

    ApiDisabled:
      description: API desabilitada
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            ok: false
            error:
              code: api_disabled
              message: API /api/v1 está desativada.

    ForbiddenOrDisabled:
      description: Token sem permissão de escrita ou API desabilitada
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    NotFound:
      description: Tipo ou índice não encontrado
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    MethodNotAllowed:
      description: Escrita não permitida para o tipo informado
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    InternalError:
      description: Erro interno
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"