Propostas

Propostas comerciais, PDF e envio.

16 rotas. Todas exigem a chave de API no header Authorization, salvo quando marcadas como públicas. Abrir este módulo no Swagger.

Listar propostas por período e status

POST /companie/offer/filterAdvanced

Filtra as propostas da empresa da chave.

• filter usa a data do status (status_date). Com other_period, informe date_start e date_end (YYYY-MM-DD).
• status: Todos ou um status específico.
• opportunityId, companieUserId e personId filtram por oportunidade, usuário criador e contato. Envie os três sempre, mesmo vazios ([]): sem eles a rota devolve 500.
• Paginação: skip (registros a pular) e take (tamanho da página). total é o total do filtro.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
opportunityId	número[]
companieUserId	número[]
personId	número[]
order	created_at_asc · created_at_desc	sim
status	Todos · Aberta · Cancelada · Em Negociação · Fechada · Perdida	sim
filter	all · today · yesterday · this_week · last_week · this_month · last_month · last_30_days · …	sim
date_start	string
date_end	string
skip	número	sim
take	número	sim

Respostas

Status	Descrição
200	Página de propostas com produtos, histórico de status e oportunidade.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Buscar propostas por texto

GET /companie/offer/autocomplete/find

Procura q no número, nome, WhatsApp, e-mail, documento (sem pontos e traço) e status da proposta. Ordena da mais antiga para a mais nova. Os três parâmetros são obrigatórios na prática.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
q	query	string	sim	Texto a procurar.
skip	query	número	sim	Registros a pular.
take	query	número	sim	Tamanho da página.

Respostas

Status	Descrição
200	Propostas encontradas.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Detalhar proposta

GET /companie/offer/{id}

Proposta de outra empresa ou inexistente devolve 200 com corpo null.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Proposta com produtos e dados da empresa, ou null.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Excluir proposta

DELETE /companie/offer/{id}

Remove a proposta com produtos, anexos e histórico de status.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Proposta excluída.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Criar proposta

POST /companie/offer

Cria a proposta com status Aberta e número sequencial da empresa. O criador é o usuário da chave.

• person_id: id do contato. Os dados person_* são uma cópia na proposta e também atualizam o contato (nome, documento, e-mail e WhatsApp).
• person_document é obrigatório na prática (CPF/CNPJ só com dígitos, até 14).
• Com opportunity_id, os produtos da oportunidade são copiados para a proposta (à vista, cartão, 1 parcela) e o total é calculado. A resposta traz o total anterior a essa cópia; consulte o detalhe para o valor final.
• Endereço e observação são preenchidos depois, em PUT /companie/offer/address/{id} e PUT /companie/offer/obs/{id}.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
person_id	número	sim
opportunity_id	número ou null
person_name	string	sim
person_name_fantasy	string
person_birth	data ou null
person_document	string
person_email	string
person_whatsapp	string
person_rg	string
person_gender	string
person_civil_status	string

Respostas

Status	Descrição
200	Proposta criada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_person_not_exist ou error_opportunity_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar dados pessoais da proposta

PUT /companie/offer/personal/{id}

Atualiza os campos person_* da proposta e também o nome, documento, e-mail e WhatsApp do contato. person_whatsapp: só dígitos, com DDD (10 ou 11).

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	número	sim	Id da proposta.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
person_id	número	sim
person_name	string	sim
person_name_fantasy	string
person_birth	data ou null
person_document	string
person_email	string
person_whatsapp	string	sim
person_rg	string
person_gender	string
person_civil_status	string

Respostas

Status	Descrição
200	Proposta atualizada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_contract_not_exist (proposta não encontrada) ou error_person_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar endereço da proposta

PUT /companie/offer/address/{id}

Atualiza o endereço na proposta e no contato. person_address_zipcode: CEP com 8 dígitos; person_address_state: UF com 2 letras.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
person_address_zipcode	string	sim
person_address	string	sim
person_address_number	string	sim
person_address_complement	string
person_address_province	string	sim
person_address_city	string	sim
person_address_state	string	sim

Respostas

Status	Descrição
200	Proposta atualizada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar observação da proposta

PUT /companie/offer/obs/{id}

Texto livre de até 6000 caracteres. Aparece no PDF na variável {{obs}}.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
obs	string	sim

Respostas

Status	Descrição
200	Proposta atualizada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Alterar status da proposta

PUT /companie/offer/status/{id}

Grava o novo status, a status_date e uma linha no histórico (offer_status).

• Cancelada numa proposta ligada a oportunidade também marca a oportunidade como Perdida.
• Os demais status não mexem na oportunidade.
• financialIds é aceito, mas ignorado.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
status	Aberta · Cancelada · Em Negociação · Fechada · Perdida	sim
financialIds	número[]

Respostas

Status	Descrição
200	Proposta atualizada.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Listar produtos da proposta

GET /companie/offer/product/{id}

id é o id da proposta.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Produtos da proposta, com o cadastro do produto em product.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_products_not_exist (proposta não encontrada) (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Editar produto da proposta

PUT /companie/offer/product/{id}

id é o id do produto na proposta (offer_products.id). O total da proposta é recalculado pela soma dos produtos.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
product_value	número	sim
qtd	número	sim
value	número	sim
form_of_payment	creditcard · boleto · pix	sim
method	in_sight · installments · recurrence	sim
qtd_installments	número ou null
total	número	sim

Respostas

Status	Descrição
200	Produto atualizado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_product_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Remover produto da proposta

DELETE /companie/offer/product/{id}

id é o id do produto na proposta (offer_products.id). O total da proposta é recalculado.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	Produto removido.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_products_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Adicionar produto à proposta

POST /companie/offer/product

• product_id: id do produto cadastrado; product_name e product_value são cópias do cadastro.
• value: valor unitário negociado; total: valor da linha (normalmente value * qtd). O servidor não recalcula: soma o total enviado ao total da proposta.
• method: in_sight (à vista), installments (parcelado, informe qtd_installments) ou recurrence (recorrente).
• A resposta é a proposta atualizada, não o produto. Para pegar o id do produto, liste os produtos da proposta.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
offer_id	número	sim
product_id	número	sim
product_name	string	sim
product_value	número	sim
qtd	número	sim
value	número	sim
form_of_payment	creditcard · boleto · pix	sim
method	in_sight · installments · recurrence	sim
qtd_installments	número ou null
total	número	sim

Respostas

Status	Descrição
200	Proposta com o novo total.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_not_exist ou error_product_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Baixar PDF da proposta

GET /companie/offer/pdf/{id}

Rota pública

Não exige chave de API.

Rota pública: não exige chave. É o link enviado ao cliente.

• Gera o PDF com o modelo de proposta da empresa (GET /companie/offer-custom). Sem modelo, devolve error_offer_custom_not_exist.
• Enquanto a proposta está Aberta, o PDF é gerado de novo a cada chamada e o HTML fica gravado. Nos outros status, usa o HTML gravado na última geração.
• A resposta não traz Content-Type: trate o corpo como binário (application/pdf).
• Propostas sem oportunidade podem falhar com 500.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
id	URL	string	sim

Respostas

Status	Descrição
200	PDF da proposta. (application/pdf)
400	Parâmetros inválidos. (ValidationError)
409	error_offer_not_exist ou error_offer_custom_not_exist (ErrorCode)

Testar no Swagger

Enviar proposta por e-mail

GET /companie/offer/sendMail/{offerId}

GET com efeito colateral: envia um e-mail ao person_email da proposta com o PDF anexado (Proposta_<número>.pdf). Cada chamada envia de novo.

• Usa o modelo de proposta da empresa da chave (GET /companie/offer-custom).
• Não muda o status da proposta.
• Propostas sem oportunidade podem falhar com 500.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
offerId	URL	string	sim

Respostas

Status	Descrição
200	E-mail enviado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
409	error_offer_not_exist ou error_offer_custom_not_exist (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Consultar o modelo de proposta da empresa

GET /companie/offer-custom

Cada empresa tem um modelo (HTML) usado no PDF e no e-mail da proposta. Devolve null se a empresa ainda não configurou o modelo (Configurações › Proposta); nesse caso PDF e e-mail falham com error_offer_custom_not_exist.

Respostas

Status	Descrição
200	Modelo de proposta, ou null.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger