{
  "openapi": "3.1.0",
  "info": {
    "title": "Fossa Séptica Braga — pedido de orçamento",
    "version": "1.0.0",
    "summary": "Pedir um orçamento gratuito de fossa séptica, fossa estanque ou ETAR compacta por JSON.",
    "description": "API pública para agentes de IA e integrações pedirem orçamento no distrito de Braga. O email é obrigatório. Respondemos por email em até 2 dias úteis. Só envie depois de a pessoa autorizar o tratamento dos dados. Documentação: https://fossasepticabraga.pt/para-agentes/. Servidor MCP: https://fossasepticabraga.pt/mcp.",
    "contact": {
      "name": "Fossa Séptica Braga",
      "email": "ola@fossasepticabraga.pt",
      "url": "https://fossasepticabraga.pt/para-agentes/"
    }
  },
  "servers": [
    {
      "url": "https://fossasepticabraga.pt"
    }
  ],
  "externalDocs": {
    "description": "Para agentes de IA",
    "url": "https://fossasepticabraga.pt/para-agentes/"
  },
  "paths": {
    "/api/orcamento": {
      "get": {
        "operationId": "descreverApi",
        "summary": "Descrição resumida da API",
        "responses": {
          "200": {
            "description": "Campos e valores aceites"
          }
        }
      },
      "post": {
        "operationId": "pedirOrcamento",
        "summary": "Criar um pedido de orçamento",
        "parameters": [
          {
            "name": "X-Dry-Run",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Só valida; nada é guardado nem enviado."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "nome",
                  "email",
                  "concelho",
                  "servico",
                  "consentimento_rgpd"
                ],
                "additionalProperties": false,
                "properties": {
                  "nome": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254,
                    "description": "Obrigatório. Respondemos para este email."
                  },
                  "telefone": {
                    "type": "string",
                    "maxLength": 20,
                    "description": "Opcional. Telefone português com 9 dígitos."
                  },
                  "concelho": {
                    "type": "string",
                    "enum": [
                      "Amares",
                      "Barcelos",
                      "Braga",
                      "Cabeceiras de Basto",
                      "Celorico de Basto",
                      "Esposende",
                      "Fafe",
                      "Guimarães",
                      "Póvoa de Lanhoso",
                      "Terras de Bouro",
                      "Vieira do Minho",
                      "Vila Nova de Famalicão",
                      "Vila Verde",
                      "Vizela"
                    ]
                  },
                  "freguesia": {
                    "type": "string",
                    "maxLength": 80
                  },
                  "servico": {
                    "type": "string",
                    "enum": [
                      "Fossa séptica nova",
                      "Substituir fossa antiga",
                      "ETAR compacta",
                      "Limpeza ou esvaziamento de fossa",
                      "Não sei"
                    ]
                  },
                  "imovel": {
                    "type": "string",
                    "enum": [
                      "Moradia de habitação própria",
                      "2.ª habitação",
                      "Casa antiga a recuperar",
                      "Turismo rural ou AL",
                      "Exploração agrícola",
                      "Terreno ainda sem casa"
                    ]
                  },
                  "pessoas": {
                    "type": "string",
                    "enum": [
                      "1–2",
                      "3–4",
                      "5–6",
                      "7–10",
                      "Mais de 10"
                    ]
                  },
                  "prazo": {
                    "type": "string",
                    "enum": [
                      "Menos de 1 mês",
                      "1–3 meses",
                      "3–6 meses",
                      "Mais de 6 meses"
                    ]
                  },
                  "rede_esgoto": {
                    "type": "string",
                    "enum": [
                      "Sim",
                      "Não",
                      "Não sei"
                    ]
                  },
                  "mensagem": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "consentimento_rgpd": {
                    "type": "boolean",
                    "const": true,
                    "description": "Tem de ser true, dado pela pessoa a quem o pedido diz respeito."
                  },
                  "consentimento_marketing": {
                    "type": "boolean",
                    "default": false
                  },
                  "origem": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "agente": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "dry_run": {
                    "type": "boolean",
                    "default": false
                  }
                }
              },
              "example": {
                "nome": "Ana Silva",
                "email": "ana@example.com",
                "concelho": "Vila Verde",
                "servico": "Fossa séptica nova",
                "pessoas": "3–4",
                "consentimento_rgpd": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pedido registado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "referencia": {
                      "type": "string"
                    },
                    "estado": {
                      "type": "string"
                    },
                    "prazo_resposta_horas": {
                      "type": "integer"
                    },
                    "mensagem": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Validação (dry-run), pré-visualização ou pedido duplicado"
          },
          "400": {
            "description": "JSON inválido"
          },
          "413": {
            "description": "Corpo maior que 8192 bytes"
          },
          "415": {
            "description": "Content-Type não é application/json"
          },
          "422": {
            "description": "Dados inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "erro": {
                      "type": "string",
                      "const": "validacao"
                    },
                    "mensagem": {
                      "type": "string"
                    },
                    "detalhes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "campo": {
                            "type": "string"
                          },
                          "mensagem": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Demasiados pedidos deste endereço"
          },
          "503": {
            "description": "Limite diário de pedidos automáticos"
          }
        }
      }
    }
  }
}