openapi.yaml

openapi: 3.0.3
info:
  title: AgroSmart API
  version: 3.0.0
  description: |
    API para coleta e consulta de cotacoes de graos (Coamo e LAR),
    com historico em banco e autenticacao por token.
servers:
  - url: https://agrosmartapi.onrender.com
    description: Ambiente de producao
  - url: http://localhost:3000
    description: Ambiente de desenvolvimento
tags:
  - name: Health
    description: Rotas publicas de status da API
  - name: Cotacoes
    description: Consulta e coleta direta de cotacoes
  - name: Utils
    description: Rotas auxiliares, analiticas e de exportacao
paths:
  /:
    get:
      tags: [Health]
      summary: Status basico da API
      responses:
        "200":
          description: API online
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  mensagem:
                    type: string
                    example: AgroSmart API online
                  health:
                    type: string
                    example: /health
  /health:
    get:
      tags: [Health]
      summary: Health check
      responses:
        "200":
          description: API saudavel
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  servico:
                    type: string
                    example: AgroSmart API
                  timestamp:
                    type: string
                    format: date-time
  /api/cotacoes/coamo:
    get:
      tags: [Cotacoes]
      summary: Retorna cotacoes da Coamo
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
      responses:
        "200":
          description: Lista de cotacoes da Coamo
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Cotacao"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/InternalError"
  /api/cotacoes/lar:
    get:
      tags: [Cotacoes]
      summary: Retorna cotacoes da LAR
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
      responses:
        "200":
          description: Lista de cotacoes da LAR
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Cotacao"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/InternalError"
  /api/cotacoes/todos:
    get:
      tags: [Cotacoes]
      summary: Retorna cotacoes de Coamo e LAR
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
      responses:
        "200":
          description: Cotacoes consolidadas
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CotacoesConsolidadas"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/InternalError"
  /api/cotacoes/filtro:
    get:
      tags: [Utils]
      summary: Filtra cotacoes atuais por fonte e texto
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
        - name: fonte
          in: query
          schema:
            type: string
            enum: [all, coamo, lar]
            default: all
        - name: grao
          in: query
          schema:
            type: string
        - name: local
          in: query
          schema:
            type: string
        - name: descricao
          in: query
          schema:
            type: string
        - name: fornecedor
          in: query
          schema:
            type: string
        - name: unidade
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Cotacoes filtradas
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FiltroResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/InternalError"
  /api/cotacoes/melhor-preco:
    get:
      tags: [Utils]
      summary: Retorna a cotacao atual com maior preco para o filtro informado
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
        - name: fonte
          in: query
          schema:
            type: string
            enum: [all, coamo, lar]
            default: all
        - name: grao
          in: query
          required: true
          schema:
            type: string
        - name: local
          in: query
          schema:
            type: string
        - name: descricao
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Melhor preco encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MelhorPrecoResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
  /api/cotacoes/comparativo:
    get:
      tags: [Utils]
      summary: Compara o melhor preco atual entre Coamo e LAR
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
        - name: grao
          in: query
          required: true
          schema:
            type: string
        - name: local
          in: query
          schema:
            type: string
        - name: descricao
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Comparativo entre as fontes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComparativoResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
  /api/cotacoes/variacao:
    get:
      tags: [Utils]
      summary: Calcula a variacao historica de um grao em uma fonte
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - name: fonte
          in: query
          required: true
          schema:
            type: string
            enum: [coamo, lar]
        - name: grao
          in: query
          required: true
          schema:
            type: string
        - name: local
          in: query
          schema:
            type: string
        - name: descricao
          in: query
          schema:
            type: string
        - name: dataInicio
          in: query
          schema:
            type: string
            example: "2026-04-01"
        - name: dataFim
          in: query
          schema:
            type: string
            example: "2026-04-10"
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
      responses:
        "200":
          description: Variacao calculada
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VariacaoResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
  /api/cotacoes/periodo:
    get:
      tags: [Utils]
      summary: Consulta historico de cotacoes por periodo
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - name: fonte
          in: query
          schema:
            type: string
            enum: [all, coamo, lar]
            default: all
        - name: grao
          in: query
          schema:
            type: string
        - name: local
          in: query
          schema:
            type: string
        - name: descricao
          in: query
          schema:
            type: string
        - name: dataInicio
          in: query
          schema:
            type: string
            example: "2026-04-01"
        - name: dataFim
          in: query
          schema:
            type: string
            example: "2026-04-10"
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
      responses:
        "200":
          description: Itens historicos encontrados no periodo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeriodoResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
  /api/cotacoes/exportar:
    get:
      tags: [Utils]
      summary: Exporta cotacoes atuais filtradas em CSV
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/ForceParam"
        - name: fonte
          in: query
          schema:
            type: string
            enum: [all, coamo, lar]
            default: all
        - name: grao
          in: query
          schema:
            type: string
        - name: local
          in: query
          schema:
            type: string
        - name: descricao
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Arquivo CSV gerado
          content:
            text/csv:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
  /api/cotacoes/historico:
    get:
      tags: [Utils]
      summary: Retorna historico de coletas
      security:
        - bearerAuth: []
        - apiTokenHeader: []
      parameters:
        - name: fonte
          in: query
          description: Fonte desejada
          schema:
            type: string
            enum: [all, coamo, lar]
            default: all
        - name: limit
          in: query
          description: Quantidade maxima de registros (1..500)
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Lista de snapshots de historico
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/HistoricoSnapshot"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Token
    apiTokenHeader:
      type: apiKey
      in: header
      name: x-api-token
  parameters:
    ForceParam:
      name: force
      in: query
      description: Se true, ignora cache e força nova coleta
      schema:
        type: boolean
        default: false
  responses:
    BadRequestError:
      description: Erro de validacao da requisicao
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Fonte invalida. Use coamo, lar ou all.
    UnauthorizedError:
      description: Token ausente ou invalido
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Token invalido.
    NotFoundError:
      description: Nenhum registro encontrado
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Nenhuma cotacao encontrada para o filtro informado.
    InternalError:
      description: Erro interno
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error: Falha ao coletar cotacoes da Coamo
  schemas:
    Cotacao:
      type: object
      properties:
        fornecedor:
          type: string
          example: Coamo Agroindustrial Cooperativa
        grao:
          type: string
          example: SOJA
        descricao:
          type: string
          example: 60 KG
        data_hora:
          type: string
          example: 05/03/2026 12:00
        preco:
          type: string
          example: R$ 150,00
        unidade:
          type: string
          example: SC
        local:
          type: string
          example: Campo Mourao
      required: [fornecedor, grao, descricao, data_hora, preco, unidade, local]
    CotacoesConsolidadas:
      type: object
      properties:
        coamo:
          type: array
          items:
            $ref: "#/components/schemas/Cotacao"
        larAgro:
          type: array
          items:
            $ref: "#/components/schemas/Cotacao"
      required: [coamo, larAgro]
    CotacaoComFonte:
      allOf:
        - $ref: "#/components/schemas/Cotacao"
        - type: object
          properties:
            fonte:
              type: string
              enum: [coamo, lar]
              example: coamo
          required: [fonte]
    CotacaoAnalitica:
      allOf:
        - $ref: "#/components/schemas/CotacaoComFonte"
        - type: object
          properties:
            precoNumerico:
              type: number
              example: 112
          required: [precoNumerico]
    FiltroResponse:
      type: object
      properties:
        fonte:
          type: string
          enum: [all, coamo, lar]
        total:
          type: integer
          example: 2
        filtros:
          type: object
          additionalProperties: true
        itens:
          type: array
          items:
            $ref: "#/components/schemas/CotacaoComFonte"
      required: [fonte, total, filtros, itens]
    MelhorPrecoResponse:
      type: object
      properties:
        fonte:
          type: string
          enum: [all, coamo, lar]
        criterio:
          type: string
          example: maior_preco
        totalConsiderado:
          type: integer
          example: 2
        filtros:
          type: object
          additionalProperties: true
        item:
          $ref: "#/components/schemas/CotacaoAnalitica"
      required: [fonte, criterio, totalConsiderado, filtros, item]
    ComparativoDiferenca:
      type: object
      properties:
        valor:
          type: number
          nullable: true
          example: 4.5
        percentual:
          type: number
          nullable: true
          example: 4.19
        melhorFonte:
          type: string
          nullable: true
          example: coamo
    ComparativoResponse:
      type: object
      properties:
        filtros:
          type: object
          additionalProperties: true
        coamo:
          allOf:
            - $ref: "#/components/schemas/CotacaoAnalitica"
          nullable: true
        lar:
          allOf:
            - $ref: "#/components/schemas/CotacaoAnalitica"
          nullable: true
        diferenca:
          $ref: "#/components/schemas/ComparativoDiferenca"
      required: [filtros, diferenca]
    PeriodoInfo:
      type: object
      properties:
        dataInicio:
          type: string
          format: date-time
          nullable: true
        dataFim:
          type: string
          format: date-time
          nullable: true
    PeriodoItem:
      allOf:
        - $ref: "#/components/schemas/CotacaoAnalitica"
        - type: object
          properties:
            snapshotId:
              type: integer
              example: 10
            collectedAt:
              type: string
              format: date-time
            slotLabel:
              type: string
              nullable: true
            triggerType:
              type: string
              example: scheduled
          required: [snapshotId, collectedAt, triggerType]
    PeriodoResponse:
      type: object
      properties:
        fonte:
          type: string
          enum: [all, coamo, lar]
        filtros:
          type: object
          additionalProperties: true
        periodo:
          $ref: "#/components/schemas/PeriodoInfo"
        totalSnapshots:
          type: integer
          example: 10
        totalItens:
          type: integer
          example: 37
        itens:
          type: array
          items:
            $ref: "#/components/schemas/PeriodoItem"
      required: [fonte, filtros, periodo, totalSnapshots, totalItens, itens]
    VariacaoPonto:
      type: object
      properties:
        snapshotId:
          type: integer
          example: 10
        collectedAt:
          type: string
          format: date-time
        slotLabel:
          type: string
          nullable: true
        triggerType:
          type: string
        preco:
          type: string
          example: R$ 112,00
        precoNumerico:
          type: number
          example: 112
        item:
          $ref: "#/components/schemas/CotacaoComFonte"
      required: [snapshotId, collectedAt, triggerType, preco, precoNumerico, item]
    VariacaoResponse:
      type: object
      properties:
        fonte:
          type: string
          enum: [coamo, lar]
        filtros:
          type: object
          additionalProperties: true
        periodo:
          $ref: "#/components/schemas/PeriodoInfo"
        totalPontos:
          type: integer
          example: 10
        primeiro:
          $ref: "#/components/schemas/VariacaoPonto"
        ultimo:
          $ref: "#/components/schemas/VariacaoPonto"
        variacao:
          type: object
          properties:
            valor:
              type: number
              nullable: true
            percentual:
              type: number
              nullable: true
        historico:
          type: array
          items:
            $ref: "#/components/schemas/VariacaoPonto"
      required: [fonte, filtros, periodo, totalPontos, primeiro, ultimo, variacao, historico]
    HistoricoSnapshot:
      type: object
      properties:
        id:
          type: integer
          example: 123
        source:
          type: string
          enum: [coamo, lar]
          example: coamo
        payload:
          type: array
          items:
            $ref: "#/components/schemas/Cotacao"
        itemCount:
          type: integer
          example: 12
        collectedAt:
          type: string
          format: date-time
          example: "2026-03-05T12:00:00-03:00"
        slotLabel:
          type: string
          nullable: true
          example: "12:00"
        triggerType:
          type: string
          example: scheduled
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
      required: [id, source, payload, itemCount, collectedAt, triggerType]
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Erro interno do servidor
        details:
          type: object
          nullable: true