openapi: 3.1.0
info:
  title: API REST de Dinaup
  version: '2026-11-11'
  summary: Leer informes, renderizar documentos y escribir registros en la empresa de una clave API.
  description: |
    Especificación de los endpoints de datos de la API REST de Dinaup, escrita a partir de su referencia:
    https://doc.dinaup.com/docs/desarrollo/integraciones/api-rest-referencia

    Cada empresa tiene su URL. Las rutas no distinguen mayúsculas. Todos los valores de los registros
    viajan como texto. Los endpoints de usuarios finales (`/api/Login`, `/api/Register`…) y el almacén
    clave-valor (`/api/GetKV`, `/api/SetKV`) no están en este fichero: están en
    https://doc.dinaup.com/docs/desarrollo/integraciones/api-rest-usuarios-finales
servers:
  - url: https://{claveDeConexion}.dinaup.io
    description: El servidor de tu empresa
    variables:
      claveDeConexion:
        default: tu-empresa
        description: La clave de conexión de tu empresa, en minúsculas.
security:
  - bearer: []
tags:
  - name: Estado
  - name: Clave
  - name: Informes
  - name: Documentos
  - name: Escritura
paths:
  /ping:
    get:
      tags: [Estado]
      summary: Saber si el servidor responde
      operationId: ping
      security: []
      responses:
        '200':
          description: El servidor responde.
          content:
            text/plain:
              schema: { type: string, examples: [pong] }
        '503':
          description: El servidor está arrancando.
  /version:
    get:
      tags: [Estado]
      summary: La versión del servidor
      operationId: version
      security: []
      responses:
        '200':
          description: La versión, en texto. Responde también durante el arranque.
          content:
            text/plain:
              schema: { type: string }
  /api/whoami:
    get:
      tags: [Clave]
      summary: El usuario que hay detrás de la clave
      description: Devuelve el empleado por defecto de la clave. Es la primera llamada de una integración.
      operationId: whoami
      responses:
        '200':
          description: El empleado por defecto de la clave.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user: { type: string }
        '401': { $ref: '#/components/responses/TokenInvalido' }
        '429': { $ref: '#/components/responses/RitmoAgotado' }
        '503': { $ref: '#/components/responses/SinTurno' }
  /api/reports:
    post:
      tags: [Informes]
      summary: Ejecutar un informe de Flex
      description: |
        Devuelve una página de las filas de un informe. El informe define columnas, filtros y agrupaciones;
        la petición elige la página y puede añadir filtros y orden.

        Para recorrerlo entero, pide páginas hasta que llegue una con menos filas que `resultsPerPage`.
        La página más alta es `50000 / resultsPerPage + 1`, con división entera: por encima, `data` llega vacía.
      operationId: runReport
      parameters:
        - name: id
          in: query
          required: true
          description: El informe. Con el ID de una sección, usa su informe principal.
          schema: { type: string, format: uuid }
        - name: page
          in: query
          description: La página, mayor que 0.
          schema: { type: integer, minimum: 1, default: 1 }
        - name: resultsPerPage
          in: query
          description: Filas por página, mayor que 0.
          schema: { type: integer, minimum: 1, default: 10 }
        - name: withFiles
          in: query
          description: Incluye los adjuntos de las filas en `files`.
          schema: { type: boolean, default: false }
        - name: safeColumnsName
          in: query
          description: Nombra las columnas por su GUID. Renombrar un campo no rompe la integración.
          schema: { type: boolean, default: false }
        - name: calculatePages
          in: query
          description: Con `false` no cuenta las filas. `totalPages` llega a `-1` y la respuesta tarda menos.
          schema: { type: boolean, default: true }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Variables'
                - $ref: '#/components/schemas/ConsultaDeInforme'
            examples:
              variables:
                summary: Solo las variables del informe
                value: { desde: '2026-01-01', hasta: '2026-01-31' }
              estructurada:
                summary: Variables, filtros y orden
                value:
                  variables: { desde: '2026-01-01' }
                  filter:
                    - { field: pr_estado, op: '=', value: '1' }
                  order:
                    - { field: fechaia, desc: true }
      responses:
        '200':
          description: Una página del informe.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PaginaDeInforme' }
        '400':
          description: |
            Un parámetro, el cuerpo, un filtro o un orden no valen, o el servidor no encuentra el informe o
            rechaza un campo o un valor. Se comprueba antes que el token.
          content:
            text/plain: { schema: { type: string } }
            application/problem+json: { schema: { type: object } }
        '401':
          description: El token no vale, o el empleado de la clave no puede consultar el informe.
        '429': { $ref: '#/components/responses/RitmoAgotado' }
        '500':
          description: Otro fallo al ejecutar el informe, con el motivo.
          content:
            text/plain: { schema: { type: string } }
        '503': { $ref: '#/components/responses/SinTurno' }
  /api/dynamicdocuments:
    post:
      tags: [Documentos]
      summary: Renderizar un documento dinámico
      operationId: renderDynamicDocument
      parameters:
        - name: id
          in: query
          required: true
          description: El documento dinámico.
          schema: { type: string, format: uuid }
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Variables' }
            example: { clienteId: 123e4567-e89b-12d3-a456-426614174000 }
      responses:
        '200':
          description: El documento renderizado, como texto.
          content:
            text/plain:
              schema: { type: string }
        '400':
          description: El `id` no es un GUID, el cuerpo no es un diccionario de textos o el documento no existe o está eliminado.
        '401': { $ref: '#/components/responses/TokenInvalido' }
        '429': { $ref: '#/components/responses/RitmoAgotado' }
        '500':
          description: Otro fallo, con el motivo.
        '503': { $ref: '#/components/responses/SinTurno' }
  /api/writeoperations:
    post:
      tags: [Escritura]
      summary: Crear, editar y borrar registros
      description: |
        Escribe en una sección. Con `id` vacío o ausente crea el registro; con un GUID existente edita los
        campos enviados. No hay `DELETE`: un borrado es una edición con `eliminado` a `"1"`, sin `scripts`.

        Un lote admite 25 operaciones y 2.500 entre operaciones y líneas. Todos los objetos de un lote llevan
        los mismos campos. En un lote, la respuesta es `200` aunque una fila falle: comprueba `confirmed` y
        `aError` de cada resultado, y reintenta solo las filas con `aError`.
      operationId: writeOperations
      parameters:
        - name: sectionId
          in: query
          required: true
          description: La sección.
          schema: { type: string, format: uuid }
        - name: FieldPrimary
          in: query
          required: true
          description: El campo que identifica el registro, normalmente `id`.
          schema: { type: string, default: id }
        - name: scripts
          in: query
          description: |
            Con `true` ejecuta los scripts de la sección al guardar, como la interfaz, un registro cada vez.
            Con `false` escribe el lote de una vez.
          schema: { type: boolean, default: false }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/Registro'
                - $ref: '#/components/schemas/RegistroConLineas'
                - type: array
                  minItems: 1
                  maxItems: 25
                  items: { $ref: '#/components/schemas/Registro' }
                - type: array
                  minItems: 1
                  maxItems: 25
                  items: { $ref: '#/components/schemas/RegistroConLineas' }
            examples:
              alta:
                summary: Crear un registro
                value: { id: '', pr_cliente: <id-del-cliente>, pr_importe: '100.00' }
              conLineas:
                summary: Un registro con sus líneas
                value:
                  Main: { id: '', pr_cliente: <id-del-cliente> }
                  List:
                    - { pr_item: <id-del-producto>, pr_cantidad: '10' }
              borrado:
                summary: Borrar un registro
                value: { id: 123e4567-e89b-12d3-a456-426614174000, eliminado: '1' }
      responses:
        '200':
          description: Un registro devuelve un objeto; un lote, una lista con un objeto por registro.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResultadoDeEscritura'
                  - type: array
                    items: { $ref: '#/components/schemas/ResultadoDeEscritura' }
        '400':
          description: |
            La petición se para entera antes de escribir: un campo que no existe, un valor con mal formato, un
            `id` que no existe, una referencia que no existe, un lote vacío, por encima de un tope o con juegos
            de campos distintos. Se comprueba antes que el token.
          content:
            text/plain: { schema: { type: string } }
        '401': { $ref: '#/components/responses/TokenInvalido' }
        '413':
          description: El cuerpo pasa del tamaño máximo (1.232.896 bytes por defecto).
        '415':
          description: 'Falta la cabecera `Content-Type: application/json`.'
        '429': { $ref: '#/components/responses/RitmoAgotado' }
        '500':
          description: El servidor rechazó un registro suelto al guardarlo. El cuerpo lleva el motivo.
          content:
            text/plain: { schema: { type: string } }
        '503': { $ref: '#/components/responses/SinTurno' }
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        El token de una clave API con secreto, Compatible WebHook marcado y un empleado por defecto. Se copia
        en Play, en la tarjeta Cómo conectar de Administración → Claves API. No es la clave API en crudo.
  headers:
    X-Dinaup-VCores:
      description: Las peticiones que la clave atiende a la vez.
      schema: { type: string }
    Retry-After:
      description: Los segundos que hay que esperar antes de repetir la petición.
      schema: { type: integer, minimum: 1 }
  responses:
    TokenInvalido:
      description: El token falta, tiene mal formato o no corresponde a ninguna clave.
      headers:
        WWW-Authenticate:
          schema: { type: string, examples: [Bearer] }
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                examples:
                  - Bearer token was not provided.
                  - The provided token has an invalid format.
                  - The provided token is invalid.
    RitmoAgotado:
      description: La clave o la licencia han agotado su ritmo. Repite pasados los segundos de `Retry-After`.
      headers:
        Retry-After: { $ref: '#/components/headers/Retry-After' }
    SinTurno:
      description: |
        El servidor arranca, la base de datos no responde, la cola de la clave está llena (100 peticiones) o
        el turno no llegó a tiempo (30 segundos por defecto; la cabecera `X-Dinaup-Timeout-Ms` pide menos).
      headers:
        Retry-After: { $ref: '#/components/headers/Retry-After' }
  schemas:
    Variables:
      type: object
      description: Un diccionario plano con las variables, todas como texto.
      additionalProperties:
        type: [string, 'null']
    ConsultaDeInforme:
      type: object
      additionalProperties: false
      properties:
        variables: { $ref: '#/components/schemas/Variables' }
        filter:
          type: array
          items:
            type: object
            required: [field, op, value]
            properties:
              field:
                type: string
                description: |
                  El nombre de la columna (`pr_...`), un campo de sistema (`id`, `nombre`, `fecha`, `fecham`,
                  `fechaia`, `eliminado`, `posicion`), el GUID de la columna o un camino `guidDeRelacion.campo`.
              op:
                type: string
                enum: ['=', '<>', '>', '<', '>=', '<=', '*', in, en]
                description: '`*` es «contiene». `in` (o `en`) compara con varios valores, separados por `[|]`.'
              value:
                type: string
                description: Sigue el formato de su campo, igual que en las escrituras.
        order:
          type: array
          maxItems: 5
          items:
            type: object
            required: [field]
            properties:
              field: { type: string }
              desc: { type: boolean, default: false }
    PaginaDeInforme:
      type: object
      properties:
        data:
          type: array
          description: Las filas. Cada valor llega como texto.
          items:
            type: object
            additionalProperties: { type: [string, 'null'] }
        currentPage: { type: integer }
        totalPages:
          type: integer
          description: '`-1` sin recuento. `1` si el informe oculta la paginación.'
        totalResults:
          type: integer
          description: No trae el total de filas. Llega a `0`.
        files:
          type: [array, 'null']
          description: Con `withFiles=true`, los adjuntos de las filas.
          items: { $ref: '#/components/schemas/Adjunto' }
    Adjunto:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        file: { type: string }
        path: { type: string }
        extension: { type: string }
        height: { type: integer }
        width: { type: integer }
        crc: { type: string }
        sizeInBytes: { type: integer }
        compatibilityPreview: {}
        mime: { type: string }
        isImage: { type: boolean }
        url_original: { type: string }
        url_1080: { type: string }
        url_720: { type: string }
        url_300: { type: string }
        url_100: { type: string }
        url_32: { type: string }
    Registro:
      type: object
      description: |
        Los campos de un registro, cada uno por su columna (`pr_XXXXXXXXX`), con el valor como texto: decimal
        con punto (`"1234.5"`), booleano `"1"` o `"0"`, fecha y hora `yyyy-MM-dd HH:mm:ss` en UTC, fecha
        `yyyy-MM-dd`, hora `HH:mm:ss`, y una referencia como su GUID, `""` o `[campo=valor]`.
      properties:
        id:
          type: string
          description: Vacío o ausente crea el registro. Un GUID existente lo edita.
        eliminado:
          type: string
          enum: ['0', '1']
          description: '`"1"` borra el registro.'
      additionalProperties:
        type: [string, 'null']
    RegistroConLineas:
      type: object
      description: Un registro con su tabla de líneas, como una venta. `Main` y `List` van con la inicial en mayúscula.
      required: [Main, List]
      properties:
        Main: { $ref: '#/components/schemas/Registro' }
        List:
          type: array
          items: { $ref: '#/components/schemas/Registro' }
    ResultadoDeEscritura:
      type: object
      properties:
        sectionID: { type: string }
        aError:
          type: string
          description: El motivo del fallo de esa fila. Vacío si fue bien.
        description: { type: [string, 'null'] }
        dynamicDocumentResult: { type: string }
        optimized: { type: boolean }
        rowID:
          type: string
          description: El ID del registro. En un alta, el que asignó Dinaup.
        tokenID: { type: string }
        confirmed:
          type: boolean
          description: La fila se guardó.
        isAdded:
          type: boolean
          description: '`true` si se creó, `false` si se editó.'
        dateResult: { type: string, format: date-time }
