Guia de Integração - API de Cotação Automatizada

Bem-vindo ao guia de integração da API de Cotação. Este documento fornece todas as informações necessárias para que sistemas de terceiros possam enviar solicitações de cotação de seguros para processamento automático via Playwright.

🔗 Visão Geral

A API atua como um gatilho para um robô de automação (worker). Ao receber uma requisição válida, o sistema:

1. Valida a estrutura dos dados.
2. Armazena as informações para processamento.
3. Inicia imediatamente o robô que realizará o preenchimento no portal de seguros.

🛠 Especificação Técnica

Endpoint de Cotação

• URL Base: http://[DOMINIO_OU_IP]:3000
• Método: POST
• Caminho: /cotacao
• Content-Type: application/json

📋 Estrutura do JSON (Payload)

Abaixo estão detalhados os campos obrigatórios para uma requisição bem-sucedida:

👤 Objeto: segurado

Campo	Tipo	Descrição
cpf	String (Numeric)	CPF do segurado (Apenas números).
nomeSocial	String	Nome completo ou social do segurado.
telefone	String (Numeric)	Telefone com DDD (Apenas números).
email	String	E-mail válido do segurado.
cep	String (Numeric)	CEP de residência (Apenas números).
nome	String (Opcional)	Nome do segurado. Pode ser autopreenchido pela busca do CPF no portal.
sexo	String (Opcional)	"Masculino" ou "Feminino". O validator aceita maiúsculas/minúsculas indistintamente.
estadoCivil	String (Opcional)	Valores aceitos: Solteiro(a), Casado(a), Viúvo(a), Divorciado(a), Separado(a), União estável. O validator é tolerante a maiúsculas/minúsculas e acentos.

🛡 Objeto: seguro

Campo	Tipo	Descrição
tipo	String	Valores aceitos: Seguro novo, Renovação com nossa corretora, Renovação de outra corretora. O validator é tolerante a maiúsculas/minúsculas e acentos. Para ambas as opções de Renovação, o conjunto de campos exigidos é o mesmo (ver linhas seguradoraAnterior, apoliceAnterior, etc. abaixo — Regra 8).
nomeHierarquico	String (Opcional)	Nome do corretor ou responsável. Se omitido, o padrão aplicado é "Diego Gervasio".
seguradorasDisponiveis	Array de String (Opcional)	Lista de seguradoras a cotar. Quando informado, a automação mantém selecionadas as seguradoras enviadas e desmarca as demais. Se não informado, mantém o padrão do portal. Valores aceitos (case/acento-insensível) — 12 canônicos e 5 aliases: Canônicos: aliro, allianz, azul, bradesco, hdi seguros, hdi seguros fit, hdi seguros basico, mapfre, porto, suhai, tokio, yelum. Aliases: hdi → hdi seguros; hdi fit → hdi seguros fit; hdi basico / hdi basicos / hdi seguros basicos → hdi seguros basico. Qualquer outro valor é rejeitado com VALIDATION_ERROR (HTTP 422).
seguradoraAnterior	String	Obrigatório para Renovação. Nome da seguradora anterior.
sucursalAnterior	String	Obrigatório para Renovação quando seguro.seguradorasDisponiveis não for enviado, ou quando seguro.seguradorasDisponiveis incluir bradesco, ou quando seguro.seguradoraAnterior contiver porto. Caso contrário, não envie (a API rejeita).
apoliceAnterior	String	Obrigatório para Renovação. Número da apólice anterior.
coberturaAnterior	String	Obrigatório para Renovação. Cobertura da apólice anterior.
statusApoliceAnterior	String	Obrigatório para Renovação. Status da apólice anterior.
inicioVigenciaAnterior	String	Obrigatório para Renovação. Data de início de vigência da apólice anterior.
fimVigenciaAnterior	String	Obrigatório para Renovação quando seguro.seguradorasDisponiveis não for enviado. Quando seguro.seguradorasDisponiveis for enviado, passa a ser opcional.
renovacaoMesmoVeiculo	String	Obrigatório para Renovação quando seguro.seguradorasDisponiveis não for enviado. Quando seguro.seguradorasDisponiveis for enviado, passa a ser opcional.
renovacaoInclusaoCasco	String	Obrigatório para Renovação quando seguro.seguradorasDisponiveis não for enviado. Quando seguro.seguradorasDisponiveis for enviado, passa a ser opcional. Quando enviado, só é aceito quando seguro.seguradorasDisponiveis incluir yelum, mapfre ou aliro, ou quando seguro.seguradorasDisponiveis não for informado.
itemApoliceAnterior	String	(Opcional) Item da apólice anterior.
qtdSinistrosParcialAnterior	String	(Opcional) Quantidade de sinistros de perda parcial na apólice anterior.
ciApoliceAnterior	String	(Opcional) C.I. da apólice anterior.
classeBonusAnterior	String	(Opcional) Classe de bônus da apólice anterior.
comissaoApoliceAnterior	String (Opcional)	Comissão da apólice anterior (campo Padrao2000_Cobertura7045 do portal). Aparece nas opções de Renovação. O portal o renderiza desabilitado por padrão (habilitado apenas em certas combinações de seguradora) — se estiver indisponível, invisível ou desabilitado, a automação ignora e registra no log, sem falhar.
bonusRenovacaoTodasSeguradoras	String	Obrigatório para Renovação. "Sim" ou "Não" para bônus aplicado em todas as seguradoras.
bonusAllianz	String	(Opcional) Classe de bônus Allianz. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir allianz (a API rejeita caso contrário).
bonusSuhai	String	(Opcional) Classe de bônus Suhai. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir suhai (a API rejeita caso contrário).
bonusPortoAzulItau	String	(Opcional) Classe de bônus Porto/Azul/Itau. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir porto ou azul (a API rejeita caso contrário).
bonusMapfre	String	(Opcional) Classe de bônus Mapfre. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir mapfre (a API rejeita caso contrário).
bonusTokio	String	(Opcional) Classe de bônus Tokio. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir tokio (a API rejeita caso contrário).
bonusHdi	String	(Opcional) Classe de bônus HDI. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir qualquer HDI (hdi seguros, hdi seguros fit, hdi seguros basico) (a API rejeita caso contrário).
bonusBradesco	String	(Opcional) Classe de bônus Bradesco. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir bradesco (a API rejeita caso contrário).
bonusYelumAliroIndiana	String	(Opcional) Classe de bônus Yelum/Aliro/Indiana. Se seguro.seguradorasDisponiveis for enviado, só envie quando incluir yelum ou aliro (a API rejeita caso contrário).

🚗 Objeto: veiculo

Campo	Tipo	Descrição
placa	String	Placa do veículo (ex: ABC1D23).
chassiRemarcado	String	"Sim" ou "Não".
financiado	String	"Sim" ou "Não".
alienacaoFiduciaria	String (Opcional)	Texto da alienação fiduciária (ex.: nome da financeira). Usar apenas quando financiado for "Sim" (a API rejeita caso contrário). Se o portal não exibir este campo, a automação ignora e registra no log.
antifurto	String	Valores: "Alarme Sonoro", "Bloqueador", "Rastreador", "Dispositivos comuns", "Não".
alarmeSonoroAllianz	String (Opcional)	Ex: "Corta Combustível - RF-ST2001". Usar apenas quando antifurto for "Alarme Sonoro" (a API rejeita caso contrário).
bloqueadorAllianz	String (Opcional)	Ex: "CAR SYSTEM - Bloqueador". Texto da opção de bloqueador para Allianz. Usar apenas quando antifurto for "Bloqueador" (a API rejeita caso contrário).
bloqueadorBradescoSeguros	String (Opcional)	Ex: "Cielocel GSM/GPRS Gs8". Texto da opção de bloqueador para Bradesco Seguros. Usar apenas quando antifurto for "Bloqueador" (a API rejeita caso contrário).
bloqueadorYelum	String (Opcional)	Texto da opção de bloqueador para Yelum. Usar apenas quando antifurto for "Bloqueador" (a API rejeita caso contrário).
bloqueadorPorto	String (Opcional)	Texto da opção de Porto Seguro. Usar quando antifurto for "Bloqueador". Também é aceito quando antifurto for "Rastreador" (Porto Seguro) (a API rejeita caso contrário).
gerenciadoraTokio	String (Opcional)	Texto da gerenciadora para Tokio Marine quando exigido (ex.: quando o valor selecionado for "CONTROLLOC GPS").
alarmeSonoroAntiFurtoBradesco	String (Opcional)	Ex: "Cielocel GSM/GPRS Gs8". Texto da opção Bradesco. Usar quando antifurto for "Alarme Sonoro" e também quando antifurto for "Dispositivos comuns" (a API rejeita caso contrário).
antifurtoTokio	String (Opcional)	Ex: "CONTROLLOC GPS". Texto da opção Tokio Marine (serve tanto para antifurto/rastreador quanto para bloqueador). Se o campo não existir/não estiver visível no portal, a automação ignora e registra no log.
antifurtoMapfre	String (Opcional)	Ex: "CAR SYSTEM - Bloqueador". Texto da opção de antifurto/bloqueador para Mapfre. Usar apenas quando antifurto for "Bloqueador" (a API rejeita caso contrário).
rastreadorAllianz	String (Opcional)	Texto da opção de rastreador para Allianz. Usar apenas quando antifurto for "Rastreador" (a API rejeita caso contrário).
rastreadorBradescoSeguros	String (Opcional)	Texto da opção de rastreador para Bradesco Seguros. Usar apenas quando antifurto for "Rastreador" (a API rejeita caso contrário).
rastreadorYelum	String (Opcional)	Texto da opção de rastreador para Yelum. Usar apenas quando antifurto for "Rastreador" (a API rejeita caso contrário).
rastreadorMapfre	String (Opcional)	Texto da opção de rastreador para Mapfre. Usar apenas quando antifurto for "Rastreador" (a API rejeita caso contrário).
dispositivosComunsAllianz	String (Opcional)	Obrigatório quando antifurto for "Dispositivos comuns". Texto da opção de dispositivos comuns para Allianz. Se o portal não exibir este campo, a automação ignora e registra no log.
acessorios	String (Opcional)	"Sim" ou "Não" para expandir a seção "Blindagem, kit Gás, acessórios, equipamentos ou opcionais".
kitacessorios	String (Opcional)	"Sim" ou "Não" para marcar Acessórios (item dentro da seção). Usar apenas quando acessorios for "Sim" (a API rejeita caso contrário).
opcionais	String (Opcional)	"Sim" ou "Não" para marcar Opcionais (item dentro da seção). Usar apenas quando acessorios for "Sim" (a API rejeita caso contrário).
opcionais2	String (Opcional)	Lista de opcionais (separados por vírgula), ex.: "Air bag motorista, Air bag passageiro". Usar apenas quando acessorios for "Sim" e opcionais for "Sim" (a API rejeita caso contrário).
equipamentos	String (Opcional)	"Sim" ou "Não" para marcar Equipamentos (item dentro da seção). Usar apenas quando acessorios for "Sim" (a API rejeita caso contrário).
capotaFibra	String (Opcional)	Valor do equipamento Capota de Fibra (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
franquiaCapotaFibra	String (Opcional)	"Sim" ou "Não" para marcar franquia da Capota de Fibra. Se omitido, a automação não altera. Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
equipamentoEspecial	String (Opcional)	Valor do equipamento Equipamento Especial (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
franquiaEquipamentoEspecial	String (Opcional)	"Sim" ou "Não" para marcar franquia do Equipamento Especial. O padrão do portal já é "Sim"; se omitido, a automação não altera. Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
telefoneCelularVeicular	String (Opcional)	Valor do equipamento Telefone Celular Veicular (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
franquiaTelefoneCelularVeicular	String (Opcional)	"Sim" ou "Não" para marcar franquia do Telefone Celular Veicular. O padrão do portal já é "Sim"; se omitido, a automação não altera. Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
rebaixado	String (Opcional)	"Sim" ou "Não". Informa se o veículo é rebaixado. Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
tunado	String (Opcional)	"Sim" ou "Não". Informa se o veículo é tunado. Usar apenas quando acessorios for "Sim" e equipamentos for "Sim" (a API rejeita caso contrário).
radioAmFm	String (Opcional)	Valor do acessório Radio AM/FM (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
cdPlayer	String (Opcional)	Valor do acessório CD Player (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
franquiaCdPlayer	String (Opcional)	"Sim" ou "Não" para marcar franquia do CD Player. O padrão do portal já é "Sim"; se omitido, a automação não altera. Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
dvdPlayer	String (Opcional)	Valor do acessório DVD Player (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
rodasLigaLeve	String (Opcional)	Valor do acessório Rodas de Liga Leve (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
kitMultimidia	String (Opcional)	Valor do acessório Kit Multimídia (numérico, ex.: 1000,00). Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
franquiaRadioAmFm	String (Opcional)	"Sim" ou "Não" para marcar franquia do Radio AM/FM. O padrão do portal já é "Sim"; se omitido, a automação não altera. Usar apenas quando acessorios for "Sim" e kitacessorios for "Sim" (a API rejeita caso contrário).
blindagem	String (Opcional)	"Sim" ou "Não" para marcar Blindagem.
coberturaBlindagem	String (Opcional)	Obrigatório quando blindagem for "Sim". Texto da cobertura de blindagem.
valorBlindagem	String (Opcional)	Obrigatório quando coberturaBlindagem estiver preenchido. Valor da blindagem (numérico, ex.: 1000,00).
comFranquia	String (Opcional)	"Sim" ou "Não" para marcar "Com franquia". Se blindagem for "Sim" (ou coberturaBlindagem for enviado) e não for passado, o padrão assumido é "Não".
kitGas	String (Opcional)	"Sim" ou "Não" para marcar Kit Gás.
coberturaKitGas	String (Opcional)	Obrigatório quando kitGas for "Sim". "Sim" ou "Não" para marcar Cobertura de Kit Gás.
valorKitGas	String (Opcional)	Obrigatório quando coberturaKitGas for "Sim". Valor do Kit Gás (numérico, ex.: 1000,00).
comFranquiaKitGas	String (Opcional)	"Sim" ou "Não" para marcar "Com franquia" do Kit Gás. Se coberturaKitGas for "Sim" e não for passado, o padrão assumido é "Não".
possuiAntifurtoPorto	String (Opcional)	Ex: "Sim". "Sim" ou "Não" para marcar "Possui algum antifurto da Porto Seguro?" (serve tanto no fluxo geral quanto no fluxo de bloqueador).
hdiSegurosBasico	String (Opcional)	Ex: "Sim". "Sim" ou "Não" para acionar a seleção básica da HDI após avançar. Se antifurto for "Bloqueador", este campo é opcional (pode ser omitido).
pcdCnhEspecial	String (Opcional)	"Sim" ou "Não". PcD / CNH Especial. Se o portal não exibir este campo, a automação ignora e registra no log.
valorAdaptacaoPcd	String (Opcional)	Valor da adaptação PcD (numérico, ex.: 1000,00). Usar apenas quando pcdCnhEspecial for "Sim" (a API rejeita caso contrário). Se o portal não exibir este campo, a automação ignora e registra no log.
cepPernoite	String (Numeric)	CEP onde o veículo fica guardado (Apenas números).
cepCirculacao	String (Numeric)	CEP de circulação (Apenas números). Se o portal não exibir este campo, a automação ignora e registra no log.
kmMes	String (Numeric)	Estimativa de KM rodados por mês (Apenas números). Se o portal não exibir este campo, a automação ignora e registra no log.
tipoUso	String	Finalidade de uso do veículo. 27 valores aceitos (case/acento-insensível) — descobertos ao vivo no select Padrao2000_Cobertura8999 do portal: Particular, Prestar serviços, Representante comercial/vendas, Táxi, Transporte por aplicativos - Veículo próprio, Transporte comercial de carga, Transporte por aplicativos - Veículo alugado, Ambulância, Auto escola, Bombeiro, Chapa de fábrica, Entrega de Mercadorias, Fins publicitários / Expositor, Frete/Carreto/Mudanças, Funerária, Locadora (Balcão), Locadora (Contrato), Lotação com cobrança de passagem, Lotação sem cobrança de passagem, Policiamento / Vigilância / Ronda / Escolta, Test Drive, Transporte de valores, Transporte de funcionários, Transporte de paciente (exceto ambulância), Escolar, Turismo, Veículos oficiais.
categoriaTaxiVeiculo	String	Obrigatório quando tipoUso for "Táxi". 5 valores aceitos (case/acento-insensível) — descobertos ao vivo no select Padrao2000_Cobertura9000: Comum, Comum com ponto privado, Comum rádio táxi, Especial rádio táxi, Luxo. A API rejeita caso seja enviado quando tipoUso não for "Táxi".
utilizacaoLocadoraContrato	String	Obrigatório quando tipoUso for "Locadora (Contrato)". 8 valores aceitos (case/acento-insensível) — descobertos ao vivo no select Padrao2000_Cobertura6117: Transporte de funcionários, Táxi, Lotação - Com cobrança de passagem, Lotação - Sem cobrança de passagem, Turismo, Prestação de serviços, Representação Comercial/Vendas, Transporte de carga. A API rejeita caso seja enviado quando tipoUso não for "Locadora (Contrato)".
usoComercialDoisOuMaisDias	String	Obrigatório quando tipoUso for "Particular". Valores: "Sim" ou "Não". A API rejeita caso seja enviado quando tipoUso não for "Particular".
usoTrabalho	String	Uso do veículo para trabalho. 6 valores aceitos (case/acento-insensível) — descobertos ao vivo no select Padrao2000_Cobertura191: "Sim e o mantém em garagem (portão manual)", "Sim e o mantém em garagem (portão automático/porteiro)", "Sim e o mantém em estacionamento privado, pago ou fechado", "Sim, mas o mantém fora de garagem (na rua)", "Não utiliza o veículo para se locomover ao local de trabalho", "Não trabalha".
usoEstudo	String	Uso do veículo para estudo. 6 valores aceitos (case/acento-insensível) — descobertos ao vivo no select Padrao2000_Cobertura192: "Sim e o guarda em garagem (portão manual)", "Sim e o guarda em garagem (portão automático/porteiro)", "Sim e o guarda em estacionamento privado pago ou fechado", "Sim, mas o mantém fora de garagem ('na rua')", "Não utiliza o veículo para se locomover ao local de estudo", "Não estuda".

➕ Objeto: complementares

Campo	Tipo	Descrição
tipoGaragem	String	Tipo de garagem (select Padrao2000_Cobertura190 na P4). 4 valores oficiais no portal: Sim, com portão manual, Sim, com portão automático, ou porteiro, Sim, em estacionamento privado pago ou fechado., Não. O validator aceita qualquer string; o worker faz busca parcial no Select2 (strings curtas como "Portão automático" casam).
relacaoSeguradoProprietario	String	"Sim" ou "Não".
relacaoSeguradoComProprietario	String	Obrigatório quando relacaoSeguradoProprietario for "Não". Select Padrao2000_Cobertura7181 na P4. 15 valores oficiais: Próprio, Ascendentes, Cônjuge, Descendentes, enteado, Empregado, Espólio, Executivo, Irmãos e/ou parentes até 2 grau, Leasing, Sócio, Outros, Própria empresa (PJ), Empresas do mesmo grupo e quadro societário, Representantes legais da empresa, Alugados (com contrato). O validator aceita qualquer string; busca parcial no Select2.
proprietarioCpf	String	Obrigatório para algumas relações quando relacaoSeguradoProprietario for "Não". CPF do proprietário (apenas números).
proprietarioNome	String	Obrigatório para algumas relações quando relacaoSeguradoProprietario for "Não". Nome do proprietário.
proprietarioNomeSocial	String (Opcional)	Nome social do proprietário.
proprietarioSexo	String	Obrigatório para algumas relações quando relacaoSeguradoProprietario for "Não". "Masculino" ou "Feminino". O validator aceita maiúsculas/minúsculas indistintamente.
proprietarioNascimento	String	Obrigatório para algumas relações quando relacaoSeguradoProprietario for "Não". Data de nascimento (DD/MM/AAAA).
proprietarioEstadoCivil	String	Obrigatório para algumas relações quando relacaoSeguradoProprietario for "Não". Valores aceitos: Solteiro(a), Casado(a), Viúvo(a), Divorciado(a), Separado(a), União estável. O validator é tolerante a maiúsculas/minúsculas e acentos.
principalCondutor	String (Opcional)	"Sim" ou "Não". Recomendado enviar "Sim" para manter o fluxo mais simples e evitar a abertura de campos adicionais no portal. Se omitido, a automação mantém o valor padrão do portal. Quando omitido, a API permite enviar os campos do principal condutor; se enviar qualquer dado além de principalCondutorRelacaoSegurado, então CPF, Nome, Sexo, Nascimento e Estado Civil passam a ser obrigatórios.
principalCondutorRelacaoSegurado	String (Opcional)	Select Padrao2000_Condutor01_Propriosegurado na P4. 10 valores oficiais: Conjuge, Pai, Mãe, Filho(a), Irmão(ã), Outro(s), Motorista Particular, Diretor/Sócio/Dirigente, Funcionário/Empregado. Quando principalCondutor for omitido, este campo pode ser enviado sozinho; se enviar outros dados do principal condutor, CPF, Nome, Sexo, Nascimento e Estado Civil passam a ser obrigatórios.
principalCondutorCpf	String (Numeric)	Obrigatório quando principalCondutor for "Não" (Regra 10), ou quando outros sub-campos do principal condutor forem enviados sem principalCondutor. CPF do principal condutor (apenas números, 11 dígitos).
principalCondutorNome	String	Obrigatório quando principalCondutor for "Não" (Regra 10), ou quando outros sub-campos do principal condutor forem enviados sem principalCondutor. Nome do principal condutor.
principalCondutorNomeSocial	String (Opcional)	Nome social do principal condutor.
principalCondutorSexo	String	Obrigatório quando principalCondutor for "Não" (Regra 10), ou quando outros sub-campos do principal condutor forem enviados sem principalCondutor. "Masculino" ou "Feminino". O validator aceita maiúsculas/minúsculas indistintamente.
principalCondutorNascimento	String	Obrigatório quando principalCondutor for "Não" (Regra 10), ou quando outros sub-campos do principal condutor forem enviados sem principalCondutor. Data de nascimento (DD/MM/AAAA).
principalCondutorEstadoCivil	String	Obrigatório quando principalCondutor for "Não" (Regra 10), ou quando outros sub-campos do principal condutor forem enviados sem principalCondutor. Valores aceitos: Solteiro(a), Casado(a), Viúvo(a), Divorciado(a), Separado(a), União estável. O validator é tolerante a maiúsculas/minúsculas e acentos.
ramoAtividadeComercialProfissional	String	Obrigatório quando veiculo.tipoUso não for "Particular". 37 valores aceitos (case/acento-insensível) — descobertos ao vivo no select Padrao2000_Cobertura74150. Ver lista completa no Swagger (/api-docs → Complementares.ramoAtividadeComercialProfissional). A API rejeita caso seja enviado quando veiculo.tipoUso for "Particular".
profissaoPrincipalCondutor	String	Obrigatório quando veiculo.tipoUso não for "Particular". Lista oficial no portal (Padrao2000_Condutor01_Profissao) tem mais de 500 profissões. Por causa do volume, o validator aceita qualquer string e o worker faz busca parcial no portal. Exemplos seguros: Motorista Profissional, Outros, Aposentado, Estudante, Funcionário Público, Empresário.
seguroCorretorProximo	String	"Sim" ou "Não".
condutoresQueUtilizam	String (Opcional)	Só se aplica quando veiculo.tipoUso for "Transporte por aplicativos - Veículo próprio" ou "Transporte de funcionários" — "Informar os condutores que utilizam o veículo?" (select Padrao2000_Cobertura7998 da P4, inspecionado ao vivo em jun/2026). 3 valores aceitos (case/acento-insensível): É utilizado por um único condutor, É utilizado por dois condutores, É utilizado por três condutores. O portal só exibe — e torna obrigatório — este campo para esses tipos de uso; quando visível e omitido no payload, o worker aplica o default É utilizado por um único condutor. Para os demais tipos de uso é ignorado (warn no log se enviado).
tipoResidencia	String	Ex: "Casa/sobrado", "Apartamento".
pessoas17a25	String	"Sim" ou "Não".

➕ Objeto: cobertura

Campo	Tipo	Descrição
plano	String (Opcional)	Plano de cobertura (Página 5). Se omitido, o portal mantém o padrão "FÁCIL". Valores aceitos (case-insensitive): "facil", "pleno", "total", "personalizado".
modalidade	String (Opcional)	Modalidade (Página 5) selecionada no portal (Select2). Se omitido, mantém o padrão do portal (ex.: "Valor de Mercado").
percentualAjuste	String (Opcional)	% Ajuste (Página 5). Campo numérico opcional (ex.: "100", "95,5"). Se omitido, mantém o padrão do portal.
franquiaPrimeiraOpcao	String (Opcional)	Primeira opção de franquia (Página 5) selecionada no portal (Select2). Se omitido, mantém o padrão do portal (ex.: "Normal 100%").
franquiaSegundaOpcao	String (Opcional)	Segunda opção de franquia (Página 5) selecionada no portal (Select2). Se omitido, mantém o padrão do portal (ex.: "Reduzida 50%").
danosMateriaisTerceiros	String (Opcional)	Danos materiais a terceiros (Página 5) selecionado no portal (Select2). Se omitido, mantém o padrão do portal (ex.: "100.000,00").
danosCorporaisTerceiros	String (Opcional)	Danos corporais a terceiros (Página 5) selecionado no portal (Select2). Se omitido, mantém o padrão do portal (ex.: "100.000,00").
appMortePorPassageiro	String (Opcional)	APP Morte (por passageiro) (Página 5). Campo de valor opcional (ex.: "10000,00", "10.000,00"). Se omitido, mantém o padrão do portal (ex.: "10.000,00").
appInvalidezPorPassageiro	String (Opcional)	APP Invalidez (por passageiro) (Página 5). Campo de valor opcional (ex.: "10000,00", "10.000,00"). Se omitido, mantém o padrão do portal (ex.: "10.000,00").
danosMorais	String (Opcional)	Danos morais (Página 5). Campo de valor opcional (ex.: "10000,00", "10.000,00"). Se omitido, mantém o padrão do portal (ex.: "10.000,00").
despesasExtras	String (Opcional)	Despesas extras (Página 5) selecionada no portal (Select2). Se omitido, mantém o padrão do portal (ex.: "Não contratada").
maisAssistencias	String/Boolean (Opcional)	+ Assistências (Página 5). Envie "Sim" (ou true) para clicar no botão de abrir assistências. Se omitido, mantém o padrão do portal.
maisAssistenciasSeguradoras	String (Opcional)	Seguradora específica para + Assistências (ex.: "allianz"). Só é aplicada quando maisAssistencias for "Sim". Se omitido, mantém todas selecionadas no portal. Se seguro.seguradorasDisponiveis for enviado, esta seguradora deve estar presente nele.

Exemplos de uso:

"cobertura": { "plano": "facil" }
"cobertura": { "plano": "pleno" }
"cobertura": { "plano": "total" }
"cobertura": { "plano": "personalizado" }
"cobertura": { "modalidade": "Valor de Mercado" }
"cobertura": { "plano": "pleno", "modalidade": "Valor de Mercado" }
"cobertura": { "percentualAjuste": "100" }
"cobertura": { "plano": "pleno", "modalidade": "Valor de Mercado", "percentualAjuste": "95,5" }
"cobertura": { "franquiaPrimeiraOpcao": "Normal 100%" }
"cobertura": { "plano": "pleno", "franquiaPrimeiraOpcao": "Normal 100%" }
"cobertura": { "franquiaSegundaOpcao": "Reduzida 50%" }
"cobertura": { "plano": "pleno", "franquiaPrimeiraOpcao": "Normal 100%", "franquiaSegundaOpcao": "Reduzida 50%" }
"cobertura": { "danosMateriaisTerceiros": "100.000,00" }
"cobertura": { "plano": "pleno", "danosMateriaisTerceiros": "100.000,00" }
"cobertura": { "danosCorporaisTerceiros": "100.000,00" }
"cobertura": { "plano": "pleno", "danosCorporaisTerceiros": "100.000,00" }
"cobertura": { "appMortePorPassageiro": "10.000,00" }
"cobertura": { "plano": "pleno", "appMortePorPassageiro": "10.000,00" }
"cobertura": { "appInvalidezPorPassageiro": "10.000,00" }
"cobertura": { "plano": "pleno", "appInvalidezPorPassageiro": "10.000,00" }
"cobertura": { "danosMorais": "10.000,00" }
"cobertura": { "plano": "pleno", "danosMorais": "10.000,00" }
"cobertura": { "despesasExtras": "Não contratada" }
"cobertura": { "plano": "pleno", "despesasExtras": "Não contratada" }
"cobertura": { "maisAssistencias": "Sim" }
"cobertura": { "maisAssistencias": "Sim", "maisAssistenciasSeguradoras": "allianz" }

📦 Exemplos de Payloads Completos

Exemplo 0 - Payload pronto para teste (resiliência de seletores):

• Arquivo: data/requests/cotacao-seletores-resiliencia.json
• Observação: a API aceita objeto único ou array de cotações. Este arquivo está no formato array (1 item) para facilitar reuso.

Exemplo 1 - Fluxo simples (rápido até Cobertura):

{
  "id": "COT_EXEMPLO_001",
  "segurado": {
    "cpf": "12345678900",
    "nomeSocial": "Cliente Exemplo",
    "telefone": "11999999999",
    "email": "cliente.exemplo@teste.com",
    "cep": "01001000"
  },
  "seguro": {
    "tipo": "Novo",
    "nomeHierarquico": "NOME DO CORRETOR"
  },
  "veiculo": {
    "placa": "ABC1D23",
    "chassiRemarcado": "Não",
    "financiado": "Não",
    "antifurto": "Não",
    "cepPernoite": "01001000",
    "cepCirculacao": "01001000",
    "kmMes": "800",
    "tipoUso": "Particular",
    "usoTrabalho": "Não",
    "usoEstudo": "Não",
    "usoComercialDoisOuMaisDias": "Não"
  },
  "complementares": {
    "tipoGaragem": "Sim, com portão manual",
    "relacaoSeguradoProprietario": "Sim",
    "principalCondutor": "Sim",
    "seguroCorretorProximo": "Não",
    "tipoResidencia": "Casa/sobrado",
    "pessoas17a25": "Não"
  },
  "cobertura": {
    "plano": "pleno"
  }
}

Exemplo 2 - Cobertura com vários campos:

{
  "id": "COT_EXEMPLO_002",
  "segurado": {
    "cpf": "22233344455",
    "nomeSocial": "Cliente Cobertura Completa",
    "telefone": "11988887777",
    "email": "cobertura.completa@teste.com",
    "cep": "01310930"
  },
  "seguro": {
    "tipo": "Novo",
    "nomeHierarquico": "NOME DO CORRETOR"
  },
  "veiculo": {
    "placa": "DEF2G34",
    "chassiRemarcado": "Não",
    "financiado": "Não",
    "antifurto": "Não",
    "cepPernoite": "01310930",
    "cepCirculacao": "01310930",
    "kmMes": "1200",
    "tipoUso": "Particular",
    "usoTrabalho": "Não",
    "usoEstudo": "Não",
    "usoComercialDoisOuMaisDias": "Não"
  },
  "complementares": {
    "tipoGaragem": "Sim, com portão automático",
    "relacaoSeguradoProprietario": "Sim",
    "principalCondutor": "Sim",
    "seguroCorretorProximo": "Não",
    "tipoResidencia": "Apartamento",
    "pessoas17a25": "Não"
  },
  "cobertura": {
    "plano": "personalizado",
    "modalidade": "Valor de Mercado",
    "percentualAjuste": "95,5",
    "franquiaPrimeiraOpcao": "Normal 100%",
    "franquiaSegundaOpcao": "Reduzida 50%",
    "danosMateriaisTerceiros": "100.000,00",
    "danosCorporaisTerceiros": "100.000,00",
    "appMortePorPassageiro": "10.000,00",
    "appInvalidezPorPassageiro": "10.000,00",
    "danosMorais": "10.000,00",
    "despesasExtras": "Não contratada"
  }
}

Exemplo 3 - Seguradoras selecionadas + maioria dos campos preenchidos:

{
  "id": "COT_EXEMPLO_003",
  "segurado": {
    "cpf": "33344455566",
    "nomeSocial": "Cliente Perfil Completo",
    "telefone": "11977776666",
    "email": "perfil.completo@teste.com",
    "cep": "04538132"
  },
  "seguro": {
    "tipo": "Novo",
    "nomeHierarquico": "NOME DO CORRETOR",
    "seguradorasDisponiveis": ["allianz", "porto", "tokio", "hdi seguros"],
    "bonusAllianz": "5",
    "bonusPortoAzulItau": "4",
    "bonusTokio": "3",
    "bonusHdi": "2"
  },
  "veiculo": {
    "placa": "GHI3J45",
    "chassiRemarcado": "Não",
    "financiado": "Sim",
    "alienacaoFiduciaria": "BANCO EXEMPLO",
    "antifurto": "Não",
    "cepPernoite": "04538132",
    "cepCirculacao": "04538132",
    "kmMes": "1500",
    "tipoUso": "Particular",
    "usoTrabalho": "Sim",
    "usoEstudo": "Não",
    "usoComercialDoisOuMaisDias": "Não",
    "blindagem": "Não",
    "kitGas": "Não"
  },
  "complementares": {
    "tipoGaragem": "Sim, com portão automático",
    "relacaoSeguradoProprietario": "Não",
    "relacaoSeguradoComProprietario": "Cônjuge",
    "proprietarioCpf": "55566677788",
    "proprietarioNome": "Patrícia Exemplo",
    "proprietarioSexo": "Feminino",
    "proprietarioNascimento": "20/11/1988",
    "proprietarioEstadoCivil": "Casado(a)",
    "principalCondutor": "Não",
    "principalCondutorRelacaoSegurado": "Cônjuge",
    "principalCondutorCpf": "55566677788",
    "principalCondutorNome": "Patrícia Exemplo",
    "principalCondutorSexo": "Feminino",
    "principalCondutorNascimento": "20/11/1988",
    "principalCondutorEstadoCivil": "Casado(a)",
    "seguroCorretorProximo": "Não",
    "tipoResidencia": "Apartamento",
    "pessoas17a25": "Não"
  },
  "cobertura": {
    "plano": "total",
    "modalidade": "Valor de Mercado",
    "percentualAjuste": "100",
    "franquiaPrimeiraOpcao": "Normal 100%",
    "franquiaSegundaOpcao": "Reduzida 50%",
    "danosMateriaisTerceiros": "100.000,00",
    "danosCorporaisTerceiros": "100.000,00",
    "appMortePorPassageiro": "10.000,00",
    "appInvalidezPorPassageiro": "10.000,00",
    "danosMorais": "10.000,00",
    "despesasExtras": "Não contratada"
  }
}

💻 Exemplos de Integração

Via cURL (Terminal)

curl -X POST http://localhost:3000/cotacao \
-H "Content-Type: application/json" \
-d '{
  "id": "COT_12345",
  "segurado": { "cpf": "12345678900", "nomeSocial": "João Silva" },
  ...
}'

Via JavaScript (Fetch API)

const response = await fetch('http://localhost:3000/cotacao', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(dadosCotacao)
});

const result = await response.json();
console.log(result.message);

⚠️ Tratamento de Erros

A API utiliza códigos de status HTTP padrão:

• 201 Created: Requisição aceita e worker iniciado.
• 400 Bad Request: Erro de validação. O corpo da resposta conterá um array details com os campos ausentes ou inválidos.
• 500 Internal Server Error: Erro inesperado no servidor.

Exemplo de erro (400):

{
  "error": "Dados incompletos ou inválidos",
  "details": [
    "Campo segurado.cpf é obrigatório e está vazio",
    "Campo veiculo.placa é obrigatório e está vazio"
  ]
}

⚠️ Campos desconhecidos (validação estrita)

Se o JSON contiver um nome de campo incorreto, a API retornará 400 informando o campo inválido e sugerindo o nome correto quando possível.

{
  "error": "Dados incompletos ou inválidos",
  "details": [
    "Item 0: Campo veiculo.antifurtoBradesco não é suportado. Use veiculo.alarmeSonoroAntiFurtoBradesco"
  ]
}

📝 Observações Importantes

• Logs: cada execução gera um arquivo .txt em logs/ com o detalhamento das ações por cotação/worker.
• Erros: em falhas de automação, são gerados screenshots em logs/ (ex.: ERRO_<ID>_worker<NUM>.png e ERRO_IMPRESSAO_<ID>_<DATA>.png).
• Payload pronto para teste: data/requests/cotacao-seletores-resiliencia.json (array com 1 item).
• Campos ausentes/condicionais no portal: se algum campo não estiver presente ou visível no momento do preenchimento (ex.: veiculo.kmMes), a automação ignora e registra o motivo no log.
• Combobox com busca (Select2): a automação tenta localizar a opção por texto normalizado (case/acentos/underscores/múltiplos espaços) com correspondência exata e parcial. Se não encontrar, pode selecionar a opção destacada (ou a primeira opção disponível) e registrar aviso no log.
• Modais do portal: se um modal inesperado bloquear cliques (ex.: ClienteDiario2), a automação tenta fechar o modal e repetir a ação.
• Impressão expressa (PDF): após finalizar o cálculo, a automação pode abrir o menu de impressão, selecionar Impressão expressa e clicar em Download PDF. O arquivo é salvo em data/pdfs/ (padrão: <ID>_<CPF>_<DD-MM-AAAA>.pdf).
• IDs do portal (Padrao2000_*): os IDs Padrao2000_CoberturaNNNN e Padrao2000_AcessorioNNNN usados nos seletores foram centralizados em pages/selectors/coberturas.ts (evita strings literais espalhadas).

📡 Webhook (notificação automática ao final da cotação)

Ao final do worker (quando a cotação é processada com sucesso), a API envia automaticamente um POST ao endpoint configurado pela variável de ambiente WEBHOOK_URL, com os prêmios extraídos. Não há retry nem fila.

Configuração (variáveis de ambiente)

Variável	Obrigatório?	Uso
WEBHOOK_URL	Para ativar o webhook	URL completa do destinatário (POST).
WEBHOOK_CLIENT_KEY	Para ativar o webhook	Enviado como header x-client-key.
WEBHOOK_CLIENT_SECRET	Para ativar o webhook	Enviado como header x-client-secret.

Se qualquer das 3 variáveis estiver ausente, o webhook é silenciosamente pulado (apenas um warn no log). Timeout: 15s. Falhas no destinatário são logadas mas não afetam o worker.

Payload

{
  "cotacaoId": "27c08695-0361-4eed-9eb7-bf723c2636ee",
  "seguradoCpf": "34683964813",
  "capturadoEm": "2026-06-09T15:53:09.765Z",
  "totalCardsDetectados": 10,
  "totalCardsAproveitados": 7,
  "temPremios": true,
  "cards": [ /* lista de objetos com seguradora, prêmios, coberturas */ ]
}

Quando temPremios = false

O webhook sempre é chamado mesmo sem prêmios. Use o campo temPremios para roteamento (não confie em cards.length diretamente). O campo opcional mensagem traz a explicação legível:

{
  "cotacaoId": "V3-turismo",
  "totalCardsDetectados": 10,
  "totalCardsAproveitados": 0,
  "temPremios": false,
  "mensagem": "Portal renderizou 10 card(s), mas nenhum tinha conteúdo extraível (todos retornaram 'sem retorno da cotação' ou similar). Comum em cotações com tipoUso != Particular onde o portal não calcula prêmios para a combinação enviada.",
  "cards": []
}

Causas comuns de temPremios=false:

• Combinação tipoUso + seguradorasDisponiveis sem produto disponível no portal (ex.: Turismo + porto).
• Cotações com tipoUso != Particular em geral — o portal frequentemente não calcula prêmios.
• Algum campo obrigatório do portal ocultado por display:none (esses campos são pulados pelo worker, mas o cálculo pode depender deles em alguns casos).

📝 Documentação Interativa

Para testar os campos em tempo real e ver o esquema completo, acesse o Swagger UI:
👉 http://localhost:3000/api-docs