openapi: 3.0.3
info:
  title: Crawler jurídico (multi-tribunal)
  description: |
    API HTTP para consulta pública de processos por **tribunal** (código canônico).

    **TJ-MT** (`tjmt`): consulta operacional via API do portal (Hellgate).

    **TRF 1ª a 6ª região** (`trf1` … `trf6`): **TRF1** e **TRF6** usam **crawler** da consulta
    pública PJe (dados alinhados ao portal). **TRF2–5** usam a API **Datajud** do CNJ quando
    existe `DATAJUD_API_KEY` no ambiente (pode haver defasagem em relação ao portal); sem chave,
    a consulta responde **503** com `error: datajud_api_key_ausente`. Ver `src/trf/README.md`.

    **Número do processo:** CNJ com ou sem máscara; o adaptador normaliza conforme a API de cada tribunal.

    **Arquivados:** depende do tribunal; no TJ-MT use `exibirArquivados` alinhado ao portal.

    **Autenticação:** `API_KEY` obrigatória no servidor (sem ela o processo não inicia).
    Rotas **`/api/v1/*`** exigem `Authorization: Bearer <API_KEY>` ou `X-API-Key`.
    **Públicos:** `GET /` (documentação HTML), `GET /health`, `GET /openapi.yaml`; preflight `OPTIONS`.
  version: 0.5.0

servers:
  - url: http://localhost:8080
    description: Desenvolvimento local
  - url: https://{host}
    description: Produção
    variables:
      host:
        default: crawler.unithub.com.br

tags:
  - name: consulta
    description: Consulta processual
  - name: tribunais
    description: Catálogo de tribunais suportados
  - name: sistema
    description: Saúde e documentação

paths:
  /:
    get:
      tags: [sistema]
      summary: Página de documentação (HTML)
      description: Interface pública com exemplos de requisição; não exige API_KEY.
      operationId: docHtml
      security: []
      responses:
        "200":
          description: HTML
          content:
            text/html:
              schema:
                type: string

  /health:
    get:
      tags: [sistema]
      summary: Health check
      operationId: healthCheck
      security: []
      responses:
        "200":
          description: Serviço ativo
          content:
            text/plain:
              schema:
                type: string
                example: ok

  /openapi.yaml:
    get:
      tags: [sistema]
      summary: Especificação OpenAPI (YAML)
      operationId: getOpenApiYaml
      security: []
      responses:
        "200":
          description: Arquivo OpenAPI 3
          content:
            application/yaml:
              schema:
                type: string

  /api/v1/tribunais:
    get:
      tags: [tribunais]
      summary: Listar tribunais disponíveis
      operationId: listarTribunais
      security:
        - bearerAuth: []
        - apiKeyHeader: []
      responses:
        "200":
          description: Lista de códigos e nomes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListaTribunaisResponse"
        "401":
          description: API_KEY obrigatória e inválida ou ausente
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/consulta:
    get:
      tags: [consulta]
      summary: Consultar por query string
      operationId: consultaGet
      security:
        - bearerAuth: []
        - apiKeyHeader: []
      parameters:
        - name: tribunal
          in: query
          description: Código canônico do tribunal (ex. `tjmt`, `trf1` … `trf6`). Alias — `court`.
          required: true
          schema:
            type: string
            example: tjmt
        - name: court
          in: query
          description: Sinônimo de `tribunal`.
          required: false
          schema:
            type: string
        - name: numeroUnico
          in: query
          description: Número CNJ (com ou sem máscara). Alternativas — `numero` ou `cnj`.
          required: true
          schema:
            type: string
            example: "1011293-58.2019.8.11.0015"
        - name: exibirArquivados
          in: query
          required: false
          schema:
            type: string
            example: "true"
        - name: arquivados
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Resultado da consulta
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsultaResponse"
        "400":
          description: Validação ou tribunal não suportado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorTribunal"
        "401":
          description: API_KEY obrigatória e inválida ou ausente
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Falha na consulta ao tribunal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Integração do tribunal ainda indisponível (ex. TRF sem crawler)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorComDetalhe"

    post:
      tags: [consulta]
      summary: Consultar por JSON
      operationId: consultaPost
      security:
        - bearerAuth: []
        - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConsultaRequest"
      responses:
        "200":
          description: Resultado da consulta
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsultaResponse"
        "400":
          description: Validação ou tribunal não suportado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorTribunal"
        "401":
          description: API_KEY obrigatória e inválida ou ausente
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Falha na consulta ao tribunal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Integração do tribunal ainda indisponível (ex. TRF sem crawler)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorComDetalhe"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    ListaTribunaisResponse:
      type: object
      required: [tribunais]
      properties:
        tribunais:
          type: array
          items:
            $ref: "#/components/schemas/InfoTribunal"

    InfoTribunal:
      type: object
      properties:
        codigo:
          type: string
          example: tjmt
        nome:
          type: string
        implementado:
          type: boolean

    ConsultaRequest:
      type: object
      required: [tribunal, numeroUnico]
      properties:
        tribunal:
          type: string
          description: Código canônico (ex. `tjmt`)
        tribunalCodigo:
          type: string
          description: Alias de `tribunal`
        court:
          type: string
          description: Alias de `tribunal`
        numeroUnico:
          type: string
        numero:
          type: string
        cnj:
          type: string
        numeroProcesso:
          type: string
        exibirArquivados:
          oneOf:
            - type: boolean
            - type: string
        arquivados:
          oneOf:
            - type: boolean
            - type: string
      example:
        tribunal: tjmt
        numeroUnico: "1011293-58.2019.8.11.0015"
        exibirArquivados: true

    ConsultaResponse:
      oneOf:
        - $ref: "#/components/schemas/ConsultaEncontrada"
        - $ref: "#/components/schemas/ConsultaNaoEncontrada"

    ConsultaNaoEncontrada:
      type: object
      required: [encontrado, numeroConsulta, tribunal, tribunalNome]
      properties:
        encontrado:
          type: boolean
          enum: [false]
        numeroConsulta:
          type: string
        tribunal:
          type: string
        tribunalNome:
          type: string

    ConsultaEncontrada:
      type: object
      required:
        - encontrado
        - numeroConsulta
        - tribunal
        - tribunalNome
        - numeroUnico
        - totalInstanciasNaLista
        - ultimoEvento
        - quantidadeEventos
        - movimentacoes
      properties:
        encontrado:
          type: boolean
          enum: [true]
        numeroConsulta:
          type: string
        tribunal:
          type: string
        tribunalNome:
          type: string
        numeroUnico:
          type: string
        totalInstanciasNaLista:
          type: integer
        instanciaSelecionada:
          type: integer
          nullable: true
          description: Grau/instância usada na resposta (maior grau quando há várias tramitações).
        nota:
          type: string
          description: Presente quando há mais de uma tramitação com o mesmo número.
        ultimoEvento:
          type: object
          nullable: true
        quantidadeEventos:
          type: integer
        movimentacoes:
          type: array
          items:
            type: object
        metadados:
          type: object
          nullable: true

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

    ErrorComDetalhe:
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            detail:
              type: object
              description: Metadados adicionais (ex. região TRF, URL do portal).
              additionalProperties: true

    ErrorTribunal:
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            tribunaisDisponiveis:
              type: array
              items:
                $ref: "#/components/schemas/InfoTribunal"
            codigoInformado:
              type: string
