Changelog

2026-11-14Copy Anchor Link

Adicionado

• MCP: operadores podem conectar agentes quando a organização liga Permitir que operadores conectem agentes (Configurações → API → Conexão com IA; desligada por padrão). O agente vê e faz só o que a pessoa que autorizou vê e faz na tela: permissões oferecidas conforme as dela, conversas e grupos na mesma visibilidade da caixa de entrada e indicadores no recorte do dashboard dela. Veja Conectar um agente por MCP.
• Indicadores e relatórios (GET /analytics/snapshot e GET /analytics/reports/*) trazem scope (org, department ou own) quando lidos por uma conexão de agente. Chaves de API comuns não mudam.
• Erro 403 missing_permission: a pessoa que autorizou a conexão de agente não tem mais a permissão no CRM. Veja Erros.

Mudado

• MCP: as permissões da conexão são conferidas a cada chamada contra as permissões atuais de quem autorizou, e não só contra o papel de proprietário ou administrador.

2026-11-13Copy Anchor Link

Adicionado

• Endpoints de leitura em Beta: GET /pipelines (funis com etapas em ordem), GET /members (equipe; user_id é o assigned_to de negócios e conversas), GET /conversations (lista com contato, canal, situação, responsável e última atividade; filtros status/channel/assigned_to/contact_id/is_group/active_since/active_until) e GET /conversations/{id}/messages (texto e transcrição das mensagens, sem o arquivo de mídia). As listas de conversas e mensagens paginam com has_more, sem total.
• O escopo conversations:read deixa de ser reservado: libera GET /conversations e, junto com messages:read, a leitura das mensagens.
• GET /deals aceita o filtro assigned_to, e os negócios passam a trazer product_id, assigned_to, won_at, lost_at e lost_reason.
• MCP: novas ferramentas de leitura linha a linha (listar_funis, listar_equipe, listar_negocios, listar_contatos, consultar_contato, listar_conversas, ler_mensagens e buscar_mensagens), cada uma com permissão própria na tela de consentimento. Veja Conectar um agente por MCP.
• Endpoints de leitura em Beta: GET /campaigns (campanhas de disparo com contadores, sem destinatários), GET /automations (gatilho, situação e uso, sem o fluxo), GET /tasks, GET /appointments (sem anotações internas, link da reunião e token de cancelamento), GET /forms (contadores e perguntas) e GET /forms/{id}/responses (sem respostas de teste). Todas paginam com has_more e next_offset, sem total.
• MCP: seis ferramentas de leitura (listar_campanhas, listar_automacoes, listar_tarefas, listar_agendamentos, listar_formularios e listar_respostas_formulario), totalizando 26 ferramentas.
• Endpoints de relatórios agregados em Beta, com o escopo analytics:read e sem dados de contato: GET /analytics/reports/funnel, GET /analytics/reports/service, GET /analytics/reports/dispatch e GET /analytics/reports/operations. Todos aceitam days de 1 a 90 (padrão 30) no fuso da organização; o do funil aceita também pipeline_id. Veja a referência.
• MCP: quatro ferramentas de relatório (relatorio_funil, relatorio_atendimento, relatorio_disparos e relatorio_operacoes), totalizando 30 ferramentas.
• Endpoint GET /groups/broadcasts: lista as mensagens agendadas em grupos (as 500 mais recentes da organização, de qualquer origem), com situação agregada, contadores por grupo e filtro status. No MCP, a ferramenta listar_agendamentos_em_grupos, totalizando 31 ferramentas.
• Escritas internas em Beta: POST /tasks (cria tarefa para a equipe, vinculada a negócio, contato ou conversa), POST /tasks/{id}/complete (conclui em nome de quem criou a chave; tarefa já concluída volta com changed: false e cancelada responde 409) e POST /notes (nota interna em contato ou negócio, só para a equipe). Exigem os novos escopos tasks:write e notes:write e o cabeçalho Idempotency-Key; a repetição devolve o recibo com replayed: true. Nada é enviado ao contato e nenhuma automação dispara. Veja a referência.
• MCP: três ferramentas de ação, criar_tarefa, concluir_tarefa e registrar_nota_interna, totalizando 34 ferramentas. As permissões tasks:write e notes:write vêm desmarcadas na tela de consentimento e o aplicativo pede confirmação a cada chamada.

Mudado

• MCP: toda lista responde no mesmo formato, data, total (null quando o CRM não conta o filtro), has_more e next_offset. Deixam de existir pagination e as chaves groups, broadcasts, deliveries, contracts, templates e context; atualize instruções salvas que as citem. A API REST não muda.
• MCP: listar_funis e relatorio_funil trocam position da etapa por stage_order, a partir de 1, como em consultar_indicadores. listar_funis troca também position do funil por pipeline_order, a partir de 1. relatorio_funil omite por padrão as etapas e os funis sem negócio aberto e sem movimento na janela, informando quantos em hidden_empty_stages e hidden_empty_pipelines; hide_empty_stages: false traz todos.
• MCP: buscar_mensagens e listar_agendamentos_da_agenda só devolvem telefone e e-mail com include_contact_details: true; a foto do contato deixa de sair. listar_contratos aceita from e to em AAAA-MM-DD.
• MCP: filtros de data em AAAA-MM-DD passam a ser lidos como 00:00 no fuso horário da organização, em todas as listas; antes valiam em UTC. Instante com offset continua valendo como informado. A API REST não muda.
• MCP: buscar_contexto_contrato passa a encontrar o negócio também pelo nome do produto em q, para quem pode ver produtos.
• GET /tasks: a tarefa aberta com vencimento passado sai com status overdue, e o filtro status=overdue passa a devolvê-las; pending e in_progress filtram só as em dia.
• GET /conversations/{id}/messages: sender_kind vem contact nas mensagens recebidas, em vez de null.
• Leituras que o banco recusa sempre respondem 500 com code query_rejected; no MCP, a consulta deixa de vir marcada como retryable.
• MCP: consultar_agendamento passa a se chamar consultar_agendamento_em_grupos e listar_agendamentos passa a se chamar listar_agendamentos_da_agenda, para um agente não confundir a agenda de reuniões com mensagens agendadas em grupos. Aplicativos conectados recebem os nomes novos na próxima listagem de ferramentas; atualize instruções salvas que citem os nomes antigos.
• Agendamento em grupos por conexão de agente (MCP): no máximo 200 destinos a cada 24 horas por pessoa e organização, somando as conexões dela. Acima disso POST /groups/broadcasts responde 429 daily_limit e nada é agendado. Chaves de integração comuns não mudam.
• Escritas por conexões de agente (POST /tasks, POST /tasks/{id}/complete e POST /notes): no máximo 200 por pessoa e organização a cada 24 horas, somando tarefas e notas e as conexões dela. Acima disso a resposta é 429 daily_limit e nada é gravado. Chaves de integração criadas em Configurações → API não têm esse teto.
• MCP: agendar_mensagens_em_grupos, preparar_contrato e enviar_contrato_para_assinatura passam a ser anunciadas como ações que pedem confirmação a cada chamada (destructiveHint). A lista de ferramentas informa validade de 5 minutos e cache privado à conexão (ttlMs, cacheScope) aos aplicativos que usam a revisão 2026-07-28 do protocolo, atendida no mesmo endereço dos aplicativos anteriores.
• MCP: todos os campos das ferramentas têm descrição; scheduled_at de agendar_mensagens_em_grupos é validado antes do envio (AAAA-MM-DDTHH:mm:ss, com offset opcional) e um lote recusado informa o que conferir. Nomes de grupos saem sem caracteres invisíveis, como já acontecia nas demais leituras.
• Chaves com analytics:read, deals:read e contacts:read passam a alcançar os endpoints novos: analytics:read lista campanhas e automações, deals:read lista tarefas e contacts:read lista agendamentos e respostas de formulários. GET /forms aceita contacts:read ou analytics:read.
• Chaves já existentes passam a alcançar os endpoints novos conforme os escopos que têm: conversations:read lista conversas, conversations:read + messages:read lê o texto das mensagens, e deals:read ou conversations:read lista a equipe (nome e papel). Revise os escopos das suas chaves em Configurações → API e revogue o que não usa.

Corrigido

• GET /pipelines (e a ferramenta listar_funis do MCP) respondia 500 em toda chamada: o vínculo entre funis e etapas ficou ambíguo para o banco. A consulta agora nomeia o vínculo.

2026-08-20Copy Anchor Link

Adicionado

• Endpoint POST /messages/send em Beta. Envia mensagem WhatsApp (texto ou mídia) por uma conexão WhatsApp da organização, com destino em exatamente um entre conversation_id, contact_id ou phone (contato/conversa criados quando necessário). Suporta mídia via media_url pública (image/video/audio/document, com content como caption) e operador opcional via sender_user_id — a mensagem sai assinada e, com assign_conversation (default true), a conversa sem dono é atribuída a ele. O envio é assíncrono via fila do CRM (resposta 201 com queued: true) e respeita opt-out LGPD (403 contact_opted_out). Requer o novo escopo messages:write (agora disponível em Configurações → API).

2026-07-03Copy Anchor Link

Adicionado

• Endpoints de leitura em Beta: GET /contacts (lista com busca livre q, filtros email/phone/source e sync incremental por created_since/updated_since), GET /contacts/{id}, GET /deals (filtros pipeline_id/stage_id/contact_id/status/external_id + sync incremental) e GET /deals/{id}. Leitura de negócios usa o novo escopo deals:read.
• Base URL versionada https://crm.oficinamartech.com/api/v1 — agora a forma canônica. O caminho sem versão (/api) segue funcionando como alias legado, sem data de sunset.

Mudado

• A especificação OpenAPI publicada em /openapi.json passa a ser a única fonte da verdade do contrato (versão 0.2.0), gerada dos mesmos schemas Zod que validam as requisições.

2026-06-15Copy Anchor Link

Corrigido

• POST /contacts e POST /deals agora tratam strings vazias ("") em campos opcionais como ausentes. Integrações no-code (n8n, Make, Zapier) costumam enviar email: "" quando não há valor; antes isso retornava 400 Invalid email mesmo com telefone informado. A regra continua a mesma — basta email ou telefone para identificar o contato.

2026-06-14Copy Anchor Link

Adicionado

• Endpoint POST /deals em Beta. Cria um negócio em uma etapa do pipeline (pipeline_id + stage_id obrigatórios), com value, currency, status, expected_close_date, assigned_to e source. Pode vincular um contato por contact.id ou criá-lo por contact.email/contact.phone (mesma lógica do POST /contacts). custom_fields é gravado em metadata (chaves de negócio cadastradas são validadas). Idempotência por external_id. Requer o escopo deals:write (agora disponível).

2026-06-13Copy Anchor Link

Adicionado

• Endpoint POST /contacts em Beta. Cria ou atualiza um contato (upsert por email → telefone), com name, email, phone, UTMs, fbclid/gclid/src/sck, landing_page_url/referrer e campos personalizados. A organização é resolvida pela API key. Requer o escopo contacts:write (agora disponível).

2026-05-20Copy Anchor Link

Adicionado

• CORS habilitado em GET /contacts/message-search para suportar playground em docs.crm.oficinamartech.com. Origens permitidas via env DOCS_PLAYGROUND_ORIGINS. Handler OPTIONS retorna 204 com preflight headers.

Mudado

• Documentação completamente reescrita. Estrutura Diátaxis (Começar / Guias / Referência / Recursos), aparência Mintlify/Resend, busca cmd+K funcional, dark/light toggle, mobile-friendly. Worker JS legado em apps/docs substituído por Next.js + Fumadocs.

2026-05-19Copy Anchor Link

Adicionado

• Endpoint GET /contacts/message-search em Beta. Busca contatos por termos em mensagens com filtros de canal, direção e tempo.
• Documentação pública em docs.crm.oficinamartech.com.

Convenções de versionamentoCopy Anchor Link

• Adicionado — novo recurso ou endpoint
• Mudado — alteração em comportamento ou contrato existente
• Corrigido — fix de bug em comportamento documentado
• Depreciado — recurso marcado para remoção futura (com data de Sunset)
• Removido — recurso retirado (só ocorre após período de deprecação)
• Segurança — fix com implicação de segurança