openapi: 3.1.0
info:
  title: Notaí - Emissão de Nota Fiscal via WhatsApp
  description: |
    API da plataforma Notaí para emissão automatizada de Notas Fiscais de Serviço Eletrônicas (NFS-e) via WhatsApp.
    
    ## Sobre o Notaí
    O Notaí é uma plataforma brasileira SaaS que permite a emissão de notas fiscais de serviço diretamente pelo WhatsApp, 
    utilizando inteligência artificial para automatizar todo o processo.
    
    ## Como Funciona
    1. O usuário envia os dados da nota pelo WhatsApp
    2. A IA processa automaticamente as informações
    3. A nota fiscal é emitida e enviada ao cliente
    
    ## Público-Alvo
    - MEI (Microempreendedor Individual)
    - Prestadores de serviço autônomos
    - Profissionais liberais
    - Micro e pequenas empresas
    - Contadores e escritórios de contabilidade
    
    ## Contato
    - WhatsApp Suporte: (11) 99675-4495
    - WhatsApp Emissão: (11) 99785-2477
    - Email: contato@suanotai.com.br
  version: 1.0.0
  contact:
    name: Suporte Notaí
    email: contato@suanotai.com.br
    url: https://suanotai.com.br
  license:
    name: Proprietário
    url: https://suanotai.com.br/termos
  x-logo:
    url: https://suanotai.com.br/lovable-uploads/4455ec13-5c43-4783-97fd-76a9e7618370.webp
    altText: Notaí Logo

servers:
  - url: https://suanotai.com.br
    description: Produção

tags:
  - name: Notas Fiscais
    description: Operações relacionadas à emissão de notas fiscais
  - name: Empresas
    description: Gestão de empresas e cadastros
  - name: Planos
    description: Informações sobre planos e assinaturas

paths:
  /api/emitir-nota:
    post:
      tags:
        - Notas Fiscais
      summary: Emitir Nota Fiscal de Serviço
      description: |
        Emite uma nota fiscal de serviço eletrônica (NFS-e) para o cliente.
        Esta operação é realizada automaticamente via WhatsApp com IA.
      operationId: emitirNota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotaFiscalRequest'
      responses:
        '200':
          description: Nota fiscal emitida com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotaFiscalResponse'
        '400':
          description: Dados inválidos
        '401':
          description: Não autorizado
        '429':
          description: Limite de notas atingido

  /api/consultar-nota:
    get:
      tags:
        - Notas Fiscais
      summary: Consultar Nota Fiscal
      description: Consulta o status e detalhes de uma nota fiscal emitida
      operationId: consultarNota
      parameters:
        - name: numero_nota
          in: query
          required: true
          schema:
            type: string
          description: Número da nota fiscal
      responses:
        '200':
          description: Detalhes da nota fiscal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotaFiscalResponse'
        '404':
          description: Nota não encontrada

  /api/planos:
    get:
      tags:
        - Planos
      summary: Listar Planos Disponíveis
      description: Retorna a lista de planos e preços disponíveis
      operationId: listarPlanos
      responses:
        '200':
          description: Lista de planos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plano'

components:
  schemas:
    NotaFiscalRequest:
      type: object
      required:
        - cliente_nome
        - cliente_documento
        - valor
        - descricao_servico
      properties:
        cliente_nome:
          type: string
          description: Nome completo do cliente
          example: "João da Silva"
        cliente_documento:
          type: string
          description: CPF ou CNPJ do cliente
          example: "123.456.789-00"
        cliente_email:
          type: string
          format: email
          description: Email do cliente para envio da nota
          example: "cliente@email.com"
        valor:
          type: number
          format: float
          description: Valor do serviço em reais
          example: 1500.00
        descricao_servico:
          type: string
          description: Descrição do serviço prestado
          example: "Consultoria em marketing digital"

    NotaFiscalResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID único da nota fiscal
        numero_nota:
          type: string
          description: Número oficial da nota fiscal
        status:
          type: string
          enum: [pendente, emitida, cancelada, erro]
          description: Status da nota fiscal
        data_emissao:
          type: string
          format: date-time
          description: Data e hora da emissão
        pdf_url:
          type: string
          format: uri
          description: URL para download do PDF da nota
        xml_url:
          type: string
          format: uri
          description: URL para download do XML da nota
        cliente:
          type: object
          properties:
            nome:
              type: string
            documento:
              type: string
        valor:
          type: number
          format: float
        descricao:
          type: string

    Plano:
      type: object
      properties:
        nome:
          type: string
          description: Nome do plano
          example: "Starter"
        limite_notas:
          type: integer
          description: Quantidade de notas incluídas por mês
          example: 50
        preco_mensal:
          type: number
          format: float
          description: Preço mensal em reais
          example: 97.00
        preco_anual:
          type: number
          format: float
          description: Preço anual em reais
          example: 970.00
        preco_nota_extra:
          type: number
          format: float
          description: Preço por nota extra
          example: 2.50
        recursos:
          type: array
          items:
            type: string
          description: Lista de recursos incluídos
          example:
            - "Emissão via WhatsApp"
            - "Dashboard completo"
            - "Suporte por email"

    Empresa:
      type: object
      properties:
        id:
          type: string
          format: uuid
        cnpj:
          type: string
          description: CNPJ da empresa
          example: "12.345.678/0001-90"
        razao_social:
          type: string
          description: Razão social da empresa
        inscricao_municipal:
          type: string
          description: Inscrição municipal
        cidade:
          type: string
          description: Cidade da empresa
        estado:
          type: string
          description: Estado (UF) da empresa
          example: "SP"
        plano:
          type: string
          description: Plano atual da empresa
        notas_emitidas:
          type: integer
          description: Total de notas emitidas no mês
        limite_notas:
          type: integer
          description: Limite de notas do plano

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtido após autenticação

security:
  - bearerAuth: []

externalDocs:
  description: Documentação completa do Notaí
  url: https://suanotai.com.br/blog
