Changelog

A API segue versionamento na URL (api-v1-*). Mudanças que quebram contrato sobem a versão major; acréscimos compatíveis (novos campos opcionais) podem entrar sem nova versão.

v1

Primeira versão pública da API REST do CRM Vendee. Recursos disponíveis:

• Leads — POST /api-v1-leads: entrada de lead com criação automática de empresa, contato e negócio; idempotência por external_id.
• Negócios — GET /api-v1-deals (lista com filtros e paginação), GET /api-v1-deals/:id (com contato, empresa e última atividade), POST/PATCH, e as ações move-stage, win e lose.
• Contatos — GET /api-v1-contacts (lista + detalhe), POST/PATCH.
• Empresas — GET /api-v1-companies (lista + detalhe), POST/PATCH.
• Pipelines — GET /api-v1-pipelines: funis e etapas do workspace.
• Autenticação por API Key (X-API-Key: vnd_...) com escopos por recurso e isolamento por workspace.
• Gestão de chaves (criar / listar / revogar) pelo app, restrita a administradores e gestores.

Webhooks

• Webhooks — assinatura de eventos com entrega assinada (HMAC), régua de reenvio e histórico de entregas. Veja Webhooks.

Mudanças de agosto de 2026

Nenhuma quebra de contrato — tudo abaixo é acréscimo compatível.

• Cinco eventos novos de webhook. deal.created, contact.created e lead.received passaram a ser emitidos de verdade (constavam no catálogo e nunca disparavam), e proposal.accepted / proposal.rejected tornaram-se assináveis. O catálogo vai de 7 para 12 eventos.
• As ações de negócio pela API agora disparam webhook. POST /api-v1-deals/:id/move-stage, /win e /lose emitem deal.stage_changed, deal.won e deal.lost — antes só a movimentação feita pelo app disparava. A emissão é best-effort: uma falha ao enfileirar nunca altera a resposta da API, e o retorno antecipado de /win e /lose em negócio já fechado continua idempotente, sem duplicar evento.
• Histórico de entregas no app. Em Configurações › API e Integrações há uma seção com os últimos 50 envios: evento, situação, resposta do seu servidor e quando — é onde se descobre por que um webhook parou de chegar.
• A tela de chaves abre mesmo com a API desligada, em modo somente leitura, para explicar o motivo. O acesso continua barrado no servidor: toda chave é verificada a cada uso.

Mudanças de setembro de 2026

Nenhuma quebra de contrato: o que já funcionava continua respondendo igual.

• Notas pela API. GET /api-v1-notes, GET /api-v1-notes/:id e POST /api-v1-notes para ler e registrar observações em negócios, com os escopos notes:read e notes:write. Veja Notas.
• Reenvio sem duplicar. Os POST de negócios, contatos, empresas, atividades e notas aceitam o cabeçalho Idempotency-Key: repetir a mesma chamada (por exemplo, depois de uma queda de rede) devolve o registro já criado em vez de criar outro. Veja Atividades → Idempotência.
• Referência gerada da mesma fonte que a API usa. As fichas de cada recurso (Negócios, Contatos, Empresas, Atividades, Notas, Pipelines, Leads, Webhooks) passam a ter campos, erros e exemplos gerados do mesmo catálogo que o servidor lê. Some a chance de a documentação dizer uma coisa e a API fazer outra.
• Cinco fichas novas publicadas para você se preparar — ainda sem endereço no ar. Responsáveis, Origens de lead, Motivos de perda, Tipos de atividade e Campos personalizados já têm página de referência. Chamar o endereço delas hoje devolve 404 not_found; avisaremos aqui quando cada uma entrar no ar. Elas existem porque hoje a API devolve owner_id e loss_reason_id sem nenhum jeito de descobrir o nome por trás do código.
• Criar uma chave passa a aceitar qualquer escopo bem formado, no formato recurso:read, recurso:write ou recurso:manage — antes era uma lista fechada, e cada recurso novo exigia mudança no servidor para a chave poder nascer com ele. Um escopo bem formado cujo endereço ainda não existe fica registrado na chave, mas inerte: não libera acesso a nada até o endereço correspondente entrar no ar. O que vale hoje continua listado em Chaves e escopos.