Fluxos comuns

Quatro sequências que cruzam módulos, com a rota de cada passo. Os detalhes de corpo e respostas estão na Referência de rotas; as convenções de datas, valores e paginação em Autenticação e convenções.

Lead, oportunidade, ganha ou perdida

1. Descubra as etapas. GET /companie/funnel devolve os funis com funnel_step[].id.
2. Crie o lead. POST /companie/captured/lead/api cria contato e oportunidade de uma vez e devolve o id da oportunidade. Se preferir separar, use POST /companie/person e depois POST /companie/opportunity com person_id, funnel_step_id e companie_user_id.
3. Acompanhe. GET /companie/opportunity/id/:id traz etapa, responsável, contatos, produtos, anotações e o histórico de etapas e status. Para listar por período, POST /companie/opportunity/filterAdvanced/....
4. Mova de etapa. PUT /companie/opportunity/workflow/:id com o novo funnel_step_id.
5. Escolha o motivo. GET /companie/responsesWinLose/active lista os motivos de ganho e perda ativos.
6. Feche. PUT /companie/opportunity/status/:id com status Ganha ou Perdida e responses_win_lose_id. Cada chamada grava uma linha no histórico de status; Aberta reabre, salvo se a oportunidade já tem contrato faturado.

Ganhar não cria contrato

Marcar a oportunidade como Ganha não gera proposta nem contrato. Para isso, siga o fluxo abaixo. A exceção é reuse_contract_id, que reaproveita um contrato Aberto ou Cancelado de uma proposta desta oportunidade.

Proposta, contrato, faturar e emitir NFS-e

1. Crie a proposta. POST /companie/offer com person_id e os dados person_*. Com opportunity_id, os produtos da oportunidade são copiados para a proposta.
2. Complete a proposta. Produtos em POST /companie/offer/product (um por chamada), endereço em PUT /companie/offer/address/:id. O PDF sai em GET /companie/offer/pdf/:id e o envio por e-mail em GET /companie/offer/sendMail/:offerId.
3. Gere o contrato a partir da proposta. Não existe uma rota "fechar proposta": o fechamento é criar o contrato. POST /companie/contract com offer_id localiza ou cria o cliente, copia o endereço e os produtos da proposta. Uma proposta só gera um contrato (409 error_exist_offer_contract na segunda tentativa). Se quiser registrar o status da proposta, PUT /companie/offer/status/:id com Fechada; Cancelada também marca a oportunidade como Perdida.
4. Complete o contrato. PUT /companie/contract/payment/:id preenche o responsável financeiro (resp_financial_email e resp_financial_document são obrigatórios para faturar), desconto, multa e juros. Sem proposta de origem, envie também o endereço em PUT /companie/contract/address/:id e os produtos em POST /companie/contract/product.
5. Fature. POST /companie/contract/invoice com contract_id e first_pay_day_date. Gera as cobranças (no Asaas, na Cel Cash ou só como lançamentos, conforme a empresa) e muda o contrato para Ag.Pagamento; ele passa a Ativo no primeiro pagamento confirmado. O contrato precisa estar Aberto, ter ao menos um produto e a empresa precisa ter plano de contas ativo.
6. Localize o lançamento. GET /companie/financial/serviceInvoiceCompany/financialOptions lista as receitas elegíveis, com os produtos do contrato para preencher contractProductIds. Alternativa: GET /companie/contract/:id ou a listagem do financeiro.
7. Emita a NFS-e. POST /companie/financial/serviceInvoiceCompany/issue com type vinculada, financialId, customerId, customerServiceId e servicesAmount. Exige NFS-e configurada, saldo de créditos de nota e cliente com CPF/CNPJ, e-mail e endereço completos. A rota espera cerca de 20 segundos pela prefeitura; se voltar processing: true, consulte depois em GET /companie/financial/serviceInvoiceCompany/:serviceInvoiceId. O PDF sai em GET .../serviceInvoiceCompany/:serviceInvoiceId/pdf.

customerServiceId

A emissão exige a atividade econômica (serviço) cadastrada para o cliente no LeadSim. A rota que lista essas atividades não faz parte da API de integração; cadastre a atividade na tela de Clientes e use o id dela, ou emita a primeira nota pela tela para conferir os dados.

Conferir cobranças pagas num período e dar baixa

1. Liste os lançamentos do período. POST /companie/financial/filterAdvanced/:filter/:date_start/:date_end. Para "o que foi pago em setembro": other_period/2026-09-01/2026-09-30 na URL e, no corpo, type: "R", date: "P" (filtra pela data do pagamento), status: ["Paga"], received: true, skip e take. Envie também client_id, contract_id, provider_id, pla_account_id e form_of_payment como [].
2. Confira o que está em aberto. Mesma rota com date: "V" (vencimento), status: ["Aberta", "Vencida"] e received: null. Cada item traz payment_link (cobranças integradas), nfe_id/nfe_status e o status já recalculado (Aberta vencida volta como Vencida).
3. Dê baixa no que foi recebido fora do LeadSim. PUT /companie/financial/payed/:id com received_value e received_date. Em cobrança integrada ao Asaas, registra o recebimento em dinheiro lá também. Para várias de uma vez, POST /companie/financial/bulk/payed.
4. Desfaça se precisar. PUT /companie/financial/revertPayed/:id.

A baixa não é idempotente

PUT /companie/financial/payed/:id não recusa lançamento já pago: chamar de novo sobrescreve a baixa e soma de novo nos totais do cliente. Antes de dar baixa, confira o status do lançamento na listagem.

Enviar contrato para assinatura digital e acompanhar

1. Confira o saldo. GET /companie/user/signatureCreditBalance. Cada envio debita 1 crédito; sem saldo a rota de envio responde 403.
2. Escolha o layout (opcional). GET /companie/contract-custom/list lista os layouts de contrato da empresa para contract_custom_ids. Sem ele, vale o layout gravado no contrato ou o padrão da empresa.
3. Envie. POST /companie/contract/:contractId/signatures/request com signers[]: name, action (SIGN, APPROVE, SIGN_AS_A_WITNESS...) e delivery_method (DELIVERY_METHOD_EMAIL com email, DELIVERY_METHOD_SMS ou DELIVERY_METHOD_WHATSAPP com phone, ou DELIVERY_METHOD_LINK para você mesmo entregar o link). Exige a Autentique configurada na empresa.
4. Acompanhe. GET /companie/contract/:contractId/signatures/request consulta a Autentique na hora: autentiqueDocument.signatures[] traz, por signatário, public_id, o link e se já assinou (signed) ou recusou (rejected). Depois de todas as assinaturas, files.signed é o PDF assinado e files.certificate o certificado. Não há webhook: consulte periodicamente.
5. Reenvie o convite a quem não recebeu. POST /companie/contract/:contractId/signatures/:publicId/resendSignature reenvia sem novo crédito. Já um novo request cria outro documento e debita outro crédito, e só é aceito enquanto o documento não foi assinado.
6. Visão geral. GET /companie/contract/signatures/report resume a situação das assinaturas da empresa.