openapi: 3.1.0
info:
  title: Nexa Interiores - Public & Agent API
  version: 1.0.0
  description: API pública, documentação e especificações de ferramentas (function calling) da Nexa Interiores. Permite consultar catálogo de mobiliário de luxo, dados do showroom em Ribeirão Preto, agendamento de curadoria de interiores gratuita e serviços de inteligência visual para arquitetura.
  contact:
    name: Suporte Técnico e Agentes Nexa Interiores
    email: contato@nexainteriores.com.br
    url: https://nexainteriores.com.br
  license:
    name: Proprietary
    url: https://nexainteriores.com.br/privacy
servers:
  - url: https://nexainteriores.com.br
    description: Servidor de Produção Oficial
paths:
  /api/store-info:
    get:
      operationId: getStoreInfo
      summary: Obter informações institucionais, showroom e contatos da Nexa Interiores
      description: Retorna os dados canônicos da loja (NAP), endereço físico no Jardim Botânico em Ribeirão Preto, horário de funcionamento, telefones e canais oficiais de atendimento.
      responses:
        '200':
          description: Dados cadastrais e de localização retornados com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreInfoResponse'
        '500':
          description: Erro interno ao consultar dados da loja.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/collections:
    get:
      operationId: listCollections
      summary: Listar coleções e categorias de móveis de alto padrão
      description: Retorna as categorias de produtos trabalhadas pela Nexa Interiores (Sofás de Alto Padrão, Poltronas de Design, Salas de Jantar de Luxo e Decoração Exclusiva).
      responses:
        '200':
          description: Lista de categorias retornada com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsResponse'
        '500':
          description: Erro interno ao listar coleções.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/curation/request:
    post:
      operationId: requestCuration
      summary: Solicitar agendamento de Curadoria de Interiores Gratuita
      description: Registra uma solicitação de curadoria de interiores sem custo para dimensionamento e harmonização de mobiliário com especialistas da Nexa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CurationBookingRequest'
      responses:
        '200':
          description: Solicitação recebida com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurationBookingResponse'
        '400':
          description: Dados da requisição inválidos ou campos obrigatórios ausentes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Erro interno ao processar agendamento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: O recurso solicitado não foi encontrado.
            hint:
              type: string
              example: Consulte a especificação OpenAPI em /openapi.json ou a documentação em /docs.
            status:
              type: integer
              example: 404
    StoreInfoResponse:
      type: object
      required:
        - name
        - brand
        - address
        - phone
        - email
        - openingHours
        - whatsappUrl
      properties:
        name:
          type: string
          example: Nexa Interiores
        brand:
          type: string
          example: Mobiliário de Alto Padrão e Curadoria Gratuita
        address:
          type: object
          required:
            - street
            - number
            - neighborhood
            - city
            - state
            - postalCode
            - country
          properties:
            street:
              type: string
              example: Av. Norma Valério Corrêa
            number:
              type: string
              example: '316'
            neighborhood:
              type: string
              example: Jardim Botânico
            city:
              type: string
              example: Ribeirão Preto
            state:
              type: string
              example: SP
            postalCode:
              type: string
              example: 14021-614
            country:
              type: string
              example: Brasil
        phone:
          type: string
          example: '+5516997908686'
        email:
          type: string
          example: contato@nexainteriores.com.br
        whatsappUrl:
          type: string
          example: https://wa.me/5516997908686
        openingHours:
          type: object
          required:
            - weekdays
            - saturday
            - sunday
          properties:
            weekdays:
              type: string
              example: 09:00 - 19:00
            saturday:
              type: string
              example: 09:00 - 13:00
            sunday:
              type: string
              example: Fechado (Atendimento sob agendamento)
        coordinates:
          type: object
          required:
            - latitude
            - longitude
          properties:
            latitude:
              type: number
              example: -21.215317
            longitude:
              type: number
              example: -47.803685
    CollectionsResponse:
      type: object
      required:
        - categories
      properties:
        categories:
          type: array
          items:
            type: object
            required:
              - id
              - name
              - description
            properties:
              id:
                type: string
                example: sofas
              name:
                type: string
                example: Sofás de Alto Padrão
              description:
                type: string
                example: Sofás modulares e living com acabamento em linhos nobres e couros legítimos.
    CurationBookingRequest:
      type: object
      required:
        - customerName
        - customerPhone
      properties:
        customerName:
          type: string
          example: Mariana Souza
        customerPhone:
          type: string
          example: '+5516999998888'
        city:
          type: string
          example: Ribeirão Preto
        roomType:
          type: string
          example: Living integrado
    CurationBookingResponse:
      type: object
      required:
        - status
        - message
        - whatsappDirectLink
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Solicitação recebida com sucesso.
        whatsappDirectLink:
          type: string
          example: https://wa.me/5516997908686