> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtener el consumo por insumo

> Lee el consumo por insumo en su propia unidad, agrupado por día o semana UTC a partir del registro inmutable de movimientos de existencias, como contrato de evidencia. Requiere analytics:read. Nunca se suman cantidades de insumos o unidades distintas; coverage informa los movimientos sin unidad verificada, un alcance de bodegas restringido y la ventana cubierta cuando la lectura se trunca. Solo se incluye una narración cuando pasa la verificación determinística de fidelidad numérica. Solo cantidades. Por defecto, la ventana son los últimos 30 días hasta ahora; una ventana mal formada, invertida o demasiado amplia devuelve 400. Determinístico; se calcula en vivo sobre los datos de la clínica dental.



## OpenAPI

````yaml /openapi.es.json get /v1/analytics/consumption-trend
openapi: 3.1.0
info:
  description: >-
    La API pública para desarrolladores de Muveya: recursos /v1 de solo lectura,
    limitados a un tenant y autenticados con una clave de API opaca. Un
    presupuesto de solicitudes por clave.
  title: API para desarrolladores de Muveya
  version: 0.1.0
servers:
  - description: Producción
    url: https://api.muveya.com
security: []
tags:
  - name: Clave de API
  - name: Clínicas
  - name: Bodegas
  - name: Catálogo
  - name: Inventario
  - name: Pedidos
  - name: Entregas
  - name: Analítica
paths:
  /v1/analytics/consumption-trend:
    get:
      tags:
        - Analítica
      summary: Obtener el consumo por insumo
      description: >-
        Lee el consumo por insumo en su propia unidad, agrupado por día o semana
        UTC a partir del registro inmutable de movimientos de existencias, como
        contrato de evidencia. Requiere analytics:read. Nunca se suman
        cantidades de insumos o unidades distintas; coverage informa los
        movimientos sin unidad verificada, un alcance de bodegas restringido y
        la ventana cubierta cuando la lectura se trunca. Solo se incluye una
        narración cuando pasa la verificación determinística de fidelidad
        numérica. Solo cantidades. Por defecto, la ventana son los últimos 30
        días hasta ahora; una ventana mal formada, invertida o demasiado amplia
        devuelve 400. Determinístico; se calcula en vivo sobre los datos de la
        clínica dental.
      operationId: getAnalyticsConsumptionTrend
      parameters:
        - name: from
          in: query
          required: false
          description: >-
            Inicio inclusivo de la ventana, en ISO-8601 (por defecto, 30 días
            antes de `to`).
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: Fin exclusivo de la ventana, en ISO-8601 (por defecto, ahora).
          schema:
            type: string
            format: date-time
        - name: granularity
          in: query
          required: false
          description: Tamaño del tramo; por defecto `day`.
          schema:
            type: string
            enum:
              - day
              - week
        - name: catalogItemId
          in: query
          required: false
          description: Limita la tendencia a un insumo del catálogo.
          schema:
            type: string
      responses:
        '200':
          description: La tendencia de consumo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionTrend'
          headers:
            X-RateLimit-Limit:
              description: El presupuesto de solicitudes por clave en la ventana actual.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Remaining:
              description: Solicitudes restantes en la ventana actual (0 cuando se agotan).
              schema:
                type: integer
                minimum: 0
            X-RateLimit-Reset:
              description: Segundos hasta que se reinicie la ventana actual.
              schema:
                type: integer
                minimum: 1
            RateLimit:
              description: >-
                Estado del presupuesto de solicitudes según el borrador de la
                IETF, por ejemplo "limit=120, remaining=119, reset=60".
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Política según el borrador de la IETF, por ejemplo "120;w=60"
                (límite;segundos de la ventana).
              schema:
                type: string
        '400':
          description: >-
            La ventana está mal formada, invertida o es más amplia que el
            máximo.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          headers:
            X-RateLimit-Limit:
              description: El presupuesto de solicitudes por clave en la ventana actual.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Remaining:
              description: Solicitudes restantes en la ventana actual (0 cuando se agotan).
              schema:
                type: integer
                minimum: 0
            X-RateLimit-Reset:
              description: Segundos hasta que se reinicie la ventana actual.
              schema:
                type: integer
                minimum: 1
            RateLimit:
              description: >-
                Estado del presupuesto de solicitudes según el borrador de la
                IETF, por ejemplo "limit=120, remaining=119, reset=60".
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Política según el borrador de la IETF, por ejemplo "120;w=60"
                (límite;segundos de la ventana).
              schema:
                type: string
        '401':
          description: >-
            La clave de API falta, no es válida, fue revocada, expiró o está
            vinculada a una clínica dental suspendida.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: La clave de API no tiene el scope que requiere esta ruta.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: >-
            La clave de API superó su límite de solicitudes en la ventana
            actual.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          headers:
            Retry-After:
              description: Segundos (valor positivo) hasta que se permita otra solicitud.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Limit:
              description: El presupuesto de solicitudes por clave en la ventana actual.
              schema:
                type: integer
                minimum: 1
            X-RateLimit-Remaining:
              description: Solicitudes restantes en la ventana actual (0 cuando se agotan).
              schema:
                type: integer
                minimum: 0
            X-RateLimit-Reset:
              description: Segundos hasta que se reinicie la ventana actual.
              schema:
                type: integer
                minimum: 1
            RateLimit:
              description: >-
                Estado del presupuesto de solicitudes según el borrador de la
                IETF, por ejemplo "limit=120, remaining=119, reset=60".
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Política según el borrador de la IETF, por ejemplo "120;w=60"
                (límite;segundos de la ventana).
              schema:
                type: string
      security:
        - apiKeyBearer: []
components:
  schemas:
    ConsumptionTrend:
      type: object
      additionalProperties: false
      required:
        - metric
        - definition
        - granularity
        - period
        - movementCount
        - timezone
        - asOf
        - freshness
        - evidenceId
        - truncated
        - filters
        - coverage
        - series
        - unverifiedItems
      properties:
        metric:
          type: string
        definition:
          type: string
          description: La definición legible de la métrica.
        granularity:
          type: string
          enum:
            - day
            - week
        period:
          type: object
          additionalProperties: false
          required:
            - from
            - to
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        movementCount:
          type: integer
          description: Todos los movimientos de consumo leídos, medidos o no.
        timezone:
          type: string
        asOf:
          type: string
          format: date-time
        freshness:
          type: string
          enum:
            - live
        evidenceId:
          type: string
        truncated:
          type: boolean
          description: >-
            true cuando la lectura del registro de movimientos alcanzó su tope;
            se lee del más reciente al más antiguo, así que coverage.coveredFrom
            indica dónde empiezan las cifras.
        filters:
          type: object
          additionalProperties:
            type: string
        coverage:
          $ref: '#/components/schemas/ConsumptionCoverage'
        series:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionSeries'
        unverifiedItems:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionUnverifiedItem'
        narration:
          $ref: '#/components/schemas/ConsumptionNarration'
    ProblemDetails:
      type: object
      additionalProperties: false
      required:
        - type
        - title
        - status
        - detail
        - instance
        - code
        - requestId
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
        instance:
          type: string
        code:
          type: string
        requestId:
          type: string
    ConsumptionCoverage:
      type: object
      additionalProperties: false
      required:
        - measuredMovementCount
        - unverifiedMovementCount
        - warehouseScope
      properties:
        measuredMovementCount:
          type: integer
          description: Movimientos con unidad verificada, incorporados a las series.
        unverifiedMovementCount:
          type: integer
          description: >-
            Movimientos sin unidad verificada, contados aparte y sin sumarse a
            ninguna serie.
        warehouseScope:
          type: string
          enum:
            - all
            - restricted
          description: >-
            `restricted` cuando el lector solo ve algunas bodegas: las series no
            son totales de la clínica dental.
        coveredFrom:
          type: string
          format: date-time
          description: >-
            Aparece cuando la lectura alcanzó su tope: las cifras cubren solo
            [coveredFrom, period.to).
    ConsumptionSeries:
      type: object
      additionalProperties: false
      description: >-
        Consumo de un insumo en una unidad medida. Las cantidades se suman solo
        dentro de una serie, nunca entre series.
      required:
        - seriesKey
        - catalogItemId
        - unitOfMeasure
        - totalConsumed
        - usedQuantity
        - issuedQuantity
        - movementCount
        - buckets
      properties:
        seriesKey:
          type: string
          description: >-
            Clave estable de la serie en este reporte:
            `<catalogItemId>:<unitOfMeasure>`.
        catalogItemId:
          type: string
        itemName:
          type: string
          description: >-
            El nombre del insumo; se omite cuando el catálogo ya no reconoce el
            id.
        sku:
          type: string
          description: El SKU del insumo; se omite cuando el catálogo ya no reconoce el id.
        unitOfMeasure:
          type: string
          description: >-
            La unidad registrada en los movimientos de esta serie (identidad de
            medida inmutable).
        totalConsumed:
          type: number
          description: Cantidad consumida, en `unitOfMeasure`.
        usedQuantity:
          type: number
          description: >-
            El uso observado: existencias registradas donde se usaron, en
            `unitOfMeasure`.
        issuedQuantity:
          type: number
          description: >-
            Existencias entregadas a salas que no cuentan su stock: un consumo
            estimado, en `unitOfMeasure`. usedQuantity + issuedQuantity =
            totalConsumed.
        movementCount:
          type: integer
        buckets:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionTrendBucket'
    ConsumptionUnverifiedItem:
      type: object
      additionalProperties: false
      description: >-
        Un insumo con consumo registrado antes de que existiera la identidad de
        unidad: se cuenta, nunca se cuantifica.
      required:
        - catalogItemId
        - movementCount
      properties:
        catalogItemId:
          type: string
        itemName:
          type: string
          description: >-
            El nombre del insumo; se omite cuando el catálogo ya no reconoce el
            id.
        sku:
          type: string
          description: El SKU del insumo; se omite cuando el catálogo ya no reconoce el id.
        movementCount:
          type: integer
    ConsumptionNarration:
      type: object
      additionalProperties: false
      description: >-
        Las afirmaciones que puede hacer un resumen, cada una igual a la
        evidencia en su propia unidad. Solo se incluye cuando pasa la
        verificación determinística de fidelidad numérica.
      required:
        - evidenceId
        - period
        - acknowledgesTruncation
        - acknowledgesUnverified
        - acknowledgesRestrictedScope
        - claims
      properties:
        evidenceId:
          type: string
        period:
          type: object
          additionalProperties: false
          required:
            - from
            - to
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        acknowledgesTruncation:
          type: boolean
        acknowledgesUnverified:
          type: boolean
        acknowledgesRestrictedScope:
          type: boolean
        claims:
          type: array
          items:
            oneOf:
              - type: object
                additionalProperties: false
                required:
                  - kind
                  - seriesKey
                  - field
                  - value
                  - unit
                properties:
                  kind:
                    type: string
                    enum:
                      - series
                  seriesKey:
                    type: string
                  field:
                    type: string
                    enum:
                      - totalConsumed
                      - movementCount
                  value:
                    type: number
                  unit:
                    type: string
              - type: object
                additionalProperties: false
                required:
                  - kind
                  - field
                  - value
                  - unit
                properties:
                  kind:
                    type: string
                    enum:
                      - coverage
                  field:
                    type: string
                    enum:
                      - movementCount
                      - unverifiedMovementCount
                  value:
                    type: number
                  unit:
                    type: string
                    enum:
                      - movements
    ConsumptionTrendBucket:
      type: object
      additionalProperties: false
      required:
        - bucketStart
        - consumedQuantity
        - usedQuantity
        - issuedQuantity
        - movementCount
      properties:
        bucketStart:
          type: string
          format: date-time
          description: Inicio del intervalo en UTC.
        consumedQuantity:
          type: number
          description: >-
            Cantidad consumida en el intervalo, en la unidad de la serie a la
            que pertenece.
        usedQuantity:
          type: number
          description: >-
            El uso observado en el intervalo: existencias registradas donde se
            usaron.
        issuedQuantity:
          type: number
          description: >-
            Existencias entregadas en el intervalo a salas que no cuentan su
            stock: un consumo estimado. usedQuantity + issuedQuantity =
            consumedQuantity.
        movementCount:
          type: integer
  securitySchemes:
    apiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: >-
        Clave de API opaca mvy_test_ enviada como token Bearer. El servidor
        deriva de ella exactamente una clínica dental; la ruta nunca lleva un
        selector de clínica dental.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.