openapi: 3.1.0
info:
  title: OrçaZap API
  version: 0.1.0
  description: |
    API do OrçaZap — orçamento automático de serviço pelo WhatsApp.

    Gera um orçamento formatado a partir da descrição (texto) do serviço,
    retornando itens (material e mão de obra), valores individuais, valor total,
    prazo sugerido e condição de pagamento. Foco em prestadores de serviço
    brasileiros (pedreiro, eletricista, pintor, etc.).

    ## Estado (julho/2026)
    Este contrato descreve a API pretendida. O endpoint `/orcamento` será
    disponibilizado quando o backend do OrçaZap estiver no ar. Até lá, a forma
    de gerar um orçamento é pelo WhatsApp (+55 21 95941-3223).

    ## Integração com agentes de IA
    Este OpenAPI pode ser usado para criar Custom GPTs (Actions), ferramentas
    de function-calling ou servidores MCP que geram orçamentos via o OrçaZap.
  contact:
    name: Thales Corp
    url: https://orcazap.pages.dev/
servers:
  - url: https://orcazap.pages.dev
    description: Produção (a definir quando backend ativo)
paths:
  /orcamento:
    post:
      summary: Gera um orçamento de serviço
      description: |
        Recebe a descrição de um serviço (em texto, como o prestador falaria)
        e retorna um orçamento estruturado com itens, valores e total.
        Opcionalmente aceita áudio em base64 (equivalente ao áudio do WhatsApp).
      operationId: gerarOrcamento
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - descricao
              properties:
                descricao:
                  type: string
                  description: Descrição do serviço em linguagem natural (como o prestador falaria no WhatsApp).
                  example: "Cliente quer pintar dois quartos, massa corrida e duas demãos."
                profissao:
                  type: string
                  description: Profissão/prestador (ajuda a refinar o orçamento).
                  enum: [pedreiro, eletricista, pintor, gesseiro, encanador, marceneiro, serralheiro, dedetizador, chaveiro, tecnico-refrigeracao, montador, frete-e-mudanca, diarista, jardineiro]
                  example: pintor
                regiao:
                  type: string
                  description: Cidade/estado (opcional, para refletir preços locais).
                  example: "Rio de Janeiro, RJ"
                nome_prestador:
                  type: string
                  description: Nome do prestador (entra no orçamento final).
                  example: "JR Reformas"
      responses:
        '200':
          description: Orçamento gerado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  servico:
                    type: string
                    description: Descrição resumida do serviço.
                  itens:
                    type: array
                    items:
                      type: object
                      properties:
                        descricao:
                          type: string
                        valor:
                          type: number
                          format: float
                  total:
                    type: number
                    format: float
                  prazo_sugerido:
                    type: string
                  condicao_pagamento:
                    type: string
                  prestador:
                    type: string
              example:
                servico: "Pintura de dois quartos (massa corrida + duas demãos)"
                itens:
                  - { descricao: "Massa corrida (preparo das paredes)", valor: 350.00 }
                  - { descricao: "Tinta acrílica - duas demãos (2 quartos)", valor: 600.00 }
                  - { descricao: "Mão de obra", valor: 800.00 }
                total: 1750.00
                prazo_sugerido: "3 dias"
                condicao_pagamento: "50% início, 50% entrega"
                prestador: "JR Reformas"
        '400':
          description: Requisição inválida (descrição ausente).
        '429':
          description: Limite de requisições excedido.
        '501':
          description: Endpoint ainda não implementado (usar WhatsApp até o backend ficar pronto).