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 › Dados e integraçõ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.

Lead sem e-mail reaproveita o contato pelo telefone. POST /api-v1-leads sem email compara o phone (em qualquer formato) com os contatos da conta e, se achar, liga o lead a esse contato (created.contact vem false) em vez de criar outro. Com email informado nada muda. Veja Leads.
Busca de contato por telefone. GET /api-v1-contacts/telefone/buscar?telefone=... encontra um contato pelo telefone, em qualquer formato — a busca normaliza o número antes de comparar contra phone, phone2 e whatsapp. Escopo contacts:read. Veja Contatos.
Aviso quando o responsável muda. Os eventos deal.owner_changed e lead.owner_changed avisam sua integração quando o responsável de um negócio ou lead muda (pela tela, pelo Otto ou por automação), com from_owner_id e to_owner_id em context. Veja Webhooks.
Campo personalizado com chave inexistente agora é recusado. Gravar custom_fields com uma chave que não foi cadastrada em Configurações › Listas do CRM › Campos devolve 422 validation_error, em negócios, contatos e empresas.
Chave de API revogada pode ser apagada. Uma chave já revogada some da lista de vez, pelo botão Apagar em Configurações › Dados e integrações › API e Integrações.
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 de catálogo entraram no ar. Responsáveis, Origens de lead, Motivos de perda, Tipos de atividade e Campos personalizados (escopo catalogos:read) já respondem de verdade — a chamada deixou de devolver 404 not_found. Elas existem porque a API devolve owner_id e loss_reason_id sem nenhum jeito de descobrir o nome por trás do código. Veja Chaves e escopos.
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.

Mudanças de outubro de 2026