{
 "openapi": "3.1.0",
 "info": {
  "title": "Fossas Sépticas Santarém — 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 Santarém. Obrigatórios: nome, email, telefone, concelho, servico, consent. Respondemos por email em até 2 dias úteis. Só envie depois de a pessoa autorizar o tratamento dos dados. Documentação: https://fossasepticasantarem.pt/para-agentes/. Servidor MCP: https://fossasepticasantarem.pt/mcp.",
  "contact": {
   "name": "Fossas Sépticas Santarém",
   "email": "ola@fossasepticasantarem.pt",
   "url": "https://fossasepticasantarem.pt/para-agentes/"
  }
 },
 "servers": [
  {
   "url": "https://fossasepticasantarem.pt"
  }
 ],
 "externalDocs": {
  "description": "Para agentes de IA",
  "url": "https://fossasepticasantarem.pt/para-agentes/"
 },
 "paths": {
  "/api/orcamento": {
   "get": {
    "operationId": "descreverApi",
    "summary": "Campos, serviços, concelhos e opções aceites",
    "responses": {
     "200": {
      "description": "Descrição da API"
     }
    }
   },
   "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": "Valida sem guardar nem enviar."
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "nome",
         "email",
         "telefone",
         "concelho",
         "servico",
         "consent"
        ],
        "additionalProperties": false,
        "properties": {
         "nome": {
          "type": "string",
          "minLength": 2,
          "maxLength": 100
         },
         "email": {
          "type": "string",
          "minLength": 5,
          "maxLength": 254,
          "format": "email",
          "description": "Obrigatório. Respondemos para este email."
         },
         "telefone": {
          "type": "string",
          "minLength": 9,
          "maxLength": 20,
          "description": "Obrigatório. Telefone português com 9 dígitos, com ou sem +351."
         },
         "concelho": {
          "type": "string",
          "enum": [
           "Abrantes",
           "Alcanena",
           "Almeirim",
           "Alpiarça",
           "Benavente",
           "Cartaxo",
           "Chamusca",
           "Constância",
           "Coruche",
           "Entroncamento",
           "Ferreira do Zêzere",
           "Golegã",
           "Mação",
           "Ourém",
           "Rio Maior",
           "Salvaterra de Magos",
           "Santarém",
           "Sardoal",
           "Tomar",
           "Torres Novas",
           "Vila Nova da Barquinha"
          ],
          "description": "Concelho do distrito de Santarém. Aceita também o campo localidade com o nome do concelho no texto."
         },
         "localidade": {
          "type": "string",
          "maxLength": 80
         },
         "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",
           "nova",
           "substituir",
           "etar",
           "limpeza",
           "nao-sei"
          ],
          "description": "Valor ou slug do serviço."
         },
         "imovel": {
          "type": "string",
          "enum": [
           "Moradia de habitação própria",
           "2.ª habitação",
           "Ruína 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"
          ]
         },
         "licenca": {
          "type": "string",
          "enum": [
           "Já tenho projeto aprovado",
           "Em curso",
           "Ainda não",
           "Não sei"
          ]
         },
         "rede_esgoto": {
          "type": "string",
          "enum": [
           "Sim",
           "Não",
           "Não sei"
          ]
         },
         "mensagem": {
          "type": "string",
          "maxLength": 2000
         },
         "consent": {
          "type": "boolean",
          "const": true,
          "description": "Tem de ser true, dado pela pessoa a quem o pedido diz respeito."
         },
         "submetido_por": {
          "type": "string",
          "enum": [
           "agente"
          ]
         },
         "nome_do_agente": {
          "type": "string",
          "maxLength": 60
         },
         "agente": {
          "type": "string",
          "maxLength": 60
         },
         "dry_run": {
          "type": "boolean",
          "default": false
         }
        }
       },
       "example": {
        "nome": "Ana Silva",
        "email": "ana@example.com",
        "telefone": "960000000",
        "concelho": "Abrantes",
        "servico": "Fossa séptica nova",
        "consent": true
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Pedido registado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "referencia": {
           "type": [
            "string",
            "null"
           ]
          },
          "estado": {
           "type": "string"
          },
          "prazo_resposta": {
           "type": "string"
          },
          "mensagem": {
           "type": "string"
          },
          "email": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "200": {
      "description": "Validação (dry-run), pré-visualização ou pedido duplicado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "referencia": {
           "type": [
            "string",
            "null"
           ]
          },
          "estado": {
           "type": "string"
          },
          "prazo_resposta": {
           "type": "string"
          },
          "mensagem": {
           "type": "string"
          },
          "email": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "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"
     },
     "502": {
      "description": "Falha ao registar o pedido"
     },
     "503": {
      "description": "Limite diário de pedidos automáticos"
     }
    }
   }
  }
 }
}