Propostas comerciais

Submeter um pedido de proposta de gestão de condomínio — um contacto de quem procura uma administração.

É o ponto que um formulário de um sítio ou um agente de atendimento usa para fazer chegar um contacto à empresa, sem passar por correio eletrónico.

Submeter um pedido de proposta

POST /proposals

Permissão · commercial:write · aceita Idempotency-Key

Quem está a pedir

Campo	Tipo	Descrição
ClientName	texto	Obrigatório. Nome de quem pede
ClientAddress	texto	Obrigatório. Morada
ClientEMail	texto	Correio eletrónico
ClientPhone	texto	Telefone
ClientMobilePhone	texto	Telemóvel
ClientDoor · ClientBlock · ClientFloor · ClientSide	texto	Porta, bloco, piso e lado
ClientPlace · ClientZipCode · ClientZipCodePlace	texto	Localidade e código postal

Pelo menos um de ClientEMail, ClientPhone ou ClientMobilePhone é obrigatório — um contacto a que ninguém consegue responder não vale a pena ser registado.

O condomínio

Campo	Tipo	Descrição
BuildingAddress	texto	Obrigatório. Morada do condomínio
BuildingDoor · BuildingPlace	texto	Porta e localidade
BuildingZipCode · BuildingZipCodePlace	texto	Código postal
BuildingTaxId	inteiro	Contribuinte do condomínio, se já tiver
BuildingYears	inteiro	Idade do edifício, em anos

O que lá existe

Campo	Tipo	Descrição
TotalHousing	inteiro	Frações de habitação
TotalStores	inteiro	Lojas
TotalGarages	inteiro	Garagens
TotalHouseStorage	inteiro	Arrecadações
TotalLifts	inteiro	Elevadores
AssistanceLiftsName	texto	Quem faz a manutenção dos elevadores
HasCondominiumRoom	booleano	Tem sala de condomínio
HasGateHouse	booleano	Tem portaria
HasGate	booleano	Tem portão
HasMaid	booleano	Tem empregada de limpeza
HasMaidCompany	booleano	A limpeza é feita por empresa
MaidCompany	texto	Qual

O contexto

Campo	Tipo	Descrição
VeryOldCondominiumDebts	texto	Dívidas antigas do condomínio
WhichLedContactCompany	texto	O que os levou a contactar
HowKnowledgeCompany	texto	Como conheceram a empresa

Pedido

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/proposals" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "ClientName": "João Pereira",
        "ClientEMail": "joao.pereira@exemplo.pt",
        "ClientMobilePhone": "912345678",
        "ClientAddress": "Rua do Comércio, 40",
        "ClientPlace": "Lisboa",
        "ClientZipCode": "1100-150",
        "BuildingAddress": "Avenida Central, 88",
        "BuildingPlace": "Lisboa",
        "BuildingZipCode": "1000-200",
        "BuildingYears": 22,
        "TotalHousing": 18,
        "TotalStores": 2,
        "TotalGarages": 18,
        "TotalLifts": 2,
        "HasCondominiumRoom": true,
        "HasGateHouse": false,
        "WhichLedContactCompany": "Insatisfação com a administração actual.",
        "HowKnowledgeCompany": "Recomendação de um conhecido."
      }'

Resposta · 201

{ "Reference": "2026/PR/114" }

A referência que a numeração lhe deu. É por ela que a proposta passa a ser conhecida em qualquer conversa sobre o assunto — guarde-a e apresente-a a quem submeteu.

A proposta não se lê de volta

Não há ponto para consultar ou acompanhar uma proposta submetida. O seguimento é feito no backoffice pela equipa comercial: orçamentação, aprovação e plano de negócio ficam do lado deles.

Só o preenchimento inicial vem de fora — quem envia um contacto não define o preço dele.

Erros

Estado	Código	Quando
400	INVALID_BODY	Corpo em falta ou JSON inválido
400	MISSING_FIELD	Falta ClientName, ClientAddress, BuildingAddress, ou qualquer forma de contacto
401	INVALID_KEY · KEY_REVOKED · KEY_EXPIRED	Ver Autenticação
403	FORBIDDEN_SCOPE	A credencial não tem commercial:write
409	IDEMPOTENCY_KEY_REUSED	A chave já foi usada noutro pedido
422	PROPOSAL_NOT_CREATED	Não chegou a ser registada. Reporte

Use chave de idempotência num formulário público

Um visitante que carregue duas vezes no botão, ou uma repetição depois de um tempo esgotado, cria dois contactos iguais na lista da equipa comercial. Uma chave por submissão evita isso. Ver Idempotência.