openapi: 3.0.3
info:
  title: dog-go-go API (núcleo)
  version: 1.0.0
servers:
  - url: /
paths:
  /healthz:
    get:
      summary: Liveness
      responses:
        '200':
          description: OK
  /healthz/db:
    get:
      summary: PostgreSQL
      responses:
        '200':
          description: Conectado
        '503':
          description: Error de conexión
  /api/auth/register:
    post:
      summary: Registro (crea clínica si no envías clinicId)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string }
                password: { type: string }
                clinicName: { type: string }
                clinicId: { type: string }
      responses:
        '201': { description: Creado }
  /api/auth/login:
    post:
      summary: Login JWT
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string }
                password: { type: string }
      responses:
        '200': { description: token }
  /api/me:
    get:
      summary: Usuario actual
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Perfil }
  /api/patients:
    get:
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Lista }
    post:
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/reports/summary:
    get:
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: 'Conteos, revenue y desglose por estado' }
  /api/reports/export/patients.csv:
    get:
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: CSV pacientes
          content:
            text/csv:
              schema:
                type: string
  /api/reports/export/appointments.csv:
    get:
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: CSV citas
          content:
            text/csv:
              schema:
                type: string
  /api/reports/export/invoices.csv:
    get:
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: CSV facturas
          content:
            text/csv:
              schema:
                type: string
  /api/invoices/{id}:
    get:
      summary: Factura con líneas de detalle
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Factura }
        '404': { description: No encontrada }
  /api/invoices/{id}/items:
    post:
      summary: Añadir concepto a factura (recalcula importe total)
      security: [{ bearerAuth: [] }]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [description, lineAmount]
              properties:
                description: { type: string }
                lineAmount: { type: string }
                amount: { type: string }
                price: { type: number }
      responses:
        '201': { description: Factura actualizada con ítems }
        '404': { description: No encontrada }
  /api/catalog/products:
    get:
      summary: Lista catálogo (tienda)
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Productos }
    post:
      summary: Alta producto catálogo
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/catalog/products/{id}:
    patch:
      summary: Actualizar producto
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
    delete:
      summary: Baja producto
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: Sin cuerpo }
  /api/shop/orders:
    get:
      summary: Pedidos tienda
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: Lista }
    post:
      summary: Crear pedido borrador
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/shop/orders/{id}:
    get:
      summary: Pedido con líneas
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
    patch:
      summary: Cambiar estado / notas
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/shop/orders/{id}/items:
    post:
      summary: Línea de pedido (recalcula total)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Pedido actualizado }
  /api/clinical/patients/{patientId}/vaccinations:
    get:
      summary: Historial vacunas del paciente
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Lista }
    post:
      summary: Registrar vacuna (VET|ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/providers/{id}/verification:
    patch:
      summary: Estado verificación partner (ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/modules:
    get:
      summary: Vet360 — módulos y flags por clínica
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: OK }
        '401': { description: Sin JWT }
  /api/v360/patients/{patientId}/timeline:
    get:
      summary: Línea de tiempo unificada (módulo emr)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
        '403': { description: module_disabled }
        '404': { description: not_found }
  /api/v360/patients/{patientId}/procedures:
    post:
      summary: Alta procedimiento / cirugía (emr; VET|ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
        '403': { description: Forbidden }
  /api/v360/domain-events:
    get:
      summary: Eventos de dominio (módulo events; ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: limit, in: query, schema: { type: integer } }
      responses:
        '200': { description: Lista DomainEvent }
  /api/v360/vaccine-protocols:
    get:
      summary: Protocolos de vacunación (módulo vaccines)
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: OK }
    post:
      summary: Crear protocolo (VET|ADMIN)
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/v360/patients/{patientId}/vaccines/generate-schedule:
    post:
      summary: Generar eventos programados (VET|ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: created }
        '400': { description: birthDate requerida }
  /api/v360/patients/{patientId}/vaccines/scheduled:
    get:
      summary: Vacunas programadas
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/crm/messages:
    get:
      summary: Cola CRM
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: OK }
  /api/v360/crm/automation-rules:
    get:
      summary: Reglas de automatización
      security: [{ bearerAuth: [] }]
      responses:
        '200': { description: OK }
    post:
      summary: Crear regla (ADMIN)
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/v360/crm/messages/{id}/sent:
    patch:
      summary: Marcar mensaje como enviado
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/patients/{patientId}/grooming/sessions:
    get:
      summary: Sesiones grooming
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
    post:
      summary: Nueva sesión (VET|ADMIN|RECEPTION)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/v360/walker/kyc:
    post:
      summary: Alta/actualización KYC paseador
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: OK }
  /api/v360/walker/kyc/{providerId}:
    patch:
      summary: Revisión KYC (ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: providerId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/walker/ratings:
    post:
      summary: Valoración paseador
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/v360/patients/{patientId}/walker/jobs:
    post:
      summary: Crear trabajo de paseo
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/v360/walker/jobs/{jobId}:
    patch:
      summary: Actualizar trabajo (estado, paseador)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: jobId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/walker/pings:
    post:
      summary: Ping geolocalización
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/v360/walker/{walkerProviderId}/pings:
    get:
      summary: Historial pings por paseador
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: walkerProviderId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/patients/{patientId}/hospital/stays:
    get:
      summary: Estancias hospitalarias
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
    post:
      summary: Nueva estancia (VET|ADMIN|RECEPTION)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/v360/hospital/stays/{stayId}/updates:
    post:
      summary: Actualización de estancia
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: stayId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/v360/hospital/stays/{stayId}/close:
    patch:
      summary: Cerrar estancia
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: stayId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/patients/{patientId}/imaging/studies:
    get:
      summary: Estudios de imagen (referencias)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
    post:
      summary: Registrar estudio (VET|ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/v360/billing/external-links:
    post:
      summary: Enlazar factura con sistema externo (FiscalTech)
      security: [{ bearerAuth: [] }]
      responses:
        '201': { description: Creado }
  /api/v360/billing/invoices/{invoiceId}/external-link:
    get:
      summary: Enlace externo por factura
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: invoiceId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
  /api/v360/patients/{patientId}/shop/subscriptions:
    get:
      summary: Suscripciones tienda del paciente
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
    post:
      summary: Crear suscripción
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: patientId, in: path, required: true, schema: { type: string } }
      responses:
        '201': { description: Creado }
  /api/v360/shop/subscriptions/{subscriptionId}/emit-renewal-due:
    post:
      summary: Emitir evento de renovación (prueba; ADMIN)
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: subscriptionId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT