{"openapi":"3.1.0","info":{"title":"ERP SSG Containers - API v1","version":"0.4.0","description":"Fonte unica do contrato da API (plano 5.5). A tela em `public/` e a Sara (agente) usam as mesmas rotas.\nServido em `GET /api/v1/openapi.json`.\n\n**Autenticacao**: cookie `ssg_erp_session` (humano, via `POST /api/login`) ou `Authorization: Bearer <token>`\n(agente; hash em `erp.api_token`). **Permissao por acao** (`config/permissoes.json`): o token recebe uma lista\nexplicita, sempre subconjunto do perfil `agente`; `403` quando a acao nao cabe ao ator.\n\n**Idempotencia**: toda escrita aceita `Idempotency-Key` (obrigatoria com token). Mesma chave + mesmo ator +\nmesmo corpo devolve a resposta gravada com `Idempotent-Replay: true`; corpo diferente devolve `409`.\n\n**Erros**: `{erro, codigo, ...}`. `400` validacao, `401` sem identidade, `403` acao nao permitida, `404`,\n`409` conflito (`transicao_invalida` vem com `permitidas[]`), `422` regra de negocio, `502` provedor externo.\n\n**Paginacao**: `?pagina=1&por_pagina=50` (max 200) -> `{itens, total, pagina}`.\n"},"servers":[{"url":"http://127.0.0.1:3030/api/v1","description":"loopback no servidor da SSG (a Sara chama daqui; nao ha porta publica ainda)"}],"tags":[{"name":"sessao","description":"login","identidade":null,"saude":null},{"name":"clientes"},{"name":"negocios"},{"name":"propostas"},{"name":"equipamentos"},{"name":"auditoria"},{"name":"admin"}],"components":{"securitySchemes":{"cookie":{"type":"apiKey","in":"cookie","name":"ssg_erp_session"},"bearer":{"type":"http","scheme":"bearer","description":"token ssgerp_... gerado por scripts/criar_token.js ou POST /admin/tokens"}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Obrigatoria para token de servico. Use algo deterministico do evento de origem (id da mensagem, chave da fila).","schema":{"type":"string","maxLength":200}},"id":{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},"pagina":{"name":"pagina","in":"query","schema":{"type":"integer","default":1}},"por_pagina":{"name":"por_pagina","in":"query","schema":{"type":"integer","default":50,"maximum":200}}},"schemas":{"Erro":{"type":"object","required":["erro","codigo"],"properties":{"erro":{"type":"string","description":"mensagem legivel em portugues"},"codigo":{"type":"string","examples":["validacao","nao_permitido","transicao_invalida","documento_duplicado","idempotency_key_obrigatoria"]},"permitidas":{"type":"array","items":{"type":"string"},"description":"so em transicao_invalida"},"campo":{"type":"string"}}},"Me":{"type":"object","properties":{"ator":{"type":"string","examples":["Henrique","Sara"]},"perfil":{"type":"string","enum":["comercial","gestao","financeiro","admin","agente"]},"tipo":{"type":"string","enum":["humano","agente"]},"token":{"type":["object","null"],"properties":{"id":{"type":"integer"},"nome":{"type":"string"}}},"permissoes":{"type":"array","items":{"type":"string"}}}},"Barra":{"type":"object","description":"estado das 5 etapas do negocio","properties":{"proposta":{"$ref":"#/components/schemas/EstadoEtapa"},"aprovacao_cliente":{"$ref":"#/components/schemas/EstadoEtapa"},"contrato":{"$ref":"#/components/schemas/EstadoEtapa"},"assinatura":{"$ref":"#/components/schemas/EstadoEtapa"},"faturamento":{"$ref":"#/components/schemas/EstadoEtapa"}}},"EstadoEtapa":{"type":"string","enum":["feito","andamento","pendente","bloqueado"]},"ClienteBusca":{"type":"object","properties":{"fonte":{"type":"string","enum":["erp","og"],"description":"erp = ja esta no ERP (tem id); og = so no espelho do Otimo Gestor (use cod_og)"},"id":{"type":["integer","null"]},"cod_og":{"type":["integer","null"]},"tipo_pessoa":{"type":["string","null"],"enum":["PJ","PF",null]},"documento_mascarado":{"type":["string","null"]},"razao_social":{"type":["string","null"]},"nome_fantasia":{"type":["string","null"]},"cidade":{"type":["string","null"]},"uf":{"type":["string","null"]},"similaridade":{"type":["number","null"]}}},"ClienteEntrada":{"type":"object","required":["tipo_pessoa","documento","razao_social"],"properties":{"tipo_pessoa":{"type":"string","enum":["PJ","PF"]},"documento":{"type":"string","description":"CNPJ (14) ou CPF (11)","so digitos ou com mascara":null},"razao_social":{"type":"string"},"nome_fantasia":{"type":"string"},"inscricao_estadual":{"type":"string"},"data_fundacao":{"type":"string","format":"date"},"email":{"type":"string"},"telefone":{"type":"string"},"whatsapp":{"type":"string"},"site":{"type":"string"},"end_logradouro":{"type":"string"},"end_numero":{"type":"string"},"end_complemento":{"type":"string"},"end_bairro":{"type":"string"},"end_cidade":{"type":"string"},"end_uf":{"type":"string","maxLength":2},"end_cep":{"type":"string"},"ramo":{"type":"string"},"porte":{"type":"string"},"grupo_cliente":{"type":"string"},"tabela_preco":{"type":"string"},"cond_pagamento":{"type":"string"},"canal_origem":{"type":"string","enum":["mindschannel","site","indicacao","google","instagram","telefone","carteira","outro"]},"obs":{"type":"string"},"cod_og":{"type":"integer","description":"codigo no Otimo Gestor","se ja souber":null},"contatos":{"type":"array","items":{"$ref":"#/components/schemas/ContatoEntrada"}}}},"ContatoEntrada":{"type":"object","required":["nome"],"properties":{"nome":{"type":"string"},"papel":{"type":"string","enum":["socio","representante_legal","financeiro","recebimento","outro"],"default":"outro"},"cpf":{"type":"string"},"cargo":{"type":"string"},"email":{"type":"string"},"telefone":{"type":"string"},"assina_contrato":{"type":"boolean","default":false}}},"Cliente":{"type":"object","description":"cliente do ERP + contatos + historico unificado (ERP, Otimo Gestor, cobranca da Sara) + resumo 360","properties":{"id":{"type":"integer"},"cod_og":{"type":["integer","null"]},"tipo_pessoa":{"type":"string"},"documento":{"type":"string"},"documento_mascarado":{"type":"string"},"razao_social":{"type":"string"},"nome_fantasia":{"type":["string","null"]},"contatos":{"type":"array","items":{"type":"object"}},"historico":{"type":"array","items":{"$ref":"#/components/schemas/HistoricoItem"}},"resumo":{"type":["object","null"],"description":"linha de v_cliente_360 (n_contratos_vigentes","equipamentos_atuais":null,"faturado_12m":null,"ltv...)":null},"negocios":{"type":"array","items":{"$ref":"#/components/schemas/Negocio"}},"equipamentos":{"type":"array","items":{"type":"object"}}}},"HistoricoItem":{"type":"object","properties":{"fonte":{"type":"string","enum":["erp","og","cobranca"]},"tipo":{"type":"string","enum":["proposta","negocio","contrato","contrato_og","fatura_og","pedido_og","cobranca"]},"id":{"type":"integer"},"ref":{"type":"string"},"status":{"type":["string","null"]},"data":{"type":["string","null"],"format":"date"},"valor":{"type":["number","null"]},"descricao":{"type":["string","null"]}}},"ItemProposta":{"type":"object","required":["descricao","valor_unitario"],"properties":{"descricao":{"type":"string","description":"livre: 'Container reefer 40 pes HC'"},"tipo_produto":{"type":["string","null"],"description":"slug opcional (reefer","dry":null,"modulo":null,"sanitario_vip...)":null},"quantidade":{"type":"number","default":1},"valor_unitario":{"type":"number"},"periodicidade":{"type":"string","enum":["mensal","unico"],"default":"mensal"}}},"PropostaEntrada":{"type":"object","required":["tipo","itens"],"properties":{"tipo":{"type":"string","enum":["locacao","venda","servico","misto"]},"itens":{"type":"array","items":{"$ref":"#/components/schemas/ItemProposta"}},"modalidade_texto":{"type":"string","description":"\"LOCACAO REEFER\", compativel com o OG"},"valida_ate":{"type":"string","format":"date","description":"obrigatoria para pedir aprovacao"},"prazo_meses":{"type":"integer"},"dia_vencimento":{"type":"integer","minimum":1,"maximum":31},"cond_pagamento":{"type":"string"},"tipo_frete":{"type":"string","enum":["cif","fob","incluso","gratis","a_combinar"]},"valor_frete":{"type":"number","default":0},"valor_mobilizacao":{"type":"number","default":0},"valor_desmobilizacao":{"type":"number","default":0},"munck_incluso":{"type":"boolean"},"valor_desconto":{"type":"number","default":0},"end_instalacao":{"type":"string"},"cidade_instalacao":{"type":"string"},"uf_instalacao":{"type":"string"},"clausulas_principais":{"type":"string"},"observacoes":{"type":"string"}}},"Proposta":{"allOf":[{"$ref":"#/components/schemas/PropostaEntrada"},{"type":"object","properties":{"id":{"type":"integer"},"negocio_id":{"type":"integer"},"numero":{"type":"string","examples":["P-2026-0001","P-2026-0001-r2"]},"revisao":{"type":"integer"},"status":{"$ref":"#/components/schemas/StatusProposta"},"valor_itens":{"type":"number"},"valor_mensal":{"type":"number"},"valor_total":{"type":"number","description":"itens + frete + mobilizacao + desmobilizacao - desconto"},"permitidas":{"type":"array","items":{"$ref":"#/components/schemas/StatusProposta"},"description":"transicoes possiveis a partir do status atual"},"arquivo_pdf":{"type":["string","null"]}}}]},"StatusProposta":{"type":"string","enum":["rascunho","aguardando_aprovacao","aprovada_interna","reprovada_interna","enviada","aceita","recusada","expirada","substituida","cancelada"]},"NegocioEntrada":{"type":"object","required":["prospect_nome"],"properties":{"prospect_nome":{"type":"string"},"prospect_email":{"type":"string"},"prospect_telefone":{"type":"string"},"prospect_documento":{"type":"string"},"tipo":{"type":"string","enum":["locacao","venda","misto","servico"]},"responsavel":{"type":"string","description":"nome da vendedora (usuario humano ativo). Obrigatorio para agente."},"origem":{"type":"string","examples":["whatsapp","mindschannel","site","google_ads","indicacao"]},"cidade_entrega":{"type":"string"},"uf_entrega":{"type":"string"},"cliente_id":{"type":"integer","description":"se o cliente ja existe no ERP"},"proposta":{"$ref":"#/components/schemas/PropostaEntrada","description":"cria a proposta em rascunho junto"}}},"Negocio":{"type":"object","properties":{"id":{"type":"integer"},"numero":{"type":"string","examples":["NEG-2026-0001"]},"etapa":{"type":"string","enum":["proposta","aprovacao_cliente","contrato","assinatura","faturamento","concluido","perdido","cancelado"]},"prospect_nome":{"type":"string"},"cliente_id":{"type":["integer","null"]},"responsavel":{"type":"string"},"barra":{"$ref":"#/components/schemas/Barra"},"resumo_etapa":{"type":"string"},"dias_na_etapa":{"type":"integer"},"proposta_id":{"type":["integer","null"]},"proposta_numero":{"type":["string","null"]},"proposta_status":{"type":["string","null"]},"valor_proposta":{"type":["number","null"]},"contrato_id":{"type":["integer","null"]},"contrato_status":{"type":["string","null"]}}},"NegocioCompleto":{"allOf":[{"$ref":"#/components/schemas/Negocio"},{"type":"object","properties":{"proposta_atual":{"oneOf":[{"$ref":"#/components/schemas/Proposta"},{"type":"null"}]},"propostas":{"type":"array","items":{"type":"object"}},"contrato":{"type":["object","null"]},"eventos":{"type":"array","items":{"$ref":"#/components/schemas/Evento"}}}}]},"Evento":{"type":"object","properties":{"id":{"type":"integer"},"criado_em":{"type":"string","format":"date-time"},"etapa":{"type":"string"},"ref_tipo":{"type":["string","null"]},"ref_id":{"type":["integer","null"]},"de":{"type":["string","null"]},"para":{"type":["string","null"]},"detalhe":{"type":["string","null"]},"usuario":{"type":"string","examples":["Henrique","Sara (agente)"]},"ator_tipo":{"type":"string","enum":["humano","agente","sistema","webhook"]}}},"Transicao":{"type":"object","required":["para"],"properties":{"para":{"$ref":"#/components/schemas/StatusProposta"},"motivo":{"type":"string","description":"obrigatorio em reprovada_interna e cancelada (min. 5)"},"canal":{"type":"string","enum":["whatsapp","email","manual","zapsign"],"description":"obrigatorio em enviada"},"evidencia":{"type":"string","description":"obrigatoria em aceita: 'print WA 15/11', id da mensagem..."}}},"Equipamento":{"type":"object","description":"linha de v_equipamento_360","properties":{"id":{"type":"integer"},"serial":{"type":"string"},"tipo":{"type":"string"},"status":{"type":"string","enum":["em_fabricacao","disponivel","reservado","reservado_venda","em_preparacao","em_qc","em_manutencao","em_transito","locado","vendido","baixado"]},"local":{"type":["string","null"]},"cliente_atual_cod_og":{"type":["integer","null"]},"cliente_atual_nome":{"type":["string","null"]},"contrato_og_cod":{"type":["string","null"]},"contrato_atual_numero":{"type":["string","null"]}}},"MovimentoEntrada":{"type":"object","required":["tipo","data_movimento","aprovado_por"],"properties":{"tipo":{"type":"string","enum":["saida_locacao","saida_venda","reserva_venda","retorno_locacao","entrada","ajuste"]},"data_movimento":{"type":"string","format":"date","description":"quando aconteceu (nao aceita data futura)"},"data_entrega_prevista":{"type":"string","format":"date","description":"so na reserva_venda (obrigatoria; pode ser futura). Locado: tem que ser depois do vig_final"},"status_para":{"type":"string","description":"so no ajuste (destino); opcional com cancelar_reserva"},"cancelar_reserva":{"type":"boolean","description":"so no ajuste (gestao) - limpa a reserva de venda"},"cliente_id":{"type":"integer","description":"erp.cliente.id"},"cliente_cod_og":{"type":"integer","description":"codigo do cliente no OG (ERP ou espelho)"},"contrato_id":{"type":"integer","description":"erp.contrato.id"},"contrato_og_cod":{"type":"string","description":"codigo do contrato no OG (\"2026-0099\") ou numero do ERP; se nao existir no ERP, grava so o codigo (aviso)"},"aprovado_por":{"type":"string","description":"humano que autorizou (com token de agente: usuario ativo financeiro/gestao/admin)"},"aprovacao_ref":{"type":"string","description":"prova do OK: id da mensagem do WhatsApp / nota. Obrigatoria para agente"},"observacao":{"type":"string","description":"obrigatoria no ajuste (min. 5)"},"fotos":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"referencias (id de midia","URL":null,"caminho)":null}}},"EventoEquipamento":{"type":"object","properties":{"id":{"type":"integer"},"equipamento_id":{"type":"integer"},"tipo":{"type":["string","null"],"description":"nulo nos eventos do importador"},"data_movimento":{"type":["string","null"],"format":"date"},"data_entrega_prevista":{"type":["string","null"],"format":"date"},"status_de":{"type":["string","null"]},"status_para":{"type":["string","null"]},"cliente_id":{"type":["integer","null"]},"cliente_cod_og":{"type":["integer","null"]},"contrato_id":{"type":["integer","null"]},"contrato_og_cod":{"type":["string","null"]},"aprovado_por":{"type":["string","null"]},"aprovacao_ref":{"type":["string","null"]},"observacao":{"type":["string","null"]},"fotos":{"type":["array","null"],"items":{"type":"string"}},"usuario":{"type":["string","null"],"examples":["Henrique","Sara (agente)","importador"]},"ator_tipo":{"type":["string","null"],"enum":["humano","agente","sistema","webhook",null]},"ator_usuario_id":{"type":["integer","null"]},"ator_token_id":{"type":["integer","null"]},"evento":{"type":"string"},"detalhe":{"type":["string","null"]},"criado_em":{"type":"string","format":"date-time"}}},"MovimentoResposta":{"type":"object","properties":{"evento":{"$ref":"#/components/schemas/EventoEquipamento"},"equipamento":{"type":"object","properties":{"id":{"type":"integer"},"serial":{"type":"string"},"status":{"type":"string"},"cliente_atual_id":{"type":["integer","null"]},"cliente_atual_cod_og":{"type":["integer","null"]},"contrato_atual_id":{"type":["integer","null"]},"contrato_og_cod":{"type":["string","null"]},"reserva_venda":{"$ref":"#/components/schemas/ReservaVenda"}}},"permitidas":{"type":"array","items":{"type":"string"},"description":"movimentos aceitos a partir do status novo","para este ator":null},"avisos":{"type":"array","items":{"type":"string"}}}},"ReservaVenda":{"type":["object","null"],"description":"reserva de venda ativa (nula quando nao ha)","properties":{"cliente_id":{"type":["integer","null"]},"cliente_cod_og":{"type":["integer","null"]},"contrato_id":{"type":["integer","null"]},"contrato_og_cod":{"type":["string","null"]},"data_entrega_prevista":{"type":"string","format":"date"},"evento_id":{"type":"integer"}}},"EventosEquipamento":{"type":"object","properties":{"equipamento":{"type":"object","properties":{"id":{"type":"integer"},"serial":{"type":"string"},"status":{"type":"string"}}},"permitidas":{"type":"array","items":{"type":"string"}},"itens":{"type":"array","items":{"$ref":"#/components/schemas/EventoEquipamento"}},"total":{"type":"integer"}}},"TokenEntrada":{"type":"object","required":["usuario","nome","permissoes"],"properties":{"usuario":{"type":"string","examples":["Sara"]},"nome":{"type":"string","examples":["sara@srv1958369"]},"permissoes":{"type":"array","items":{"type":"string"}},"expira_em":{"type":"string","format":"date"}}}}},"security":[{"cookie":[]},{"bearer":[]}],"paths":{"/saude":{"get":{"tags":["sessao"],"security":[],"summary":"healthcheck (publico)","responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"versao":{"type":"string"},"banco_ms":{"type":"integer"}}}}}}}}},"/openapi.json":{"get":{"tags":["sessao"],"security":[],"summary":"este contrato","responses":{"200":{"description":"OpenAPI 3.1"}}}},"/me":{"get":{"tags":["sessao"],"summary":"quem sou e o que posso","responses":{"200":{"description":"identidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"sem sessao ou token invalido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/clientes":{"get":{"tags":["clientes"],"summary":"busca por nome parecido (trigram, sem acento) ou documento, ERP + espelho do OG","description":"acao `cliente:buscar`. Sem `q`, lista os primeiros. `q` com so digitos busca por documento (prefixo).","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"example":"nutri"},{"name":"fonte","in":"query","schema":{"type":"string","enum":["erp","og"]}},{"name":"limite","in":"query","schema":{"type":"integer","default":20,"maximum":50}}],"responses":{"200":{"description":"lista","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/ClienteBusca"}},"total":{"type":"integer"}}}}}}}},"post":{"tags":["clientes"],"summary":"cadastrar cliente no ERP (acao cliente:criar)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClienteEntrada"}}}},"responses":{"201":{"description":"criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cliente"}}}},"400":{"description":"validacao (CNPJ/CPF invalido","campo faltando)":null},"409":{"description":"documento duplicado (codigo documento_duplicado","traz cliente_id)":null}}}},"/clientes/{id}":{"parameters":[{"$ref":"#/components/parameters/id"}],"get":{"tags":["clientes"],"summary":"pagina 360 do cliente (dados, contatos, historico unificado, resumo, negocios, equipamentos)","responses":{"200":{"description":"cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cliente"}}}},"404":{"description":"nao encontrado"}}},"patch":{"tags":["clientes"],"summary":"editar campos do cliente (acao cliente:editar)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClienteEntrada"}}}},"responses":{"200":{"description":"cliente atualizado"},"409":{"description":"documento duplicado"}}}},"/clientes/og/{cod_og}":{"get":{"tags":["clientes"],"summary":"pre-visualizar cliente que so existe no espelho do Otimo Gestor (nao cria nada)","parameters":[{"name":"cod_og","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"cliente do espelho com historico por cod_og (id null se nao esta no ERP)"},"404":{"description":"nao existe no espelho"}}}},"/clientes/importar-og/{cod_og}":{"post":{"tags":["clientes"],"summary":"trazer cliente do espelho para o ERP (cria erp.cliente ligado por cod_og; idempotente)","parameters":[{"name":"cod_og","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"documento":{"type":"string","description":"so quando o espelho nao tem CNPJ"}}}}}},"responses":{"200":{"description":"ja existia; devolve o existente"},"201":{"description":"criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cliente"}}}},"400":{"description":"espelho sem documento e nenhum informado (campo documento)"},"409":{"description":"documento ja esta em outro cliente do ERP"}}}},"/clientes/{id}/contatos":{"post":{"tags":["clientes"],"summary":"adicionar contato (acao cliente:contato)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContatoEntrada"}}}},"responses":{"201":{"description":"contato"}}}},"/clientes/{id}/contatos/{cid}":{"patch":{"tags":["clientes"],"summary":"editar/inativar contato","parameters":[{"$ref":"#/components/parameters/id"},{"name":"cid","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ContatoEntrada"},{"type":"object","properties":{"ativo":{"type":"boolean"}}}]}}}},"responses":{"200":{"description":"contato"}}}},"/negocios":{"get":{"tags":["negocios"],"summary":"o funil (v_pipeline), com a barra de 5 etapas por negocio","parameters":[{"name":"situacao","in":"query","schema":{"type":"string","enum":["andamento","concluidos","perdidos","todos"],"default":"andamento"}},{"name":"etapa","in":"query","schema":{"type":"string"}},{"name":"responsavel","in":"query","schema":{"type":"string"}},{"name":"cliente_id","in":"query","schema":{"type":"integer"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"nome do prospect/cliente","numero do negocio ou da proposta":null},{"$ref":"#/components/parameters/pagina"},{"$ref":"#/components/parameters/por_pagina"}],"responses":{"200":{"description":"lista","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/Negocio"}},"total":{"type":"integer"},"pagina":{"type":"integer"}}}}}}}},"post":{"tags":["negocios"],"summary":"abrir negocio (com proposta em rascunho junto, se vier `proposta`)","description":"acao `negocio:criar` (+ `proposta:criar` implicita). Exemplo do plano 5.5.4.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegocioEntrada"},"example":{"prospect_nome":"Padaria do Joao","prospect_telefone":"5522999990000","tipo":"locacao","responsavel":"Stella","origem":"whatsapp","cidade_entrega":"Goiania","uf_entrega":"GO","proposta":{"tipo":"locacao","prazo_meses":18,"dia_vencimento":10,"valida_ate":"2026-11-29","tipo_frete":"cif","valor_frete":3990,"valor_mobilizacao":3990,"valor_desmobilizacao":3990,"munck_incluso":false,"itens":[{"descricao":"Modulo minimercado 20 pes","tipo_produto":"modulo","quantidade":1,"valor_unitario":1650,"periodicidade":"mensal"}]}}}}},"responses":{"201":{"description":"criado","content":{"application/json":{"schema":{"type":"object","properties":{"negocio":{"$ref":"#/components/schemas/Negocio"},"proposta":{"oneOf":[{"$ref":"#/components/schemas/Proposta"},{"type":"null"}]}}}}}},"400":{"description":"validacao (responsavel precisa ser usuario humano ativo)"}}}},"/negocios/resumo":{"get":{"tags":["negocios"],"summary":"contagem e valor por etapa (acao pipeline:ler)","responses":{"200":{"description":"resumo"}}}},"/negocios/{id}":{"parameters":[{"$ref":"#/components/parameters/id"}],"get":{"tags":["negocios"],"summary":"negocio completo (proposta atual, revisoes, contrato, eventos)","responses":{"200":{"description":"negocio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegocioCompleto"}}}},"404":{"description":"nao encontrado"}}},"patch":{"tags":["negocios"],"summary":"editar dados do prospect/negocio","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NegocioEntrada"}}}},"responses":{"200":{"description":"negocio"}}}},"/negocios/{id}/perder":{"post":{"tags":["negocios"],"summary":"marcar como perdido (acao negocio:perder; motivo obrigatorio)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["motivo"],"properties":{"motivo":{"type":"string","minLength":5}}}}}},"responses":{"200":{"description":"negocio"},"409":{"description":"ja encerrado"},"422":{"description":"contrato em assinatura/faturamento"}}}},"/propostas":{"post":{"tags":["propostas"],"summary":"criar proposta num negocio que nao tem proposta ativa (acao proposta:criar)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PropostaEntrada"},{"type":"object","required":["negocio_id"],"properties":{"negocio_id":{"type":"integer"}}}]}}}},"responses":{"201":{"description":"proposta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposta"}}}},"409":{"description":"ja existe proposta ativa (proposta_ativa_existente)"}}}},"/propostas/{id}":{"parameters":[{"$ref":"#/components/parameters/id"}],"get":{"tags":["propostas"],"summary":"proposta com itens e transicoes permitidas","responses":{"200":{"description":"proposta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposta"}}}}}},"patch":{"tags":["propostas"],"summary":"editar cabecalho (so em rascunho; acao proposta:editar)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropostaEntrada"}}}},"responses":{"200":{"description":"proposta recalculada"},"409":{"description":"nao_editavel"}}}},"/propostas/{id}/itens":{"put":{"tags":["propostas"],"summary":"substituir a lista inteira de itens (so em rascunho; acao proposta:item)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["itens"],"properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/ItemProposta"}}}}}}},"responses":{"200":{"description":"proposta recalculada"}}}},"/propostas/{id}/transicao":{"post":{"tags":["propostas"],"summary":"uma rota, N acoes (maquina de estados da proposta)","description":"| para | acao exigida | quem (perfil) | regra |\n|---|---|---|---|\n| aguardando_aprovacao | proposta:pedir_aprovacao | comercial, financeiro, gestao, admin, agente | >=1 item, total > 0, valida_ate |\n| aprovada_interna / reprovada_interna | proposta:aprovar / proposta:reprovar | **gestao, admin** (agente nunca) | reprovar exige motivo |\n| rascunho (de reprovada_interna) | proposta:editar | | volta para corrigir |\n| enviada | proposta:marcar_enviada | | exige canal |\n| aceita | proposta:marcar_aceita | | exige evidencia; negocio vai para aprovacao_cliente |\n| recusada | proposta:marcar_recusada | | |\n| expirada | proposta:editar | | so com validade vencida (o job diario faz sozinho) |\n| cancelada | proposta:cancelar | | exige motivo |\n","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transicao"},"examples":{"pedir":{"value":{"para":"aguardando_aprovacao"}},"aceitar":{"value":{"para":"aceita","evidencia":"print WhatsApp 15/11 (msg 3EB0...)"}}}}}},"responses":{"200":{"description":"proposta + etapa do negocio","content":{"application/json":{"schema":{"type":"object","properties":{"proposta":{"$ref":"#/components/schemas/Proposta"},"negocio":{"type":"object","properties":{"id":{"type":"integer"},"numero":{"type":"string"},"etapa":{"type":"string"}}}}}}}},"403":{"description":"acao nao permitida para o ator (ex.: token tentando aprovar)"},"409":{"description":"transicao_invalida, com permitidas[]"},"422":{"description":"regra de negocio (sem itens","sem validade":null,"valor zero)":null}}}},"/propostas/{id}/revisar":{"post":{"tags":["propostas"],"summary":"criar revisao (nova proposta rev+1; a anterior vira substituida)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropostaEntrada"},"description":"so o que muda; o resto e copiado da anterior"}}},"responses":{"201":{"description":"nova proposta"},"409":{"description":"nao_revisavel"}}}},"/propostas/{id}/pdf":{"post":{"tags":["propostas"],"summary":"gerar o PDF (v1 HTML -> LibreOffice; grava proposta.arquivo_pdf)","parameters":[{"$ref":"#/components/parameters/id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"201":{"description":"arquivo","content":{"application/json":{"schema":{"type":"object","properties":{"arquivo":{"type":"string"},"sha256":{"type":"string"},"bytes":{"type":"integer"},"motor":{"type":"string"}}}}}},"502":{"description":"LibreOffice falhou"}}},"get":{"tags":["propostas"],"summary":"baixar o PDF gerado","parameters":[{"$ref":"#/components/parameters/id"}],"responses":{"200":{"description":"application/pdf"},"404":{"description":"ainda nao gerado"}}}},"/equipamentos":{"get":{"tags":["equipamentos"],"summary":"lista (v_equipamento_360) com filtros","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"tipo","in":"query","schema":{"type":"string"}},{"name":"local","in":"query","schema":{"type":"string"}},{"name":"cliente_cod_og","in":"query","schema":{"type":"integer"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"serial","serial do fabricante":null,"cliente":null,"contrato OG ou codigo de produto":null},{"$ref":"#/components/parameters/pagina"},{"$ref":"#/components/parameters/por_pagina"}],"responses":{"200":{"description":"lista","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/Equipamento"}},"total":{"type":"integer"}}}}}}}}},"/equipamentos/estoque":{"get":{"tags":["equipamentos"],"summary":"estoque por status","por local x tipo e por tipo x subcategoria; tipos e locais":null,"responses":{"200":{"description":"estoque"}}}},"/equipamentos/{id}":{"get":{"tags":["equipamentos"],"summary":"360 do equipamento (eventos, historico de contratos, componentes, reconciliacao com o espelho)","parameters":[{"$ref":"#/components/parameters/id"}],"responses":{"200":{"description":"equipamento"},"404":{"description":"nao encontrado"}}}},"/equipamentos/{id}/eventos":{"parameters":[{"$ref":"#/components/parameters/id"}],"get":{"tags":["equipamentos"],"summary":"trilha do equipamento (equipamento_evento, mais recente primeiro) + movimentos permitidos ao ator agora (acao equipamento:ler)","responses":{"200":{"description":"eventos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventosEquipamento"}}}},"404":{"description":"nao encontrado"}}},"post":{"tags":["equipamentos"],"summary":"lancar movimento de estoque (acao equipamento:evento; ajuste exige equipamento:ajuste)","description":"Uma transacao: grava o evento, muda status/cliente/contrato do equipamento e o historico contrato x equipamento.\n**Agente (Sara) so lanca com o OK explicito de um humano**: `aprovado_por` (usuario ativo financeiro/gestao/admin,\nna pratica o Henrique) e `aprovacao_ref` (id da mensagem do WhatsApp ou nota com o OK) sao obrigatorios; sem eles 422.\n\n| tipo | de | para | exige |\n|---|---|---|---|\n| saida_locacao | disponivel | locado | contrato (contrato_id ou contrato_og_cod); cliente sai do contrato se nao vier |\n| saida_venda | disponivel, reservado_venda | vendido | cliente ou contrato; em reservado_venda usa o comprador da reserva (outro: 409 reservado_para_venda) e limpa a reserva |\n| reserva_venda | disponivel / locado | reservado_venda / locado | data_entrega_prevista (pode ser futura) + comprador; contrato de venda opcional. **Locado**: so se data_entrega_prevista > vig_final do contrato atual |\n| retorno_locacao | locado | disponivel (ou reservado_venda se reservado) | limpa cliente/contrato e fecha o vinculo; se vier contrato/cliente, tem que ser o atual |\n| entrada | em_fabricacao, em_transito | disponivel | so serial ja cadastrado; sem cliente/contrato |\n| ajuste | qualquer | status_para | **gestao/admin** (equipamento:ajuste); observacao (motivo) obrigatoria; cancelar_reserva=true limpa a reserva |\n\nReserva de venda de container locado: vig_final nulo ou ja passado (renovacao tacita) -> `409 fim_de_locacao_indefinido`\n(confirmar o fim da locacao antes; a data nao e presumida); entrega ate vig_final -> `409 entrega_dentro_da_locacao` (com vig_final).\nCom reserva: saida_locacao e nova reserva -> `409 reservado_para_venda`. saida_venda direto de locado -> `409 transicao_invalida`\ncom `permitidas` incluindo reserva_venda e `dica`.\n\nTransicao fora da matriz: `409 transicao_invalida` com `de`, `para`, `tipo` e `permitidas[]` (tipos aceitos a partir do status atual).\nMesma `Idempotency-Key` devolve o evento original (`Idempotent-Replay: true`), inclusive depois das 24 h (chave guardada no evento).\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovimentoEntrada"},"examples":{"saida":{"value":{"tipo":"saida_locacao","data_movimento":"2026-11-21","contrato_og_cod":"2026-0099","aprovado_por":"Henrique","aprovacao_ref":"wa:5522999990000:3EB0A1 \"pode liberar o SSGU 298617 2\""}}}}}},"responses":{"201":{"description":"evento gravado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovimentoResposta"}}}},"400":{"description":"validacao (tipo","data_movimento":null,"aprovado_por":null,"contrato na saida_locacao":null,"observacao no ajuste)":null},"403":{"description":"acao nao permitida (comercial; agente ou financeiro tentando ajuste)"},"404":{"description":"equipamento nao encontrado"},"409":{"description":"transicao_invalida (com permitidas[] e dica), reservado_para_venda, fim_de_locacao_indefinido, entrega_dentro_da_locacao (com vig_final), idempotency_key_reutilizada, serial_ambiguo"},"422":{"description":"aprovacao_obrigatoria, aprovador_invalido, data_futura, sem_reserva, cliente_nao_encontrado, contrato_nao_encontrado, cliente_contrato_divergente, contrato_divergente, cliente_divergente, data_anterior_ao_vinculo"}}}},"/equipamentos/serial/{serial}/eventos":{"parameters":[{"name":"serial","in":"path","required":true,"schema":{"type":"string"},"description":"serial exato (\"SSGU 150035 2\", url-encoded) ou sem espacos, se unico"}],"get":{"tags":["equipamentos"],"summary":"o mesmo que GET /equipamentos/{id}/eventos, pelo serial","responses":{"200":{"description":"eventos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventosEquipamento"}}}},"404":{"description":"nao encontrado"}}},"post":{"tags":["equipamentos"],"summary":"o mesmo que POST /equipamentos/{id}/eventos, pelo serial (o jeito da Sara)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovimentoEntrada"}}}},"responses":{"201":{"description":"evento gravado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovimentoResposta"}}}},"403":{"description":"acao nao permitida"},"404":{"description":"equipamento nao encontrado"},"409":{"description":"transicao_invalida / idempotency_key_reutilizada / serial_ambiguo"},"422":{"description":"regra (aprovacao_obrigatoria","aprovador_invalido...)":null}}}},"/cadastros":{"get":{"tags":["sessao"],"summary":"listas de apoio (tipos","locais":null,"subcategorias":null,"usuarios humanos":null,"origens)":null,"responses":{"200":{"description":"cadastros"}}}},"/eventos":{"get":{"tags":["auditoria"],"summary":"trilha de um negocio (negocio_evento)","parameters":[{"name":"negocio_id","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"eventos","content":{"application/json":{"schema":{"type":"object","properties":{"itens":{"type":"array","items":{"$ref":"#/components/schemas/Evento"}}}}}}}}}},"/auditoria":{"get":{"tags":["auditoria"],"summary":"auditoria de escritas (acao auditoria:ler; comercial ve so as proprias)","parameters":[{"name":"ref_tipo","in":"query","schema":{"type":"string"}},{"name":"ref_id","in":"query","schema":{"type":"integer"}},{"name":"ator","in":"query","schema":{"type":"string"}},{"name":"ator_tipo","in":"query","schema":{"type":"string","enum":["humano","agente","sistema","webhook"]}},{"name":"acao","in":"query","schema":{"type":"string"}},{"name":"desde","in":"query","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/pagina"},{"$ref":"#/components/parameters/por_pagina"}],"responses":{"200":{"description":"linhas de auditoria"}}}},"/admin/tokens":{"get":{"tags":["admin"],"summary":"listar tokens (sem o hash)","responses":{"200":{"description":"lista"}}},"post":{"tags":["admin"],"summary":"criar token de servico (o token em claro aparece UMA vez)","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEntrada"}}}},"responses":{"201":{"description":"token criado (campo token so nesta resposta)"},"400":{"description":"acao fora do perfil do usuario"}}}},"/admin/tokens/{id}":{"parameters":[{"$ref":"#/components/parameters/id"}],"patch":{"tags":["admin"],"summary":"mudar permissoes / ativo / expira_em (sem deploy)","responses":{"200":{"description":"token"}}},"delete":{"tags":["admin"],"summary":"revogar (ativo=false)","responses":{"200":{"description":"revogado"}}}},"/admin/usuarios":{"get":{"tags":["admin"],"summary":"usuarios e perfis","responses":{"200":{"description":"lista"}}},"post":{"tags":["admin"],"summary":"criar usuario","responses":{"201":{"description":"usuario"}}}},"/admin/usuarios/{id}":{"patch":{"tags":["admin"],"summary":"mudar perfil / ativo / email","parameters":[{"$ref":"#/components/parameters/id"}],"responses":{"200":{"description":"usuario"}}}}}}