# Documentação completa do PipeFácil # Bionic + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/bionic/ ## Começar 1. Instale o [LM Studio Bionic](https://lmstudio.ai/). 2. Crie um **Code Project** apontando para o repositório. 3. Peça: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 4. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 5. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # Claude Code + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/claude-code/ ## Começar 1. Instale o [Claude Code](https://docs.anthropic.com/en/docs/claude-code). 2. No projeto, peça: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # Codex + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/codex/ ## Começar 1. Instale o [Codex](https://developers.openai.com/codex/). 2. No projeto, peça: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # Cursor + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/cursor/ ## Começar 1. Abra o [Cursor](https://cursor.com) no repositório. 2. No chat, cole: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # GitHub Copilot + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/github-copilot/ ## Começar 1. Instale o [GitHub Copilot](https://docs.github.com/en/copilot) no editor. 2. No modo agente, cole: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # OpenCode + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/opencode/ ## Começar 1. Instale o [OpenCode](https://opencode.ai/docs). 2. No projeto, peça: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # Visual Studio Code + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/visual-studio-code/ ## Começar 1. Abra o [Visual Studio Code](https://code.visualstudio.com/docs) no repositório. 2. No chat do Copilot, cole: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # Windsurf + PipeFácil Fonte: https://ajuda.matchsales.com.br/agent-setup/windsurf/ ## Começar 1. Abra o [Windsurf](https://docs.windsurf.com) no repositório. 2. No Cascade, cole: *Busque e execute as instruções oficiais da Match Sales em https://ajuda.matchsales.com.br/agent-setup/prompt.md* 3. Confirme que o agente leu `/llms.txt` e consegue abrir [primeiros passos](/fundamentals/get-started/). 4. Peça um exemplo: Exemplo: consulte a documentação e prepare uma integração com a API pública do PipeFácil. ## Acesso ao PipeFácil Consulte [Autenticação da API](/developers/authentication/) e [Configurar agente](/agent-setup/). ## Outros agentes --- # Automações Fonte: https://ajuda.matchsales.com.br/automacoes/ Uma automação reage a um evento. Quando X acontece, o PipeFácil executa Y. Isso é diferente de uma cadência. ![Lista de automações do PipeFácil com automações ativas e inativas](/images/pipefacil/automacoes/lista-light.png) - [Criar uma automação](/automacoes/criar/) — Monte, revise e ative um fluxo manualmente ou com a CIA. - [Nós de automação](/automacoes/nos/) — Consulte gatilhos, ações e blocos que controlam o fluxo. - [Executar uma automação](/automacoes/executar/) — Libere uma execução que já está na fila. ## Quando usar Use uma automação para reagir a um evento no CRM, como a criação de um lead ou o recebimento de uma mensagem. Para atividades comerciais planejadas por dia, use uma [cadência](/cadencias/). ## Guias relacionados - [Acompanhar execuções](/automacoes/acompanhar/) - [Simular no Playground](/automacoes/simular/) ![Fluxo de boas-vindas ligando gatilho e ações de envio e classificação](shotAutomacaoBoasVindasLight.src) ## Comece com uma tarefa do time - [Automatizar o primeiro atendimento de campanhas](/automacoes/primeiro-atendimento/). - [Enviar lembretes por data do lead](/automacoes/agendar-mensagem/). --- # Acompanhar execuções de automações Fonte: https://ajuda.matchsales.com.br/automacoes/acompanhar/ Em **Automações**, selecione **Ver execuções** no fluxo. O histórico apresenta a situação de cada execução e permite abrir seus detalhes. ![Histórico de execuções de uma automação com estados e ações por execução](/images/pipefacil/automacoes/execucoes-light.png) ## Ler o histórico Use os filtros e percorra as páginas. Confira se uma contagem representa o recorte filtrado ou o total da automação antes de comparar os números. Abra uma execução para consultar o grafo realizado e os dados de entrada e saída dos nós. Um erro em um nó explica onde a execução parou; não significa que os nós anteriores foram desfeitos. A definição registrada pertence à execução. Alterações posteriores no editor não mudam o caminho executado no passado. Ao salvar uma automação editada, as execuções que ainda estão na fila ou aguardando são canceladas. As execuções em andamento continuam. ## Acompanhar pelo lead No detalhe do lead, abra **Automações** para localizar execuções ligadas ao negócio. Use o vínculo com a execução para consultar o contexto completo. ## Cancelar O cancelamento pede confirmação e interrompe o trabalho ainda pendente. Mensagens enviadas e alterações concluídas continuam existindo. Confira as execuções restantes antes de acionar novamente um fluxo. Para liberar uma espera já na fila, veja [Executar agora](/automacoes/executar/). Para cancelar as pendências do negócio dentro de um fluxo, use [Parar automações do negócio](/automacoes/nos/acao-parar-automacoes/). --- # Enviar lembretes por data do lead Fonte: https://ajuda.matchsales.com.br/automacoes/agendar-mensagem/ Use uma automação quando o envio depende de uma data do lead, como vencimento ou retorno combinado. Para um envio individual em uma conversa, use [Agendar uma mensagem](/conversas/agendar-mensagem/). ## Prepare os dados Crie um [campo personalizado](/configuracoes/campos/) de data ou data e hora e disponibilize-o no funil. Use um nome como “Vencimento” ou “Próximo contato”. Um lembrete de cobrança envia uma comunicação ao cliente. Ele não processa pagamento nem altera a assinatura do workspace. ## Configure o lembrete 1. Em **Automações**, crie um fluxo no escopo dos leads que devem receber o lembrete. 2. No gatilho **Agendamento**, escolha o modo por campo de data e selecione o campo preparado. 3. Configure o deslocamento em relação à data e o comportamento para datas já passadas. 4. Adicione **Enviar WhatsApp**, escolha o canal e revise a mensagem ou modelo. 5. Confira o fluxo com um lead controlado, revise os destinatários e salve. Ative quando o resultado estiver correto. 6. No lead e em **Ver execuções**, confira o agendamento e o resultado depois do horário previsto. ![Gatilho Agendamento por campo de data com deslocamento e tratamento de datas passadas](shotAutomacaoAgendamentoLight.src) ## Alterações e datas passadas Alterar a data rearma o agendamento pendente. Limpar o campo ou torná-lo inválido cancela o agendamento anterior. O tratamento de uma data já passada depende da opção escolhida: ignorar ou executar imediatamente. Um campo que guarda somente a data é interpretado no início do dia. Um deslocamento “antes” pode cair no dia anterior; confira o horário resultante antes de ativar. Salvar uma automação por data pode alcançar leads abertos que já têm o campo preenchido. Revise o escopo e o tratamento de datas passadas antes de ativar uma comunicação em escala. ## Canal e acompanhamento No WhatsApp Cloud, a janela precisa estar aberta no momento do envio de texto livre. Para contatos fora da janela, use um modelo aprovado adequado ao lembrete. Uma execução agendada ainda não confirma entrega. Consulte o nó de envio e o resultado em [Acompanhar execuções](/automacoes/acompanhar/). --- # Criar uma automação Fonte: https://ajuda.matchsales.com.br/automacoes/criar/ Neste tutorial, você cria uma automação que reage a um evento e executa uma sequência de ações. Antes de começar, defina qual evento inicia o fluxo, qual resultado você espera e quais dados o fluxo pode alterar. Você também precisa de permissão para criar ou editar automações. ## Planeje o fluxo Uma automação tem um gatilho e um ou mais nós conectados. O gatilho inicia a execução. As ações alteram dados ou comunicam algo. Os blocos de fluxo escolhem caminhos ou distribuem responsáveis. Planeje primeiro um caminho simples. Por exemplo: quando um lead entra em uma etapa, envie uma mensagem, espere uma resposta e crie uma tarefa caso não haja retorno. ## Crie manualmente 1. No PipeFácil, vá até **Automações** e selecione **Nova automação**. ![Lista de automações com o botão Nova automação](/images/pipefacil/automacoes/lista-light.png) 2. Selecione o escopo e o [gatilho](/automacoes/nos/#gatilhos) que inicia a automação. 3. Selecione **Adicionar próximo bloco**. Escolha uma ação ou um bloco de fluxo e preencha as configurações exibidas no painel. 4. Conecte cada nó ao próximo resultado esperado. Em uma [condição](/automacoes/nos/fluxo-condicao/), configure os dois caminhos antes de continuar o fluxo. 5. Renomeie a automação com um nome que descreva o evento e o resultado. Revise os nós, seus destinos e os dados que podem ser enviados. 6. Salve a automação e ative-a quando a revisão terminar. ## Crie com a CIA Selecione **Criar com a CIA** quando quiser começar com uma sugestão de fluxo. Descreva o evento, o público e o resultado esperado. A CIA monta um rascunho no editor. Revise todo o rascunho antes de salvar. Confirme o gatilho, os destinatários, os tempos de espera, os valores de campos e as URLs de webhook. Ajuste os nós manualmente quando necessário. ## Valide antes de usar Use um lead de teste e um cenário que não envie mensagens indevidas. Verifique se cada caminho chega ao nó esperado e se os dados alterados correspondem ao plano. Depois, abra **Ver execuções** para acompanhar a fila e as tentativas. ![Tela de execuções de uma automação com ações disponíveis para uma execução](/images/pipefacil/automacoes/execucoes-light.png) Para liberar uma execução agendada, consulte [Executar uma automação](/automacoes/executar/). ## Simular e acompanhar Quando o recurso **Playground** estiver habilitado no workspace, use **Simular** para percorrer o fluxo, alterar o cenário e avançar o relógio. A simulação não envia mensagens reais nem grava as alterações do cenário. Depois de ativar, consulte o histórico de execução e os dados de cada nó. Veja [Simular uma automação](/automacoes/simular/) e [Acompanhar execuções](/automacoes/acompanhar/). ## Receitas de uso - [Primeiro atendimento de leads de campanha](/automacoes/primeiro-atendimento/): origem, classificação, responsável e resposta. - [Lembrete por data do lead](/automacoes/agendar-mensagem/): vencimento ou próximo contato. Para agendar somente uma mensagem em uma conversa, use o [agendamento do compositor](/conversas/agendar-mensagem/). ## Próximos passos - [Consultar os nós de automação](/automacoes/nos/) - [Executar uma automação](/automacoes/executar/) - [Criar um disparo](/disparos/criar/) --- # Executar uma automação Fonte: https://ajuda.matchsales.com.br/automacoes/executar/ Libere uma execução pendente sem esperar o próximo horário agendado. Você precisa ter permissão para consultar as execuções da automação. 1. No PipeFácil, vá até **Automações**. 2. Localize a automação e selecione **Ver execuções**. 3. Na execução com status **Na fila**, abra **Ações da execução**. ![Tela de execuções de uma automação com o menu Executar agora aberto](/images/pipefacil/automacoes/execucoes-light.png) 4. Selecione **Executar agora**. O comando libera a execução que já está na fila. A automação pode enviar mensagens ou alterar dados do lead. Para iniciar uma nova execução, use uma automação com gatilho **Acionamento manual**. No compositor da conversa de um lead aberto, digite `/`, escolha **Automações** e selecione um fluxo disponível. A API pública de gestão de automações não oferece uma rota para iniciar execuções. ## Próximos passos - [Responder uma conversa](/conversas/responder/) - [Criar um disparo](/disparos/criar/) --- # Nós de automação Fonte: https://ajuda.matchsales.com.br/automacoes/nos/ Cada automação começa com um gatilho. Depois, conecte ações para alterar dados ou comunicar algo. Use blocos de fluxo quando o resultado depender de uma regra ou de distribuição entre pessoas. Para montar o fluxo completo, consulte [Criar uma automação](/automacoes/criar/). ![Fluxo com gatilho Lead criado, envio de WhatsApp e aplicação de tag](guideShot0Light.src) ## Gatilhos - [Lead criado](/automacoes/nos/gatilho-lead-criado/) — Inicie o fluxo quando um novo lead entrar no CRM. - [Lead movimentado para esta etapa](/automacoes/nos/gatilho-lead-movido-etapa/) — Inicie o fluxo quando o lead chegar a uma etapa. - [Lead ganho](/automacoes/nos/gatilho-lead-ganho/) — Reaja quando o negócio for marcado como ganho. - [Lead perdido](/automacoes/nos/gatilho-lead-perdido/) — Reaja quando o negócio for marcado como perdido. - [Lead reatribuído](/automacoes/nos/gatilho-lead-reatribuido/) — Inicie ações após trocar o responsável do lead. - [Mensagem recebida](/automacoes/nos/gatilho-mensagem-recebida/) — Reaja a uma mensagem recebida na conversa do lead. - [Campo preenchido](/automacoes/nos/gatilho-campo-preenchido/) — Inicie o fluxo quando um campo receber um valor. - [Agendamento](/automacoes/nos/gatilho-agendamento/) — Reaja a um evento de agendamento ligado ao lead. ## Ações - [Enviar WhatsApp](/automacoes/nos/acao-enviar-whatsapp/) — Envie uma mensagem pelo canal conectado. - [Criar tarefa](/automacoes/nos/acao-criar-tarefa/) — Crie uma pendência com título, prazo e responsável. - [Trocar responsável](/automacoes/nos/acao-trocar-responsavel/) — Atribua o lead a outra pessoa do workspace. - [Adicionar corresponsável](/automacoes/nos/acao-adicionar-corresponsavel/) — Inclua outra pessoa no acompanhamento do lead. - [Esperar](/automacoes/nos/acao-esperar/) — Adie o próximo nó por um período configurado. - [Mover etapa](/automacoes/nos/acao-mover-etapa/) — Avance ou mova o lead para uma etapa escolhida. - [Adicionar tag](/automacoes/nos/acao-adicionar-tag/) — Marque o lead com uma tag existente. - [Remover tag](/automacoes/nos/acao-remover-tag/) — Retire uma tag do lead. - [Atualizar campo](/automacoes/nos/acao-atualizar-campo/) — Grave um valor em um campo do lead. - [Criar lead](/automacoes/nos/acao-criar-lead/) — Abra um novo lead a partir da execução. - [Webhook](/automacoes/nos/acao-webhook/) — Envie os dados do fluxo para uma URL externa. ## Fluxo - [Condição](/automacoes/nos/fluxo-condicao/) — Direcione a execução por dois caminhos conforme uma regra. - [Round robin](/automacoes/nos/fluxo-round-robin/) — Distribua o lead entre os responsáveis configurados. ## Guias relacionados - [Acionamento manual](/automacoes/nos/gatilho-manual/) - [Gatilho Webhook](/automacoes/nos/gatilho-webhook/) - [Contato ou time sem resposta](/automacoes/nos/gatilho-sem-resposta/) - [Conversa fechada](/automacoes/nos/conversa-fechada/) - [Criar evento na agenda](/automacoes/nos/acao-criar-evento/) - [Analisar com a CIA](/automacoes/nos/acao-analisar-cia/) - [Parar automações do negócio](/automacoes/nos/acao-parar-automacoes/) - [Encerrar automação](/automacoes/nos/fluxo-encerrar/) - [Comentários do Instagram](/automacoes/nos/instagram/) - [E-mail e conversão Meta Ads](/automacoes/nos/acoes-de-marketing/) --- # Usar a ação Adicionar corresponsável Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-adicionar-corresponsavel/ Use esta ação quando mais de uma pessoa precisa acompanhar o mesmo lead sem trocar o responsável principal. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Adicionar corresponsável**. 3. Selecione a pessoa que também acompanhará o lead. 4. Revise o restante do fluxo e salve a automação. ![Ação Adicionar co-responsável com uma pessoa selecionada](guideShot0Light.src) O responsável principal do lead não muda. Revise os acessos da pessoa escolhida antes de ativar o fluxo. ## Exemplo Quando o lead avançar para negociação, adicione a pessoa de pré-venda como corresponsável. ## Próximos passos - [Trocar o responsável](/automacoes/nos/acao-trocar-responsavel/) - [Convidar membros](/configuracoes/membros/) - [Criar uma automação](/automacoes/criar/) --- # Usar a ação Adicionar tag Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-adicionar-tag/ Use esta ação para identificar leads que passaram por um evento ou uma etapa do processo. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Adicionar tag**. 3. Selecione a tag que deve ser aplicada ao lead. 4. Revise a conexão com o próximo nó e salve a automação. ![Ação Adicionar tag com a tag CRM selecionada](guideShot0Light.src) A tag escolhida é adicionada quando a execução chega ao nó. Use tags que tenham um significado claro para busca e segmentação. ## Exemplo Quando um lead é criado por uma campanha, adicione a tag _Origem: campanha_. ## Próximos passos - [Remover uma tag](/automacoes/nos/acao-remover-tag/) - [Usar o gatilho Lead criado](/automacoes/nos/gatilho-lead-criado/) - [Filtrar leads](/pipeline/filtrar-leads/) --- # Analisar um lead com a CIA Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-analisar-cia/ O nó **Analisar com a CIA** solicita a análise comercial do lead. O fluxo continua depois da solicitação; o resultado aparece na aba CIA quando estiver pronto. O recurso depende da disponibilidade da CIA no workspace. Configure o nó e revise o contexto do negócio antes de ativar. Não use a solicitação como garantia de que uma nota ou sugestão já está disponível no nó seguinte. Veja [Análises e scorecard](/cia/analises/). ![Busca de blocos do editor com a ação Analisar com a CIA](guideShot0Light.src) --- # Usar a ação Atualizar campo Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-atualizar-campo/ Use esta ação para registrar uma informação do processo diretamente no lead. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Atualizar campo**. 3. Selecione o campo e informe o valor disponível no painel. 4. Revise o valor que será gravado e salve a automação. ![Ação Atualizar campo configurada para definir a prioridade como Alta](guideShot0Light.src) Quando a execução chega ao nó, o campo recebe o valor configurado. Confirme o tipo do campo para evitar gravar uma informação incompatível. ## Exemplo Quando uma proposta é enviada, atualize o campo _Situação da proposta_ para _Enviada_. ## Próximos passos - [Usar o gatilho Campo preenchido](/automacoes/nos/gatilho-campo-preenchido/) - [Usar uma condição](/automacoes/nos/fluxo-condicao/) - [Configurar campos](/configuracoes/campos/) --- # Usar a ação Criar evento na agenda Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-criar-evento/ A ação cria um evento na agenda do responsável pelo lead. O workspace precisa ter o recurso de calendário. 1. No editor, adicione **Criar evento na agenda**. 2. Informe o título e configure início, duração e fuso conforme o painel. 3. Escolha convidados e conferência, quando necessários. 4. Revise os dados e conecte o próximo nó. ![Ação Criar evento na agenda com título, campo de início, duração e convidados](guideShot0Light.src) Confira a pessoa responsável e os dados de contato antes de ativar. A reunião aparece no [calendário](/calendario/) e pode conter convidados do workspace ou o contato do negócio. --- # Usar a ação Criar lead Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-criar-lead/ Use esta ação para criar outra oportunidade do mesmo contato em outro funil. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Criar lead**. 3. Escolha o funil e a etapa de destino e revise os dados usados na cópia. 4. Revise os campos obrigatórios e salve a automação. ![Ação Criar lead com o funil de destino Retenção selecionado](guideShot0Light.src) O nó cria um novo lead quando a execução chega a ele. Configure dados suficientes para o novo negócio entrar no processo certo. ## Exemplo Quando a venda for concluída, crie uma oportunidade do mesmo contato no funil de pós-venda. ## Próximos passos - [Criar um lead](/pipeline/criar-lead/) - [Mover uma etapa](/automacoes/nos/acao-mover-etapa/) - [Usar uma condição](/automacoes/nos/fluxo-condicao/) --- # Usar a ação Criar tarefa Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-criar-tarefa/ Use esta ação para transformar uma etapa do fluxo em uma pendência para o time. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Criar tarefa**. 3. Informe o título, o prazo e as demais opções exibidas no painel. 4. Confira o responsável e salve a automação. ![Ação Criar tarefa com título, descrição, categoria e prazo](guideShot0Light.src) Quando a execução chegar ao nó, a tarefa ficará ligada ao lead do fluxo. Escolha um prazo que permita ao time agir antes do próximo passo automático. ## Exemplo Depois de enviar uma proposta, crie uma tarefa de follow-up para vencer em três dias. ## Próximos passos - [Esperar antes do próximo nó](/automacoes/nos/acao-esperar/) - [Organizar tarefas](/tarefas/organizar/) - [Criar uma automação](/automacoes/criar/) --- # Usar a ação Enviar WhatsApp Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-enviar-whatsapp/ Use esta ação para enviar uma mensagem ao contato depois que o fluxo chegar a este nó. Você precisa de um canal de WhatsApp conectado e de conteúdo apropriado para o momento da conversa. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Enviar WhatsApp**. 3. Selecione o canal e configure a mensagem ou o modelo disponível no painel. 4. Revise o destinatário, o conteúdo e a conexão com o próximo nó. Salve a automação. A mensagem é enviada quando a execução chega ao nó. Teste o fluxo com um lead de teste antes de ativar uma mensagem para clientes. ## Exemplo Depois que o lead entra em uma etapa, envie uma mensagem de apresentação e espere a resposta. ## Conteúdo e canal O nó aceita texto, mídia, scripts globais e modelos, conforme as opções do editor e o provedor conectado. Revise as variáveis usando os dados do lead. O conteúdo é resolvido no momento do envio. O envio respeita as regras do canal. Na Cloud API, texto livre exige a [janela de atendimento aberta naquele canal](/conversas/janela-de-atendimento/); fora dela, use um modelo aprovado. ![Painel Enviar WhatsApp com canal, origem da mensagem e opção de aguardar resposta](shotAutomacaoEnviarWhatsappLight.src) ## Aguarde uma escolha ou resposta Quando o template tem botões de resposta rápida, conecte os caminhos dos botões e configure **Prazo de espera**. Ligue a saída **Se não responder** para definir o que acontece ao vencer o prazo. Botões de abrir URL não são respostas rápidas. Para conteúdo sem esses botões, **Aguardar resposta** permite continuar por **Qualquer resposta** ou **Se não responder**. Ao usar variáveis de modelo, confira o mapeamento do canal e do template. Ele também é utilizado no inbox e nos disparos. Revise os valores antes de ativar o fluxo. Veja um exemplo em [Primeiro atendimento de campanhas](/automacoes/primeiro-atendimento/). ## Próximos passos - [Esperar antes do próximo nó](/automacoes/nos/acao-esperar/) - [Configurar um canal](/integracoes/canais/) - [Responder uma conversa](/conversas/responder/) --- # Usar a ação Esperar Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-esperar/ Use esta ação para separar ações no tempo, como uma mensagem de retorno depois de alguns dias. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Esperar**. 3. Configure o período disponível no painel. 4. Conecte o próximo nó, revise a programação e salve a automação. ![Espera de tempo fixo configurada para dois dias](guideShot0Light.src) A execução fica na fila até o período configurado terminar. Para liberar uma execução que já está na fila, consulte [Executar uma automação](/automacoes/executar/). ## Exemplo Depois de enviar uma mensagem, espere dois dias antes de criar uma tarefa de follow-up. ## Esperar uma resposta Além de **Tempo fixo**, o editor oferece **Resposta do contato** e **Resposta do time**. Configure o prazo e conecte tanto a saída de resposta quanto a saída **Sem resposta**. Uma resposta depois do prazo não deve ser tratada como resposta dentro da espera. Para iniciar um fluxo somente quando o prazo terminar, consulte os [gatilhos de falta de resposta](/automacoes/nos/gatilho-sem-resposta/). ## Próximos passos - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Enviar uma mensagem no WhatsApp](/automacoes/nos/acao-enviar-whatsapp/) - [Executar uma automação](/automacoes/executar/) --- # Usar a ação Mover etapa Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-mover-etapa/ Use esta ação para avançar, recuar ou encerrar o lead de acordo com o resultado do fluxo. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Mover etapa**. 3. Selecione o funil e a etapa de destino disponíveis no painel. 4. Revise os campos obrigatórios ou o motivo de perda exigidos pela etapa e salve a automação. ![Ação Mover etapa com destino em Vendas B2B, Qualificação](guideShot0Light.src) Quando a execução chega ao nó, o lead muda para o destino configurado. As regras da etapa continuam sendo aplicadas. ## Exemplo Depois de receber uma resposta, mova o lead para a etapa _Em atendimento_. ## Próximos passos - [Usar o gatilho Mensagem recebida](/automacoes/nos/gatilho-mensagem-recebida/) - [Mover um lead](/pipeline/mover-lead/) - [Usar uma condição](/automacoes/nos/fluxo-condicao/) --- # Parar automações do negócio Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-parar-automacoes/ A ação **Parar automações do negócio** cancela as automações pendentes daquele negócio, incluindo esperas, timers e outros fluxos na fila. Ela também encerra o fluxo atual. Adicione o nó no ponto em que o processo deve terminar as pendências. Não conecte uma próxima ação esperando continuidade após esse encerramento. Gatilhos que ocorrerem depois podem iniciar novas execuções. A ação não desativa as definições das automações e não desfaz ações concluídas. Para terminar somente o fluxo atual, use [Encerrar automação](/automacoes/nos/fluxo-encerrar/). Para cancelar manualmente, consulte [Acompanhar execuções](/automacoes/acompanhar/). ![Busca de blocos do editor com a ação Parar automações do negócio](guideShot0Light.src) --- # Usar a ação Remover tag Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-remover-tag/ Use esta ação para retirar uma classificação que não representa mais a situação do lead. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Remover tag**. 3. Selecione a tag que deve ser retirada do lead. 4. Revise o fluxo e salve a automação. ![Ação Remover tag com a tag CRM selecionada](guideShot0Light.src) O nó remove a tag selecionada quando a execução chega a ele. Confira se a tag não é necessária para outro processo antes de ativar a automação. ## Exemplo Quando o lead responde, remova a tag _Aguardando resposta_. ## Próximos passos - [Adicionar uma tag](/automacoes/nos/acao-adicionar-tag/) - [Usar o gatilho Mensagem recebida](/automacoes/nos/gatilho-mensagem-recebida/) - [Filtrar leads](/pipeline/filtrar-leads/) --- # Usar a ação Trocar responsável Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-trocar-responsavel/ Use esta ação para encaminhar o lead para uma pessoa específica do workspace. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Trocar responsável**. 3. Selecione a pessoa que receberá o lead. 4. Revise as ações seguintes e salve a automação. ![Ação Trocar responsável com Ana Silva selecionada](guideShot0Light.src) A pessoa selecionada passa a ser responsável pelo lead quando a execução chega ao nó. Verifique se ela tem acesso ao funil e ao canal usados no processo. ## Exemplo Depois de qualificar o lead, troque o responsável para um closer. ## Próximos passos - [Adicionar um corresponsável](/automacoes/nos/acao-adicionar-corresponsavel/) - [Usar round robin](/automacoes/nos/fluxo-round-robin/) - [Convidar membros](/configuracoes/membros/) --- # Usar a ação Webhook Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acao-webhook/ Use esta ação para integrar a automação a outro sistema que recebe webhooks. Você precisa de uma URL do serviço externo e deve saber quais dados ele espera receber. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Ações**, escolha **Webhook**. 3. Informe a URL e configure os dados disponíveis no painel. 4. Teste o recebimento no serviço externo, revise os dados enviados e salve a automação. ![Ação Webhook com URL de exemplo e seção de cabeçalhos](guideShot0Light.src) O nó chama a URL configurada quando a execução chega a ele. Use uma URL controlada pelo seu time e não inclua segredos em dados que possam ficar visíveis no editor. ## Exemplo Quando um lead chega a uma etapa, envie um webhook para criar uma atividade em outro sistema. ## Próximos passos - [Usar o gatilho Lead movimentado para esta etapa](/automacoes/nos/gatilho-lead-movido-etapa/) - [Executar uma automação](/automacoes/executar/) - [Criar uma automação](/automacoes/criar/) --- # E-mail e conversão Meta Ads Fonte: https://ajuda.matchsales.com.br/automacoes/nos/acoes-de-marketing/ ## Enviar e-mail A ação **Enviar e-mail** dispara um modelo do provedor de e-mail marketing para o contato do lead. Selecione a integração e o modelo no editor. A edição do conteúdo ocorre no provedor. Confira se o contato possui um e-mail utilizável e se a integração está ativa. Consulte as saídas e erros na execução antes de reenviar. ## Conversão Meta Ads A ação **Conversão Meta Ads** comunica o resultado do lead à Meta pela Conversions API. Confira a integração e o evento escolhido no editor antes de ativar o fluxo. Quando disponíveis, os dados de rastreamento do lead acompanham a conversão para ajudar a Meta a relacionar o resultado com o anúncio. Isso inclui identificadores da Meta e valores de campanha recebidos pelo formulário ou pela página de captura. A Meta pode não atribuir a conversão quando esses dados não existem ou não correspondem a um evento reconhecido. O payload das automações também contém os dados de rastreamento do negócio. Use esse bloco em ações de webhook quando o sistema conectado precisar receber a origem e a campanha. Consulte [Origem e rastreamento de leads](/integracoes/origem-e-rastreio-de-leads/) para saber de onde vêm os valores e onde encontrá-los no lead. Essas ações dependem dos recursos e conexões disponíveis no workspace. A execução não garante que o provedor aceitará todos os dados; acompanhe o histórico em [Execuções](/automacoes/acompanhar/). --- # Automatizar o fechamento da conversa Fonte: https://ajuda.matchsales.com.br/automacoes/nos/conversa-fechada/ ## Gatilho Conversa fechada Dispara quando a conversa é fechada pelo botão da caixa de entrada ou pela ação do fluxo. Precisa haver um negócio aberto ligado à conversa. Configure escopo e ações no editor. ![Painel do gatilho Conversa fechada](guideShot0Light.src) ## Ação Fechar conversa Fecha a conversa do lead e a marca como lida. Ela sai da caixa de entrada e do recorte de atendimentos sem resposta até o contato escrever novamente. Fechar a conversa não encerra o negócio. Configure ganho ou perda separadamente se o processo exigir, incluindo as validações da etapa. Veja [Encerrar atendimentos](/conversas/gerenciar/). --- # Usar o bloco Condição Fonte: https://ajuda.matchsales.com.br/automacoes/nos/fluxo-condicao/ Use este bloco quando o fluxo precisa tomar caminhos diferentes conforme os dados do lead ou o resultado de uma etapa anterior. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Fluxo**, escolha **Condição**. 3. Configure a regra usando os campos e valores disponíveis no painel. 4. Conecte um próximo nó para cada resultado da condição e salve a automação. ![Bloco Condição com a regra Status do lead é igual a Aberto e saída para os demais casos](guideShot0Light.src) O bloco separa a execução entre os caminhos configurados. Sempre defina o que acontece em cada resultado antes de ativar a automação. Para verificar uma tag, selecione **Tags do lead** e escolha uma tag do workspace. Use **tem a tag** ou **não tem a tag** para testar uma tag específica. Use **tem alguma tag** ou **não tem nenhuma tag** para verificar se o lead tem tags. ## Exemplo Se o campo _Origem_ indicar uma indicação, atribua o lead ao time de parcerias. Caso contrário, encaminhe-o ao time comercial. ## Horário, canal e tags Uma condição pode verificar o horário atual, o horário comercial do workspace e uma janela personalizada. Datas apresentadas nas mensagens respeitam o fuso do workspace. Ao filtrar a origem de uma mensagem, selecione também o canal quando o fluxo precisa distinguir números ou contas do mesmo provedor. Revise todas as saídas: a execução segue pela primeira regra correspondente. ## Próximos passos - [Atualizar um campo](/automacoes/nos/acao-atualizar-campo/) - [Trocar o responsável](/automacoes/nos/acao-trocar-responsavel/) - [Criar uma automação](/automacoes/criar/) --- # Encerrar a execução do fluxo Fonte: https://ajuda.matchsales.com.br/automacoes/nos/fluxo-encerrar/ O bloco **Encerrar automação** termina a execução naquele ponto. Não recebe uma ação posterior. Use o bloco no final de um caminho de condição ou quando o objetivo do fluxo já foi cumprido. Revise os outros caminhos antes de ativar a automação. Para cancelar também esperas e execuções pendentes do negócio, use [Parar automações do negócio](/automacoes/nos/acao-parar-automacoes/). ![Busca de blocos do editor com a opção Encerrar automação](guideShot0Light.src) --- # Usar o bloco Round robin Fonte: https://ajuda.matchsales.com.br/automacoes/nos/fluxo-round-robin/ Use este bloco para revezar as execuções entre caminhos conectados. Em cada caminho, uma ação pode atribuir o lead a uma pessoa. 1. No editor, selecione **Adicionar próximo bloco** depois do nó anterior. 2. Em **Fluxo**, escolha **Round robin**. 3. Configure as saídas que participam do ciclo. 4. Conecte cada saída ao caminho correspondente e salve a automação. ![Configuração do bloco Round robin com duas saídas e ação Adicionar saída](guideShot0Light.src) O bloco escolhe uma saída em ciclo. Para distribuir responsáveis, conecte cada saída a uma ação de trocar responsável e confira os membros selecionados. ## Exemplo Quando um lead é criado, distribua-o entre as pessoas de pré-venda e crie uma tarefa de primeiro contato. ## Próximos passos - [Trocar o responsável](/automacoes/nos/acao-trocar-responsavel/) - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Convidar membros](/configuracoes/membros/) --- # Usar o gatilho Agendamento Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-agendamento/ O gatilho **Agendamento** inicia uma automação pela data de um campo do lead ou por uma programação recorrente. Criar uma reunião no calendário é outra operação. ## Escolha o modo | Modo | Uso | | ---------------------- | -------------------------------------------------------------------- | | Campo de data | Executa em relação a um vencimento ou retorno preenchido no lead. | | Programação recorrente | Executa periodicamente sobre os leads abertos no escopo configurado. | 1. Em **Automações**, crie ou abra o fluxo e escolha o escopo. 2. No nó inicial, selecione **Agendamento** e escolha o modo. 3. No modo por campo, selecione a data, o deslocamento e a regra para datas passadas. No recorrente, confira a programação apresentada no editor. 4. Conecte as ações e revise o público. Salve e ative depois de conferir o cenário. ![Painel do gatilho com modos Campo de data e Recorrente e opções para datas passadas](shotAutomacaoAgendamentoLight.src) ## Campo de data e mudanças posteriores O horário resulta do valor do campo mais o deslocamento. Campo de data sem hora começa no início do dia; um deslocamento anterior pode cair no dia anterior. Mudar a data substitui o agendamento pendente. Limpar o campo ou informar uma data inválida cancela o anterior. Para datas passadas, escolha entre ignorar e executar imediatamente. Ao salvar um fluxo por data, os leads abertos do escopo que já têm o campo podem receber um agendamento. Confira o recorte antes de ativar ações de comunicação. ## Exemplos e próximos passos - [Enviar um lembrete por data do lead](/automacoes/agendar-mensagem/). - [Agendar uma mensagem individual na conversa](/conversas/agendar-mensagem/). - [Criar um evento na agenda durante o fluxo](/automacoes/nos/acao-criar-evento/). - [Acompanhar execuções](/automacoes/acompanhar/). --- # Usar o gatilho Campo preenchido Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-campo-preenchido/ Use este gatilho quando uma informação preenchida no lead deve iniciar o próximo passo do processo. 1. Em **Automações**, crie ou abra uma automação. 2. Selecione o escopo que inclui o campo usado no processo. 3. No nó inicial, escolha **Campo preenchido** e selecione o campo observado. 4. Conecte a ação seguinte, revise o valor esperado e salve o fluxo. ![Gatilho Campo preenchido observando a prioridade quando ela for preenchida](guideShot0Light.src) O fluxo começa quando o campo configurado recebe um valor. Use uma [condição](/automacoes/nos/fluxo-condicao/) quando valores diferentes exigirem caminhos diferentes. ## Exemplo Quando o campo _Origem_ é preenchido, adicione uma tag que identifica a campanha. ## Próximos passos - [Atualizar um campo](/automacoes/nos/acao-atualizar-campo/) - [Adicionar uma tag](/automacoes/nos/acao-adicionar-tag/) - [Usar uma condição](/automacoes/nos/fluxo-condicao/) --- # Usar o gatilho Lead criado Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-lead-criado/ Use este gatilho para iniciar a primeira ação sobre um lead novo, como aplicar uma tag, atribuir um responsável ou enviar uma mensagem. 1. Em **Automações**, selecione **Nova automação** ou abra uma automação que esteja em edição. 2. No nó inicial, escolha o escopo **Global** e selecione **Lead criado**. 3. Selecione **Adicionar próximo bloco** e conecte a primeira ação do fluxo. 4. Revise a ação e salve a automação antes de ativá-la. ![Painel do gatilho Lead criado com escopo global](guideShot0Light.src) O gatilho inicia a execução para o lead que acabou de entrar no CRM. Use uma [condição](/automacoes/nos/fluxo-condicao/) quando o fluxo depender de dados preenchidos no novo lead. Para criar uma rotina comercial antes ou depois desse evento, use uma [cadência](/cadencias/). ## Exemplo Quando um lead é criado, adicione a tag _Novo contato_ e crie uma tarefa de primeiro atendimento. ## Próximos passos - [Adicionar uma tag](/automacoes/nos/acao-adicionar-tag/) - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Criar uma automação](/automacoes/criar/) --- # Usar o gatilho Lead ganho Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-lead-ganho/ Use este gatilho para iniciar ações de pós-venda depois que um negócio for ganho. 1. Em **Automações**, crie ou abra uma automação. 2. Selecione o escopo que inclui os leads que podem ser ganhos. 3. No nó inicial, escolha **Lead ganho**. 4. Conecte as ações de pós-venda, revise o fluxo e ative a automação. ![Painel do gatilho Lead ganho](guideShot0Light.src) O fluxo executa as ações conectadas quando o lead muda para uma situação de ganho. ## Exemplo Quando um lead é ganho, crie uma tarefa de onboarding e adicione uma tag de cliente. ## Próximos passos - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Adicionar uma tag](/automacoes/nos/acao-adicionar-tag/) - [Criar uma automação](/automacoes/criar/) --- # Usar o gatilho Lead movimentado para esta etapa Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-lead-movido-etapa/ Use este gatilho para executar ações ligadas à chegada do lead em uma etapa específica. 1. Em **Automações**, crie ou abra uma automação. 2. No nó inicial, selecione o escopo **Etapa**. 3. Escolha a etapa que deve iniciar o fluxo e selecione **Lead movimentado para esta etapa**. 4. Adicione o próximo nó, revise o destino da etapa e salve a automação. ![Gatilho de movimentação com escopo Etapa, funil Vendas B2B e etapa Proposta](guideShot0Light.src) O fluxo começa quando o lead chega à etapa configurada. Ele não substitui as regras que exigem campos ou motivo de perda ao mover um lead. ## Exemplo Quando o lead chega à etapa _Proposta enviada_, crie uma tarefa de retorno para a pessoa responsável. ## Próximos passos - [Mover uma etapa](/automacoes/nos/acao-mover-etapa/) - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Mover um lead](/pipeline/mover-lead/) --- # Usar o gatilho Lead perdido Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-lead-perdido/ Use este gatilho para registrar ou encaminhar ações depois que o negócio for perdido. 1. Em **Automações**, crie ou abra uma automação. 2. Selecione o escopo que inclui os leads que podem ser perdidos. 3. No nó inicial, escolha **Lead perdido**. 4. Adicione as ações necessárias, revise o fluxo e salve a automação. ![Painel do gatilho Lead perdido](guideShot0Light.src) O fluxo começa depois que o lead entra em uma situação de perda. O preenchimento do motivo de perda continua seguindo a configuração da etapa do funil. ## Exemplo Quando um lead é perdido, atualize um campo de acompanhamento e envie os dados para um webhook. ## Próximos passos - [Atualizar um campo](/automacoes/nos/acao-atualizar-campo/) - [Usar um webhook](/automacoes/nos/acao-webhook/) - [Mover um lead](/pipeline/mover-lead/) --- # Usar o gatilho Lead reatribuído Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-lead-reatribuido/ Use este gatilho para coordenar o handoff entre as pessoas responsáveis pelo mesmo lead. 1. Em **Automações**, crie ou abra uma automação. 2. Selecione o escopo que deve observar a mudança de responsável. 3. No nó inicial, escolha **Lead reatribuído**. 4. Conecte a ação que deve ocorrer depois da atribuição e salve o fluxo. ![Painel do gatilho Lead reatribuído](guideShot0Light.src) O fluxo usa a troca de responsável como evento inicial. Revise as ações para evitar atribuir novamente o mesmo lead sem necessidade. ## Exemplo Quando um lead é reatribuído, crie uma tarefa para a nova pessoa responsável revisar o histórico. ## Próximos passos - [Trocar o responsável](/automacoes/nos/acao-trocar-responsavel/) - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Usar round robin](/automacoes/nos/fluxo-round-robin/) --- # Usar o gatilho Acionamento manual Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-manual/ Esse gatilho inicia o fluxo quando uma pessoa escolhe a automação em um lead aberto. Ele usa escopo global. 1. No editor, escolha **Acionamento manual** e conecte as ações desejadas. 2. Revise e ative a automação. 3. Abra a conversa de um lead aberto e digite `/` no compositor. 4. Escolha **Automações** e selecione o fluxo disponível. ![Painel do gatilho Acionamento manual com escopo global](guideShot0Light.src) A execução pode enviar mensagens ou alterar o negócio. Consulte [Acompanhar execuções](/automacoes/acompanhar/) para conferir o resultado. Esse comando cria uma execução; **Executar agora** libera uma execução que já está na fila. --- # Usar o gatilho Mensagem recebida Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-mensagem-recebida/ Use este gatilho para reagir a uma resposta recebida do contato. 1. Em **Automações**, crie ou abra uma automação. 2. Selecione o escopo que deve observar as conversas. 3. No nó inicial, escolha **Mensagem recebida**. 4. Adicione a ação ou a condição que deve avaliar a nova mensagem e salve o fluxo. ![Painel do gatilho Mensagem recebida](guideShot0Light.src) O gatilho depende de uma conversa ligada ao lead. Antes de enviar uma resposta automática, confirme se o canal e o conteúdo configurado atendem ao processo comercial. ## Exemplo Quando uma mensagem é recebida, mova o lead para a etapa _Em atendimento_ e crie uma tarefa de retorno. ## Próximos passos - [Mover uma etapa](/automacoes/nos/acao-mover-etapa/) - [Criar uma tarefa](/automacoes/nos/acao-criar-tarefa/) - [Responder uma conversa](/conversas/responder/) --- # Gatilhos de falta de resposta Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-sem-resposta/ | Gatilho | Início da contagem | Quando dispara | | -------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | | Contato sem resposta | Última mensagem enviada pela equipe. | O contato não responde dentro do prazo; uma vez por conversa sem resposta. | | Time sem resposta | Primeira mensagem do contato ainda sem resposta. | Ninguém do time responde dentro do prazo, pelo CRM ou pelo aparelho. | No editor, escolha o gatilho, configure o prazo e conecte as ações. O contrato aceita prazos entre 60 e 2.592.000 segundos, de um minuto a 30 dias. Confira o escopo, o canal e as condições antes de ativar. Por exemplo, **Time sem resposta** pode criar uma tarefa para acompanhar um atendimento pendente. Use um gatilho para iniciar um fluxo depois do silêncio. Para segurar um fluxo que já está executando, use [Esperar uma resposta](/automacoes/nos/acao-esperar/). ![Painel do gatilho Contato sem resposta com configuração do prazo](guideShot0Light.src) --- # Usar o gatilho Webhook Fonte: https://ajuda.matchsales.com.br/automacoes/nos/gatilho-webhook/ O gatilho de webhook recebe chamadas de formulários, páginas ou integrações. Ele usa escopo global. 1. No editor, escolha **Webhook** no gatilho inicial. 2. Configure o caminho, método HTTP e autenticação oferecidos no painel. 3. Revise o mapeamento de dados e as ações seguintes. 4. Salve e use a URL gerada na integração externa. ![Gatilho Webhook com método POST, identificação por telefone e caminho do payload](guideShot0Light.src) Guarde os segredos quando forem exibidos e envie o corpo no formato configurado. Uma chamada aceita pode criar um lead e iniciar ações reais. Confira o histórico de execução. Esse gatilho recebe dados. A [ação Webhook](/automacoes/nos/acao-webhook/) envia dados para uma URL externa. O teste de webhook pela [API de gestão](/developers/automacoes/) apenas prepara um corpo assinado. --- # Comentários do Instagram em automações Fonte: https://ajuda.matchsales.com.br/automacoes/nos/instagram/ ## Gatilho Comentário no Instagram Escolha a conta e configure os comentários que devem iniciar o fluxo. Um comentário vira lead quando corresponde à automação configurada para recebê-lo. ## Ações disponíveis | Ação | Resultado | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Responder comentário | Publica uma resposta visível na publicação. | | Responder no Direct | Envia a resposta privada para quem comentou e abre a conversa no inbox. O provedor permite uma resposta privada por comentário. | | Ocultar comentário | Oculta da publicação; quem comentou continua vendo o próprio comentário. | Revise os filtros e o conteúdo antes de ativar. A conexão da conta precisa ter as permissões necessárias para comentários. Veja [Conectar Instagram](/integracoes/instagram/). --- # Automatizar o primeiro atendimento de campanhas Fonte: https://ajuda.matchsales.com.br/automacoes/primeiro-atendimento/ Comece com um fluxo pequeno para uma campanha. Ao terminar, um lead deve chegar ao destino correto, receber uma classificação e seguir para atendimento. Você precisa do canal conectado, do funil com suas etapas, das tags e da permissão para editar automações. ## Defina como o lead chega | Origem | Onde configurar | | ----------------------------------------------- | ------------------------------------------------------------------ | | Formulário instantâneo do Facebook ou Instagram | [Formulários de leads da Meta](/integracoes/formularios-de-leads/) | | Mensagem pelo WhatsApp ou Direct | [Canal e funil de entrada](/integracoes/canais/) | | Cadastro de um site ou sistema externo | [Criar lead pela API](/developers/negocios/) | Para campanhas diferentes, configure o destino na origem ou use condições com os dados efetivamente recebidos. Não presuma que toda mensagem inclui o nome da campanha ou os mesmos [campos de rastreamento](/integracoes/origem-e-rastreio-de-leads/). ## Monte o primeiro fluxo 1. Em **Automações**, selecione **Nova automação** e defina o escopo do funil ou etapa. 2. Escolha **Lead criado** para a primeira entrada, ou **Mensagem recebida** quando o processo deve começar com uma mensagem. Revise o escopo para evitar respostas repetidas a cada interação. 3. Adicione **Adicionar tag** para classificar o interesse, como “Consórcio”. 4. Confira a [distribuição de leads](/configuracoes/distribuicao-de-leads/). Se o próprio fluxo atribuir alguém, use **Trocar responsável** e, quando necessário, **Adicionar corresponsável**. 5. Adicione **Enviar WhatsApp**, selecione o canal e a mensagem ou modelo aprovado. 6. Configure o próximo passo: aguardar uma resposta, mover etapa ou criar tarefa. Conecte também o caminho para quando o contato não responder. 7. Revise, simule o fluxo quando disponível e ative somente depois de conferir o cenário. ![Exemplo de fluxo com Lead criado, Enviar WhatsApp e Adicionar tag](shotAutomacaoBoasVindasLight.src) O vendedor e o gestor precisam dos [acessos adequados](/configuracoes/membros/) para atender e acompanhar os leads. ![Configuração do envio pelo canal Vendas com mensagem e espera pela resposta](shotAutomacaoEnviarWhatsappLight.src) ## Respostas com opções Na ação **Enviar WhatsApp**, um template com botões de resposta rápida permite conectar os caminhos correspondentes. Configure o **Prazo de espera** e a saída **Se não responder**. Botão de abrir site não equivale a botão de resposta rápida. Sem botões de resposta rápida, a opção **Aguardar resposta** oferece os caminhos **Qualquer resposta** e **Se não responder**. Confira as opções efetivamente apresentadas para o conteúdo e provedor escolhidos. Na Cloud, use modelos aprovados quando a janela estiver fechada. Não substitua o modelo por texto livre só porque o fluxo é automático. ## Confira o resultado Use um lead controlado e confira entrada no funil, tag, responsável, mensagem e caminho de resposta. Depois, abra [Ver execuções](/automacoes/acompanhar/) para localizar a execução e os nós alcançados. --- # Simular uma automação Fonte: https://ajuda.matchsales.com.br/automacoes/simular/ O **Playground** depende de liberação no workspace. A simulação usa a definição do fluxo para mostrar o caminho e as saídas sem enviar mensagens reais nem gravar os dados do cenário. 1. Abra o fluxo e selecione **Simular** quando a ação estiver disponível. 2. Configure o cenário do gatilho e os dados usados pelas condições. 3. Execute a simulação e acompanhe a linha do tempo e as saídas. 4. Avance o relógio nas esperas e indique respostas do contato ou do time quando o cenário oferecer essas decisões. 5. Ajuste o fluxo e repita os caminhos necessários antes de ativá-lo. ![Cenário do Playground com os dados do contato, lead e mensagem para simulação](guideShot0Light.src) Uma resposta simulada depois do prazo segue o comportamento de atraso; não deve escolher o caminho de resposta dentro do prazo. A simulação não confirma disponibilidade do canal, aprovação de modelos ou entrega real do provedor. Após ativar, use [o histórico de execuções](/automacoes/acompanhar/) para acompanhar o funcionamento. --- # Cadências Fonte: https://ajuda.matchsales.com.br/cadencias/ Uma cadência é uma sequência comercial no tempo. Ela diz o que o vendedor deve fazer, e quando, em um lead. ![Lista de cadências com etapas, atividades e status de execução](/images/pipefacil/cadencias/lista-light.png) - [Automações](/automacoes/) - [Modo Foco](/foco/) - [Funil](/pipeline/) ## Guias da rotina - [Criar uma cadência](/cadencias/criar/) - [Gerenciar a matrícula de um lead](/cadencias/matriculas/) - [Métricas e matrículas](/cadencias/metricas/) - [Cadências pela API](/developers/cadencias/) --- # Criar uma cadência Fonte: https://ajuda.matchsales.com.br/cadencias/criar/ A cadência define quem entra, quais atividades o vendedor executa e como a rotina termina. O workspace precisa ter o recurso e as permissões de edição. 1. Em **Cadências**, crie uma rotina e defina o nome e o funil. 2. Configure a entrada: gatilho e condições que matriculam o lead. Sem condições adicionais, todos os leads compatíveis com o gatilho entram. 3. Na régua, adicione os dias e as atividades na ordem de execução. 4. Abra cada atividade, selecione o canal e escreva o objetivo. O vendedor lê esse objetivo no Modo Foco. 5. Para WhatsApp, escolha a orientação: mensagem escrita pelo vendedor, script padrão ou configuração por vendedor. Canais oficiais também usam modelos aprovados quando necessário. 6. Configure os resultados que encerram a rotina, revise as validações e salve. ![Editor de cadência com entrada, dias, atividades e regras de encerramento](guideShot0Light.src) Uma mensagem marcada como obrigatória pode impedir a conclusão da atividade no Modo Foco até o vendedor utilizá-la. Confira as regras e os canais de cada pessoa antes de ativar a rotina. Quando a CIA estiver disponível, ela pode preparar um rascunho. Revise entrada, mensagens, dias e resultados antes de salvar. Veja [Gerenciar a matrícula](/cadencias/matriculas/), [Métricas](/cadencias/metricas/) e [Modo Foco](/foco/). --- # Gerenciar a cadência de um lead Fonte: https://ajuda.matchsales.com.br/cadencias/matriculas/ No detalhe do lead, abra **Cadência**. A aba reúne a matrícula e as atividades da instância daquele negócio. ## Matricular e trocar Escolha uma cadência ativa do funil. Quando o lead já avançou no atendimento, selecione o dia inicial disponível. Dias anteriores não geram atividades. Trocar a cadência substitui a rotina atual. Confira as tarefas pendentes antes de confirmar a alteração. ![Matrícula do lead com seleção da cadência e do dia inicial](guideShot0Light.src) ## Pausar, retomar e remover **Pausar** interrompe a rotina; **Retomar** volta a operar a instância pausada. A remoção encerra a matrícula e cancela tarefas abertas. Ela não desfaz mensagens já enviadas. ## Executar atividades Leia o objetivo da atividade e confira o número de tentativas. Execute pelo Modo Foco ou pelos comandos disponíveis na aba. WhatsApp, e-mail e chamadas dependem da integração e podem gerar cobrança. **Pular** exige um motivo. Uma conclusão manual registra o estado da atividade e não confirma um envio ao provedor. Veja [Modo Foco](/foco/) e [Operar cadências pela API](/developers/cadencias/). --- # Métricas e matrículas de cadências Fonte: https://ajuda.matchsales.com.br/cadencias/metricas/ A lista de cadências apresenta matrículas e situação geral. Na aba **Métricas** do editor, a régua mostra os resultados de cada atividade. ![Métricas da cadência com matrículas, atividades, atrasos e resultados](guideShot0Light.src) ## Ler a régua Confira quantos negócios estão ativos, pausados ou encerrados e quais resultados encerraram a matrícula. Selecione a posição para consultar os leads relacionados. Chegar a uma atividade e terminar nela são recortes diferentes. Compare os dois antes de concluir que uma etapa converteu ou interrompeu todos os negócios que passaram por ela. O resultado considera o momento do encerramento da matrícula. A etapa atual do lead pode ter mudado depois; não substitua o resultado histórico pela situação atual. Confira desde quando os dados são medidos e o período da análise. Veja [Gerenciar matrículas](/cadencias/matriculas/) e [Consultar matrículas pela API](/developers/cadencias/). --- # Calendário Fonte: https://ajuda.matchsales.com.br/calendario/ O calendário mostra eventos do workspace. A conexão com o Google Calendar fica em Integrações. ![Calendário semanal do PipeFácil com reuniões e tarefas agendadas](/images/pipefacil/calendario/semana-light.png) - [Integrações](/integracoes/) - [Tarefas](/tarefas/) ## Guias relacionados - [Criar reuniões e acompanhar gravações](/calendario/reunioes/) - [Campos de evento no lead](/calendario/campos-de-evento/) - [Calendário pela API](/developers/calendario/) --- # Campos de evento no lead Fonte: https://ajuda.matchsales.com.br/calendario/campos-de-evento/ O tipo de campo **Evento** representa uma reunião no lead. Sua configuração define o modelo usado para os dados da agenda. ## Configurar Em **Configurações** > **Campos**, crie ou edite um campo do tipo evento. Configure as informações da reunião e os convidados oferecidos pelo modelo. O modelo pode usar membros do workspace e o contato do lead. Também pode usar campos do tipo **Membro do workspace** para selecionar convidados a partir do cadastro do negócio. ![Configuração de campo Evento com modelo da reunião, duração e convidados](guideShot0Light.src) ## Preencher no lead Adicione o campo ao funil e à etapa. No detalhe do lead, preencha ou ajuste a reunião pelo campo. Confira data, hora, responsável e convidados no calendário. Um convidado do time não é o contato do cliente. Revise cada identidade para evitar convites para a pessoa errada. Consulte [Regras de campos](/configuracoes/regras-de-campos/) e [Reuniões](/calendario/reunioes/). --- # Criar reuniões e acompanhar gravações Fonte: https://ajuda.matchsales.com.br/calendario/reunioes/ A agenda reúne reuniões, tarefas, etapas de cadência e eventos externos disponíveis. Uma reunião pode ser criada no CRM mesmo sem uma conta Google conectada; a conferência automática depende da integração. 1. Em **Calendário**, use a ação de criar reunião. 2. Informe título, início, fim e fuso. Para compromissos de dia inteiro, escolha a opção correspondente. 3. Defina o responsável e os convidados. Membros do time e contatos são identidades diferentes. 4. Crie uma conferência quando disponível ou cole o link de uma reunião existente. 5. Para gravar, habilite o bot quando o recurso estiver disponível e use um link de Google Meet ou Microsoft Teams. 6. Confira os dados e salve a reunião. ![Formulário Nova reunião com data, hora, conferência, convidados e descrição](guideShot0Light.src) O bot precisa conseguir entrar na reunião. A solicitação de gravação não confirma que o áudio já foi capturado. Acompanhe os eventos na linha do tempo do lead e abra o link da gravação quando estiver disponível. Quando uma reunião estiver vinculada a um lead, seu histórico mantém o contexto do negócio. Se um convidado deixar de existir, o registro histórico pode identificá-lo como removido. Veja [Campos de evento](/calendario/campos-de-evento/) e [Calendário pela API](/developers/calendario/). --- # CIA Fonte: https://ajuda.matchsales.com.br/cia/ CIA é o copiloto comercial do PipeFácil. Ele resume ligações, sugere campos e aplica um scorecard. ![Configuração da CIA com templates de resumo e análise de fechamento](/images/pipefacil/configuracoes/cia-light.png) - [Funil](/pipeline/) - [Configurações](/configuracoes/) ## Guias relacionados - [Análises comerciais e scorecard](/cia/analises/) ## Escolha a ferramenta de IA | Ferramenta | Uso | | ---------- | -------------------------------------------------------------------------------- | | CIA | Apoia o vendedor com análise, resumo, sugestões e contexto comercial. | | Agente SDR | Atende e qualifica contatos no canal e transfere o atendimento conforme o fluxo. | | Automação | Executa ações a partir de eventos; pode incluir uma ação de IA. | A CIA não passa a responder clientes apenas por estar disponível no workspace. Para atendimento automático, consulte [Criar um agente SDR](/sdr/criar/). Para uma sequência de ações, use [Automações](/automacoes/). ## Disponibilidade e consumo Confira a disponibilidade do recurso no workspace e as permissões do membro. Para ajustar os padrões da CIA, use sua seção em **Configurações**; consulte os resultados na aba CIA do lead. Operações de IA podem consumir MS Coins, como análises, resumos, sugestões do copiloto e geração de fluxos com a CIA. O agente SDR também pode consumir coins ao classificar mensagens, responder e realizar testes com IA. O consumo depende das operações executadas e da configuração comercial do workspace. Não considere uma interação como garantia de uma única cobrança, nem um teste com IA como necessariamente gratuito. Confirme saldo, preços e condições com o responsável pela conta. --- # Análises comerciais e scorecard Fonte: https://ajuda.matchsales.com.br/cia/analises/ A CIA utiliza o contexto comercial disponível para produzir análises e sugestões. Abra a aba CIA do lead para consultar o resultado e o relatório. ## Critérios e evidências O scorecard usa critérios configurados para o workspace. Os critérios podem ter tipos diferentes; revise as perguntas e a escala esperada antes de comparar resultados. O relatório apresenta o resumo e a justificativa por fase, quando disponíveis. A quantidade de fases analisadas ajuda a entender a cobertura da nota. Uma nota parcial não representa evidência sobre etapas que não foram analisadas. ![Resultado de análise com performance geral, estado da negociação e notas por fase](shotCiaScorecardLight.src) ## Copiloto e edição do processo O copiloto pode sugerir preenchimentos e ações. Confira os dados e o efeito antes de aplicar uma sugestão. Na criação de automações com a CIA, revise o rascunho no editor antes de ativá-lo. As funções dependem dos recursos disponíveis no workspace. Um pedido de análise pode terminar de forma assíncrona; acompanhe a aba CIA até o resultado aparecer. Veja [Criar automações com a CIA](/automacoes/criar/) e [Solicitar análise em um fluxo](/automacoes/nos/acao-analisar-cia/). ## Ativação e consumo Se a aba ou uma ação não aparecer, confira a disponibilidade da CIA no workspace e as permissões do membro. Ativar um agente SDR é um procedimento separado; veja [CIA, SDR e consumo de IA](/cia/). Uma solicitação de análise usa IA e pode consumir MS Coins. Confira as condições da conta antes de repetir análises ou configurar chamadas automáticas em escala. --- # Configurações Fonte: https://ajuda.matchsales.com.br/configuracoes/ Configurações é o painel do workspace. A barra lateral agrupa **Conta**, **Workspace**, **Equipe** e **Conexões**. O que cada pessoa vê depende da permissão. Sem a permissão de configurar funis, a seção **Funis** não aparece. ![Área de Configurações do PipeFácil com a navegação de conta, workspace, equipe e conexões](/images/pipefacil/configuracoes/perfil-light.png) - [Configurar funis](/configuracoes/funis/) — Crie o funil, edite etapas e defina quem pode vê-lo. - [Gerenciar membros e acessos](/configuracoes/membros/) — Convide o time e confira presença, permissões e visibilidade. ## Nesta área ## Guias relacionados - [Regras de campos](/configuracoes/regras-de-campos/) - [Comportamentos do funil](/configuracoes/comportamentos-do-funil/) - [Categorias de tarefas](/configuracoes/categorias-de-tarefas/) - [Catálogo de produtos](/configuracoes/produtos/) ## Organize o atendimento - [Criar e usar tags](/configuracoes/tags/). - [Distribuir leads entre vendedores](/configuracoes/distribuicao-de-leads/). - [Conectar o WhatsApp](/integracoes/whatsapp/). --- # Criar campos personalizados Fonte: https://ajuda.matchsales.com.br/configuracoes/campos/ Campos personalizados são definições do workspace. O funil decide se o campo aparece e se ele é obrigatório na etapa. Você precisa da permissão de configurar campos. ![Lista de campos personalizados agrupados por empresa e sem grupo](/images/pipefacil/configuracoes/campos-light.png) 1. Vá até **Configurações** > **Campos**. 2. Selecione **Novo campo**. ![Diálogo Novo campo com nome, descrição, tipo, grupo e obrigatoriedade](/images/pipefacil/configuracoes/campos-novo-light.png) 3. Informe o nome e o tipo. Tipos comuns: **Texto**, **Número**, **Moeda**, **Seleção**, **Data** e **Sim/Não**. 4. Se o tipo for **Seleção** ou **Múltipla escolha**, cadastre as opções. 5. Salve o campo. 6. Em **Configurações** > **Funis**, abra o funil e a aba **Campos**. Marque visibilidade e obrigatoriedade por etapa. Um campo obrigatório na etapa abre o diálogo **Campos obrigatórios** quando alguém tenta avançar o lead sem preenchê-lo. ## Tipos e regras adicionais O tipo **Membro do workspace** permite selecionar uma pessoa do time. O tipo **Evento** vincula o campo a uma reunião. Veja [Campos de evento e reuniões](/calendario/campos-de-evento/). Use **Placeholder** para orientar o preenchimento sem gravar um valor. Para mostrar um campo apenas quando outro possuir um valor, configure a regra de visibilidade. **Editável somente pela API** mantém o valor visível no aplicativo, mas restringe sua alteração à API pública. Configure a visibilidade e os níveis **sugerido** e **obrigatório** no funil e nas etapas. Consulte [Regras de campos](/configuracoes/regras-de-campos/). ## Organizar campos em abas No editor de campos do funil, selecione **Nova aba** para criar uma seção. Arraste campos personalizados, Nome, Valor, Previsão de fechamento e campos do sistema para outra aba ou use **Mover para a aba**. E-mail e Telefone permanecem no cabeçalho do lead. A busca procura campos em todas as abas. As abas, a ordem dos campos e a exibição dos campos do sistema organizam o detalhe do lead em cada funil. Você pode mover ou ocultar Probabilidade, Responsável, Corresponsável, No estágio, Empresa e Origem. Ocultar um campo do sistema altera apenas sua exibição no detalhe; não muda atribuições nem outros dados. Até personalizar o funil, ele segue a organização do workspace. Essa organização não altera o tipo, o valor salvo ou as regras de visibilidade e obrigatoriedade do campo. No detalhe do lead, selecione **Editar campos** para atualizar os valores disponíveis naquela etapa. Essa ação altera os dados do lead, não a definição compartilhada do campo. ## Próximos passos - [Configurar funis](/configuracoes/funis/) - [Criar um lead](/pipeline/criar-lead/) --- # Categorias de tarefas Fonte: https://ajuda.matchsales.com.br/configuracoes/categorias-de-tarefas/ Categorias classificam atividades como ligação, reunião ou follow-up. A gestão exige a permissão de configurar categorias de tarefas. 1. Em **Configurações**, abra **Categorias de tarefa**. 2. Selecione **Nova categoria**, informe o nome e ajuste a aparência disponível no formulário. 3. Salve e escolha a categoria ao [criar uma tarefa](/tarefas/criar/). ![Cadastro de categoria de tarefa com nome e cor](guideShot0Light.src) Você pode renomear as categorias padrão, mas não arquivá-las. Para categorias próprias, **Arquivar** retira a opção do uso corrente e preserva as tarefas e o histórico. Use **Restaurar** quando quiser utilizá-la novamente. ![Lista de categorias padrão e personalizadas, com grupo de arquivadas](guideShot1Light.src) Confira a categoria e o prazo antes de comparar [métricas de tarefas](/tarefas/metricas/). --- # Comportamentos do funil Fonte: https://ajuda.matchsales.com.br/configuracoes/comportamentos-do-funil/ Os comportamentos determinam como leads de WhatsApp e Instagram são agrupados e exibidos. A aba depende da disponibilidade do recurso no workspace e da permissão de gestão. ## Escolha os comportamentos | Comportamento | Efeito | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Clientes recorrentes | O contato pode ter um negócio neste funil mesmo com negócios em outros funis. Um negócio encerrado neste funil pode voltar no retorno do contato. | | Funil multicanal | Permite um negócio aberto por canal neste funil, como WhatsApp e Instagram para o mesmo contato. | | Fila de atendimento | Os leads na etapa escolhida ficam sem responsável e são visíveis ao time com acesso ao funil. | Essas regras não substituem o acesso ao funil nem as permissões de cada membro. Revise canais de entrada e distribuição junto com o comportamento. 1. Vá até **Configurações** > **Funis** e abra o funil. 2. Abra **Comportamentos** e ligue as opções desejadas. 3. Para **Fila de atendimento**, escolha a **Etapa da fila** entre as etapas ativas desse funil. Ganho e perda não podem ser a fila. 4. Confira as opções e selecione **Salvar**. ![Comportamentos do funil: clientes recorrentes, funil multicanal e fila de atendimento](guideShot0Light.src) A configuração de fila também afeta a visibilidade dos leads que já estavam na etapa. Ao entrar na fila, o lead fica sem responsável. Ao sair, a atribuição segue as regras do processo; confira o responsável no card. ## Retorno e duplicidade A criação por WhatsApp e Instagram considera o funil e os comportamentos configurados. Uma movimentação ou reabertura pode ser recusada se criar negócios abertos incompatíveis no destino. Resolva o conflito indicado antes de repetir. Os comportamentos de entrada não garantem que uma importação crie duplicatas; a importação tem suas próprias regras. ## Integrações Para configurar por API, use `behaviors`. A fila exige uma etapa já criada. Consulte [Configurar funis pela API](/developers/funis/). --- # Distribuir leads entre vendedores Fonte: https://ajuda.matchsales.com.br/configuracoes/distribuicao-de-leads/ A distribuição define quem recebe os leads criados automaticamente. A criação manual permite atribuir o responsável diretamente. Você precisa de permissão para configurar funis. Revise também o [funil de entrada e o acesso do canal](/integracoes/canais/). ## Configure a distribuição do funil 1. No **Funil**, selecione o quadro que recebe os leads. 2. Abra o menu do funil e selecione **Distribuição de leads**. 3. Escolha a estratégia. Em **Rodízio** ou **Por carga de trabalho**, selecione os participantes. 4. Se ativar **Distribuir só para quem está online**, escolha o comportamento em **Se ninguém estiver online**. 5. Salve e confira o responsável de um novo lead criado pela origem configurada. | Estratégia | Efeito | | --------------------- | --------------------------------------------------------------------------------------------------- | | Manual | Mantém quem criou como responsável. Na entrada automática por canal, usa o responsável de fallback. | | Rodízio | Alterna entre os membros ativos selecionados. | | Por carga de trabalho | Prioriza quem tem menos negócios abertos entre os participantes. | | Por canal | Distribui entre os membros do canal que podem enviar mensagens. | ![Distribuição do funil com rodízio, participantes e opção de considerar a presença](shotDistribuicaoLeadsLight.src) Se não houver participantes elegíveis, a entrada automática pode ficar com um membro de fallback. Isso não significa que o rodízio tenha distribuído para toda a equipe. ## Confira a regra do canal Em **Configurações** > **Integrações**, abra o canal e **Distribuição de leads**: - **Seguir o funil** usa a estratégia do funil de entrada. - **Entre quem tem acesso** distribui entre membros do canal com permissão de envio. O nível **Só ver** permite acompanhar o canal; ele não inclui a pessoa na distribuição por membros do canal. Um canal pode seguir o funil padrão quando não tiver outro destino configurado. ## Presença e fallback Com **Distribuir só para quem está online**, membros ocupados, ausentes, offline ou em outro workspace ficam fora da seleção online. Estar logado não garante estar online naquele workspace. Em **Se ninguém estiver online**, escolha entre distribuir pela mesma regra ignorando a presença ou deixar com quem criou o lead. Na entrada por canal, essa segunda opção usa o fallback da entrada. A regra de fallback também é usada quando a presença não pode ser consultada. Consulte [Presença e acessos dos membros](/configuracoes/membros/). ## Reatribua leads existentes Alterar a distribuição não reatribui automaticamente os leads já cadastrados. Abra o lead e ajuste **Responsável** em **Detalhes**. Use **Corresponsável** para incluir outra pessoa sem trocar o responsável principal. Para que o corresponsável mantenha acesso após um repasse, confira **Compartilhamento de leads** em **Configurações** > **Acessos**, além do acesso ao canal. ## Diagnostique uma atribuição inesperada Confira, nesta ordem: canal e funil de entrada, regra do canal, estratégia do funil, participantes ativos, presença e fallback. Verifique depois se uma automação trocou o responsável; a linha do tempo registra a mudança. O bloco [Round robin de automação](/automacoes/nos/fluxo-round-robin/) alterna caminhos do fluxo. Ele só altera o responsável se o caminho executar uma ação de atribuição. --- # Configurar funis Fonte: https://ajuda.matchsales.com.br/configuracoes/funis/ O funil define as colunas do quadro. As etapas de ganho e perda encerram o negócio. ![Lista de funis em Configurações com etapas, acesso e ordem de exibição](/images/pipefacil/configuracoes/funis-light.png) Você precisa da permissão de configurar funis. ## Crie um funil 1. Vá até **Configurações** > **Funis**. 2. Selecione **Novo funil**. 3. Informe o **Nome**. A descrição é opcional. 4. Selecione **Criar funil**. O backend cria as etapas padrão. ## Edite as etapas 1. Na lista de funis, selecione o funil. 2. Abra a aba **Etapas**. 3. Renomeie, reordene ou adicione colunas. As etapas de ganho e perda ficam fixas no fim. 4. Na aba **Campos**, defina quais campos aparecem e quais são obrigatórios em cada etapa. 5. Selecione **Concluir** para salvar as alterações do funil. 6. (Opcional) Na aba **Acesso**, restrinja quem vê o funil. Essa aba só aparece para papéis privilegiados. As alterações nas etapas e nos campos ficam em rascunho até você selecionar **Concluir**. Selecione **Cancelar** para descartar as alterações não salvas. A visibilidade e a obrigatoriedade dos campos neste funil não alteram a definição global. A definição vive em [Campos](/configuracoes/campos/). Na lista de funis, **Configurar** abre as etapas e os campos do funil. **Acesso** controla quais membros podem abrir o quadro. O botão **Salvar ordem** grava a posição dos funis na lista. ## Descrições e comportamentos Descreva o objetivo do funil e das etapas para orientar o time e fornecer contexto à CIA. Na aba **Comportamentos**, configure clientes recorrentes, funil multicanal e fila de atendimento, quando disponíveis no workspace. Consulte [Comportamentos do funil](/configuracoes/comportamentos-do-funil/) antes de alterar regras que afetam a criação e a visibilidade dos leads. Na aba **Campos**, configure os campos do funil nas mesmas abas do detalhe do lead. Selecione uma linha para revisar a visibilidade e a exigência por etapa. As alterações são salvas enquanto você edita. Também é possível abrir **Editar campos** no menu do detalhe de um lead. Essa edição altera a configuração compartilhada do funil, não apenas aquele lead. Veja [Regras de campos por etapa](/configuracoes/regras-de-campos/). ## Distribuição e acesso do time No menu do quadro, **Distribuição de leads** define a atribuição de novos leads automáticos. A regra do canal pode seguir essa configuração ou distribuir entre seus próprios membros. Veja [Distribuir leads entre vendedores](/configuracoes/distribuicao-de-leads/). A aba **Acesso** controla quem abre o funil. Ela não troca o responsável dos leads nem libera o envio pelo canal. Confira também [Papéis e acessos dos membros](/configuracoes/membros/). ## Próximos passos - [Mover um lead](/pipeline/mover-lead/) - [Motivos de perda](/pipeline/mover-lead/) --- # Gerenciar membros, presença e acessos Fonte: https://ajuda.matchsales.com.br/configuracoes/membros/ O papel define as permissões e o alcance dos dados de cada membro. A presença informa a disponibilidade para trabalhar naquele workspace. Confira os dois aspectos ao organizar o atendimento. ## Convide uma pessoa Você precisa da permissão de convidar membros. ![Lista de membros ativos e convites pendentes do workspace](/images/pipefacil/configuracoes/membros-light.png) 1. Vá até **Configurações** > **Membros**. 2. Selecione **Convidar membro**. ![Diálogo Convidar membro com e-mail e seleção de cargo](/images/pipefacil/configuracoes/membros-convite-light.png) 3. Informe o **E-mail**. 4. Escolha o papel: **Administrador**, **Gerente**, **Closer** ou **SDR**. 5. Envie o convite. 6. Se o diálogo mostrar **Convite criado**, copie o link para enviar manualmente. O convite também vai por e-mail. Se o e-mail já tiver conta, a pessoa entra direto no workspace. Caso contrário, ela abre o link, informa o nome e cria uma senha com no mínimo 10 caracteres. O **Proprietário** não se atribui neste diálogo. Papéis como **Parceiro**, **Suporte técnico** e **Agente** não ocupam vaga do plano e não aparecem como escolha aqui. ## Presença do time Quando a presença estiver disponível, o menu do avatar permite escolher **Disponível**, **Ocupado** ou **Aparecer offline**. O time vê os estados **Online**, **Ocupado**, **Ausente**, **Em outro workspace** ou **Offline**. ![Menu da conta com as opções Disponível, Ocupado e Aparecer offline](shotPresencaMenuLight.src) O estado considera a conexão e a atividade no workspace. **Em outro workspace** informa apenas que a pessoa está trabalhando em outro local; não revela qual. Presença não concede permissões nem muda o acesso aos dados. | Estado | Significado | | ------------------ | ------------------------------------------------------------------------ | | Online | A pessoa está disponível e ativa neste workspace. | | Ocupado | A pessoa selecionou o estado ocupado. | | Ausente | A pessoa está conectada, mas sem atividade recente. | | Em outro workspace | A pessoa está trabalhando em outro workspace; o nome dele não é exposto. | | Offline | A pessoa está sem presença ativa ou escolheu aparecer offline. | ![Resumo da presença da equipe com estados online, ocupado, ausente, em outro workspace e offline](shotPresencaEquipeLight.src) Estar logado não garante estar **Online** neste workspace. A opção **Aparecer offline** também afeta como o estado é apresentado ao time. A presença pode mudar quem recebe novos leads quando o funil usa **Distribuir só para quem está online**. Nesse caso, confira também a [regra de fallback](/configuracoes/distribuicao-de-leads/). Ela não altera as permissões para abrir registros. ## Papéis e alcance dos dados | Papel | Alcance padrão dos leads | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Proprietário e Administrador | Dados do workspace. | | Gerente | Seus próprios leads e os leads dos membros dos squads que gerencia. Sem squad gerenciado, fica com os próprios dados. | | Closer e SDR | Leads de sua responsabilidade. | Participar do mesmo squad não libera os dados dos colegas para todos. Em **Configurações** > **Squads**, confira quem gerencia a equipe e quais membros fazem parte dela. Permissão define a ação disponível; visibilidade define sobre quais registros a pessoa pode agir. Liberar a ação de ver conversas não transforma o alcance de SDR em acesso a todos os leads. ## Ajuste permissões e acompanhamento Em **Configurações** > **Acessos**, selecione o membro, revise as permissões e selecione **Salvar alterações**. Essa tela permite ajustar ações como ver conversas ou enviar mensagens, conforme o acesso de quem configura. ![Permissões individuais para ver conversas, enviar mensagens e usar templates](shotMembrosAcessosLight.src) Para o cenário “vendedor atende, gestor acompanha”, confira o responsável do lead e os squads gerenciados pelo gestor. Não é necessário transformar cada observador em administrador para organizar a equipe. O campo **Corresponsável** inclui outra pessoa no negócio. Com **Compartilhamento de leads** ativo em **Configurações** > **Acessos**, o corresponsável mantém a visibilidade após trocar o responsável. Esse compartilhamento não substitui o acesso ao canal para enviar mensagens. ![Controle Compartilhamento de leads para manter a visibilidade do corresponsável](shotCompartilhamentoLeadsLight.src) ## Confira o acesso em cada camada | Camada | Onde conferir | Efeito | | ----------------------------------- | ---------------------------------------- | ----------------------------------------------------------- | | Papel e permissões | Membros e Acessos | Define ações e alcance de dados. | | Responsável, corresponsável e squad | Detalhe do lead e Squads | Define quais leads entram no alcance do membro. | | Acesso ao funil | Configurações > Funis > Acesso | Controla a abertura de um funil restrito. | | Acesso ao canal | Integrações > canal > Acesso dos membros | Separa acompanhar o canal de enviar por ele. | | Filtros do inbox | Conversas | Pode ocultar registros que a pessoa tem permissão para ver. | Gerentes podem acompanhar os canais dos membros dos squads que gerenciam. Esse acompanhamento não concede automaticamente permissão para enviar pelo número de outra pessoa. ## Investigue uma conversa que não aparece Confira o workspace selecionado, o papel do membro, o responsável do negócio e o squad do gerente. Depois, verifique o acesso ao canal e limpe os [filtros do inbox](/conversas/filtrar/). Se outro membro autorizado vê a mensagem, verifique o alcance dos dados antes de tratar o caso como falha de recebimento. Se todos os membros autorizados deixaram de receber, consulte [Diagnosticar o WhatsApp](/integracoes/solucionar-problemas-whatsapp/). ## Próximos passos - [Distribuir leads entre vendedores](/configuracoes/distribuicao-de-leads/). - [Configurar o acesso ao canal](/integracoes/canais/). - [Primeiros passos](/fundamentals/get-started/) - [Conceitos](/fundamentals/concepts/) --- # Catálogo e produtos do negócio Fonte: https://ajuda.matchsales.com.br/configuracoes/produtos/ O catálogo centraliza produtos disponíveis ao workspace. A aba de produtos do lead registra os itens daquela negociação. A disponibilidade depende dos recursos e permissões do workspace. 1. Em **Configurações**, abra a seção de produtos e cadastre o item com seus valores comerciais. ![Novo produto com nome, SKU, valor e descrição antes de confirmar o cadastro](shotProdutoCadastroLight.src) 2. Abra o [detalhe do lead](/pipeline/detalhe-do-lead/) e a aba de produtos. 3. Selecione os itens, ajuste as quantidades e confira o total. 4. Confira os itens, as quantidades e o total gravados no negócio. O preço no negócio é uma cópia da condição comercial daquele item. Alterar o catálogo não reprecifica automaticamente os itens já associados ao negócio. Ao desligar acréscimo, desconto ou frete, confira como os valores e o total foram recalculados. A composição de produtos do lead não equivale a cobrar uma assinatura do workspace. ## Escopo do catálogo A composição registra produtos e valores da negociação. A aba de produtos não gera nem envia um documento de orçamento ao cliente. Para enviar uma proposta, prepare o documento no processo comercial da empresa e use os anexos da conversa quando apropriado. Cadastrar um SKU e o preço não estabelece uma integração com ERP nem um controle de estoque. Confira o escopo de uma integração específica antes de planejar a migração desses processos. --- # Regras de campos por funil e etapa Fonte: https://ajuda.matchsales.com.br/configuracoes/regras-de-campos/ A definição do campo pertence ao workspace. O funil e as etapas definem como ele aparece durante o processo. ![Níveis do campo: oculto não aparece; visível permite preencher; sugerido pede o preenchimento mas permite pular; obrigatório bloqueia o avanço sem valor](/_astro/niveis-de-campos.CBsaENFr.svg) ## Níveis de preenchimento | Nível | Resultado | | ----------- | ------------------------------------------------------------------------------ | | Oculto | O campo não aparece naquela configuração. | | Visível | A pessoa pode preencher, sem solicitação ao entrar na etapa. | | Sugerido | O diálogo oferece o campo ao entrar na etapa; permite continuar sem preencher. | | Obrigatório | O avanço depende do preenchimento. | Um campo obrigatório também é sugerido e visível. Um campo sugerido também é visível. No funil, reduza o nível de exigência antes de ocultar um campo solicitado. 1. Vá até **Configurações** > **Funis** e abra o funil. 2. Na aba **Campos**, escolha a aba que contém o campo. 3. Selecione a linha do campo para abrir as etapas e ajustar o nível. 4. Confira o resumo da regra e as etapas que mostram o campo. As alterações são salvas enquanto você edita. Um campo obrigatório em uma etapa ativa continua obrigatório nas etapas ativas seguintes, exceto nas etapas de perda. Altere a configuração na etapa de origem para retirar essa exigência. Campos sugeridos não propagam da mesma forma. A configuração base do funil também é considerada. ## Visibilidade condicional Na definição do campo, configure a exibição conforme o valor de outro campo. O campo pai pode ser de seleção, múltipla seleção ou sim/não. Escolha os valores que tornam o campo filho visível. Na múltipla seleção, basta uma opção correspondente. A regra considera também a visibilidade dos campos anteriores da cadeia. Dependências circulares não são válidas; a cadeia tem limite de dez níveis. Um campo oculto pela condição não deve bloquear o avanço por obrigatoriedade. Revise a configuração no funil de destino quando mover o lead entre funis. ## Campos padrão, placeholder e API As regras por etapa também podem solicitar campos padrão do negócio. Um **Placeholder** orienta o que digitar; não conta como valor preenchido. **Editável somente pela API** deixa o valor somente para leitura no aplicativo. Considere quem irá preenchê-lo antes de torná-lo obrigatório no processo. Veja [Cadastros e campos pela API](/developers/cadastros/) e [Configurar funis pela API](/developers/funis/). --- # Criar e usar tags Fonte: https://ajuda.matchsales.com.br/configuracoes/tags/ Tags são rótulos do workspace para organizar e filtrar leads. Crie uma lista curta de origens, interesses ou segmentos que seu time realmente utiliza. ## Cadastre uma tag Você precisa de permissão para configurar tags. 1. Em **Configurações** > **Tags**, selecione **Nova tag**. 2. Informe o nome e escolha a cor. 3. Selecione **Criar tag**. Confira o novo rótulo na lista. ![Diálogo Nova tag com nome, cor e confirmação de criação](shotNovaTagLight.src) Na lista, use a ação de edição para alterar nome ou cor e selecione **Salvar**. ## Aplique em um lead Abra o [detalhe do lead](/pipeline/detalhe-do-lead/) e ajuste as tags. Depois, use o filtro de tags no funil para localizar os leads marcados. ![Lista de tags do workspace com cores, busca e ação Nova tag](shotTagsLight.src) Uma tag como “Interesse: consórcio” registra uma classificação do time. Os [dados de campanha e UTMs](/integracoes/origem-e-rastreio-de-leads/) guardam o rastreamento recebido da origem; confira esses dados antes de classificar uma campanha. Para marcar leads automaticamente, use [Adicionar tag](/automacoes/nos/acao-adicionar-tag/) ou [Remover tag](/automacoes/nos/acao-remover-tag/) no editor de automações. ## Exclua com cuidado Excluir uma tag remove o rótulo de todos os leads que a utilizam. A exclusão pede confirmação e não pode ser desfeita. Se deseja apenas desmarcar um negócio, remova a tag no próprio lead. --- # Contatos Fonte: https://ajuda.matchsales.com.br/contatos/ Contatos guarda as pessoas do workspace. Um lead pode apontar para um contato. Leads criados sem dados de contato podem ficar sem esse vínculo. O mesmo contato pode aparecer em mais de um negócio. A lista vive no servidor. Busca e filtros sobrevivem ao recarregar a página. ![Lista de contatos do PipeFácil com nome, telefone, e-mail e última mensagem](/images/pipefacil/contatos/lista-light.png) Quando o recurso estiver disponível no workspace, você pode [mesclar os contatos](/contatos/mesclar/). - [Buscar um contato](/contatos/buscar/) — Ache por nome, telefone ou e-mail e recorte a lista. - [Mesclar contatos](/contatos/mesclar/) — Mantenha um cadastro e incorpore o contato duplicado. ## Nesta área --- # Abrir a ficha do contato Fonte: https://ajuda.matchsales.com.br/contatos/abrir/ A ficha reúne identidade, negócios e atividade do contato. 1. Em **Contatos**, selecione a linha da pessoa. ![Ficha de contato com identidade, atividades, negócios e botão Abrir conversa](/images/pipefacil/contatos/ficha-light.png) 2. No cartão de identidade, edite primeiro nome, sobrenome, telefone ou e-mail. O nome exibido combina primeiro nome e sobrenome. 3. Em **Negócios**, abra o lead ligado ao contato. 4. Nas abas **Atividades**, **Tarefas** e **Notas**, confira o histórico dos negócios mais recentes. A atividade vem dos leads do contato. Se houver muitos negócios, a ficha mostra só os mais recentes e avisa o recorte. Na ficha, edite o telefone para adicionar o número do WhatsApp. Se o número já pertencer a outro contato, confira quem usa o número e selecione **Juntar contatos**. Para excluir, use as ações da ficha. O diálogo pede confirmação. Depois o PipeFácil volta para a lista. ## Contato cadastrado sem conversa **Abrir conversa** procura o histórico associado ao contato. Se o cadastro ainda não tem conversa, abra seu lead no funil e siga [Iniciar uma conversa](/conversas/iniciar/). A pesquisa do inbox localiza conversas existentes; ela não substitui a busca dos cadastros em **Contatos**. ## Próximos passos - [Responder uma conversa](/conversas/responder/) - [Abrir o detalhe do lead](/pipeline/detalhe-do-lead/) --- # Buscar um contato Fonte: https://ajuda.matchsales.com.br/contatos/buscar/ A busca e os filtros de **Contatos** rodam no servidor. 1. No PipeFácil, vá até **Contatos**. 2. No campo **Nome, telefone ou e-mail...**, digite o que você procura. 3. Selecione **Filtros**. Escolha **Tipo** (Clientes ou Internos), **Situação** (Ativos ou Bloqueados) e se o contato tem lead. ![Lista de contatos filtrada por busca com o popover de filtros aberto](/images/pipefacil/contatos/busca-filtros-light.png) 4. (Opcional) Marque **Com e-mail** ou **Com conversa**. 5. Para zerar, selecione **Limpar** no popover. O contador ao lado de **Contatos** é o total do recorte no servidor, não só da página visível. Quem tem permissão de excluir pode marcar linhas e apagar em lote. A exclusão pede confirmação. ## Próximos passos - [Abrir a ficha do contato](/contatos/abrir/) - [Funil](/pipeline/) --- # Mesclar contatos Fonte: https://ajuda.matchsales.com.br/contatos/mesclar/ Junte dois cadastros quando a mesma pessoa aparecer como contatos diferentes. A ação **Juntar com outro contato** depende da disponibilidade do recurso e das permissões do membro. Confira essas condições se a opção não aparecer na ficha. Você precisa das permissões para editar e excluir contatos. A mesclagem é irreversível. 1. Em **Contatos**, abra o cadastro que deve permanecer. 2. No menu de ações **⋯** do contato, selecione **Juntar com outro contato**. 3. Escolha um dos contatos sugeridos com o mesmo nome ou pesquise o cadastro duplicado por nome, telefone, e-mail ou usuário do Instagram. 4. Selecione o cadastro duplicado e confira a prévia **Como fica**. Use **Inverter** se o outro cadastro deve permanecer. ![Prévia da junção de cadastros duplicados mostrando Como fica e a ação Inverter](shotContatosMesclarLight.src) 5. Selecione **Juntar contatos**. Revise o aviso de exclusão irreversível e confirme em **Juntar contatos**. ![Aviso de junção irreversível com os dados que serão transferidos](shotContatosConfirmacaoLight.src) Por padrão, o contato aberto permanece. Se usar **Inverter**, a prévia mostra a nova escolha. Conversas, negócios e outros dados relacionados passam para o cadastro escolhido. O PipeFácil copia os campos que estiverem ausentes sem substituir valores existentes. O contato incorporado é apagado com a mesma regra de privacidade da exclusão. Ele não pode ser recuperado. Se os dois contatos tiverem negócios abertos incompatíveis, feche ou mova um deles antes de tentar novamente. ## Telefones e pessoas diferentes O cadastro que permanece conserva seu telefone preenchido. O telefone do cadastro incorporado só preenche esse campo quando ele está vazio. Mesclar não cria uma lista de números alternativos para envio. Use a mesclagem para cadastros duplicados da mesma pessoa, como identidades de WhatsApp e Instagram que pertencem ao mesmo contato. Dois decisores de uma empresa não se tornam a mesma pessoa por participar da mesma negociação. Para iniciar atendimento e entender campos de telefone secundário, consulte [Iniciar uma conversa](/conversas/iniciar/). ## Próximos passos - [Buscar um contato](/contatos/buscar/) - [Abrir o detalhe do lead](/pipeline/detalhe-do-lead/) --- # Conversas Fonte: https://ajuda.matchsales.com.br/conversas/ Conversas é o inbox do PipeFácil. Cada thread pertence a um contato e pode ter um lead ativo. Você lê a mensagem, responde no compositor e acompanha o negócio no mesmo painel. Use **Sem resposta** para localizar conversas abertas cuja última mensagem veio do contato. ![Inbox do PipeFácil com lista de conversas, thread aberta e lead relacionado](/images/pipefacil/conversas/inbox-light.png) - [Responder uma conversa](/conversas/responder/) — Abra a thread, escolha o canal e envie a mensagem. ## Nesta área ## Comece ou programe o atendimento - [Iniciar uma conversa pelo lead](/conversas/iniciar/) quando ainda não há histórico. - [Agendar uma mensagem](/conversas/agendar-mensagem/) para um envio individual futuro. - [Diagnosticar problemas no WhatsApp](/integracoes/solucionar-problemas-whatsapp/) para falhas de acesso, entrada ou envio. --- # Agendar uma mensagem Fonte: https://ajuda.matchsales.com.br/conversas/agendar-mensagem/ Agende uma mensagem individual em uma conversa de WhatsApp existente. O horário informado usa o fuso do workspace. Você precisa de acesso para enviar pelo canal. O agendamento pelo compositor aceita WhatsApp Cloud e Lite; ele não inicia uma conversa que ainda não existe. Para o primeiro envio, consulte [Iniciar uma conversa](/conversas/iniciar/). ## Agende pelo compositor 1. Em **Conversas**, abra a conversa e confira o canal de envio. 2. Escreva a mensagem e selecione **Agendar envio**, identificado pelo ícone de calendário com relógio. 3. No diálogo **Agendar mensagem**, escolha uma data e a hora futura. Confira o fuso apresentado. 4. Se a janela do WhatsApp Cloud não cobrir o horário escolhido, selecione um **Modelo aprovado**. Revise a prévia: nesse caso, o modelo substitui o texto do rascunho. 5. Confirme em **Agendar** e confira o envio na faixa de agendamentos da conversa. ![Agendamento de mensagem com data, fuso e seleção de modelo para a janela fechada](shotAgendarMensagemLight.src) Agendar confirma que o envio foi marcado. Confira o resultado depois do horário previsto; canal desconectado ou recusa do provedor podem impedir a entrega. ## Edite ou cancele Use as ações do agendamento na conversa para editar o horário ou cancelar um envio pendente. Confira o conteúdo e o canal antes de confirmar uma edição. Um envio que já saiu ou foi cancelado não pode ser reagendado como se continuasse pendente. ## Janela do WhatsApp Cloud A janela precisa permitir o texto livre no **horário marcado**, não apenas no momento em que você agenda. A mensagem recebida em outro canal não abre essa janela. O WhatsApp Lite não usa a janela da Cloud nem os modelos da Meta. Para lembretes vinculados a vencimentos ou rotinas de vários leads, use uma [automação por campo de data](/automacoes/agendar-mensagem/). --- # Filtrar a caixa de entrada Fonte: https://ajuda.matchsales.com.br/conversas/filtrar/ A lista do inbox aceita chips rápidos e um popover de filtros. 1. Em **Conversas**, escolha **Todos**, **Não lidas**, **Sem resposta**, **Agendadas**, **Internos** ou **Fechadas**. Em telas estreitas, abra o menu de opções para ver filtros ocultos. 2. Selecione o botão **Filtros**. ![Inbox de conversas com o popover de filtros por responsável, funil e origem](/images/pipefacil/conversas/filtros-light.png) 3. Ajuste **Responsável**, **Funil**, **Etapa**, origem e canal. 4. Para zerar, selecione **Limpar** no popover. **Internos** mostra contatos marcados como internos, não conversas do time entre si. **Sem resposta** mostra conversas abertas cuja última mensagem foi enviada pelo contato. Quando você filtra por número, o PipeFácil considera as mensagens daquele número. Responder pelo número filtrado remove a conversa desse recorte. O filtro de canal lista os números e provedores que você pode ver. Sem canal conectado, a lista fica vazia. ## Ordenação e conversas fechadas Escolha a ordem das conversas pelo menu da lista: mais recentes ou mais antigas. **Todos** consulta conversas abertas. Use **Fechadas** para localizar atendimentos encerrados. Os filtros por responsável, funil, etapa e origem usam o negócio ativo do contato. O histórico de mensagens pode reunir vários canais, mas o filtro da lista e o canal de envio são escolhas separadas. Consulte [Encerrar e organizar atendimentos](/conversas/gerenciar/). ## Visibilidade do membro Filtros refinam a lista à qual você já tem acesso. Selecionar **Todos** não amplia o alcance do papel nem permite ver negócios de outros vendedores. Se a conversa aparece para outra pessoa, confira responsável, squad, compartilhamento de leads e acesso ao canal em [Membros e acessos](/configuracoes/membros/). ## Próximos passos - [Responder uma conversa](/conversas/responder/) - [Disparos](/disparos/) --- # Encerrar e organizar atendimentos Fonte: https://ajuda.matchsales.com.br/conversas/gerenciar/ Fechar uma conversa encerra o atendimento na caixa de entrada. Isso não marca automaticamente o negócio como ganho ou perdido. 1. Em **Conversas**, abra o atendimento que deseja encerrar. 2. Use a ação de fechar a conversa. Ela é marcada como lida e sai da lista de abertas. 3. Abra **Fechadas** para localizar o histórico e reabrir o atendimento quando necessário. ![Caixa de entrada com conversa aberta e ação de fechar atendimento no cabeçalho](guideShot0Light.src) Uma nova mensagem do contato reabre a conversa. O fechamento também pode iniciar uma automação com gatilho **Conversa fechada**, quando houver negócio aberto e um fluxo ativo compatível. ## Seleção em massa Use a seleção da lista para operar vários atendimentos com as ações disponíveis. A exclusão exige permissão específica e confirmação. Confira a seleção antes de concluir; excluir uma conversa é diferente de fechar o atendimento. Os filtros e a ordem da lista ajudam a priorizar atendimentos. Veja [Filtrar a caixa de entrada](/conversas/filtrar/) e [Gerenciar mensagens](/conversas/mensagens/). --- # Iniciar uma conversa pelo lead Fonte: https://ajuda.matchsales.com.br/conversas/iniciar/ Use o detalhe do lead para enviar a primeira mensagem, mesmo quando o contato ainda não aparece no inbox. Você precisa de um telefone no contato, um canal ativo e permissão para ver conversas e enviar mensagens. Confira também seu [acesso ao canal](/integracoes/canais/). ## Faça o primeiro envio 1. No **Funil**, abra o lead que deseja contatar. Se ainda não existe, [crie o lead](/pipeline/criar-lead/) com o telefone do contato. 2. No detalhe, abra a área da conversa. Quando estiver recolhida e ainda não houver histórico, selecione **Iniciar conversa**. ![Área do lead sem histórico com o botão Iniciar conversa](shotLeadSemConversaLight.src) 3. Confira o telefone do contato e o canal selecionado no compositor. 4. No WhatsApp Cloud, use um modelo aprovado se a janela estiver fechada. No Lite, escreva a mensagem conforme as opções do canal. 5. Revise o destinatário e envie. Depois do envio, confira a mensagem no histórico. ![Compositor de primeiro envio com janela fechada e ação Escolher modelo](shotIniciarConversaLight.src) **Buscar conversa...** pesquisa históricos existentes. Para escolher um contato e iniciar pelo inbox, selecione **Nova conversa**. Busque um contato cadastrado ou crie um com telefone, se tiver permissão. A seleção abre a conversa existente ou um chat em branco; o primeiro envio cria o histórico no inbox. ## Telefone principal e campos personalizados O envio pelo lead usa o destinatário do contato. Salvar outro telefone em um campo personalizado não transforma esse campo em um seletor de destinatário. Para atender outra pessoa ou outro número, use o cadastro correspondente ao destinatário. Não substitua o telefone principal apenas para alternar atendimentos: essa alteração muda a identidade do contato. [Mesclar contatos](/contatos/mesclar/) serve para consolidar cadastros duplicados da mesma pessoa. A mesclagem não cria uma lista de telefones selecionáveis no mesmo card. ## Quando o envio não aparece ou fica bloqueado | Situação | O que conferir | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | O lead não tem telefone | Preencha o telefone do contato, com código do país e DDD. | | O canal não aparece | Confira conexão, acesso do membro e permissões. | | O texto livre fica bloqueado | Confira a [janela de atendimento do canal](/conversas/janela-de-atendimento/) e selecione um modelo aprovado quando necessário. | | Há erro ao carregar a conversa | Use **Tentar novamente**. Um erro de carregamento não confirma ausência de histórico. | ## Próximos passos - [Responder uma conversa](/conversas/responder/) - [Gerenciar membros e acessos](/configuracoes/membros/) - [Agendar uma mensagem](/conversas/agendar-mensagem/) --- # Janela de atendimento por canal Fonte: https://ajuda.matchsales.com.br/conversas/janela-de-atendimento/ Na Cloud API, a janela de atendimento dura 24 horas desde a última mensagem recebida do contato **no canal escolhido**. Ela determina se você pode enviar texto livre naquele canal. ![Um contato escreve no canal A, abrindo a janela de A por 24 horas. O canal B mantém sua própria janela; a mensagem em A não libera texto livre em B](/_astro/janela-por-canal.ClpxYRZr.svg) ## Antes de enviar 1. Confira o canal selecionado no compositor. 2. Confira o estado da janela desse canal. 3. Com a janela aberta, envie o conteúdo permitido pelo provedor. 4. Com a janela fechada, selecione um modelo aprovado e preencha suas variáveis. Uma mensagem enviada pela equipe não substitui a mensagem recebida necessária para abrir a janela. Uma conversa pode reunir vários números e provedores; o histórico agregado não determina a janela de todos eles. ## Cloud, Lite e Instagram O WhatsApp Lite por QR Code não usa essa janela da Cloud API nem oferece modelos da Meta. O Instagram tem regras próprias do provedor. Escolher outro canal muda as regras de envio aplicáveis. ## Integração por API Envie o canal explicitamente quando a integração precisa usar um número específico. `lastInboundAt` retornado no resumo da conversa é agregado por contato; não conclua que outro canal está liberado a partir desse valor. Leia [Conversas pela API](/developers/conversas/). --- # Gerenciar mensagens e mídias Fonte: https://ajuda.matchsales.com.br/conversas/mensagens/ ## Responder e localizar o contexto Use a ação de responder de um balão para vincular a nova mensagem ao trecho correto. Selecione a referência de uma resposta para voltar à mensagem original quando ela estiver disponível no histórico. Copie uma mensagem ou selecione um trecho da conversa pelas ferramentas disponíveis. Confira o canal e o destinatário antes de reutilizar esse conteúdo. ![Menu da mensagem com Responder, Encaminhar, Copiar, Selecionar mensagens e Detalhes do envio](guideShot0Light.src) ## Encaminhar Abra a ação de encaminhamento da mensagem, procure destinatários entre contatos internos e conversas recentes, e selecione até cinco contatos. Confira cada destinatário antes de enviar. O encaminhamento respeita acesso e capacidade do canal. Não transfira conteúdo para outro contato sem conferir o contexto comercial. ## Editar ou apagar para todos O menu do balão oferece edição e exclusão para mensagens enviadas pelo CRM quando o provedor permite. Mensagens recebidas ou de um provedor incompatível não oferecem as mesmas ações. Uma mensagem editada fica identificada no histórico. Uma mensagem apagada aparece como excluída. A exclusão para todos depende da confirmação do provedor; confira o resultado antes de presumir que o destinatário deixou de vê-la. ## Áudio e anexos O compositor aceita seleção de várias mídias e gravação de áudio. Autorize o microfone, revise a gravação e descarte se necessário. Um áudio enviado como mensagem de voz pode ter apresentação diferente de um arquivo de áudio comum. URLs de mídia têm validade limitada. Se um anexo deixar de abrir, recarregue seu acesso antes de concluir que o arquivo foi removido. Veja [Responder uma conversa](/conversas/responder/). --- # Responder uma conversa Fonte: https://ajuda.matchsales.com.br/conversas/responder/ Responda o contato sem sair do CRM. O painel mostra o chat e o lead ligado à conversa. O workspace precisa de um canal de WhatsApp conectado. Veja [Integrações](/integracoes/). Se o contato ainda não tem histórico no inbox, siga [Iniciar uma conversa pelo lead](/conversas/iniciar/). 1. No PipeFácil, vá até **Conversas**. 2. Selecione a thread na lista. Use **Buscar conversa...** se a lista for longa. ![Inbox do PipeFácil com lista de conversas e thread do contato selecionado](/images/pipefacil/conversas/inbox-light.png) 3. Confira o lead no cabeçalho. Se o contato tiver mais de um negócio, escolha qual está ativo. 4. No compositor, escreva a mensagem no campo **Escreva sua mensagem...** e envie. 5. (Opcional) Anexe um arquivo, um áudio ou um modelo aprovado pelo WhatsApp. 6. (Opcional) Digite `/` para abrir **Scripts**, **Templates** ou **Automações**. No WhatsApp Cloud, a janela de 24 horas é contada desde a última mensagem recebida daquele contato naquele canal. Uma mensagem em outro número não abre a janela do canal selecionado. Com a janela fechada, o compositor bloqueia o texto livre. Envie um modelo aprovado para retomar. Lite (QR Code) não usa essa janela de 24 horas e não oferece modelos da Meta. Uma conversa pode reunir mensagens do WhatsApp e do Instagram. Quando isso acontece, a timeline agrupa cada sequência por canal. Selecione o cabeçalho de um bloco para expandir ou recolher suas mensagens. O cabeçalho da conversa também mostra o lead ativo, a etapa e as sugestões disponíveis. A timeline identifica o provedor de cada bloco, como **Cloud** ou **Lite**, para você saber qual regra de envio se aplica. Para executar uma automação pelo compositor, consulte [Executar uma automação em um lead](/automacoes/executar/). ## Áudios, anexos e identificação Você pode selecionar várias mídias no compositor. Revise cada arquivo e sua legenda antes de enviar. Para gravar um áudio, permita o uso do microfone e use os controles de gravação para ouvir, descartar ou enviar. No menu do compositor, **Identificar quem está atendendo** acrescenta a identificação do atendente às mensagens compatíveis. Confira o conteúdo final quando usar legendas e modelos. Consulte [Gerenciar mensagens](/conversas/mensagens/) e [Janela de atendimento por canal](/conversas/janela-de-atendimento/). ## Envio em outro horário Para marcar um envio individual, use **Agendar envio** no compositor de uma conversa existente. Confira o horário no fuso do workspace e a janela do canal no momento marcado. Consulte [Agendar uma mensagem](/conversas/agendar-mensagem/). ## Próximos passos - [Filtrar a caixa de entrada](/conversas/filtrar/) - [Abrir o detalhe do lead](/pipeline/detalhe-do-lead/) - [Conectar o WhatsApp](/integracoes/) --- # Dashboard Fonte: https://ajuda.matchsales.com.br/dashboard/ O dashboard reúne métricas de vendas do workspace, do squad ou do próprio usuário, conforme a permissão de cada pessoa. Use os filtros para segmentar os indicadores por responsável, etiquetas, origem, número do WhatsApp, retorno, co-responsável, campos personalizados ou etapas pelas quais o negócio passou. O filtro por co-responsável aparece quando o compartilhamento de leads está ativo. Os filtros ativos aparecem abaixo do cabeçalho e podem ser removidos individualmente ou limpos juntos. Filtros salvos também podem ser aplicados no dashboard. Critérios exclusivos do funil, como etapa atual e data de criação, continuam disponíveis somente no funil. ![Dashboard do PipeFácil com métricas, funil de conversão, receita e ranking](/images/pipefacil/dashboard/visao-geral-light.png) - [Funil](/pipeline/) - [Tarefas](/tarefas/) --- # Desenvolvedores Fonte: https://ajuda.matchsales.com.br/developers/ A API pública usa uma chave que representa um membro do workspace. As permissões desse membro e a disponibilidade dos recursos determinam o acesso. `GET /api/v1/deals` consulta negócios abertos, ganhos e perdidos. Use `status` para limitar as situações. O workspace vem da chave; não envie `workspaceId`. ## Começar - [Autenticação e limites](/developers/authentication/). - [Tipos de acesso e permissões](/developers/tipos-de-acesso/). - [Conectar o servidor MCP do PipeFácil](/developers/mcp/). - [Paginação, identificadores e erros](/developers/boas-praticas/). - [Criar e consultar negócios](/developers/negocios/). - [Gerenciar cadastros e arquivos](/developers/cadastros/). - [Configurar funis e campos](/developers/funis/). - [Consultar e enviar conversas](/developers/conversas/). - [Gerenciar cadências](/developers/cadencias/). - [Gerenciar automações](/developers/automacoes/). - [Consultar e criar eventos](/developers/calendario/). ## Referência completa A [referência da API](/api/) descreve cada operação, seus parâmetros, corpo e respostas. O [OpenAPI em JSON](/api/openapi.json) mantém os nomes de campos e enums usados pelo servidor. As descrições e os guias estão em português. Conversas e automações exigem `ADVANCED_API`; cadências exigem também `CADENCE`. Calendário exige `CALENDAR`. Toda chave depende de `API_ACCESS`. Sem um recurso necessário, a API pode responder `403 FEATURE_DISABLED`. --- # Autenticação Fonte: https://ajuda.matchsales.com.br/developers/authentication/ A API pública autentica com uma chave no formato `pf_live_…`. A chave herda o workspace e as permissões de quem a emitiu. O `workspaceId` nunca vai no corpo da requisição. 1. No PipeFácil, vá até **Configurações** > **Chaves de API**. 2. Crie uma chave. Copie o valor. Ele aparece só nessa tela. ![Área de Chaves de API sem tokens emitidos no workspace](/images/pipefacil/developers/chaves-api-light.png) ![Diálogo Nova chave de API com nome e prazo de expiração](/images/pipefacil/developers/chaves-api-nova-light.png) 3. Envie a chave no cabeçalho `Authorization: Bearer pf_live_…`. O limite por volume é de 600 pedidos por minuto, por workspace e por IP. A API também limita a concorrência por workspace: 10 requisições são processadas ao mesmo tempo e até 40 aguardam por no máximo 5 segundos. Se não houver vaga, a API responde `429` com `Retry-After: 1`. Distribua as chamadas em lote em vez de enviá-las todas ao mesmo tempo. O contrato completo está na [referência da API pública](/api/). --- # Gerenciar automações pela API Fonte: https://ajuda.matchsales.com.br/developers/automacoes/ O grupo `/api/v1/automations` exige `API_ACCESS` e `ADVANCED_API`. Leituras exigem `automations.view`; escritas exigem `automations.edit`, além das regras de papel da API. ## Consultar antes de escrever Use o catálogo de gatilhos em `GET /api/v1/automations/triggers`. Consulte uma automação existente para conhecer sua definição. Novos fluxos usam `graphDefinition`, com nós e conexões; o formato legado `actions` permanece para compatibilidade. O identificador do canal de saída deve ser obtido no aplicativo ou na configuração da integração. Não existe uma rota pública de catálogo de canais neste contrato. ## Criar ou substituir O corpo exige `name`, `triggerType` e `scope`. Escopo `pipeline` exige `pipelineId`; `stage` exige `stageId`. Gatilhos `manual` e `webhook` usam escopo `global`. `respectBusinessHours` e uma `triggerWindow` não vazia são mutuamente exclusivos. O gatilho manual não aceita essas regras nem condições de disparo. Na criação, omitir `enabled` ativa o fluxo. Envie `enabled: false` enquanto prepara a definição. A substituição exige revisar o fluxo completo; consulte a operação apropriada para mudar apenas o estado de ativação. ## Segredos e teste de webhook As leituras ocultam segredos de webhook. Quando uma criação ou atualização gerar um segredo, guarde-o na resposta em que ele for exibido. `POST /api/v1/automations/{id}/test` retorna o corpo assinado que a primeira ação de webhook enviaria. Não envia o webhook nem executa o fluxo. Exige permissão de edição porque calcula a assinatura com o segredo real. ## Execuções A API permite consultar execuções, nós, logs e entregas. Use a paginação e os filtros documentados em cada rota. Os dados de uma execução representam sua definição na ocasião; editar o fluxo atual não reescreve o passado. Não existe neste grupo uma rota para iniciar manualmente a execução. No aplicativo, use [Acionamento manual](/automacoes/nos/gatilho-manual/). Para avaliar caminhos sem efeitos reais, use o [Playground](/automacoes/simular/) quando habilitado. --- # Identificadores, paginação e erros Fonte: https://ajuda.matchsales.com.br/developers/boas-praticas/ Toda requisição usa `Authorization: Bearer pf_live_…`. Guarde a chave no servidor da integração e não a inclua em código entregue ao navegador. ![Fluxo da integração: chave identifica o membro, permissões e recursos são conferidos, operação acessa os dados visíveis e devolve resposta ou erro](/_astro/fluxo-api.Bx0uNFGi.svg) ## Identificadores | Identificador | Uso | | ----------------- | ----------------------------------------------------------------------------------------------- | | `seq` de negócio | Número do lead dentro do workspace; usado em `/deals/{seq}`. | | `seq` de funil | Número do funil; usado em `/pipelines/{seq}` e no parâmetro `pipeline` da listagem de negócios. | | `seq` de empresa | Número da empresa; usado em `/companies/{seq}`. | | `id` | Identificador técnico de contato, etapa, campo, canal ou automação. Não substitua por `seq`. | | `conversationKey` | Chave retornada pela listagem de conversas; preserve seu valor e codifique ao montar a URL. | | `slug` de campo | Chave do valor em `customFields` e `properties`. A definição também tem um `id`. | ## Paginar Nas operações com cursor, envie `limit` dentro do intervalo documentado. Use o cursor retornado pela página seguinte sem interpretar seu conteúdo. Termine quando não houver próxima página. Mantenha os mesmos filtros e a mesma ordenação enquanto percorre páginas. Não reutilize o cursor de outra rota. As operações de histórico de automações usam paginação por página; consulte os parâmetros específicos da referência. Em mensagens, `since` é inclusivo. Remova duplicatas pelo ID e envie `since` junto com `cursor` quando continuar a leitura para frente. ## Tratar respostas Leia o status HTTP antes de processar o corpo. Uma resposta `204` não possui JSON. Nas respostas com envelope, os dados ficam em `data`; o formato exato está documentado em cada operação. | Status | Como tratar | | -------------- | -------------------------------------------------------------------------------------------- | | `400` ou `422` | Corrija parâmetros ou valores conforme a mensagem. Não repita o mesmo corpo automaticamente. | | `401` | Confira a chave e se ela continua ativa. | | `403` | Confira permissões, acesso ao canal e recursos contratados. | | `404` | O registro pode não existir ou estar fora da visibilidade do membro. | | `409` | Resolva o conflito de estado indicado antes de tentar novamente. | | `429` | Respeite `X-Rate-Limit-Retry-After-Seconds` ou `Retry-After`, conforme o limite atingido. | O limite geral é de 600 requisições por minuto, por workspace e por IP. Há também um limite de concorrência: 10 requisições simultâneas e até 40 na fila por no máximo 5 segundos. Uma escrita não deve ser repetida às cegas após perda de conexão: consulte o estado antes. Para executar tarefas de cadência, reutilize a mesma `idempotencyKey` da operação original. --- # Cadastros, campos e arquivos pela API Fonte: https://ajuda.matchsales.com.br/developers/cadastros/ ## Cadastros | Recurso | Coleção | Operações individuais | | --------------------- | ----------------------- | ------------------------------------------ | | Contatos | `/api/v1/contacts` | Consultar, editar e excluir por ID. | | Empresas | `/api/v1/companies` | Consultar, editar e excluir por sequência. | | Tags | `/api/v1/tags` | Consultar, editar e excluir por ID. | | Campos personalizados | `/api/v1/custom-fields` | Consultar, editar e excluir por ID. | | Membros | `/api/v1/users` | Catálogo de membros; não cria contas. | Cada recurso tem permissões e limites próprios. Consulte método, corpo e retorno na [referência](/api/). Excluir um contato não é uma operação reversível; revise os vínculos antes de executar. ## Nome do contato Envie `firstName` e `lastName` separadamente. Nas operações de criação de negócio, as chaves equivalentes são `contactFirstName` e `contactLastName`. Use os nomes retornados pelo servidor ao sincronizar cadastros. ## Definição e valor do campo A definição estabelece tipo, opções, grupo, placeholder e regra de visibilidade. Seu `id` identifica o campo; o `slug` identifica o valor dentro de `customFields` e `properties` do negócio. Em seleções, envie o **valor** da opção, não seu rótulo. Um campo com `apiOnly: true` permite atualizar seus valores pela API pública e os mantém somente para leitura no aplicativo. Uma `visibilityRule` usa `parentFieldId` e `values`. Para removê-la no PATCH, envie `clearVisibilityRule: true`. Não combine com `visibilityRule` na mesma requisição: o servidor responde `422`. ## Arquivos O upload de um campo de arquivo usa `multipart/form-data`, com o campo `file`. Não envie um caminho local como texto em JSON. Consulte as operações de arquivos em [Campos personalizados](/api/#resource-custom-fields). Para obter o arquivo vinculado ao negócio, use `GET /api/v1/deals/{seq}/properties/{slug}/file`. A URL assinada dessa rota vale por 24 horas. Para resolver uma chave de armazenamento separadamente, use `GET /api/v1/custom-fields/file?key=…`; a URL dessa operação vale por uma hora. Guarde a referência do arquivo e solicite uma URL nova quando a anterior vencer. --- # Gerenciar cadências pela API Fonte: https://ajuda.matchsales.com.br/developers/cadencias/ A API de cadências permite consultar rotinas e controlar a matrícula de um deal. Todas as rotas exigem os recursos `ADVANCED_API` e `CADENCE`. Sem qualquer um deles, a API responde `403`. ## Consultar cadências e matrículas | Ação | Método e rota | Uso | | ---------------------------- | ---------------------------------------------- | ---------------------------------------------- | | Listar cadências | `GET /api/v1/cadences` | Retorna o catálogo de cadências do workspace. | | Listar matrículas | `GET /api/v1/cadences/{cadenceId}/enrollments` | Retorna os deals matriculados em uma cadência. | | Consultar a cadência do deal | `GET /api/v1/deals/{seq}/cadence` | Retorna a instância e as tarefas do deal. | Na listagem de matrículas, use `status` para filtrar a situação. Use `day`, `step` e `at` para restringir a posição da régua. `at=reached` inclui quem passou pela posição. `at=ended` inclui quem terminou nela. ## Alterar a matrícula | Ação | Método e rota | Efeito | | ------------------ | ------------------------------------------- | --------------------------------------------------------------- | | Matricular um deal | `POST /api/v1/deals/{seq}/cadence/enroll` | Substitui a cadência atual e pode começar em um dia específico. | | Iniciar | `POST /api/v1/deals/{seq}/cadence/start` | Inicia a instância do deal. | | Pausar | `POST /api/v1/deals/{seq}/cadence/pause` | Pausa a instância, com um motivo opcional. | | Retomar | `POST /api/v1/deals/{seq}/cadence/resume` | Retoma a instância pausada. | | Remover | `POST /api/v1/deals/{seq}/cadence/unenroll` | Para a instância e cancela tarefas abertas. | ## Operar tarefas `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/execute` envia a tarefa ao provedor do canal. A operação envia de verdade por WhatsApp, e-mail ou chamada externa e pode gerar cobrança no workspace. Envie uma `idempotencyKey` obrigatória. Uma repetição da mesma chave retorna `duplicated: true` sem enviar novamente. Para alterar somente o estado da tarefa, use `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/skip` ou `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/complete-manual`. Essas rotas não enviam nada ao canal. ## Tentativas e repetição segura As tarefas da instância incluem o histórico `attempts`, com canal, sucesso, data e identificadores de envio quando disponíveis. Use esse histórico para diagnosticar uma falha antes de repetir a operação. Guarde a `idempotencyKey` antes de executar. Se a resposta se perder, repita com a mesma chave; uma nova chave representa uma nova tentativa. Não trate `skip` ou `complete-manual` como confirmação de entrega ao cliente. ## Próximos passos - [Autenticar na API pública](/developers/authentication/) - [Referência completa da API](/api/) --- # Usar o calendário pela API Fonte: https://ajuda.matchsales.com.br/developers/calendario/ As rotas de calendário exigem `CALENDAR`, além das permissões do membro da chave. `GET /api/v1/calendar/events` reúne eventos do workspace e as fontes disponíveis para esse membro. ## Janela de consulta Informe o início e o fim conforme os parâmetros da [referência](/api/resources/calendar/methods/list-calendar-window/). Datas e horas seguem ISO 8601. Para eventos de dia inteiro, o objeto de data usa `date`; para eventos com horário, usa `dateTime` e o fuso documentado. A resposta informa o estado das fontes. Uma fonte do Google Calendar indisponível não deve ser interpretada como uma agenda vazia. ## Criar e editar reuniões Use `POST /api/v1/calendar/events` e as operações individuais em `/api/v1/calendar/events/{id}`. Confira início, fim, responsável e convidados antes de gravar. Um convidado de entrada usa `type: member` com `memberId`, ou `type: contact` com `contactId`. Na resposta, a identidade aparece aninhada em `member` ou `contact`, e não como campos planos de nome e e-mail. `removed: true` significa que a identidade do convidado não existe mais. O registro permanece para preservar o histórico da reunião. ## Conferência e gravação Você pode informar `conferenceUrl` de uma reunião existente. A gravação pelo bot depende da disponibilidade do recurso e de um link compatível, Google Meet ou Microsoft Teams. A solicitação incompatível responde `400`. Veja [Reuniões e gravações](/calendario/reunioes/) para o fluxo no aplicativo e [Campos de evento](/calendario/campos-de-evento/) para vincular uma reunião ao lead. --- # Consultar e enviar conversas pela API Fonte: https://ajuda.matchsales.com.br/developers/conversas/ A API de conversas permite ler o inbox e enviar mensagens pelo PipeFácil. Todas as rotas deste grupo exigem o recurso `ADVANCED_API`. As rotas de leitura também exigem a permissão `whatsapp.view_conversations`. ## Rotas disponíveis | Ação | Método e rota | Uso | | ---------------- | ------------------------------------------------------ | ------------------------------------------------- | | Listar conversas | `GET /api/v1/conversations` | Retorna as conversas visíveis ao membro da chave. | | Listar mensagens | `GET /api/v1/conversations/{conversationKey}/messages` | Retorna o histórico de uma conversa. | | Enviar mensagem | `POST /api/v1/conversations/messages` | Envia uma mensagem pelo canal escolhido. | Em `GET /api/v1/conversations`, use `filter`, `responsibleId`, `pipelineId`, `stageId`, `source` ou `channelIds` para restringir o resultado. A busca por texto aceita o contato e o telefone. ## Ler o histórico continuamente Sem `since`, a listagem de mensagens começa pelas mais recentes e pagina para trás. Com `since`, a API pagina para frente a partir do instante informado. O parâmetro `since` é inclusivo. Ao consultar novamente, remova mensagens repetidas pelo identificador da mensagem. Ao continuar uma página para frente, envie `since` junto com `cursor`. Uma conversa fora da visibilidade da chave responde `404`. A visibilidade segue o membro que emitiu a chave, incluindo o acesso somente aos próprios registros. ## Enviar uma mensagem Em `POST /api/v1/conversations/messages`, `type` assume `text` quando omitido. Informe `channelId` ou `senderPhoneNumberId` para escolher o canal. Sem esses campos, a API usa o canal padrão do workspace. A mensagem é atribuída ao membro que emitiu a chave. O caminho legado `POST /api/v1/messages` continua disponível para clientes antigos, mas novas integrações devem usar a rota de conversas. ## Filtros e ordenação `filter` aceita `all`, `unread`, `returned`, `internal` e `closed`. Os quatro primeiros consultam conversas abertas; `closed` consulta as fechadas. `sort` aceita `recent` ou `oldest`; mantenha o valor enquanto percorre o cursor. Use `conversationKey` retornada pelo servidor para consultar mensagens. Para Instagram, o destino técnico pode vir em `contactInstagramId`, no formato `ig:`. ## Janela de envio e alterações de mensagens Na Cloud API, a janela de atendimento pertence ao par contato/canal. `lastInboundAt` da conversa é agregado entre canais e não comprova uma janela aberta no canal que você pretende usar. As mensagens incluem `editedAt` e `deletedAt` quando aplicáveis. O corpo de uma mensagem apagada pode continuar disponível para auditoria; a integração deve decidir como ocultá-lo na interface. Não confunda consulta do histórico com uma API de edição ou exclusão de mensagens: essas operações não estão expostas neste contrato público. ## Próximos passos - [Autenticar na API pública](/developers/authentication/) - [Referência completa da API](/api/) --- # Configurar funis e campos pela API Fonte: https://ajuda.matchsales.com.br/developers/funis/ ## Criar e identificar o funil Use `GET /api/v1/pipelines` para consultar funis e `POST /api/v1/pipelines` para criar. As operações individuais usam a sequência em `/api/v1/pipelines/{seq}`. ```json { "name": "Novas vendas", "description": "Qualificar e fechar novas oportunidades", "stages": [ { "name": "Qualificação", "color": "#2563eb" }, { "name": "Proposta", "color": "#7c3aed" } ] } ``` Etapas ativas são criadas na ordem enviada. Se a lista vier vazia ou omitida, o servidor cria o funil padrão. Ganho e perda são acrescentados pelo sistema. ## Alterar etapas e acesso | Ação | Operação | | ------------------------------ | ------------------------------------------------------------ | | Editar funil | `PATCH /api/v1/pipelines/{seq}` | | Criar etapa | `POST /api/v1/pipelines/{seq}/stages` | | Editar ou remover etapa | `PATCH` ou `DELETE /api/v1/pipelines/{seq}/stages/{stageId}` | | Reordenar etapas | `PATCH /api/v1/pipelines/{seq}/stages/reorder` | | Consultar ou substituir acesso | `GET` ou `PUT /api/v1/pipelines/{seq}/access` | | Consultar arquivados | `GET /api/v1/pipelines/archived` | | Desarquivar | `POST /api/v1/pipelines/{seq}/unarchive` | Revise os conflitos informados pelo servidor antes de remover uma etapa ou um funil. O catálogo de motivos de perda é atualizado por `PUT /api/v1/pipelines/loss-reasons` e pertence ao workspace. ## Comportamentos Configure `behaviors` com `recurring_clients`, `multi_channel_pipeline` e `attendance_queue` quando o workspace tiver o recurso disponível. O PATCH substitui o conjunto: envie todos os comportamentos que devem permanecer ligados. A fila de atendimento exige `attendanceQueueStageId`, uma etapa ativa desse funil. Configure depois da criação, quando você já tiver o ID da etapa. Para desligar a fila, remova `attendance_queue` de `behaviors`; enviar apenas `attendanceQueueStageId: null` não a desliga. `pipelineType` é uma entrada legada ignorada. Use `behaviors`. Leia [Comportamentos do funil](/configuracoes/comportamentos-do-funil/) para entender os efeitos sobre criação, retorno e acesso. ## Campos do funil e das etapas Use `GET /api/v1/pipelines/{seq}/fields` para consultar a configuração. Para um campo, use `GET` ou `PATCH /api/v1/pipelines/{seq}/fields/{field}`. `field` aceita o identificador do campo personalizado ou a chave do campo padrão. O contrato diferencia a configuração base do funil das alterações por etapa. Consulte as propriedades do corpo na [referência da API](/api/) e as [regras de visibilidade, sugestão e obrigatoriedade](/configuracoes/regras-de-campos/). Alterar uma definição global não equivale a alterar sua regra em um funil. --- # Conectar o servidor MCP do PipeFácil Fonte: https://ajuda.matchsales.com.br/developers/mcp/ O servidor Model Context Protocol (MCP) da Match Sales conecta seu agente ao PipeFácil pela conexão remota **Streamable HTTP**. O acesso exige autenticação. **Endereço do servidor:** [http://mcp.matchsales.com.br/mcp](http://mcp.matchsales.com.br/mcp) Esse endereço redireciona para `https://mcp.matchsales.com.br/mcp`. As configurações abaixo usam diretamente HTTPS para evitar problemas com redirecionamentos no cliente. ## Autenticação Use **OAuth** quando seu cliente oferecer esse fluxo. Conclua a autorização na página aberta pelo cliente. Para clientes que aceitam um token, envie `Authorization: Bearer pf_live_…` no cabeçalho da conexão HTTPS. Crie a chave em **Configurações → Chaves de API**, conforme o [guia de autenticação](/developers/authentication/). A documentação pública continua disponível em [llms.txt](/llms.txt), nos guias e na [referência da API](/api/). ## Instalar no seu agente 1. Escolha o cliente MCP que você usa e adicione o servidor com uma das configurações abaixo. 2. Reinicie o cliente ou atualize suas conexões MCP e conclua a autenticação. 3. Peça ao agente: **Liste as ferramentas disponíveis no MCP do PipeFácil e explique suas funções.** ### Codex No terminal, execute: ```bash codex mcp add pipefacil --url https://mcp.matchsales.com.br/mcp codex mcp login pipefacil ``` Depois, use `codex mcp list` para conferir o registro. ### Claude Code No terminal, execute: ```bash claude mcp add --transport http pipefacil https://mcp.matchsales.com.br/mcp ``` Depois, use `claude mcp list` para conferir o registro. ### Cursor Adicione o servidor ao arquivo `.cursor/mcp.json` do projeto, ou ao arquivo global de configuração MCP do Cursor: ```json { "mcpServers": { "pipefacil": { "url": "https://mcp.matchsales.com.br/mcp" } } } ``` ### Claude Desktop e clientes locais Clientes que aceitam apenas MCP local podem usar o adaptador [`mcp-remote`](https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/#connect-from-an-mcp-client-via-a-local-proxy). No Claude Desktop, abra **Configurações** > **Desenvolvedor** > **Editar configuração** e adicione: ```json { "mcpServers": { "pipefacil": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.matchsales.com.br/mcp"] } } } ``` Salve o arquivo e reinicie o Claude Desktop. Se já houver outros servidores, acrescente apenas a entrada `pipefacil` ao objeto `mcpServers` existente. ## Usar as ferramentas Depois de autenticar, consulte a lista de ferramentas retornada pelo servidor. Use os nomes e parâmetros informados pelo MCP; não assuma que sejam os mesmos da API HTTP. Antes de preparar uma integração, consulte os [guias para desenvolvedores](/developers/) e a [referência da API](/api/). Você pode [copiar o prompt de configuração do agente](/agent-setup/). Ele orienta o agente a conectar o MCP, consultar a documentação e conferir o contrato da API. ## Resolver problemas de conexão - Confira se o endereço termina em `/mcp` e se o cliente aceita **Streamable HTTP**. - Verifique o registro com `codex mcp list` ou `claude mcp list`, conforme o cliente. - Se receber `401`, conclua o OAuth ou confira o cabeçalho `Authorization`. - Se o cliente falhar ao seguir o redirecionamento HTTP, use `https://mcp.matchsales.com.br/mcp`. - Não abra `/mcp` diretamente no navegador para testar: esse caminho recebe mensagens do protocolo MCP. Use um cliente MCP ou o [MCP Inspector](https://developers.cloudflare.com/agents/model-context-protocol/guides/test-remote-mcp-server/). - Se o cliente aceitar apenas servidores locais, use o adaptador `mcp-remote` mostrado acima. Para entender o transporte e a instalação em outros clientes, consulte a [documentação da Cloudflare sobre MCP remoto](https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/). --- # Criar e consultar negócios pela API Fonte: https://ajuda.matchsales.com.br/developers/negocios/ ## Listar negócios Use `GET /api/v1/deals`. Sem `status`, a consulta inclui `open`, `won` e `lost`. Para consultar apenas abertos, envie `status=open`; para vários estados, repita o parâmetro ou separe por vírgula. ```bash curl --get 'https://pipefacil-server.matchsales.com.br/api/v1/deals' \ --header "Authorization: Bearer $PIPEFACIL_API_KEY" \ --data-urlencode 'status=open' \ --data-urlencode 'pipeline=1' \ --data-urlencode 'limit=50' ``` `pipeline` recebe a sequência do funil. `stageId`, `tagIds` e `responsibleUserIds` recebem IDs técnicos. Os negócios vêm pela criação mais recente. Os filtros do aplicativo não são todos parâmetros dessa rota: consulte a [referência](/api/resources/deals/methods/list-deals/). Para valores exatos, use `customFields[slug]`. O valor `__empty__` seleciona campos não preenchidos. Para intervalos, use `customFieldRanges[slug][from]` e `[to]`. Os slugs nativos incluem `value`, `close_probability`, `expected_close_at`, `stage_changed_at`, `updated_at`, `lost_reason`, `lost_from_stage` e `products`. Em `products`, informe um ou mais IDs; o filtro encontra negócios associados a qualquer item informado. Combine `__empty__` para incluir negócios sem itens associados. `lost_reason` e `lost_from_stage` usam valores exatos. ## Criar um negócio `POST /api/v1/deals` aceita telefone opcional. Sem telefone ou dados de contato, o negócio pode ficar sem contato. Com nome ou e-mail, pode ser criado um contato sem telefone. ```json { "name": "Proposta de consultoria", "contactFirstName": "Ana", "contactLastName": "Silva", "email": "ana@example.com", "value": 1500, "currency": "BRL" } ``` Envie primeiro nome e sobrenome separados. Quando usados, eles têm preferência sobre `contactName`. `stageId` escolhe a etapa inicial; quando omitido, o servidor usa a primeira etapa do funil escolhido pelas regras de criação. O corpo também aceita campos personalizados, empresa, dados de rastreio e metadados. Use `tracking.ctwaClid` para o identificador de clique Click to WhatsApp quando ele estiver disponível na origem. ## Atualizar e consultar o detalhe Use `GET /api/v1/deals/{seq}` e `PATCH /api/v1/deals/{seq}`. O PATCH aceita alterações parciais; revise as regras de movimento, campos obrigatórios e motivo da perda antes de mudar a etapa. `properties` contém valores resolvidos dos campos personalizados. Resumo de tarefas e última atividade podem ser nulos quando não estiverem habilitados na configuração do card. `lostFromStage` informa a etapa anterior à perda. Para extrair valores de campos em vários negócios, use `GET /api/v1/deals/custom-field-values` com os filtros da referência. ## Notas, tarefas e atividade | Ação | Rota | | ------------------------ | --------------------------------------- | | Criar nota | `POST /api/v1/deals/{seq}/notes` | | Criar tarefa | `POST /api/v1/deals/{seq}/tasks` | | Consultar atividade | `GET /api/v1/deals/{seq}/activities` | | Adicionar ou remover tag | Operações de `/api/v1/deals/{seq}/tags` | Confira o retorno de cada escrita. As tarefas têm corpo próprio, com prazo e responsável; os tipos aceitos estão na referência. Não use os exemplos de uma nota como corpo de uma tarefa. ## Receba um lead de um site ou sistema próprio A interface chama o negócio de **lead**; a API usa **deal**. Para integrar um formulário externo, comece pela [autenticação](/developers/authentication/) e siga esta sequência: 1. Consulte `GET /api/v1/pipelines` e escolha a etapa de destino. Para `stageId`, use o identificador técnico `id` da etapa, não sua sequência. 2. Envie `POST /api/v1/deals` com os dados do formulário e o `stageId` escolhido. Confira os campos exigidos pelo funil. 3. Leia a sequência `seq` retornada para consultar o registro em `GET /api/v1/deals/{seq}` e conferir o resultado. Criar o registro e enviar uma mensagem são operações distintas. Uma automação ativa com gatilho **Lead criado** pode executar ações após o cadastro. Revise o fluxo de [primeiro atendimento](/automacoes/primeiro-atendimento/) e as regras do canal antes de integrar a origem. O contrato completo do corpo está em [Criar negócio](/api/resources/deals/methods/create-deal/). --- # Tipos de acesso e permissões Fonte: https://ajuda.matchsales.com.br/developers/tipos-de-acesso/ A chave da API pública representa o membro que a criou. Cada chamada usa as permissões desse membro e seu workspace. O acesso também depende dos registros visíveis e dos recursos disponíveis. ## Papéis padrão Os papéis definem permissões padrão e visibilidade dos negócios. Use esta tabela como referência inicial: | Papel | Indicado para | Acesso e permissões padrão | | -------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Administrador | Diretores, responsáveis pela operação e gestores de TI | Acessa todos os dados do workspace e tem todas as permissões padrão. Gerencia membros, integrações e configurações. Algumas alterações são exclusivas do Proprietário. | | Gerente | Coordenadores e supervisores comerciais | Acessa os próprios negócios e os dos membros dos squads que gerencia. Pode reatribuir leads, consultar métricas do squad e exportar leads. Sem squad gerenciado, vê apenas os próprios negócios. | | Closer | Executivos de contas e vendedores responsáveis pelo fechamento | Acessa negócios sob sua responsabilidade. Conduz negociações, envia propostas conforme o processo comercial e registra o fechamento no funil. Pode usar agenda e conversas nos canais autorizados. | | SDR (Sales Development Representative) | Pré-vendedores responsáveis por prospecção e qualificação | Acessa negócios sob sua responsabilidade. Cria contatos e negócios, qualifica leads e faz o primeiro atendimento. A entrega ao Closer segue as regras de distribuição. Reatribuir manualmente exige a permissão correspondente. | O **Proprietário** é um papel separado do Administrador. Ambos acessam todos os dados do workspace. Algumas configurações, como compartilhamento de leads e alvos de distribuição de tarefas, ficam reservadas ao Proprietário. O papel Proprietário não aparece no convite de membros. Quando a API retorna um papel, ela usa um identificador em minúsculas: `admin`, `manager`, `closer` ou `sdr`. O Proprietário usa `owner`. ## Entenda as camadas de acesso O papel é apenas uma das regras que determinam o acesso: - **Permissões** definem ações, como criar negócios, exportar leads ou enviar mensagens. É possível personalizar permissões individuais em **Configurações** > **Acessos**, conforme o acesso de quem administra o workspace. - **Visibilidade** define quais negócios cada membro pode abrir. Responsável, corresponsável, compartilhamento de leads, squad e acesso ao funil podem alterar esse alcance. - **Canais** controlam quais conversas o membro pode acompanhar e por quais números pode enviar mensagens. Enviar exige a permissão de mensagens e acesso ao canal. - **Recursos do workspace** também limitam a API. Por exemplo, conversas e automações exigem acesso à API avançada; calendário exige o recurso de calendário. Para revisar presença, papéis, squads e permissões individuais, consulte [Gerenciar membros, presença e acessos](/configuracoes/membros/). Para emitir uma chave, consulte [Autenticação](/developers/authentication/). ## Interprete erros de acesso Uma resposta `403` pode indicar falta de permissão, de acesso ao canal ou de um recurso necessário. Uma resposta `404` pode indicar que o negócio não existe ou está fora da visibilidade do membro. Consulte [Identificadores, paginação e erros](/developers/boas-praticas/) para tratar as respostas da API. --- # Disparos Fonte: https://ajuda.matchsales.com.br/disparos/ Disparos enviam um modelo de WhatsApp para muitos destinatários de uma vez. Exigem um canal conectado e um modelo aprovado. ![Lista de disparos com status, destinatários, progresso e métricas de entrega](/images/pipefacil/disparos/lista-light.png) O [compositor de disparos](/disparos/criar/) permite editar o público antes do envio. Você pode escolher o funil, as etapas, a situação, os responsáveis, as tags e o canal no mesmo fluxo. - [Criar um disparo](/disparos/criar/) - [Conversas](/conversas/) - [Integrações](/integracoes/) --- # Criar um disparo Fonte: https://ajuda.matchsales.com.br/disparos/criar/ Crie um disparo e revise o público antes de iniciar o envio. Você precisa de um canal de WhatsApp conectado, um modelo aprovado e a permissão para enviar disparos. 1. No menu lateral, vá até **Disparos**. 2. Selecione **Novo disparo**. 3. Em **Mensagem**, escolha o canal e o modelo aprovado. Mapeie as variáveis do modelo. 4. Em **Público**, escolha o funil, as etapas e a situação dos leads. Ajuste responsáveis, tags, número e busca. Confira o contador de destinatários e a elegibilidade para o modelo. ![Etapa Público de um novo disparo com filtros e amostra de destinatários](/images/pipefacil/disparos/publico-light.png) 5. Confira a mensagem e o custo calculado para o recorte antes de avançar para **Revisar**. ![Etapa Mensagem de um novo disparo com seleção de canal e modelo](/images/pipefacil/disparos/mensagem-light.png) 6. (Opcional) Ative a ação para mover o lead quando ele responder e escolha a etapa de destino. 7. Revise o público, o modelo, o custo estimado e o número de destinatários. 8. Confirme o envio. Depois do envio, o disparo abre a página de acompanhamento. O custo exibido é uma estimativa baseada na categoria do modelo. ## Próximos passos - [Conectar um canal](/integracoes/) - [Responder uma conversa](/conversas/responder/) --- # Modo Foco Fonte: https://ajuda.matchsales.com.br/foco/ O Modo Foco esconde a navegação do CRM e entrega a próxima ação da fila. A fila usa as atividades das cadências vinculadas aos leads. ![Tela de entrada do Modo Foco com opções de distribuição geral e funil](/images/pipefacil/foco/selecao-light.png) ## Escolha a fila Na entrada, selecione uma das opções: - **Distribuição geral**: reúne os leads de todos os seus funis na ordem de prioridade. - **Um funil**: limita a fila aos leads de um funil específico. Selecione **Entrar no modo foco** para começar. Use **Nova cadência** para criar a rotina comercial ou **Métricas das cadências** para acompanhar os resultados. ## Execute a próxima atividade ![Tela do Modo Foco com fila de atividades, conversa do lead e ação atual](/images/pipefacil/foco/execucao-light.png) A tela de execução divide o trabalho em três áreas: - A coluna de atividades lista os dias da cadência e indica tarefas concluídas, pendentes ou vencidas. - A área central mostra a conversa e identifica o funil e a etapa atuais. - O cartão de ação apresenta o próximo passo, o número de tentativas e os comandos disponíveis. Quando uma atividade exige mensagem, use o compositor ou um modelo aprovado. Quando a etapa estiver fora da janela do WhatsApp, o cartão indica que você deve iniciar com um modelo. Use **Pular etapa** ou **Pular lead** quando a ação não puder continuar. O PipeFácil pede uma justificativa antes de avançar. - [Configurações](/configuracoes/) - [Cadências](/cadencias/) - [Tarefas](/tarefas/) --- # Fundamentos Fonte: https://ajuda.matchsales.com.br/fundamentals/ O PipeFácil é o CRM da Match Sales. O time vende em um workspace. Cada lead vive em um funil, em uma etapa. ![Visão geral do funil com etapas, leads e responsáveis](guideShot0Light.src) - [Primeiros passos](/fundamentals/get-started/) — Entre, conclua o onboarding e crie o primeiro lead. - [Crie e avance o primeiro lead](/fundamentals/primeiro-lead/) — Um tutorial curto, do login até mover o card no funil. ## Nesta área --- # Conceitos Fonte: https://ajuda.matchsales.com.br/fundamentals/concepts/ Estes termos aparecem em todo o PipeFácil. ## Workspace O workspace isola os dados do time. Funis, leads, conversas e configurações pertencem a um workspace. Se você participa de mais de um, troque pelo menu da conta. Selecione **Trocar workspace** e escolha o destino. A interface recarrega com os dados daquele workspace. ## Lead e deal Lead e deal são o mesmo negócio no funil. A interface fala em lead. A [API pública](/api/) fala em deal. Um lead tem título, etapa, responsável e campos personalizados. O contato pode ser vinculado depois, inclusive quando o negócio foi criado sem telefone. ## Funil e etapa O funil é o quadro de vendas. A etapa é uma coluna. Etapas de ganho e perda encerram o negócio. Uma etapa pode exigir campos antes de o lead avançar. Uma etapa de perda pede o [motivo da perda](/pipeline/mover-lead/). O workspace pode ter vários funis. A troca fica na barra superior do **Funil**. ![Funil com etapas em colunas e cards dos leads](guideShot0Light.src) ## Cadência e automação A [cadência](/cadencias/) agenda follow-up no tempo. A [automação](/automacoes/) reage a um evento. Use as duas juntas quando o processo pedir. ## Papel e permissão O que cada pessoa vê depende do papel e das permissões do workspace. Sem a permissão de criar leads, o botão **Novo lead** não aparece. ## Próximos passos - [Primeiros passos](/fundamentals/get-started/) - [Glossário](/glossary/) - [Funil](/pipeline/) --- # Primeiros passos Fonte: https://ajuda.matchsales.com.br/fundamentals/get-started/ Ao terminar esta página, você tem um lead no funil. ## Antes de começar Você precisa de um convite ou de uma conta já criada. ## Crie o primeiro lead 1. Entre no [PipeFácil](https://pipefacil.matchsales.com.br/) com e-mail e senha e selecione **Entrar**. Se você recebeu um convite, abra o link do e-mail, informe o nome e uma senha com no mínimo 10 caracteres. 2. Conclua o onboarding. Quem configura o workspace vê o perfil, o horário comercial, o funil, os motivos de perda, as tags e os convites. Quem entra por convite só confirma o perfil. O progresso fica associado ao membro e ao workspace. Você pode pular qualquer passo. ![Tela de onboarding do PipeFácil com as etapas de preparação do CRM](/images/pipefacil/fundamentals/onboarding-light.png) 3. No **Funil**, selecione **Novo lead**. ![Painel Novo lead aberto no funil com campos de nome, telefone e etapa](/images/pipefacil/pipeline/novo-lead-light.png) 4. No painel **Novo lead**, preencha o **Nome do lead** e a etapa. O **Telefone** é opcional; preencha os campos exigidos pela configuração do funil. 5. Selecione **Criar lead**. O card aparece na coluna da etapa escolhida. Depois do onboarding, use **Rever o tour** no menu da sua conta para revisar as telas principais do PipeFácil. ## Próximos passos - [Crie e avance o primeiro lead](/fundamentals/primeiro-lead/) - [Abra o detalhe do lead](/pipeline/detalhe-do-lead/) - [Conceitos](/fundamentals/concepts/) --- # Crie e avance o primeiro lead Fonte: https://ajuda.matchsales.com.br/fundamentals/primeiro-lead/ Neste tutorial você entra no PipeFácil, cria um lead e move o card para a próxima etapa. ## Antes de começar Você precisa de um convite ou de uma conta. Quem cria leads precisa da permissão correspondente no workspace. ## Entre no PipeFácil 1. Abra o [PipeFácil](https://pipefacil.matchsales.com.br/). 2. Informe o e-mail e a senha e selecione **Entrar**. Se o acesso veio por convite, abra o link do e-mail, informe o nome e uma senha com no mínimo 10 caracteres. 3. Se o onboarding abrir, avance ou pule os passos. O funil já existe quando alguém do workspace concluiu a etapa **Desenhe seu funil**. ## Crie o lead 1. No menu lateral, vá até **Funil**. 2. Selecione **Novo lead**. O painel usa o mesmo layout do detalhe. ![Painel Novo lead aberto no quadro do funil](/images/pipefacil/pipeline/novo-lead-light.png) 3. Selecione o título **Nome do lead** e escreva um nome, por exemplo o nome da empresa. 4. Em **Telefone**, informe o número se ele estiver disponível. O lead pode ser criado sem telefone; a configuração do funil pode exigir outros campos. 5. Confira a etapa no seletor do cabeçalho. Para nascer em outra coluna, escolha a etapa antes de salvar. 6. Selecione **Criar lead**. O card aparece na coluna da etapa escolhida. A barra do funil mostra o total de leads e o valor somado. ## Abra o detalhe e registre o contexto 1. Selecione o card no quadro. 2. Na aba **Detalhes**, preencha valor, responsável ou um campo personalizado, se o funil tiver. 3. Na aba **Nota**, escreva o que você já sabe sobre o negócio. 4. Na aba **Tarefa**, crie o próximo follow-up. O painel também mostra **Linha do tempo**. Ali entram as mudanças de etapa e as edições de campo. ## Avance a etapa 1. Arraste o card para a próxima coluna. Ou, no detalhe, abra o seletor de etapa no cabeçalho e escolha o destino. ![Seletor de etapa com funis à esquerda e etapas de destino à direita](/images/pipefacil/pipeline/seletor-etapa-light.png) 2. Se a etapa pedir campos, o diálogo **Campos obrigatórios** abre. Preencha o que estiver marcado e confirme. 3. Se a etapa for de perda, o diálogo **Motivo da perda** abre. Escolha um motivo do catálogo ou **Outro**. O lead está no funil, com detalhe e uma etapa nova. Esse é o ciclo diário do quadro. ## Próximos passos - [Filtre o quadro](/pipeline/filtrar-leads/) - [Configure o funil](/configuracoes/) - [Conecte um canal](/integracoes/) --- # Integrações Fonte: https://ajuda.matchsales.com.br/integracoes/ Integrações ligam o PipeFácil a canais e ferramentas. Sem o canal certo, conversas e disparos não saem. ![Lista de integrações do PipeFácil agrupadas por categoria e status](/images/pipefacil/integracoes/lista-light.png) - [Conectar uma conta profissional do Instagram](/integracoes/instagram/) - [Conectar o WhatsApp Lite por QR Code](/integracoes/whatsapp-lite/) - [Configurar um canal de WhatsApp](/integracoes/canais/) - [Conversas](/conversas/) - [Disparos](/disparos/) - [Calendário](/calendario/) ## Guias relacionados - [Telefonia e campanhas](/integracoes/telefonia/) - [Formulários de leads da Meta](/integracoes/formularios-de-leads/) - [Origem e rastreamento de leads](/integracoes/origem-e-rastreio-de-leads/) ## Escolha a integração pela tarefa | Tarefa | Guia | | ----------------------------------------------- | ------------------------------------------------------------------------ | | Atender pelo WhatsApp Business (Cloud) | [Conectar o WhatsApp](/integracoes/whatsapp/) | | Conectar o WhatsApp Lite por QR Code | [Conectar o WhatsApp Lite](/integracoes/whatsapp-lite/) | | Receber e responder Directs | [Conectar o Instagram](/integracoes/instagram/) | | Receber respostas de formulários de anúncios | [Formulários de leads da Meta](/integracoes/formularios-de-leads/) | | Receber cadastros de um site ou sistema próprio | [Criar leads pela API](/developers/negocios/) | | Ligar por um provedor disponível | [Telefonia](/integracoes/telefonia/) | | Trazer dados existentes | [Importar leads ou migrar do Kommo](/integracoes/importacao-e-migracao/) | Receber leads de um formulário ou sistema externo não cria automaticamente uma caixa de entrada de chat do site ou e-mail. Confira o canal de atendimento oferecido para a tarefa que deseja executar. Para definir destino, responsável e acesso, consulte [Configurar um canal](/integracoes/canais/). Para falhas de mensagens, use [Diagnosticar o WhatsApp](/integracoes/solucionar-problemas-whatsapp/). --- # Configurar um canal Fonte: https://ajuda.matchsales.com.br/integracoes/canais/ Configure cada assunto do canal na tela correspondente. Essas configurações também se aplicam a canais do Instagram. 1. Vá até **Configurações** > **Integrações**. 2. Abra o menu do canal que deseja configurar. ![Diálogo de configuração de um canal com perfil, funil, distribuição e acesso](/images/pipefacil/integracoes/canal-light.png) 3. Selecione uma seção: **Perfil do número**, **Funil de entrada**, **Distribuição de leads** ou **Acesso dos membros**. ## Registrar um número do WhatsApp Business O registro na Cloud API habilita o envio de mensagens. A tela do canal informa a próxima ação necessária de acordo com o status retornado pela Meta. 1. Vá até **Configurações** > **Integrações**. 2. Abra o menu do canal **WhatsApp Business**. 3. Selecione **Registrar número**. ![Diálogo Registrar número com PIN de duas etapas opcional e ações de registro](/images/pipefacil/integracoes/registrar-numero-light.png) 4. (Opcional) Informe o PIN de duas etapas atual do número. Se este for o primeiro registro, deixe o campo vazio. 5. Se ninguém souber o PIN atual, informe um novo PIN de seis dígitos e selecione **Definir novo PIN**. Confirme a alteração para substituir o PIN antigo e registrar o número. 6. Selecione **Registrar** para concluir. Use **Verificar número** quando o status da Meta indicar que o número ainda não foi verificado. Quando a Meta indicar que o número já está conectado, a ação disponível passa a ser **Registrar número**. ## Níveis de acesso Em **Acesso dos membros**, escolha um nível para cada pessoa: - **Sem acesso**: a pessoa não acompanha o canal. - **Só ver**: a pessoa acompanha as conversas, mas não responde. - **Ver e enviar**: a pessoa acompanha as conversas e responde pelo canal. ![Acesso de um vendedor ao canal com níveis Sem acesso, Só ver e Ver e enviar](shotCanalAcessosLight.src) O funil de entrada e a distribuição de leads são configurações separadas do nível de acesso. ## Qualidade do número A lista de canais WhatsApp Business mostra a qualidade e os alertas retornados pela Meta. Use a ação de atualizar a saúde do número para consultar o estado mais recente. Qualidade, verificação e registro são informações diferentes: siga a ação indicada no canal. ## Ligações e voz Quando a ligação pelo WhatsApp estiver habilitada no workspace e no canal, o menu **Ligar por** oferece esse provedor. Autorize o microfone do navegador antes de iniciar. As integrações API4Com e 3C Plus também podem fornecer chamadas. Consulte [Integrar telefonia](/integracoes/telefonia/) para configurar o provedor e exportar contatos para campanhas da 3C Plus. ## Funil de entrada e distribuição Em **Funil de entrada**, selecione o destino dos leads que chegam por esse canal. Em **Distribuição de leads**, escolha entre seguir a estratégia desse funil ou distribuir entre quem tem acesso para enviar pelo canal. ![Configuração do funil e da etapa de entrada do número conectado](shotCanalFunilLight.src) O funil define onde o lead entra; a distribuição define quem recebe a atribuição. Nenhuma dessas escolhas concede acesso ao membro. Consulte [Distribuir leads entre vendedores](/configuracoes/distribuicao-de-leads/) para configurar rodízio, carga de trabalho e presença. ## Canal aberto e canal restrito Quando a lista de acesso está vazia, o canal fica disponível ao workspace. Ao definir acessos individuais, confira quem mantém **Ver e enviar** e quem fica em **Só ver**. Remover todas as entradas individuais reabre o canal; não use uma lista vazia para tentar bloquear todos. Os níveis do canal continuam sujeitos às [permissões e à visibilidade dos registros](/configuracoes/membros/). Administradores têm acesso aos canais. Um gerente pode acompanhar canais da equipe que gerencia sem ganhar automaticamente permissão para enviar por eles. ## Conexão e diagnóstico Para autorizar um número novo, consulte [Conectar o WhatsApp](/integracoes/whatsapp/). Se o canal já existe e apresenta falha, consulte [Diagnosticar problemas no WhatsApp](/integracoes/solucionar-problemas-whatsapp/) antes de repetir o registro ou remover a conexão. --- # Formulários de leads da Meta Fonte: https://ajuda.matchsales.com.br/integracoes/formularios-de-leads/ Use **Formulários de leads** para receber no PipeFácil as respostas dos formulários instantâneos do Facebook e do Instagram. O recurso precisa estar liberado no workspace. Você também precisa de permissão para configurar integrações e acesso à Página na Meta. ## Integrar um formulário 1. Conecte o Meta Ads à Página que recebe os formulários. 2. Em **Configurações** > **Integrações** > **Formulários de leads**, selecione **Buscar formulários**. 3. Escolha um formulário e defina o funil, a etapa e a atribuição dos leads. 4. Associe cada pergunta do formulário a um campo de contato ou do lead. Ignore perguntas que não precisa guardar. 5. Revise as escolhas e integre o formulário. Se a Meta ainda não disponibilizou as perguntas, integre o formulário e configure o mapeamento depois. As perguntas só podem preencher campos compatíveis; crie os campos necessários em [Campos personalizados](/configuracoes/campos/). O mapeamento salvo vale para as próximas respostas. Para atualizar leads já recebidos, use **Aplicar aos leads já recebidos** depois de salvar o mapeamento. As respostas originais continuam disponíveis. ## Acompanhar o formulário O detalhe mostra leads recebidos nos últimos sete dias, o horário do lead mais recente e a quantidade trazida pela conferência. Avisos de integração ajudam a identificar formulários arquivados ou problemas de sincronização. A seção também oferece recuperação de leads que não chegaram ao funil e importação de um período anterior, quando esses recursos estão disponíveis para o formulário. Os formulários visíveis dependem da Página conectada e das permissões da conta Meta. Se um formulário não aparecer, confira o acesso da Página e atualize a lista. Se a Meta não liberar acesso aos Pixels/Datasets, refaça a conexão e autorize a empresa e o Pixel na tela da Meta. Se a consulta estiver indisponível, tente novamente em alguns minutos. Para entender os valores capturados no negócio, consulte [Origem e rastreamento de leads](/integracoes/origem-e-rastreio-de-leads/). Para usar esses dados em campanhas, veja [Conversão Meta Ads](/automacoes/nos/acoes-de-marketing/). --- # Importar leads e migrar do Kommo Fonte: https://ajuda.matchsales.com.br/integracoes/importacao-e-migracao/ Use o assistente adequado à origem dos dados. A opção depende do recurso disponível no workspace e da permissão de importação. | Origem | Opção no menu do funil | | ----------- | ------------------------ | | Planilha | **Importar leads (CSV)** | | Conta Kommo | **Importar do Kommo** | ## Importe uma planilha O assistente aceita CSV de até 10 MB e 50.000 linhas. Exporte a planilha para CSV e use o modelo oferecido na tela para conferir as colunas. 1. No **Funil**, abra o menu e selecione **Importar leads (CSV)**. 2. Escolha o funil e uma etapa de destino. Etapas de ganho e perda não participam dessa seleção. ![Primeiro passo da importação CSV com seleção do funil e da etapa de destino](shotImportarCsvDestinoLight.src) 3. Em **Enviar arquivo**, escolha o CSV ou baixe o modelo para preparar os dados. 4. Em **Mapear colunas**, associe as colunas aos campos do CRM. O telefone é obrigatório neste assistente. 5. Em **Conferir**, revise criados, atualizados e recusados. Corrija o arquivo ou o mapeamento quando necessário. 6. Selecione **Importar** e acompanhe o resultado. Consulte os erros antes de reenviar linhas recusadas. ![Envio do CSV com limites de tamanho e linhas e opção Baixar modelo](shotImportarCsvArquivoLight.src) Colunas de funil e etapa, quando mapeadas, substituem o destino padrão por linha. Sem elas, vale o destino escolhido no assistente. A importação identifica negócios abertos pelo telefone do contato e pelo funil de destino para decidir entre criação e enriquecimento. Confira a prévia; não conte com uma nova importação para duplicar os mesmos leads. A exigência de telefone deste fluxo é diferente da criação manual de um lead. ## Migre um funil do Kommo Você precisa do subdomínio e de um token de acesso do Kommo. Informe o token somente no assistente de conexão. 1. No menu do **Funil**, selecione **Importar do Kommo**. 2. Em **Conectar ao Kommo**, informe **Subdomínio** e **Token de acesso**. ![Assistente de conexão ao Kommo com campos Subdomínio e Token de acesso vazios](shotImportarKommoLight.src) 3. Em **Escolher o funil**, selecione o funil de origem. 4. Em **Mapear responsáveis**, associe cada usuário de origem a um membro do PipeFácil. Confira os registros que ficam com **Eu (quem importa)**. 5. Em **Mapear campos personalizados**, selecione campos existentes ou **Criar novo campo**. 6. Em **Revisar e importar**, confira o funil, os mapeamentos e a opção **Enriquecer leads abertos**. Confirme a importação e acompanhe o progresso. Na migração, **Leads de entrada** continua como uma etapa comum. O PipeFácil identifica ganho e perda pelos status `142` e `143` do Kommo, não pelo campo `type`. ## Revise o escopo da migração O importador trata dados do funil, contatos, negócios, tags, campos e tarefas. Não equivale a copiar toda a operação do CRM anterior. As definições de automações e o histórico de chat não são recriados por esse assistente. Levante os fluxos existentes e [recrie as automações](/automacoes/criar/) no PipeFácil antes de encerrar a operação anterior. Confira uma amostra de leads, responsáveis, valores, campos e tarefas após a importação. A conexão dos números de WhatsApp é um procedimento separado; planeje-a antes de retirar o acesso do provedor anterior. --- # Conectar o Instagram Fonte: https://ajuda.matchsales.com.br/integracoes/instagram/ Conecte uma conta profissional do Instagram ao workspace. Você precisa de acesso para gerenciar as integrações do workspace e de uma conta profissional do Instagram. ![Diálogo do Instagram com a opção de conectar uma conta profissional pela Meta](/images/pipefacil/integracoes/instagram-light.png) 1. Vá até **Configurações** > **Integrações**. 2. Localize o card **Instagram** e selecione **Conectar com o Instagram**. 3. Na janela da Meta, entre na conta profissional que deseja autorizar. 4. Conclua a autorização e feche a janela. 5. Confira a conta na lista de conexões do Instagram. Ela também aparece como um canal do workspace. Para remover a autorização, abra o card do Instagram, escolha a conta e selecione **Desconectar**. A conta permanece listada para uma reconexão futura. Para remover o canal e a conexão definitivamente, selecione **Excluir**. O histórico de mensagens permanece sem o vínculo com o canal. ## Direcione os leads Depois da conexão, abra o menu do canal para definir **Funil de entrada**, **Distribuição de leads** e **Acesso dos membros**. Consulte [Configurar um canal](/integracoes/canais/). Mensagens do Direct e respostas de formulários de anúncios têm configurações diferentes. Para formulários instantâneos do Facebook ou Instagram, use [Formulários de leads da Meta](/integracoes/formularios-de-leads/). --- # Entender a origem e o rastreamento de leads Fonte: https://ajuda.matchsales.com.br/integracoes/origem-e-rastreio-de-leads/ O rastreamento guarda a origem e os identificadores recebidos com um lead. Esses valores ajudam a conferir campanhas, mas não confirmam sozinhos a atribuição de uma conversão. ## Consultar os dados no lead No **Funil**, abra um lead e selecione **UTM / Rastreio**. A aba mostra quantos dos 25 campos têm valor. Os campos são somente para leitura no painel. Leads de formulários instantâneos podem mostrar **Meta Ads** como origem. A linha de origem também pode mostrar o nome do formulário. A aba **UTM / Rastreio** inclui nomes e identificadores de campanha, conjunto de anúncios, anúncio e formulário quando a Meta fornece esses dados. ![Aba UTM / Rastreio com dados de campanha, anúncio e formulário recebidos da Meta](guideShot0Light.src) ## Campos de rastreamento | Grupo | Campos | Uso | | ---------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Campanha | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | Identificam a origem, o canal e a campanha configurados no link. | | Detalhes do anúncio | `platform`, `campaign_name`, `adset_name`, `ad_name`, `form_name` | Mostram os nomes da plataforma, campanha, conjunto, anúncio e formulário enviados pela Meta. | | Identificadores Meta | `lead_id`, `campaign_id`, `adset_id`, `ad_id`, `form_id`, `ctwa_clid` | Guardam identificadores de leads, campanhas, anúncios, formulários e cliques recebidos. | | Referência e análise | `utm_referrer`, `referrer`, `gclientid`, `gclid` | Registram a página de origem e identificadores de ferramentas de análise ou anúncio. | | Cliques Meta | `fbclid` | Registra o identificador de clique recebido. | | Correspondência do navegador | `fbp`, `fbc`, `client_ip_address`, `client_user_agent` | Ajudam a Meta a reconhecer eventos enviados pela Conversions API. | Os formulários da Meta preenchem os valores que a Meta envia. Páginas de captura podem enviar UTMs e dados do navegador pela API pública. O PipeFácil não inventa valores ausentes; um campo vazio significa que aquela origem não forneceu o dado. Quando o formulário e a campanha fornecem o mesmo UTM, o valor explícito do formulário tem prioridade sobre o valor derivado da campanha. ## Filtrar rastreamento no funil No funil, você pode exibir campos de rastreamento como colunas e filtrar os leads por valores exatos. O filtro aceita UTMs e nomes de campanha, conjunto, anúncio e formulário da Meta. A opção **Não preenchido** inclui leads sem registro de rastreamento ou sem valor naquele campo. Um campo personalizado chamado `utm_campaign` continua separado do campo de rastreamento `tracking:utm_campaign`. ## Usar o rastreamento em campanhas A ação **Conversão Meta Ads** usa os identificadores disponíveis para enviar o resultado do lead à Meta. A plataforma pode não atribuir uma conversão quando faltam identificadores ou quando o evento não corresponde à campanha. As automações também incluem os dados de rastreamento do lead no payload. Você pode encaminhar esse bloco para uma integração externa usando uma ação de webhook. Para receber leads, consulte [Formulários de leads da Meta](/integracoes/formularios-de-leads/). Para configurar eventos, consulte [E-mail e conversão Meta Ads](/automacoes/nos/acoes-de-marketing/). --- # Diagnosticar problemas no WhatsApp Fonte: https://ajuda.matchsales.com.br/integracoes/solucionar-problemas-whatsapp/ Antes de reconectar ou repetir um envio, identifique se a falha afeta o canal inteiro, um membro ou uma automação. ## QR Code do WhatsApp Lite não conecta Na tela **QR Code do canal**, selecione **Novo QR** e leia o código atualizado pelo leitor de **Dispositivos conectados** do WhatsApp no celular principal. Depois, selecione **Atualizar status** e confira a confirmação do pareamento. Se a instância já existe, use **Abrir QR** ou **Reconectar**, conforme o estado do canal. Consulte o passo a passo em [Conectar o WhatsApp Lite](/integracoes/whatsapp-lite/). ## Canal conectado, mas sem enviar Em **Configurações** > **Integrações**, abra o canal. Confira o estado local e a orientação retornada pela Meta. Verificação, registro e qualidade do número são informações diferentes. Quando solicitado, conclua o [registro do número](/integracoes/canais/). Se o registro falhar, anote a mensagem exibida e confira a conta WhatsApp selecionada. Evite repetir a operação sem identificar a causa; não exclua o canal como tentativa genérica. ![Menu do canal com configuração, registro, verificação, desconexão e exclusão](shotCanalMenuLight.src) ## Mensagens não aparecem para um membro Compare a visibilidade de outro membro autorizado ao mesmo canal. Confira o papel, o responsável pelo lead, os squads do gerente e os filtros ativos. Depois, confira **Acesso dos membros** no canal. Se as mensagens aparecem para outra pessoa, isso não confirma falha no recebimento do canal. Consulte [Membros e acessos](/configuracoes/membros/). Se o contato estiver marcado como **Bloqueado**, as mensagens recebidas dele não entram no PipeFácil. Desbloqueie o contato para receber as próximas mensagens. ## Texto bloqueado ou envio recusado No WhatsApp Cloud, confira a [janela de 24 horas naquele canal](/conversas/janela-de-atendimento/). Fora dela, use modelo aprovado. Confira também a conexão, o acesso para enviar e a permissão para usar modelos. Se o contato estiver marcado como **Bloqueado**, o envio é recusado antes de chegar ao canal. Desbloqueie o contato para voltar a enviar mensagens. A ação de envio de WhatsApp em uma automação é ignorada para esse contato. Se já houve envio, consulte o estado e o erro da mensagem antes de reenviá-la. A presença da mensagem no histórico não comprova entrega ao destinatário. ## Mensagens anteriores à conexão não aparecem Confira quando o canal foi conectado e se mensagens novas chegam. Conexão e recuperação de histórico são processos diferentes. Não há garantia de trazer todas as mensagens antigas ao autorizar ou reconectar um número. Informe ao suporte a modalidade usada, o período ausente e se o problema afeta mensagens novas. Não apague o contato nem mescle cadastros como tentativa de recuperar o histórico. ## Automação não enviou a mensagem Abra [Ver execuções](/automacoes/acompanhar/) e localize o lead. Confira se houve execução, qual nó foi alcançado e qual erro ocorreu. Verifique gatilho, escopo, estado ativo do fluxo, destinatário e canal selecionado. Uma execução pendente ou aguardando resposta não significa que o envio falhou. Antes de executar novamente, confira se os nós anteriores já enviaram mensagens ou alteraram o lead. ## Encaminhe as evidências ao suporte Registre o horário e o fuso, o canal afetado, a etapa do procedimento e a mensagem de erro. Informe se afeta entrada, saída, uma pessoa ou todos os membros autorizados. Inclua a referência do lead e da execução quando houver. Use **Precisa de ajuda?** para abrir o atendimento. Não envie senhas, PINs ou chaves de API em capturas de tela. --- # Integrar telefonia e campanhas Fonte: https://ajuda.matchsales.com.br/integracoes/telefonia/ As integrações de telefonia dependem do recurso disponível no workspace e das credenciais do provedor. Abra a integração em **Configurações** > **Integrações** e informe as credenciais solicitadas. ![Integrações de voz disponíveis com API4Com e 3C Plus](shotTelefoniaProvedoresLight.src) ## Escolher o provedor da ligação No atendimento ou no detalhe do lead, abra **Ligar por** e escolha uma integração disponível, como API4Com, 3C Plus ou WhatsApp quando liberado. O WhatsApp usa o áudio do navegador; autorize o microfone. O estado e o histórico da chamada dependem dos eventos enviados pelo provedor. Confira o resultado na linha do tempo antes de repetir uma ligação. ## Exportar para a 3C Plus Na ação de exportação para uma campanha da 3C Plus, escolha a campanha e configure os campos solicitados. Revise o recorte de leads e os dados enviados. O retorno informa quantos contatos foram aceitos pelo provedor. Essa quantidade pode ser menor que a seleção quando houver dados inválidos ou recusados. A aceitação de um contato não confirma que a ligação ocorreu. ## Enviar leads por automação No editor de automações, use **Enviar para campanha 3C Plus** para encaminhar leads sem exportá-los manualmente. A ação aparece quando a integração 3C Plus está conectada. Selecione uma campanha e os campos que o agente verá durante a ligação. O telefone é sempre enviado. Na primeira execução, o PipeFácil cria uma lista para o bloco na campanha escolhida. Leads que já estão nessa lista não entram novamente. Leads sem telefone são ignorados. Sem selecionar uma campanha, não é possível ativar a automação. Veja [Filtrar leads](/pipeline/filtrar-leads/) para preparar o público e [Configurar canais](/integracoes/canais/) para o acesso aos recursos de voz. ## Confira a compatibilidade do provedor API4Com e 3C Plus têm opções próprias na área de integrações. Ligação pelo WhatsApp depende da disponibilidade no workspace e no canal. Se você usa outro provedor, como Nvoip, confirme com o suporte a disponibilidade antes de preparar a conexão. Não preencha credenciais de um provedor nos campos de outro. A existência de uma conta VoIP externa não significa que ela apareça como integração no PipeFácil. --- # Conectar o WhatsApp Fonte: https://ajuda.matchsales.com.br/integracoes/whatsapp/ Escolha a modalidade de WhatsApp disponível no workspace. Você precisa de permissão para gerenciar integrações. | Modalidade | Conexão | Regra de envio | | ------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- | | WhatsApp Business (Cloud) | Autorização pela Meta e registro do número | Texto livre dentro da janela de atendimento; modelo aprovado fora dela. | | WhatsApp Lite | Pareamento por QR Code | Não usa a janela de 24 horas da Cloud nem os modelos da Meta. | A disponibilidade e a quantidade de canais dependem dos recursos contratados. Não confunda número de usuários com quantidade de canais. ## Conecte pela Meta 1. Em **Configurações** > **Integrações**, abra **WhatsApp Business**. 2. Selecione **Conecte com o Facebook** ou **Conectar outro número**. 3. Na janela da Meta, confira o portfólio, a conta WhatsApp e o número que deseja autorizar. Nomes iguais podem identificar contas diferentes; confira os identificadores antes de concluir. 4. Conclua a autorização e volte à lista de canais. 5. Siga a próxima ação indicada no canal: verificação ou [registro do número](/integracoes/canais/). O status local da conexão e o registro na Meta são informações diferentes. Um canal listado ainda pode precisar de uma ação antes de enviar mensagens. ![Números de WhatsApp conectados com qualidade, funil e acesso dos membros](shotWhatsappCanaisLight.src) Se o número vem de outro provedor, confira o vínculo existente e o procedimento de migração com o suporte antes de remover conexões. O uso simultâneo no aplicativo depende da modalidade de conexão autorizada pela Meta. ## Conecte por QR Code Siga o guia [Conectar o WhatsApp Lite](/integracoes/whatsapp-lite/) para criar a instância, ler o QR Code pelo celular e confirmar o atendimento. O guia inclui capturas nos temas claro e escuro, reconexão de uma instância existente e o caminho opcional para uma conta própria da Z-API. ## Configure a entrada e confira o atendimento No menu do canal, defina **Funil de entrada**, **Distribuição de leads** e **Acesso dos membros**. Faça uma mensagem de teste recebida no número conectado e confira a conversa e o responsável. Depois, confirme um envio permitido pelas regras do canal. Não use a ausência de mensagens antigas como único teste de conexão. A autorização de um número não garante importação completa do histórico anterior; isso depende do provedor e da modalidade. Para falhas, consulte [Diagnosticar o WhatsApp](/integracoes/solucionar-problemas-whatsapp/). --- # Conectar o WhatsApp Lite Fonte: https://ajuda.matchsales.com.br/integracoes/whatsapp-lite/ Conecte o WhatsApp da sua operação ao PipeFácil por QR Code. Depois do pareamento, configure quem pode atender pelo canal. Este guia é da modalidade **WhatsApp Lite**. Para conectar pela Meta, consulte [Conectar o WhatsApp](/integracoes/whatsapp/). ## Antes de começar - Tenha acesso para gerenciar as integrações do workspace. - Confira se o WhatsApp Lite está disponível e se há capacidade para outro canal no seu plano. - Tenha em mãos o celular principal, com o WhatsApp do número que deseja conectar já funcionando. - Mantenha o celular e o computador com acesso à internet. O celular precisa conseguir ler o QR Code exibido no computador. As capturas abaixo usam dados de exemplo e acompanham o tema claro ou escuro da documentação. O QR Code das imagens é ilustrativo: use o código gerado no seu workspace. ## Crie uma instância Lite Uma instância representa a conexão de um número com o CRM. O nome ajuda sua equipe a reconhecer esse canal. 1. No PipeFácil, acesse **Configurações** > **Integrações** e abra o card **WhatsApp Lite**. O card mostra **Conectar** quando ainda não há conexão ou **Gerenciar** quando já existe um canal. ![Integrações com o card WhatsApp Lite e a ação Conectar](integracoesLight.src) 2. Em **Instâncias Lite**, selecione **Nova instância**. Informe um **Nome da instância**, como `Time comercial`. Se aparecerem abas, mantenha **Nova instância** selecionada. ![Formulário Adicionar instância Lite com o nome Time comercial e o botão Criar instância](criarLight.src) 3. Selecione **Criar instância** e aguarde a tela **QR Code do canal**. Confira o nome do canal antes de parear o celular. ![QR Code do canal Time comercial com as ações Atualizar status e Novo QR](qrLight.src) Criar a instância ainda não conecta o número. Conclua o pareamento no celular. ## Leia o QR Code pelo celular 1. No celular principal do número que deseja conectar, abra o WhatsApp e entre em **Dispositivos conectados**. Dependendo da versão do aplicativo, essa opção pode aparecer como **Aparelhos conectados**. - **Android:** abra o menu de três pontos e selecione **Dispositivos conectados**. - **iPhone:** abra **Configurações** e selecione **Dispositivos conectados**. 2. Toque em **Conectar dispositivo** ou **Conectar um aparelho**, conforme o texto do aplicativo. Se solicitado, confirme o desbloqueio do celular. 3. Com o leitor aberto no WhatsApp, aponte o celular para o QR Code exibido no PipeFácil. Aguarde a confirmação do pareamento sem fechar a tela do computador. Use o leitor de **Dispositivos conectados**, em vez da câmera comum ou do QR Code do perfil. Consulte também as [instruções de conexão do WhatsApp](https://faq.whatsapp.com/1317564962315842/?cms_platform=android&lang=pt_br). A tela renova o QR Code automaticamente enquanto aguarda o pareamento. Se ele ficar indisponível ou a leitura falhar, selecione **Novo QR** e leia o código atualizado. ## Confirme a conexão Depois de parear, a tela mostra **Canal pronto para atendimento**. Se a confirmação não aparecer, selecione **Atualizar status**. ![Confirmação Canal pronto para atendimento após o pareamento do WhatsApp Lite](confirmacaoLight.src) Feche a tela do QR Code e confira o número na lista de instâncias. O canal deve mostrar o selo **Conectado**. Verifique se o telefone corresponde ao número da sua operação. ![Instância Time comercial com número de exemplo, selo Conectado e ação Reconectar](conectadoLight.src) Para validar o atendimento, envie uma mensagem de outro número para o número conectado. Em **Conversas**, confira o recebimento e responda pelo canal Lite. Confirme a entrega no outro celular. ## Configure o canal para sua equipe No menu de ações da instância, abra a configuração que deseja ajustar: | Opção | Para que serve | | ------------------------- | -------------------------------------------------------------------------- | | **Funil de entrada** | Escolhe o funil e a etapa para a entrada dos leads do canal. | | **Distribuição de leads** | Define se a atribuição segue o funil ou os membros com acesso para enviar. | | **Acesso dos membros** | Define quem pode acompanhar as conversas e quem pode enviar mensagens. | | **Renomear** | Altera o nome usado para identificar o canal no CRM. | ![Menu da instância Lite com funil de entrada, distribuição de leads e acesso dos membros](menuLight.src) Consulte [Configurar um canal](/integracoes/canais/) para entender o roteamento e os níveis de acesso. Uma lista de acessos individuais vazia deixa o canal disponível ao workspace; ela não bloqueia todos os membros. ## Reconecte uma instância existente Use a instância já cadastrada quando precisar refazer o pareamento do mesmo canal. 1. Em **Configurações** > **Integrações**, abra **WhatsApp Lite** e localize a instância pelo nome e número. 2. Selecione **Abrir QR** quando o canal estiver desconectado. Se a ação disponível for **Reconectar**, use-a para preparar um novo pareamento. 3. No celular, repita a leitura em **Dispositivos conectados**. Aguarde **Canal pronto para atendimento** e confira o selo **Conectado** na lista. 4. Faça um novo teste de recebimento e resposta em **Conversas**. No menu da instância, **Desconectar** encerra a sessão e permite reconectar depois. **Excluir** remove o canal da operação. Não exclua a instância como tentativa de atualizar o QR Code. ## Conecte uma conta própria da Z-API Este caminho só aparece quando o provedor configurado no workspace permite usar uma instância própria. Se a aba **Minha conta Z-API** não existir, siga a criação de uma nova instância descrita neste guia. 1. Em **Nova instância**, abra a aba **Minha conta Z-API**. 2. Informe o **Nome da instância**, o **ID da instância**, o **Token da instância** e o **Client-Token**. Obtenha esses dados no painel da sua conta Z-API. ![Aba Minha conta Z-API com campos de identificação e credenciais da instância, sem dados preenchidos](contaLight.src) 3. Selecione **Conectar conta**. O PipeFácil configura os webhooks da instância automaticamente. 4. Se o número ainda precisar de pareamento, leia o QR Code pelo celular. Depois, confira o status e teste o atendimento. Essas credenciais são da Z-API, não da API pública do PipeFácil. Não compartilhe tokens em capturas de tela ou mensagens de suporte. ## Resolva as dificuldades mais comuns | Situação | O que conferir | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | **QR Code indisponível** | Selecione **Novo QR** e aguarde a nova imagem antes de ler. | | O celular não aceita o QR Code | Use o leitor de **Dispositivos conectados** no celular principal e leia o código atual. | | A leitura terminou, mas o status não mudou | Selecione **Atualizar status** e confira se o aplicativo concluiu a conexão. | | O canal está conectado, mas um membro não vê as mensagens | Confira **Acesso dos membros**, as permissões e os filtros de Conversas. | | Mensagens antigas não aparecem | Teste uma mensagem nova. Pareamento não garante a importação completa do histórico anterior. | | A criação de uma instância falha | Confira a mensagem exibida e a disponibilidade de canais no workspace antes de tentar novamente. | Se o problema continuar, consulte [Diagnosticar problemas no WhatsApp](/integracoes/solucionar-problemas-whatsapp/). Ao pedir ajuda, informe o nome do canal, o horário da tentativa e o erro exibido, sem incluir tokens ou um QR Code de conexão ativo. --- # Funil Fonte: https://ajuda.matchsales.com.br/pipeline/ O funil é o quadro de vendas do PipeFácil. Cada coluna é uma etapa. Cada card é um lead. ![Quadro do funil com etapas e cards de leads distribuídos por coluna](/images/pipefacil/pipeline/kanban-light.png) Na barra do funil, você escolhe o funil, busca leads, aplica filtros e ordena o resultado. O resumo mostra a quantidade e o valor dos leads que estão no recorte atual. Você pode: - criar um lead na etapa certa - arrastar o card para avançar o negócio - abrir o detalhe sem sair do quadro - filtrar o conjunto no servidor ## Configure os cards No menu do funil, abra **Card do lead**. Selecione **+** na seção desejada e escolha **Última atividade** para exibir a atividade mais recente do lead. O campo pode aparecer em qualquer seção do card. - [Criar um lead](/pipeline/criar-lead/) — Abra o painel Novo lead e grave o card na coluna. - [Mover um lead](/pipeline/mover-lead/) — Arraste o card ou use o seletor de etapa no detalhe. ## Nesta área ## Remova ou oculte informações do card No editor **Card do lead**, selecione a informação na prévia e use **Remover do card**. Os elementos que oferecem controle de exibição podem ser ocultados ou reativados no próprio editor. Confira a prévia e selecione **Salvar**. ![Editor do card com Dias na etapa selecionado e ação Remover do card](shotCardPersonalizarLight.src) O campo configurável **Dias na etapa** pertence ao card do quadro. A linha **No estágio**, dentro do detalhe do lead, é uma informação fixa de leitura; removê-la do card não apaga essa linha do detalhe. ## Prepare a entrada de leads - [Distribuir leads entre vendedores](/configuracoes/distribuicao-de-leads/). - [Importar leads ou migrar do Kommo](/integracoes/importacao-e-migracao/). - [Iniciar a primeira conversa](/conversas/iniciar/). --- # Criar um lead Fonte: https://ajuda.matchsales.com.br/pipeline/criar-lead/ Crie um lead no funil ativo. O card nasce na etapa que você escolher. Você precisa da permissão de criar leads. Sem ela, o botão **Novo lead** não aparece. 1. No PipeFácil, vá até **Funil**. Se o workspace tiver vários funis, escolha o funil na barra superior. 2. Selecione **Novo lead**. Para já nascer em uma coluna, use o **+** dessa coluna. ![Painel Novo lead com etapa, contato, telefone e campos do grupo Geral](/images/pipefacil/pipeline/novo-lead-light.png) 3. No título **Nome do lead**, informe o nome do negócio. 4. Em **Telefone**, informe o número se você já o conhece. Você pode criar o lead sem telefone e completar o cadastro depois. 5. (Opcional) Preencha **Contato**, **E-mail** e os campos do grupo **Geral**. 6. Confira a etapa no seletor do cabeçalho. 7. Selecione **Criar lead**. O card aparece na coluna da etapa. Se o servidor recusar, o painel permanece aberto com a mensagem no campo. O painel agrupa os campos nas abas **Geral**, **Empresa**, **Produto** e **UTM / Rastreio**. Um asterisco marca os campos obrigatórios. A etapa selecionada no cabeçalho define a coluna inicial do card. ## Próximos passos - [Abrir o detalhe do lead](/pipeline/detalhe-do-lead/) - [Mover um lead](/pipeline/mover-lead/) --- # Abrir o detalhe do lead Fonte: https://ajuda.matchsales.com.br/pipeline/detalhe-do-lead/ O detalhe é o painel do negócio. Ele abre sobre o funil e guarda campos, histórico e conversa. 1. No **Funil**, selecione o card do lead. ![Painel de detalhes de um lead com etapa, dados comerciais, tags e campos personalizados](/images/pipefacil/pipeline/detalhe-lead-light.png) 2. No cabeçalho, edite o **Nome do lead** ou a etapa. 3. Na aba **Detalhes**, atualize valor, responsável, tags e campos personalizados. O grupo **Geral** reúne os campos sem pasta. 4. Na aba **Linha do tempo**, confira mudanças de etapa, de campo e de responsável. As trocas de responsável mostram a pessoa anterior e a nova. ![Linha do tempo de um lead com evento de troca de responsável e valores anterior e atual](/images/pipefacil/pipeline/detalhe-lead-timeline-light.png) 5. Na aba **Nota**, registre o contexto. Na aba **Tarefa**, crie o próximo follow-up. Quando uma pessoa já não pertence ao workspace, a linha do tempo identifica o registro como **Membro inativo**. Se o lead ainda não tiver contato, selecione **Adicionar contato** no cabeçalho ou no menu **⋯**. Pesquise um contato do workspace para vinculá-lo ou crie um novo. Se o telefone informado já pertencer a outra pessoa, confira o contato encontrado e selecione **Usar este contato**. O painel também pode abrir a conversa do lead, quando há um canal ligado. CIA e cadência aparecem como abas extras quando o workspace tem esses recursos. Leads de formulários da Meta podem mostrar **Meta Ads** e o formulário de origem. Leads do Instagram podem mostrar a conta de origem. O cabeçalho reúne o contato, a etapa atual, o funil, as tags e as ações rápidas. A aba **Detalhes** concentra os campos do negócio. As demais abas mostram o histórico, as tarefas, as notas e a cadência vinculada. Para apagar o lead, abra o menu do cabeçalho e selecione a ação de apagar. O diálogo pede confirmação. ## Produtos, notas e automações Na aba de produtos, vincule itens do [catálogo](/configuracoes/produtos/) e ajuste as quantidades. O preço salvo no negócio é preservado quando o catálogo muda. Uma nota pode conter arquivos anexados. Para ditar uma nota, use **Ditar nota** e revise a transcrição antes de salvar. O recurso requer a CIA. A linha do tempo identifica quem realizou a ação, incluindo membros, automações e integrações, quando essa informação estiver disponível. Na aba **Automações**, consulte execuções relacionadas ao negócio e cancele as pendentes quando necessário. O cancelamento não desfaz mensagens já enviadas nem alterações concluídas. Veja [Acompanhar execuções](/automacoes/acompanhar/). ## Informações do card A configuração do card pode mostrar o resumo de tarefas e a última atividade. A probabilidade de fechamento também aparece de forma visual. Esses dados dependem da configuração do funil; o detalhe mantém o contexto completo. ## Origem e rastreamento Abra a aba **UTM / Rastreio** para consultar os valores de campanha recebidos para o lead. A tela mostra quantos dos 25 campos têm valor e deixa os dados somente para leitura. Formulários da Meta podem preencher a origem, o formulário, os dados de campanha e os identificadores enviados pela Meta. Links e páginas de captura também podem enviar UTMs e identificadores do navegador. Campos sem valor indicam que a origem não forneceu aquele dado. Consulte a [explicação dos campos de rastreamento](/integracoes/origem-e-rastreio-de-leads/) para interpretar esses dados e usá-los em automações. ## Responsável e corresponsável Na aba **Detalhes**, selecione **Responsável** para transferir o atendimento. Use **Corresponsável** para incluir outra pessoa sem substituir o responsável principal. Confira [Membros e acessos](/configuracoes/membros/) para entender a visibilidade após um repasse. O compartilhamento de leads e os acessos ao canal determinam o que a outra pessoa pode acompanhar e enviar. A [distribuição do funil](/configuracoes/distribuicao-de-leads/) define a entrada automática; trocar essa configuração não reatribui todos os negócios existentes. ## Primeira conversa Quando o lead ainda não tem histórico, use **Iniciar conversa** na área de atendimento do detalhe. Confira o telefone do contato, o canal e a regra de envio. Veja [Iniciar uma conversa pelo lead](/conversas/iniciar/). ![Ação Iniciar conversa exibida no lead que ainda não possui histórico](shotLeadSemConversaLight.src) Um telefone salvo em campo personalizado não substitui o destinatário do contato no compositor. Confira o destinatário antes de enviar. ## Próximos passos - [Mover um lead](/pipeline/mover-lead/) - [Conversas](/conversas/) - [Tarefas](/tarefas/) --- # Filtrar e ordenar o quadro Fonte: https://ajuda.matchsales.com.br/pipeline/filtrar-leads/ Os filtros do funil rodam no servidor. O quadro mostra só o conjunto que passa nas regras. 1. No **Funil**, use o campo **Buscar lead...** para achar por nome, contato ou telefone. 2. Use **Responsável** e **Tags** na barra para restringir o quadro. 3. Selecione **Filtros**. Ajuste origem, canal, leads que estão voltando e o período de criação. ![Popover de filtros do funil com origem, período, retorno e campos personalizados](/images/pipefacil/pipeline/filtros-light.png) 4. (Opcional) Inclua um campo personalizado compatível na lista de filtros. Para um campo de texto, informe o valor exato. ![Filtro do funil com o campo personalizado Cargo e um valor exato](/images/pipefacil/pipeline/filtros-campo-texto-light.png) 5. Selecione **Ordenar** e escolha mais recentes, mais antigos, última atividade, parados há mais tempo, maior valor ou nome A–Z. 6. Alterne **Kanban** e **Tabela** na barra do funil quando precisar de uma lista. Na visão **Tabela**, abra **Colunas** para escolher quais aparecem. Essa escolha fica salva neste navegador e varia por usuário e funil. ![Quadro Kanban do funil com leads distribuídos por etapa](/images/pipefacil/pipeline/kanban-light.png) A busca e os filtros somam. Para campos personalizados de texto, o filtro procura correspondência exata depois de remover espaços no início e no fim do valor. Para zerar, selecione o botão de limpar filtros na barra do funil. A ordenação continua selecionada porque não altera o recorte. O menu de exibição controla se as colunas de ganho e perda aparecem. Com elas visíveis, a ordenação também se aplica a essas colunas. ## Etapas atuais e histórico de passagem O filtro de etapa atual aceita várias etapas, inclusive **Ganho** e **Perdido**. Ele consulta onde o negócio está. **Passou pela etapa** consulta seu histórico, inclusive etapas de outros funis, e aceita um período para a passagem. Quando o compartilhamento de leads está disponível, filtre também pelo corresponsável. Esses critérios podem ser usados nos filtros salvos. ## Campos vazios e dados comerciais Use a opção de campo **não preenchido** para encontrar valores ausentes. Ela inclui valores nulos, texto vazio e listas vazias. Pode ser combinada com outros valores do mesmo campo. O filtro **Produtos** encontra negócios associados a qualquer produto selecionado. Combine vários produtos para incluir negócios com pelo menos um deles. **Não preenchido** encontra negócios sem itens associados e pode ser combinado com produtos. Os filtros de dados comerciais incluem valor, probabilidade de fechamento, previsão de fechamento, data de entrada na etapa, última atualização, motivo da perda e etapa de origem da perda. Para filtrar por probabilidade, selecione o número de chamas desejado; o quadro inclui negócios com essa quantidade ou mais. Os demais campos numéricos e datas aceitam intervalos; o motivo da perda usa texto exato. ## Exportar o recorte A exportação respeita a busca e os filtros ativos do funil. Confira o recorte antes de solicitar o arquivo. Cada negócio ocupa uma linha; a exportação inclui datas de ganho e perda quando aplicáveis. Na visão em tabela, selecione **Colunas da tabela** para exportar as colunas visíveis. Selecione **Todos os dados** para incluir campos personalizados e dados de rastreio. ## Próximos passos - [Criar um lead](/pipeline/criar-lead/) - [Configurar tags e campos](/configuracoes/) --- # Mover um lead Fonte: https://ajuda.matchsales.com.br/pipeline/mover-lead/ Mova um lead para outra etapa do mesmo funil ou para outro funil. ## Arraste no quadro 1. No **Funil**, arraste o card até a coluna de destino. 2. Se a etapa pedir campos, preencha o diálogo **Campos obrigatórios** e confirme. 3. Se a etapa for de perda, escolha o **Motivo da perda**. Se o catálogo tiver **Outro**, descreva o motivo. O card fica na nova coluna. A [linha do tempo](/pipeline/detalhe-do-lead/) registra a mudança. ## Use o seletor no detalhe 1. Abra o lead. 2. No cabeçalho, selecione o nome da etapa atual. 3. Na coluna da esquerda, escolha o funil. Na da direita, escolha a etapa. ![Seletor de etapa com funis à esquerda e etapas de destino à direita](/images/pipefacil/pipeline/seletor-etapa-light.png) O seletor move o lead entre funis. Os mesmos diálogos de campos e de perda aparecem quando a etapa exige. ## Mova vários leads 1. No **Funil**, selecione os leads ou marque **Selecionar tudo**. Para incluir todos os leads de uma coluna, use a opção de selecionar a etapa inteira. 2. Selecione **Mover** na barra de seleção. 3. Escolha o funil e a etapa de destino. 4. Se o destino for uma etapa de perda, escolha o **Motivo da perda**. A seleção em massa aceita até 1.000 leads por operação. Ela respeita os filtros ativos e não inclui leads fora do recorte atual. ## Campos sugeridos e etapa de origem da perda Uma etapa pode pedir campos **sugeridos** sem impedir o avanço. Campos **obrigatórios** precisam ser preenchidos. A validação considera o funil de destino e as regras de visibilidade do campo. Ao marcar um negócio como perdido, o sistema registra também a etapa em que ele estava. Esse dado permite analisar onde ocorreu a perda e filtrar o quadro. Veja [Regras de campos por etapa](/configuracoes/regras-de-campos/). Ao mover um lead para a fila de atendimento, ele fica sem responsável. Consulte [Comportamentos do funil](/configuracoes/comportamentos-do-funil/). ## Próximos passos - [Filtrar o quadro](/pipeline/filtrar-leads/) - [Configurar etapas e campos](/configuracoes/) --- # Agente SDR Fonte: https://ajuda.matchsales.com.br/sdr/ O agente SDR é um membro do tipo agente. Ele qualifica conversas inbound e transfere o lead para uma pessoa. A biblioteca de SDRs oferece bases prontas por objetivo. Você pode testar uma base sem envio real antes de implantá-la no workspace. ![Área de Agente SDR com contagem de agentes e configurações principais](/images/pipefacil/sdr/lista-light.png) - [Criar um agente SDR](/sdr/criar/) - [Configurar um agente externo](/sdr/agente-externo/) - [Conversas](/conversas/) - [Integrações](/integracoes/) --- # Configurar um agente externo Fonte: https://ajuda.matchsales.com.br/sdr/agente-externo/ Conecte um agente externo ao PipeFácil usando um webhook e uma chave de API própria. Você precisa de uma URL HTTPS para receber os eventos e da permissão para configurar integrações. 1. Vá até **Configurações** > **Integrações**. 2. Abra **Agente IA** e selecione **Adicionar webhook**. ![Diálogo de agente externo com nome, canal e URL do webhook](/images/pipefacil/sdr/agente-externo-light.png) 3. Informe o **Nome do agente**, escolha o canal e informe a **URL do webhook**. 4. Salve a conexão e copie a **Chave de API do agente** quando ela aparecer. A chave é exibida uma única vez. 5. No funil, escolha o agente como responsável nas regras de atribuição. O agente recebe mensagens dos negócios que estão sob sua responsabilidade. Para substituir uma chave, use **Rotacionar chave de API** e atualize a credencial no agente externo. ## Mensagens enviadas pela equipe Na configuração do webhook, **Mensagens enviadas por mim** controla a entrega das mensagens enviadas pela equipe ao agente. Ative quando o agente precisa acompanhar o atendimento humano e confira como ele interpreta esses eventos. Essa opção também afeta mensagens de cadência enviadas pela API. Revise a opção e salve a configuração antes de operar o agente. A chave identifica o membro-bot; consulte [Autenticação](/developers/authentication/) para os limites da API. --- # Criar um agente SDR Fonte: https://ajuda.matchsales.com.br/sdr/criar/ Crie um agente SDR para qualificar leads e transferir conversas ao time. Você precisa preparar o perfil, o fluxo e o estágio de sucesso do agente. 1. No PipeFácil, vá até **SDR**. 2. Na **Biblioteca de SDRs**, escolha um template ou selecione **Criar do zero**. 3. (Opcional) No template escolhido, selecione **Teste rápido** para conversar sem enviar mensagens reais. Quando terminar, selecione **Implantar no meu workspace**. 4. Informe o **Nome** e escolha o **Perfil do workspace** e o **Fluxo de atendimento**. 5. Selecione o **Estágio de sucesso** e configure a autonomia e o buffer. 6. Selecione **Criar agente**. O PipeFácil cria o agente e seu membro-bot. Um fluxo novo é publicado antes de ser vinculado ao agente. ## Distribua leads para o agente O agente recebe leads pela distribuição normal do funil. Para incluí-lo, configure o membro-bot como participante da estratégia de distribuição do funil. Depois, em **Configurações** > **Integrações**, conceda ao membro-bot acesso aos canais de WhatsApp em que ele deve responder. O canal precisa permitir envio de mensagens. A distribuição do funil escolhe o responsável do lead. A permissão do canal controla onde o agente pode enviar mensagens. Consulte [Distribuir leads entre vendedores](/configuracoes/distribuicao-de-leads/) e [Configurar acessos ao canal](/integracoes/canais/). Depois da criação, abra as configurações do agente para ajustar o perfil, o fluxo, a base de conhecimento, a autonomia e o buffer. Use o controle de status para deixar o agente **Ativo** ou **Pausado**. O teste de um template usa uma conversa temporária. Ele não cria um agente, não envia mensagens e não persiste a conversa. ## Excluir um agente A ação de exclusão aparece nas configurações do agente e pede confirmação. Revise os leads atribuídos e as integrações que usam o agente antes de concluir. ## Próximos passos - [Configurar um agente externo](/sdr/agente-externo/) - [Responder uma conversa](/conversas/responder/) - [Conectar o Instagram](/integracoes/instagram/) --- # Tarefas Fonte: https://ajuda.matchsales.com.br/tarefas/ Tarefas são pendências com prazo. Elas aparecem na lista geral e no detalhe do lead. O quadro agrupa por vencimento: **Atrasadas**, **Hoje**, **Amanhã** e **Futuras**. ![Quadro de tarefas agrupadas pelas colunas Atrasadas, Hoje, Amanhã e Futuras](/images/pipefacil/tarefas/quadro-light.png) O menu lateral mostra um contador com as tarefas pendentes atrasadas e as que vencem hoje. Cada card mostra o título, a categoria, o prazo, a pessoa responsável e o lead relacionado. A coluna **Atrasadas** aparece apenas quando existe uma tarefa vencida. - [Criar uma tarefa](/tarefas/criar/) — Defina título, prazo, categoria e o lead vinculado. ## Nesta área ## Guias relacionados - [Métricas de tarefas](/tarefas/metricas/) --- # Criar uma tarefa Fonte: https://ajuda.matchsales.com.br/tarefas/criar/ Crie um follow-up na lista geral ou a partir de um lead. Você precisa da permissão de criar tarefas. Sem ela, o botão **Nova tarefa** não aparece. 1. No PipeFácil, vá até **Tarefas**. 2. Selecione **Nova tarefa**. ![Diálogo Nova tarefa com título, prazo, categoria, responsável e lead](/images/pipefacil/tarefas/nova-light.png) 3. Informe o título. 4. Ajuste data e hora. O diálogo já sugere daqui a uma hora. 5. Escolha uma categoria disponível no workspace. Além das categorias padrão, o time pode cadastrar categorias próprias. 6. (Opcional) Escolha o responsável e o lead vinculado. 7. Selecione **Criar tarefa**. No detalhe do lead, a aba **Tarefa** abre o mesmo diálogo. Nesse caminho o lead já vem vinculado e não muda. ## Próximos passos - [Organizar o quadro de tarefas](/tarefas/organizar/) - [Modo Foco](/foco/) --- # Consultar métricas de tarefas Fonte: https://ajuda.matchsales.com.br/tarefas/metricas/ Em **Tarefas**, alterne para **Métricas**. Escolha o período, o funil e as pessoas que devem entrar na análise. O recorte das métricas tem filtros próprios. Confira esses filtros ao trocar entre quadro, lista e métricas; o que aparece em uma visualização não define automaticamente o conjunto da outra. ![Métricas de tarefas com filtros de período, indicadores, resultados por pessoa e categorias](guideShot0Light.src) Na lista de concluídas, você também pode filtrar por quem concluiu a tarefa e pelo período de conclusão. Responsável e pessoa que concluiu podem ser diferentes. Prazos, atrasos e conclusão representam momentos distintos. Uma tarefa sem vencimento não deve contar como uma tarefa vencida. Use [categorias de tarefas](/configuracoes/categorias-de-tarefas/) para organizar as atividades e [o quadro](/tarefas/organizar/) para agir sobre as pendências. --- # Organizar o quadro de tarefas Fonte: https://ajuda.matchsales.com.br/tarefas/organizar/ A tela de **Tarefas** tem quadro e lista. Os filtros valem nas duas views. ![Quadro de tarefas separado por atrasadas, hoje, amanhã e futuras](/images/pipefacil/tarefas/quadro-light.png) 1. Em **Tarefas**, use **Buscar tarefas...** para achar por texto, negócio ou contato. 2. Selecione **Filtros**. Recorte por **Vencimento**, **Categoria** e **Responsável**. 3. Alterne quadro e lista nos botões da barra. 4. No quadro, arraste um card entre **Hoje**, **Amanhã** e **Futuras** para reagendar. **Atrasadas** só aparece quando há tarefa vencida. Essa coluna não recebe arraste. Reagende pelo menu da tarefa ou mova o card para outra coluna. Marque a tarefa como concluída no card ou na lista. O lead vinculado abre no painel lateral, sem sair de **Tarefas**. ## Categorias e indicadores As categorias ajudam a separar os tipos de atividade. O workspace pode [criar, editar e arquivar categorias](/configuracoes/categorias-de-tarefas/). Os indicadores de tarefas consideram o prazo e a situação das atividades. Confira o período e os filtros antes de comparar pendências, atrasos e conclusões. Uma tarefa sem prazo não deve ser interpretada como atrasada. ## Próximos passos - [Criar uma tarefa](/tarefas/criar/) - [Abrir o detalhe do lead](/pipeline/detalhe-do-lead/) --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/list-deals/ # Listar negócios `GET /api/v1/deals` Página de negócios visíveis ao membro da chave, ordenada pela criação mais recente. Sem status, inclui abertos, ganhos e perdidos. Mantenha os mesmos filtros ao reutilizar o cursor. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `pipeline` | query | Não | `integer` | Número sequencial do funil dentro do workspace. | | `stageId` | query | Não | `string` | — | | `returning` | query | Não | `boolean` | — | | `createdFrom` | query | Não | `string` | yyyy-MM-dd | | `createdTo` | query | Não | `string` | yyyy-MM-dd | | `source` | query | Não | `string` | Slug da origem do negócio, por exemplo, manual ou whatsapp. | | `responsibleUserIds` | query | Não | `array` | Pode ser repetido ou informado como lista separada por vírgulas. | | `tagIds` | query | Não | `array` | Pode ser repetido ou informado como lista separada por vírgulas. | | `search` | query | Não | `string` | Busca por negócio, contato ou telefone. | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | Cursor opaco retornado pela página anterior. | | `customFields[slug]` | query | Não | `string` | Filtra pelo valor de um campo personalizado, usando o slug: `customFields[budget]=high`. O valor reservado `__empty__` inclui negócios sem preenchimento (campo ausente, nulo, texto vazio ou lista vazia). Pode ser combinado com outros valores, usando a regra OU. | | `status` | query | Não | `array` | Situações do negócio. Repita o parâmetro ou separe os valores por vírgula. Omitido: todas as situações. | | `customFieldRanges[slug][from]` | query | Não | `string` | Limite inicial do intervalo de um campo de data. Substitua slug pela chave do campo. | | `customFieldRanges[slug][to]` | query | Não | `string` | Limite final do intervalo de um campo de data. Combine com o limite inicial ou envie apenas um limite. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].seq` | `integer` | Não | | | `data.items[].name` | `string` | Não | | | `data.items[].value` | `number` | Não | | | `data.items[].currency` | `string` | Não | | | `data.items[].closeProbability` | `integer` | Não | | | `data.items[].source` | `string` | Não | | | `data.items[].status` | `string` | Não | | | `data.items[].isReturning` | `boolean` | Não | | | `data.items[].pipelineId` | `string` | Não | | | `data.items[].stageId` | `string` | Não | | | `data.items[].responsibleUserId` | `string` | Não | | | `data.items[].coOwnerUserId` | `string` | Não | Aceita null. | | `data.items[].lostReason` | `string` | Não | Aceita null. | | `data.items[].notes` | `string` | Não | Aceita null. | | `data.items[].daysInStage` | `integer` | Não | | | `data.items[].tags` | `array` | Não | | | `data.items[].tags[].id` | `string` | Não | | | `data.items[].tags[].name` | `string` | Não | | | `data.items[].tags[].color` | `string` | Não | | | `data.items[].responsible` | `DealMember` | Não | | | `data.items[].responsible.userId` | `string` | Não | | | `data.items[].responsible.name` | `string` | Não | Aceita null. | | `data.items[].coOwner` | `object` | Não | Aceita null. | | `data.items[].coOwner.userId` | `string` | Não | | | `data.items[].coOwner.name` | `string` | Não | Aceita null. | | `data.items[].activeChannels` | `array` | Não | | | `data.items[].lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].lastMessageText` | `string` | Não | | | `data.items[].replyPending` | `boolean` | Não | | | `data.items[].properties` | `object` | Não | Valores resolvidos dos campos personalizados. | | `data.items[].channel` | `object` | Não | Aceita null. | | `data.items[].channelOverride` | `object` | Não | Aceita null. | | `data.items[].expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].stageChangedAt` | `string` | Não | Formato: date-time. | | `data.items[].closedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].returnSignaledAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].contact` | `object` | Não | Aceita null. | | `data.items[].stage` | `object` | Não | Aceita null. | | `data.items[].company` | `object` | Não | Aceita null. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.items[].updatedAt` | `string` | Não | Formato: date-time. | | `data.items[].tracking` | `object` | Não | Aceita null. | | `data.items[].tracking.utmContent` | `string` | Não | Aceita null. | | `data.items[].tracking.utmMedium` | `string` | Não | Aceita null. | | `data.items[].tracking.utmCampaign` | `string` | Não | Aceita null. | | `data.items[].tracking.utmSource` | `string` | Não | Aceita null. | | `data.items[].tracking.utmTerm` | `string` | Não | Aceita null. | | `data.items[].tracking.utmReferrer` | `string` | Não | Aceita null. | | `data.items[].tracking.referrer` | `string` | Não | Aceita null. | | `data.items[].tracking.gclientid` | `string` | Não | Aceita null. | | `data.items[].tracking.gclid` | `string` | Não | Aceita null. | | `data.items[].tracking.fbclid` | `string` | Não | Aceita null. | | `data.items[].tracking.metaLeadId` | `string` | Não | Aceita null. | | `data.items[].tracking.fbp` | `string` | Não | Aceita null. | | `data.items[].tracking.fbc` | `string` | Não | Aceita null. | | `data.items[].tracking.clientIpAddress` | `string` | Não | Aceita null. | | `data.items[].tracking.clientUserAgent` | `string` | Não | Aceita null. | | `data.items[].tracking.ctwaClid` | `string` | Não | Aceita null. | | `data.items[].lostFromStage` | `object` | Não | Aceita null. | | `data.items[].lostFromStage.id` | `string` | Não | | | `data.items[].lostFromStage.name` | `string` | Não | | | `data.items[].lostFromStage.pipelineId` | `string` | Não | | | `data.items[].taskSummary` | `object` | Não | Resumo de tarefas quando habilitado na configuração do card. Aceita null. | | `data.items[].taskSummary.pendingCount` | `integer` | Não | | | `data.items[].taskSummary.overdueCount` | `integer` | Não | | | `data.items[].taskSummary.nextTask` | `object` | Não | Aceita null. | | `data.items[].taskSummary.nextTask.id` | `string` | Não | | | `data.items[].taskSummary.nextTask.title` | `string` | Não | | | `data.items[].taskSummary.nextTask.dueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].taskSummary.nextTask.categoryName` | `string` | Não | Aceita null. | | `data.items[].taskSummary.nextTask.categoryColor` | `string` | Não | Aceita null. | | `data.items[].lastActivity` | `object` | Não | Última atividade quando habilitada na configuração do card. Aceita null. | | `data.items[].lastActivity.id` | `string` | Não | | | `data.items[].lastActivity.type` | `string` | Não | | | `data.items[].lastActivity.occurredAt` | `string` | Não | Formato: date-time. | | `data.items[].lastActivity.title` | `string` | Não | | | `data.items[].lastActivity.body` | `string` | Não | Aceita null. | | `data.items[].lastActivity.meta` | `object` | Não | | | `data.items[].lastActivity.actor` | `object` | Não | Aceita null. | | `data.items[].lastActivity.actor.actorType` | `string` | Não | | | `data.items[].lastActivity.actor.userId` | `string` | Não | Aceita null. | | `data.items[].lastActivity.actor.userName` | `string` | Não | Aceita null. | | `data.items[].lastActivity.actor.userAvatarUrl` | `string` | Não | Aceita null. | | `data.items[].lastActivity.actor.automationId` | `string` | Não | Aceita null. | | `data.items[].lastActivity.actor.automationName` | `string` | Não | Aceita null. | | `data.items[].lastActivity.actor.copilotActionId` | `string` | Não | Aceita null. | | `data.items[].lastActivity.actor.apiKeyId` | `string` | Não | Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DealListItem" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/create-deal/ # Criar negócio `POST /api/v1/deals` Cria um negócio no workspace da chave e retorna o registro criado. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Proposta de consultoria", "contactFirstName": "Ana", "contactLastName": "Silva", "email": "ana@example.com", "value": 1500, "currency": "BRL" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Não | Aceita null. Até 255 caracteres. | | `phone` | `string` | Não | Telefone do contato, opcional. Sem telefone, o negócio pode não ter contato; um nome ou e-mail permite criar um contato sem telefone. Aceita null. | | `contactName` | `string` | Não | Nome completo do contato, dividido no primeiro espaço em firstName/lastName. Ignorado quando contactFirstName ou contactLastName é enviado. Aceita null. Até 255 caracteres. | | `contactFirstName` | `string` | Não | Aceita null. Até 255 caracteres. | | `contactLastName` | `string` | Não | Aceita null. Até 255 caracteres. | | `email` | `string` | Não | Formato: email. Aceita null. Até 255 caracteres. | | `notes` | `string` | Não | Aceita null. Até 2000 caracteres. | | `value` | `number` | Não | Aceita null. Mínimo: 0. | | `closeProbability` | `integer` | Não | Aceita null. Mínimo: 0. Máximo: 100. | | `expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. | | `currency` | `string` | Não | Padrão: BRL. Aceita null. Até 3 caracteres. | | `stageId` | `string` | Não | Padrão: primeira etapa do funil. Aceita null. | | `companyId` | `string` | Não | Aceita null. | | `channelId` | `string` | Não | Aceita null. | | `responsibleUserId` | `string` | Não | Aceita null. | | `useAssignmentStrategy` | `boolean` | Não | Aceita null. | | `customFields` | `object` | Não | Aceita null. | | `company` | `object` | Não | Aceita null. | | `company.name` | `string` | Sim | Até 255 caracteres. | | `company.domain` | `string` | Não | Aceita null. Até 255 caracteres. | | `company.cnpj` | `string` | Não | Aceita null. Até 30 caracteres. | | `company.industry` | `string` | Não | Aceita null. Até 255 caracteres. | | `company.website` | `string` | Não | Aceita null. Até 500 caracteres. | | `company.logoUrl` | `string` | Não | Aceita null. Até 500 caracteres. | | `company.notes` | `string` | Não | Aceita null. Até 2000 caracteres. | | `tracking` | `object` | Não | Aceita null. | | `tracking.utmContent` | `string` | Não | Aceita null. | | `tracking.utmMedium` | `string` | Não | Aceita null. | | `tracking.utmCampaign` | `string` | Não | Aceita null. | | `tracking.utmSource` | `string` | Não | Aceita null. | | `tracking.utmTerm` | `string` | Não | Aceita null. | | `tracking.utmReferrer` | `string` | Não | Aceita null. | | `tracking.referrer` | `string` | Não | Aceita null. | | `tracking.gclientid` | `string` | Não | Aceita null. | | `tracking.gclid` | `string` | Não | Aceita null. | | `tracking.fbclid` | `string` | Não | Aceita null. | | `tracking.metaLeadId` | `string` | Não | Aceita null. | | `tracking.fbp` | `string` | Não | Aceita null. | | `tracking.fbc` | `string` | Não | Aceita null. | | `tracking.clientIpAddress` | `string` | Não | Aceita null. | | `tracking.clientUserAgent` | `string` | Não | Aceita null. | | `tracking.ctwaClid` | `string` | Não | Aceita null. | | `metadata` | `object` | Não | Metadados adicionais do negócio. Aceita null. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealResponse` | Não | Negócio resumido retornado na criação ou atualização. | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.name` | `string` | Não | | | `data.contactId` | `string` | Não | Aceita null. | | `data.responsibleUserId` | `string` | Não | | | `data.companyId` | `string` | Não | Aceita null. | | `data.pipelineId` | `string` | Não | | | `data.stageId` | `string` | Não | | | `data.value` | `number` | Não | | | `data.currency` | `string` | Não | | | `data.closeProbability` | `integer` | Não | | | `data.source` | `string` | Não | | | `data.status` | `string` | Não | open \| won \| lost | | `data.coOwnerUserId` | `string` | Não | Aceita null. | | `data.expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stageChangedAt` | `string` | Não | Formato: date-time. | | `data.closedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lostReason` | `string` | Não | Aceita null. | | `data.customFields` | `object` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.tracking` | `object` | Não | Aceita null. | | `data.tracking.utmContent` | `string` | Não | Aceita null. | | `data.tracking.utmMedium` | `string` | Não | Aceita null. | | `data.tracking.utmCampaign` | `string` | Não | Aceita null. | | `data.tracking.utmSource` | `string` | Não | Aceita null. | | `data.tracking.utmTerm` | `string` | Não | Aceita null. | | `data.tracking.utmReferrer` | `string` | Não | Aceita null. | | `data.tracking.referrer` | `string` | Não | Aceita null. | | `data.tracking.gclientid` | `string` | Não | Aceita null. | | `data.tracking.gclid` | `string` | Não | Aceita null. | | `data.tracking.fbclid` | `string` | Não | Aceita null. | | `data.tracking.metaLeadId` | `string` | Não | Aceita null. | | `data.tracking.fbp` | `string` | Não | Aceita null. | | `data.tracking.fbc` | `string` | Não | Aceita null. | | `data.tracking.clientIpAddress` | `string` | Não | Aceita null. | | `data.tracking.clientUserAgent` | `string` | Não | Aceita null. | | `data.tracking.ctwaClid` | `string` | Não | Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealResponse" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/list-deal-custom-field-values/ # Listar valores de campos personalizados dos negócios `GET /api/v1/deals/custom-field-values` Lista paginada de valores em linhas `(negócio, campo, valor)`, com o identificador do campo personalizado. Use esse identificador para relacionar os valores com `/api/v1/custom-fields`; o mapa `properties` dos negócios usa o slug. Inclui todos os status por padrão, enquanto `GET /api/v1/deals` lista somente negócios abertos. Campos `multi_select` geram uma linha por opção selecionada. `label` é preenchido apenas para tipos com opções. Um campo limpo ainda gera uma linha com `value` nulo; slugs sem definição correspondente são omitidos. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `status` | query | Não | `array` | Pode ser repetido. Omita para incluir todos os status. | | `pipelineId` | query | Não | `string` | Identificador do funil. | | `updatedFrom` | query | Não | `string` | Instante ISO ou yyyy-MM-dd. Inclui apenas negócios atualizados a partir desse momento; use para carga incremental. | | `updatedTo` | query | Não | `string` | Instante ISO ou yyyy-MM-dd. Limite final exclusivo. | | `limit` | query | Não | `integer` | Negócios por página, não linhas. Padrão: 50. | | `cursor` | query | Não | `string` | Cursor opaco retornado pela página anterior. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].dealId` | `string` | Não | | | `data.items[].fieldId` | `string` | Não | Identificador da definição do campo; use para relacionar com /api/v1/custom-fields. | | `data.items[].fieldSlug` | `string` | Não | | | `data.items[].value` | `object` | Não | Valor salvo: texto, número, booleano ou descritor {key,name,size,mimeType} de arquivo. Aceita null. | | `data.items[].label` | `string` | Não | Rótulo legível da opção; nulo para tipos sem opções. Aceita null. | | `data.items[].updatedAt` | `string` | Não | updatedAt do negócio, usado pelo cursor e pela deduplicação incremental. Formato: date-time. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DealCustomFieldValue" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/get-deal/ # Consultar negócio `GET /api/v1/deals/{seq}` Retorna um negócio visível pelo seu número sequencial no workspace. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do negócio dentro do workspace. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealListItem` | Não | Negócio detalhado retornado na listagem ou consulta, com relações associadas. | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.name` | `string` | Não | | | `data.value` | `number` | Não | | | `data.currency` | `string` | Não | | | `data.closeProbability` | `integer` | Não | | | `data.source` | `string` | Não | | | `data.status` | `string` | Não | | | `data.isReturning` | `boolean` | Não | | | `data.pipelineId` | `string` | Não | | | `data.stageId` | `string` | Não | | | `data.responsibleUserId` | `string` | Não | | | `data.coOwnerUserId` | `string` | Não | Aceita null. | | `data.lostReason` | `string` | Não | Aceita null. | | `data.notes` | `string` | Não | Aceita null. | | `data.daysInStage` | `integer` | Não | | | `data.tags` | `array` | Não | | | `data.tags[].id` | `string` | Não | | | `data.tags[].name` | `string` | Não | | | `data.tags[].color` | `string` | Não | | | `data.responsible` | `DealMember` | Não | | | `data.responsible.userId` | `string` | Não | | | `data.responsible.name` | `string` | Não | Aceita null. | | `data.coOwner` | `object` | Não | Aceita null. | | `data.coOwner.userId` | `string` | Não | | | `data.coOwner.name` | `string` | Não | Aceita null. | | `data.activeChannels` | `array` | Não | | | `data.lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastMessageText` | `string` | Não | | | `data.replyPending` | `boolean` | Não | | | `data.properties` | `object` | Não | Valores resolvidos dos campos personalizados. | | `data.channel` | `object` | Não | Aceita null. | | `data.channelOverride` | `object` | Não | Aceita null. | | `data.expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stageChangedAt` | `string` | Não | Formato: date-time. | | `data.closedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.returnSignaledAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.contact` | `object` | Não | Aceita null. | | `data.stage` | `object` | Não | Aceita null. | | `data.company` | `object` | Não | Aceita null. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.tracking` | `object` | Não | Aceita null. | | `data.tracking.utmContent` | `string` | Não | Aceita null. | | `data.tracking.utmMedium` | `string` | Não | Aceita null. | | `data.tracking.utmCampaign` | `string` | Não | Aceita null. | | `data.tracking.utmSource` | `string` | Não | Aceita null. | | `data.tracking.utmTerm` | `string` | Não | Aceita null. | | `data.tracking.utmReferrer` | `string` | Não | Aceita null. | | `data.tracking.referrer` | `string` | Não | Aceita null. | | `data.tracking.gclientid` | `string` | Não | Aceita null. | | `data.tracking.gclid` | `string` | Não | Aceita null. | | `data.tracking.fbclid` | `string` | Não | Aceita null. | | `data.tracking.metaLeadId` | `string` | Não | Aceita null. | | `data.tracking.fbp` | `string` | Não | Aceita null. | | `data.tracking.fbc` | `string` | Não | Aceita null. | | `data.tracking.clientIpAddress` | `string` | Não | Aceita null. | | `data.tracking.clientUserAgent` | `string` | Não | Aceita null. | | `data.tracking.ctwaClid` | `string` | Não | Aceita null. | | `data.lostFromStage` | `object` | Não | Aceita null. | | `data.lostFromStage.id` | `string` | Não | | | `data.lostFromStage.name` | `string` | Não | | | `data.lostFromStage.pipelineId` | `string` | Não | | | `data.taskSummary` | `object` | Não | Resumo de tarefas quando habilitado na configuração do card. Aceita null. | | `data.taskSummary.pendingCount` | `integer` | Não | | | `data.taskSummary.overdueCount` | `integer` | Não | | | `data.taskSummary.nextTask` | `object` | Não | Aceita null. | | `data.taskSummary.nextTask.id` | `string` | Não | | | `data.taskSummary.nextTask.title` | `string` | Não | | | `data.taskSummary.nextTask.dueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.taskSummary.nextTask.categoryName` | `string` | Não | Aceita null. | | `data.taskSummary.nextTask.categoryColor` | `string` | Não | Aceita null. | | `data.lastActivity` | `object` | Não | Última atividade quando habilitada na configuração do card. Aceita null. | | `data.lastActivity.id` | `string` | Não | | | `data.lastActivity.type` | `string` | Não | | | `data.lastActivity.occurredAt` | `string` | Não | Formato: date-time. | | `data.lastActivity.title` | `string` | Não | | | `data.lastActivity.body` | `string` | Não | Aceita null. | | `data.lastActivity.meta` | `object` | Não | | | `data.lastActivity.actor` | `object` | Não | Aceita null. | | `data.lastActivity.actor.actorType` | `string` | Não | | | `data.lastActivity.actor.userId` | `string` | Não | Aceita null. | | `data.lastActivity.actor.userName` | `string` | Não | Aceita null. | | `data.lastActivity.actor.userAvatarUrl` | `string` | Não | Aceita null. | | `data.lastActivity.actor.automationId` | `string` | Não | Aceita null. | | `data.lastActivity.actor.automationName` | `string` | Não | Aceita null. | | `data.lastActivity.actor.copilotActionId` | `string` | Não | Aceita null. | | `data.lastActivity.actor.apiKeyId` | `string` | Não | Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealListItem" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/update-deal/ # Atualizar negócio `PATCH /api/v1/deals/{seq}` Atualiza parcialmente o negócio e pode movê-lo entre etapas. Mover para uma etapa de perda exige um `lostReason` válido; mover para uma etapa de ganho encerra o negócio. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do negócio dentro do workspace. | ## Corpo da requisição Content-Type: `application/json` ```json { "notes": "Contato pediu uma proposta revisada." } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Não | Aceita null. Até 255 caracteres. | | `value` | `number` | Não | Aceita null. Mínimo: 0. | | `currency` | `string` | Não | Aceita null. Até 3 caracteres. | | `closeProbability` | `integer` | Não | Aceita null. Mínimo: 0. Máximo: 100. | | `expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. | | `stageId` | `string` | Não | Aceita null. | | `companyId` | `string` | Não | Aceita null. | | `responsibleUserId` | `string` | Não | Aceita null. | | `coOwnerUserId` | `string` | Não | Aceita null. | | `lostReason` | `string` | Não | Obrigatório ao mover para uma etapa de perda. Aceita null. Até 255 caracteres. | | `notes` | `string` | Não | Aceita null. Até 2000 caracteres. | | `tagIds` | `array` | Não | Aceita null. | | `customFields` | `object` | Não | Aceita null. | | `contact` | `object` | Não | Campos opcionais do contato para atualizar junto com o negócio. Aceita null. | | `tracking` | `object` | Não | Aceita null. | | `tracking.utmContent` | `string` | Não | Aceita null. | | `tracking.utmMedium` | `string` | Não | Aceita null. | | `tracking.utmCampaign` | `string` | Não | Aceita null. | | `tracking.utmSource` | `string` | Não | Aceita null. | | `tracking.utmTerm` | `string` | Não | Aceita null. | | `tracking.utmReferrer` | `string` | Não | Aceita null. | | `tracking.referrer` | `string` | Não | Aceita null. | | `tracking.gclientid` | `string` | Não | Aceita null. | | `tracking.gclid` | `string` | Não | Aceita null. | | `tracking.fbclid` | `string` | Não | Aceita null. | | `tracking.metaLeadId` | `string` | Não | Aceita null. | | `tracking.fbp` | `string` | Não | Aceita null. | | `tracking.fbc` | `string` | Não | Aceita null. | | `tracking.clientIpAddress` | `string` | Não | Aceita null. | | `tracking.clientUserAgent` | `string` | Não | Aceita null. | | `tracking.ctwaClid` | `string` | Não | Aceita null. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealResponse` | Não | Negócio resumido retornado na criação ou atualização. | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.name` | `string` | Não | | | `data.contactId` | `string` | Não | Aceita null. | | `data.responsibleUserId` | `string` | Não | | | `data.companyId` | `string` | Não | Aceita null. | | `data.pipelineId` | `string` | Não | | | `data.stageId` | `string` | Não | | | `data.value` | `number` | Não | | | `data.currency` | `string` | Não | | | `data.closeProbability` | `integer` | Não | | | `data.source` | `string` | Não | | | `data.status` | `string` | Não | open \| won \| lost | | `data.coOwnerUserId` | `string` | Não | Aceita null. | | `data.expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stageChangedAt` | `string` | Não | Formato: date-time. | | `data.closedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lostReason` | `string` | Não | Aceita null. | | `data.customFields` | `object` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.tracking` | `object` | Não | Aceita null. | | `data.tracking.utmContent` | `string` | Não | Aceita null. | | `data.tracking.utmMedium` | `string` | Não | Aceita null. | | `data.tracking.utmCampaign` | `string` | Não | Aceita null. | | `data.tracking.utmSource` | `string` | Não | Aceita null. | | `data.tracking.utmTerm` | `string` | Não | Aceita null. | | `data.tracking.utmReferrer` | `string` | Não | Aceita null. | | `data.tracking.referrer` | `string` | Não | Aceita null. | | `data.tracking.gclientid` | `string` | Não | Aceita null. | | `data.tracking.gclid` | `string` | Não | Aceita null. | | `data.tracking.fbclid` | `string` | Não | Aceita null. | | `data.tracking.metaLeadId` | `string` | Não | Aceita null. | | `data.tracking.fbp` | `string` | Não | Aceita null. | | `data.tracking.fbc` | `string` | Não | Aceita null. | | `data.tracking.clientIpAddress` | `string` | Não | Aceita null. | | `data.tracking.clientUserAgent` | `string` | Não | Aceita null. | | `data.tracking.ctwaClid` | `string` | Não | Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealResponse" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/add-deal-tag/ # Adicionar etiqueta ao negócio `POST /api/v1/deals/{seq}/tags` Adiciona uma etiqueta ao negócio de forma idempotente e retorna a etiqueta. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Corpo da requisição Content-Type: `application/json` ```json { "tagId": "ID_DA_TAG" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `tagId` | `string` | Sim | | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Tag` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.color` | `string` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/remove-deal-tag/ # Remover etiqueta do negócio `DELETE /api/v1/deals/{seq}/tags/{tagId}` Remove uma etiqueta do negócio. Retorna `404` se ela não estiver associada. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | | `tagId` | path | Sim | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.tagId` | `string` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "tagId": { "type": "string" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/create-deal-note/ # Criar nota do negócio `POST /api/v1/deals/{seq}/notes` Cria uma nota com autoria do membro da chave e registra uma atividade `NOTE_CREATED`. Informe `content`, `attachments` ou ambos. Exige `deals.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Corpo da requisição Content-Type: `application/json` ```json { "content": "Cliente pediu retorno na próxima semana." } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `content` | `string` | Não | Aceita null. Até 10000 caracteres. | | `attachments` | `array` | Não | Comprovantes retornados por `POST /api/v1/deals/{seq}/notes/attachments`, enviados sem alterações. Aceita null. | | `attachments[].key` | `string` | Não | | | `attachments[].name` | `string` | Não | | | `attachments[].size` | `integer` | Não | Formato: int64. | | `attachments[].mimeType` | `string` | Não | | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.content` | `string` | Não | | | `data.authorMemberId` | `string` | Não | Aceita null. | | `data.authorName` | `string` | Não | Aceita null. | | `data.attachments` | `array` | Não | | | `data.attachments[].id` | `string` | Não | | | `data.attachments[].name` | `string` | Não | | | `data.attachments[].contentType` | `string` | Não | | | `data.attachments[].size` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "dealId": { "type": "string" }, "content": { "type": "string" }, "authorMemberId": { "type": "string", "nullable": true }, "authorName": { "type": "string", "nullable": true }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer", "format": "int64" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/upload-deal-note-attachment/ # Enviar anexo de nota do negócio `POST /api/v1/deals/{seq}/notes/attachments` Armazena um arquivo privado e retorna o comprovante para enviar em `attachments` na criação da nota. Exige `deals.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Corpo da requisição Content-Type: `multipart/form-data` ```json { "file": "" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `file` | `string` | Sim | Formato: binary. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `FileUploadReceipt` | Não | Comprovante do envio de arquivo; associe `key` ao valor de um campo `file_upload`. | | `data.key` | `string` | Não | | | `data.name` | `string` | Não | | | `data.size` | `integer` | Não | Formato: int64. | | `data.mimeType` | `string` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileUploadReceipt" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 413 Arquivo acima do limite da rota: 5 MB para foto de contato ou 16 MB para arquivo de campo personalizado. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 415 Arquivo vazio ou tipo de mídia não aceito pela rota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 503 O armazenamento recusou a operação ou excedeu o tempo de resposta. O arquivo não foi enviado; a operação pode ser repetida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/create-deal-task/ # Criar tarefa do negócio `POST /api/v1/deals/{seq}/tasks` Cria uma tarefa pendente vinculada ao negócio. Sem `assigneeUserId`, atribui a tarefa ao membro da chave; sem categoria, usa `outro`. Exige `tasks.create`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Corpo da requisição Content-Type: `application/json` ```json { "title": "Retornar proposta", "dueAt": "2026-10-06T14:00:00Z", "category": "follow_up" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `title` | `string` | Sim | Até 500 caracteres. | | `dueAt` | `string` | Sim | Instante ISO 8601, por exemplo, 2026-10-05T13:00:00Z. Formato: date-time. | | `assigneeUserId` | `string` | Não | Identificador de membro ativo (consulte /api/v1/users). Padrão: membro da chave. Aceita null. | | `categoryId` | `string` | Não | Identificador de categoria do workspace ou chave de sistema. Tem prioridade sobre category. Aceita null. | | `category` | `string` | Não | Chave de categoria do sistema. Padrão: outro. Valores: ligacao, reuniao, follow_up, email, outro. Aceita null. | | `description` | `string` | Não | Aceita null. Até 2000 caracteres. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | Aceita null. | | `data.assignee` | `TaskUser` | Não | | | `data.assignee.userId` | `string` | Não | | | `data.assignee.name` | `string` | Não | Aceita null. | | `data.assignee.email` | `string` | Não | Aceita null. | | `data.assignee.role` | `string` | Não | Aceita null. | | `data.creator` | `TaskUser` | Não | | | `data.creator.userId` | `string` | Não | | | `data.creator.name` | `string` | Não | Aceita null. | | `data.creator.email` | `string` | Não | Aceita null. | | `data.creator.role` | `string` | Não | Aceita null. | | `data.category` | `string` | Não | Chave legada; use categoryId/categoryName. | | `data.categoryId` | `string` | Não | | | `data.categoryName` | `string` | Não | | | `data.categoryColor` | `string` | Não | | | `data.title` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.status` | `string` | Não | Valores: pending, done. | | `data.dueAt` | `string` | Não | Formato: date-time. | | `data.doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "dealId": { "type": "string", "nullable": true }, "assignee": { "$ref": "#/components/schemas/TaskUser" }, "creator": { "$ref": "#/components/schemas/TaskUser" }, "category": { "type": "string", "description": "Chave legada; use categoryId/categoryName." }, "categoryId": { "type": "string" }, "categoryName": { "type": "string" }, "categoryColor": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "done" ] }, "dueAt": { "type": "string", "format": "date-time" }, "doneAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/list-deal-activities/ # Listar atividades do negócio `GET /api/v1/deals/{seq}/activities` Histórico de atividades paginado por cursor, dos registros mais recentes aos mais antigos. Valores desconhecidos nos filtros são ignorados. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | | `type` | query | Não | `array` | Filtro de tipo de atividade; pode ser repetido. | | `actorType` | query | Não | `array` | Filtro de tipo de autor; pode ser repetido. | | `actorUserId` | query | Não | `string` | — | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].dealId` | `string` | Não | | | `data.items[].type` | `string` | Não | | | `data.items[].field` | `string` | Não | Aceita null. | | `data.items[].changes` | `object` | Não | Aceita null. | | `data.items[].metadata` | `object` | Não | Aceita null. | | `data.items[].occurredAt` | `string` | Não | Formato: date-time. | | `data.items[].actor` | `object` | Não | Resumo do autor: usuário ou sistema. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DealActivity" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-contacts/ # Listar contatos `GET /api/v1/contacts` Lista de contatos visíveis ao membro da chave, paginada por cursor. Exige `contacts.view`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | — | | `search` | query | Não | `string` | — | | `blocked` | query | Não | `boolean` | — | | `internal` | query | Não | `boolean` | — | | `hasEmail` | query | Não | `boolean` | — | | `hasConversation` | query | Não | `boolean` | — | | `hasDeal` | query | Não | `boolean` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].seq` | `integer` | Não | | | `data.items[].phone` | `string` | Não | | | `data.items[].name` | `string` | Não | Aceita null. | | `data.items[].customName` | `string` | Não | Nome completo editável, calculado a partir de firstName + lastName. Aceita null. | | `data.items[].firstName` | `string` | Não | Aceita null. | | `data.items[].lastName` | `string` | Não | Aceita null. | | `data.items[].displayName` | `string` | Não | | | `data.items[].avatarUrl` | `string` | Não | Aceita null. | | `data.items[].email` | `string` | Não | Aceita null. | | `data.items[].blocked` | `boolean` | Não | | | `data.items[].isInternal` | `boolean` | Não | | | `data.items[].lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].lastActivityAt` | `string` | Não | Formato: date-time. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.items[].updatedAt` | `string` | Não | Formato: date-time. | | `data.items[].instagramUsername` | `string` | Não | Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/create-contact/ # Criar contato `POST /api/v1/contacts` Cria um contato no workspace da chave. O telefone identifica o contato e é obrigatório. Exige `contacts.create`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "firstName": "Ana", "lastName": "Silva", "phone": "5511999999999", "email": "ana@example.com" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `phone` | `string` | Sim | Identidade do contato. Obrigatória na criação. Até 30 caracteres. | | `customName` | `string` | Não | Aceito por compatibilidade. Dividido no primeiro espaço em firstName/lastName. Ignorado quando firstName ou lastName é enviado. Aceita null. Até 255 caracteres. | | `firstName` | `string` | Não | Aceita null. Até 255 caracteres. | | `lastName` | `string` | Não | Aceita null. Até 255 caracteres. | | `email` | `string` | Não | Formato: email. Aceita null. Até 255 caracteres. | | `instagramUsername` | `string` | Não | Nome de usuário sem o @ inicial; o valor enviado é normalizado. Aceita null. | | `notes` | `string` | Não | Aceita null. Até 2000 caracteres. | | `isInternal` | `boolean` | Não | Aceita null. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Contact` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.phone` | `string` | Não | | | `data.name` | `string` | Não | Aceita null. | | `data.customName` | `string` | Não | Nome completo editável, calculado a partir de firstName + lastName. Aceita null. | | `data.firstName` | `string` | Não | Aceita null. | | `data.lastName` | `string` | Não | Aceita null. | | `data.displayName` | `string` | Não | | | `data.avatarUrl` | `string` | Não | Aceita null. | | `data.email` | `string` | Não | Aceita null. | | `data.blocked` | `boolean` | Não | | | `data.isInternal` | `boolean` | Não | | | `data.lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastActivityAt` | `string` | Não | Formato: date-time. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.instagramUsername` | `string` | Não | Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-contact/ # Consultar contato `GET /api/v1/contacts/{id}` Retorna os detalhes do contato. Fora da visibilidade do membro, responde `404`. Exige `contacts.view`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do contato. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `ContactDetail` | Não | Item da listagem acrescido dos campos de detalhe: notas, recusa de mensagens e último envio de marketing. | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.phone` | `string` | Não | | | `data.name` | `string` | Não | Aceita null. | | `data.customName` | `string` | Não | Nome completo editável, calculado a partir de firstName + lastName. Aceita null. | | `data.firstName` | `string` | Não | Aceita null. | | `data.lastName` | `string` | Não | Aceita null. | | `data.displayName` | `string` | Não | | | `data.avatarUrl` | `string` | Não | Aceita null. | | `data.email` | `string` | Não | Aceita null. | | `data.instagramUsername` | `string` | Não | Aceita null. | | `data.blocked` | `boolean` | Não | | | `data.isInternal` | `boolean` | Não | | | `data.notes` | `string` | Não | Aceita null. | | `data.optedOutAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.optedOutKeyword` | `string` | Não | Aceita null. | | `data.optedOutSource` | `string` | Não | Aceita null. | | `data.lastMarketingAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastActivityAt` | `string` | Não | Formato: date-time. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactDetail" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-contact/ # Atualizar contato `PATCH /api/v1/contacts/{id}` Atualiza parcialmente um contato. Campos omitidos permanecem iguais; texto vazio limpa o valor. Exige `contacts.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do contato. | ## Corpo da requisição Content-Type: `application/json` ```json { "firstName": "Ana", "lastName": "Silva" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `phone` | `string` | Não | Aceita null. Até 30 caracteres. | | `customName` | `string` | Não | Aceito por compatibilidade. Dividido no primeiro espaço em firstName/lastName. Ignorado quando firstName ou lastName é enviado. Aceita null. Até 255 caracteres. | | `firstName` | `string` | Não | Aceita null. Até 255 caracteres. | | `lastName` | `string` | Não | Aceita null. Até 255 caracteres. | | `email` | `string` | Não | Formato: email. Aceita null. Até 255 caracteres. | | `instagramUsername` | `string` | Não | Aceita null. | | `blocked` | `boolean` | Não | Aceita null. | | `notes` | `string` | Não | Aceita null. Até 2000 caracteres. | | `isInternal` | `boolean` | Não | Aceita null. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Contact` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.phone` | `string` | Não | | | `data.name` | `string` | Não | Aceita null. | | `data.customName` | `string` | Não | Nome completo editável, calculado a partir de firstName + lastName. Aceita null. | | `data.firstName` | `string` | Não | Aceita null. | | `data.lastName` | `string` | Não | Aceita null. | | `data.displayName` | `string` | Não | | | `data.avatarUrl` | `string` | Não | Aceita null. | | `data.email` | `string` | Não | Aceita null. | | `data.blocked` | `boolean` | Não | | | `data.isInternal` | `boolean` | Não | | | `data.lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastActivityAt` | `string` | Não | Formato: date-time. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.instagramUsername` | `string` | Não | Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/delete-contact/ # Excluir contato `DELETE /api/v1/contacts/{id}` Anonimiza e exclui logicamente o contato, desvincula suas conversas e interrompe suas cadências. Preserva o histórico dos negócios. Exige `contacts.delete`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do contato. | ## Respostas ### 204 Sem conteúdo ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/upload-contact-avatar/ # Enviar foto do contato `POST /api/v1/contacts/{id}/avatar` Salva o arquivo multipart como foto do contato e retorna o contato atualizado. Exige `contacts.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do contato. | ## Corpo da requisição Content-Type: `multipart/form-data` ```json { "file": "" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `file` | `string` | Sim | JPEG, PNG ou WebP, até 5 MB. Formato: binary. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `ContactDetail` | Não | Item da listagem acrescido dos campos de detalhe: notas, recusa de mensagens e último envio de marketing. | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.phone` | `string` | Não | | | `data.name` | `string` | Não | Aceita null. | | `data.customName` | `string` | Não | Nome completo editável, calculado a partir de firstName + lastName. Aceita null. | | `data.firstName` | `string` | Não | Aceita null. | | `data.lastName` | `string` | Não | Aceita null. | | `data.displayName` | `string` | Não | | | `data.avatarUrl` | `string` | Não | Aceita null. | | `data.email` | `string` | Não | Aceita null. | | `data.instagramUsername` | `string` | Não | Aceita null. | | `data.blocked` | `boolean` | Não | | | `data.isInternal` | `boolean` | Não | | | `data.notes` | `string` | Não | Aceita null. | | `data.optedOutAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.optedOutKeyword` | `string` | Não | Aceita null. | | `data.optedOutSource` | `string` | Não | Aceita null. | | `data.lastMarketingAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastActivityAt` | `string` | Não | Formato: date-time. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactDetail" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 413 Arquivo acima do limite da rota: 5 MB para foto de contato ou 16 MB para arquivo de campo personalizado. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 415 Arquivo vazio ou tipo de mídia não aceito pela rota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 503 O armazenamento recusou a operação ou excedeu o tempo de resposta. O arquivo não foi enviado; a operação pode ser repetida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/remove-contact-avatar/ # Remover foto do contato `DELETE /api/v1/contacts/{id}/avatar` Remove a foto e retorna o contato atualizado. Operação idempotente. Exige `contacts.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do contato. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `ContactDetail` | Não | Item da listagem acrescido dos campos de detalhe: notas, recusa de mensagens e último envio de marketing. | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.phone` | `string` | Não | | | `data.name` | `string` | Não | Aceita null. | | `data.customName` | `string` | Não | Nome completo editável, calculado a partir de firstName + lastName. Aceita null. | | `data.firstName` | `string` | Não | Aceita null. | | `data.lastName` | `string` | Não | Aceita null. | | `data.displayName` | `string` | Não | | | `data.avatarUrl` | `string` | Não | Aceita null. | | `data.email` | `string` | Não | Aceita null. | | `data.instagramUsername` | `string` | Não | Aceita null. | | `data.blocked` | `boolean` | Não | | | `data.isInternal` | `boolean` | Não | | | `data.notes` | `string` | Não | Aceita null. | | `data.optedOutAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.optedOutKeyword` | `string` | Não | Aceita null. | | `data.optedOutSource` | `string` | Não | Aceita null. | | `data.lastMarketingAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.lastActivityAt` | `string` | Não | Formato: date-time. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactDetail" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-companies/ # Listar empresas `GET /api/v1/companies` Lista paginada de empresas do workspace. Exige `companies.view`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `query` | query | Não | `string` | — | | `page` | query | Não | `integer` | — | | `size` | query | Não | `integer` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.content` | `array` | Não | | | `data.content[].id` | `string` | Não | | | `data.content[].seq` | `integer` | Não | | | `data.content[].name` | `string` | Não | | | `data.content[].domain` | `string` | Não | Aceita null. | | `data.content[].cnpj` | `string` | Não | Aceita null. | | `data.content[].industry` | `string` | Não | Aceita null. | | `data.content[].website` | `string` | Não | Aceita null. | | `data.content[].logoUrl` | `string` | Não | Aceita null. | | `data.content[].notes` | `string` | Não | Aceita null. | | `data.content[].dealCount` | `integer` | Não | | | `data.content[].createdAt` | `string` | Não | Formato: date-time. | | `data.content[].updatedAt` | `string` | Não | Formato: date-time. | | `data.totalElements` | `integer` | Não | | | `data.totalPages` | `integer` | Não | | | `data.number` | `integer` | Não | | | `data.size` | `integer` | Não | | | `data.first` | `boolean` | Não | | | `data.last` | `boolean` | Não | | | `data.numberOfElements` | `integer` | Não | | | `data.empty` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "description": "Formato de página Spring Data.", "properties": { "data": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "number": { "type": "integer" }, "size": { "type": "integer" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "numberOfElements": { "type": "integer" }, "empty": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/create-company/ # Criar empresa `POST /api/v1/companies` Cria uma empresa no workspace da chave e retorna o registro com um novo número sequencial. Exige `companies.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Empresa Exemplo" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 255 caracteres. | | `domain` | `string` | Não | Aceita null. Até 255 caracteres. | | `cnpj` | `string` | Não | Aceita null. Até 30 caracteres. | | `industry` | `string` | Não | Aceita null. Até 255 caracteres. | | `website` | `string` | Não | Aceita null. Até 500 caracteres. | | `logoUrl` | `string` | Não | Aceita null. Até 500 caracteres. | | `notes` | `string` | Não | Aceita null. Até 2000 caracteres. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Company` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.name` | `string` | Não | | | `data.domain` | `string` | Não | Aceita null. | | `data.cnpj` | `string` | Não | Aceita null. | | `data.industry` | `string` | Não | Aceita null. | | `data.website` | `string` | Não | Aceita null. | | `data.logoUrl` | `string` | Não | Aceita null. | | `data.notes` | `string` | Não | Aceita null. | | `data.dealCount` | `integer` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-company/ # Consultar empresa `GET /api/v1/companies/{seq}` Retorna uma empresa pelo número sequencial no workspace, incluindo a quantidade de negócios. Exige `companies.view`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial da empresa dentro do workspace. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Company` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.name` | `string` | Não | | | `data.domain` | `string` | Não | Aceita null. | | `data.cnpj` | `string` | Não | Aceita null. | | `data.industry` | `string` | Não | Aceita null. | | `data.website` | `string` | Não | Aceita null. | | `data.logoUrl` | `string` | Não | Aceita null. | | `data.notes` | `string` | Não | Aceita null. | | `data.dealCount` | `integer` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-company/ # Atualizar empresa `PATCH /api/v1/companies/{seq}` Atualiza parcialmente uma empresa; campos omitidos permanecem iguais. Exige `companies.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial da empresa dentro do workspace. | ## Corpo da requisição Content-Type: `application/json` ```json { "industry": "Consultoria" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Não | Aceita null. Até 255 caracteres. | | `domain` | `string` | Não | Aceita null. Até 255 caracteres. | | `cnpj` | `string` | Não | Aceita null. Até 30 caracteres. | | `industry` | `string` | Não | Aceita null. Até 255 caracteres. | | `website` | `string` | Não | Aceita null. Até 500 caracteres. | | `logoUrl` | `string` | Não | Aceita null. Até 500 caracteres. | | `notes` | `string` | Não | Aceita null. Até 2000 caracteres. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Company` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | | | `data.name` | `string` | Não | | | `data.domain` | `string` | Não | Aceita null. | | `data.cnpj` | `string` | Não | Aceita null. | | `data.industry` | `string` | Não | Aceita null. | | `data.website` | `string` | Não | Aceita null. | | `data.logoUrl` | `string` | Não | Aceita null. | | `data.notes` | `string` | Não | Aceita null. | | `data.dealCount` | `integer` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/delete-company/ # Excluir empresa `DELETE /api/v1/companies/{seq}` Exclui a empresa e remove sua associação dos negócios vinculados. Exige `companies.delete`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial da empresa dentro do workspace. | ## Respostas ### 204 Sem conteúdo ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-pipelines/ # Listar funis `GET /api/v1/pipelines` Funis ativos do workspace. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].id` | `string` | Não | | | `data[].seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data[].position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data[].name` | `string` | Não | | | `data[].description` | `string` | Não | Aceita null. | | `data[].isDefault` | `boolean` | Não | | | `data[].isArchived` | `boolean` | Não | | | `data[].exitStageId` | `string` | Não | Aceita null. | | `data[].pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data[].behaviors` | `array` | Não | | | `data[].attendanceQueueStageId` | `string` | Não | Aceita null. | | `data[].stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data[].stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data[].stages[].seq` | `integer` | Não | | | `data[].stages[].order` | `integer` | Não | | | `data[].stages[].name` | `string` | Não | | | `data[].stages[].color` | `string` | Não | | | `data[].stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data[].stages[].isWon` | `boolean` | Não | | | `data[].stages[].isLost` | `boolean` | Não | | | `data[].stages[].isRequired` | `boolean` | Não | | | `data[].stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data[].stages[].dealCount` | `integer` | Não | Formato: int64. | | `data[].createdAt` | `string` | Não | Formato: date-time. | | `data[].updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/create-pipeline/ # Criar funil `POST /api/v1/pipelines` Cria um funil no workspace da chave e retorna suas etapas. Exige `settings.pipelines`. `stages` define as etapas **ativas**, em ordem. Quando omitido ou vazio, cria `Leads`, `Qualificação`, `Proposta`, `Negociação` e `Fechamento`. O sistema acrescenta as etapas finais `Ganho` e `Perda`. Não envie etapas finais nem `isWon`/`isLost`: a API responde `400`. O primeiro funil ativo torna-se o padrão do workspace. O limite de funis do plano se aplica; quando atingido, a API responde `409 QUOTA_EXCEEDED`. Qualquer `behaviors` exige `PIPELINE_BEHAVIORS`, ou a resposta será `400`. Para usar `attendance_queue`, crie o funil primeiro. Depois configure `behaviors` e `attendanceQueueStageId` em `PATCH /api/v1/pipelines/{seq}`, usando uma etapa do próprio funil. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Pós-venda", "description": "Clientes que já compraram", "stages": [ { "name": "Onboarding", "color": "#3b82f6" }, { "name": "Acompanhamento" } ] } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 255 caracteres. | | `description` | `string` | Não | Opcional. Objetivo do funil; usado como contexto pela CIA. Aceita null. Até 2000 caracteres. | | `stages` | `array` | Não | Etapas ativas em ordem. Omitir ou enviar lista vazia cria as etapas padrão. O sistema acrescenta as etapas de ganho e perda. Aceita null. | | `stages[].name` | `string` | Sim | Até 255 caracteres. | | `stages[].color` | `string` | Não | Cor hexadecimal. Padrão: `#6366f1`. | | `stages[].description` | `string` | Não | Opcional. Condição esperada para o negócio estar nesta etapa; usada como contexto pela CIA. Aceita null. Até 2000 caracteres. | | `behaviors` | `array` | Não | Não configure `attendance_queue` na criação: exige uma etapa do próprio funil. Configure por `PATCH` depois de criar. Aceita null. | | `pipelineType` | `string` | Não | Entrada legada, ignorada. Configure behaviors para definir o comportamento do funil. Valores: standard, recurring_clients. Aceita null. | | `attendanceQueueStageId` | `string` | Não | A fila exige uma etapa já existente neste funil. Configure após a criação, com PATCH e behaviors. Aceita null. | ## Respostas ### 201 Criado: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-archived-pipelines/ # Listar funis arquivados `GET /api/v1/pipelines/archived` Funis arquivados do workspace, ordenados pela atualização mais recente. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].id` | `string` | Não | | | `data[].seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data[].position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data[].name` | `string` | Não | | | `data[].description` | `string` | Não | Aceita null. | | `data[].isDefault` | `boolean` | Não | | | `data[].isArchived` | `boolean` | Não | | | `data[].exitStageId` | `string` | Não | Aceita null. | | `data[].pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data[].behaviors` | `array` | Não | | | `data[].attendanceQueueStageId` | `string` | Não | Aceita null. | | `data[].stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data[].stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data[].stages[].seq` | `integer` | Não | | | `data[].stages[].order` | `integer` | Não | | | `data[].stages[].name` | `string` | Não | | | `data[].stages[].color` | `string` | Não | | | `data[].stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data[].stages[].isWon` | `boolean` | Não | | | `data[].stages[].isLost` | `boolean` | Não | | | `data[].stages[].isRequired` | `boolean` | Não | | | `data[].stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data[].stages[].dealCount` | `integer` | Não | Formato: int64. | | `data[].createdAt` | `string` | Não | Formato: date-time. | | `data[].updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/replace-loss-reasons/ # Substituir motivos de perda `PUT /api/v1/pipelines/loss-reasons` Substitui o catálogo de motivos de perda do workspace. Aceita até 50 motivos, não vazios e com até 255 caracteres cada. Retorna a lista normalizada e salva. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "lossReasons": [ "Sem orçamento", "Sem aderência" ] } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `lossReasons` | `array` | Sim | | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-pipeline/ # Consultar funil `GET /api/v1/pipelines/{seq}` Retorna um funil ativo ou arquivado pelo número sequencial no workspace. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Respostas ### 200 Sucesso: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-pipeline/ # Atualizar funil `PATCH /api/v1/pipelines/{seq}` Atualiza parcialmente o funil: campos ausentes permanecem iguais. `exitStageId` deve identificar uma etapa não final do próprio funil; caso contrário, responde `409`. `behaviors` substitui todo o conjunto e exige `PIPELINE_BEHAVIORS`. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Corpo da requisição Content-Type: `application/json` ```json { "description": "Funil de novas oportunidades." } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Não | Até 255 caracteres. | | `description` | `string` | Não | Omitir ou enviar `null` preserva a descrição; texto em branco a remove. Aceita null. Até 2000 caracteres. | | `isDefault` | `boolean` | Não | `true` define este funil como padrão do workspace. | | `exitStageId` | `string` | Não | Etapa não final deste funil. | | `behaviors` | `array` | Não | Substitui todo o conjunto. | | `attendanceQueueStageId` | `string` | Não | Etapa não final do próprio funil. Adiciona `attendance_queue` a `behaviors`. Um valor em branco limpa a configuração e remove o comportamento. | | `pipelineType` | `string` | Não | Entrada legada, ignorada. Configure behaviors para definir o comportamento do funil. Valores: standard, recurring_clients. Aceita null. | ## Respostas ### 200 Sucesso: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/archive-pipeline/ # Arquivar funil `DELETE /api/v1/pipelines/{seq}` Arquiva o funil. Responde `409` se ainda houver negócios abertos ou se for o único funil ativo. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Respostas ### 204 Sem conteúdo ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/unarchive-pipeline/ # Restaurar funil `POST /api/v1/pipelines/{seq}/unarchive` Restaura um funil arquivado e retorna o registro. Em um funil ativo, não altera o estado. O limite do plano se aplica: `409 QUOTA_EXCEEDED` quando atingido. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Respostas ### 200 Sucesso: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-pipeline-access/ # Listar regras de acesso ao funil `GET /api/v1/pipelines/{seq}/access` Membros com acesso explícito ao funil. Lista vazia significa acesso para todos. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Respostas ### 200 Sucesso: membros com acesso explícito; lista vazia permite acesso para todos. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].userId` | `string` | Não | | | `data[].name` | `string` | Não | | | `data[].email` | `string` | Não | | | `data[].image` | `string` | Não | URL da foto. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": "string", "nullable": true, "description": "URL da foto." } } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/replace-pipeline-access/ # Substituir regras de acesso ao funil `PUT /api/v1/pipelines/{seq}/access` Substitui toda a lista de usuários com acesso ao funil e retorna os membros salvos. Uma lista vazia remove a restrição. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Corpo da requisição Content-Type: `application/json` ```json { "userIds": [ "ID_DO_USUARIO" ] } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `userIds` | `array` | Sim | Identificadores de usuários retornados por `GET /api/v1/users`. | ## Respostas ### 200 Sucesso: membros com acesso explícito; lista vazia permite acesso para todos. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].userId` | `string` | Não | | | `data[].name` | `string` | Não | | | `data[].email` | `string` | Não | | | `data[].image` | `string` | Não | URL da foto. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": "string", "nullable": true, "description": "URL da foto." } } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/create-pipeline-stage/ # Criar etapa do funil `POST /api/v1/pipelines/{seq}/stages` Acrescenta uma etapa ativa antes das etapas finais de ganho e perda e retorna o funil atualizado. `isWon`/`isLost` são definidos pelo sistema: enviá-los resulta em `400`. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Proposta", "color": "#2563eb" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 255 caracteres. | | `color` | `string` | Não | Cor hexadecimal. Padrão: `#6366f1`. | | `description` | `string` | Não | Opcional. Condição esperada para o negócio estar nesta etapa; usada como contexto pela CIA. Aceita null. Até 2000 caracteres. | ## Respostas ### 201 Criado: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/reorder-pipeline-stages/ # Reordenar etapas do funil `PATCH /api/v1/pipelines/{seq}/stages/reorder` Substitui a ordem das etapas ativas. `orderedStageIds` deve conter exatamente os identificadores das etapas ativas atuais; caso contrário, responde `409`. As etapas finais permanecem no fim. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Corpo da requisição Content-Type: `application/json` ```json { "orderedStageIds": [ "ID_DA_ETAPA_1", "ID_DA_ETAPA_2" ] } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `orderedStageIds` | `array` | Sim | | ## Respostas ### 200 Sucesso: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-pipeline-stage/ # Atualizar etapa do funil `PATCH /api/v1/pipelines/{seq}/stages/{stageId}` Altera o nome, a cor ou a descrição de uma etapa e retorna o funil atualizado. Etapas finais não podem ser alteradas: a API responde `409`. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | | `stageId` | path | Sim | `string` | Identificador da etapa (`stages[].id` do funil). | ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Proposta revisada" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Não | Até 255 caracteres. | | `color` | `string` | Não | | | `description` | `string` | Não | Omitir mantém a descrição; um valor em branco a remove. Até 2000 caracteres. | ## Respostas ### 200 Sucesso: funil com todas as etapas. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Pipeline` | Não | | | `data.id` | `string` | Não | | | `data.seq` | `integer` | Não | Número sequencial no workspace usado em `/api/v1/pipelines/{seq}`. | | `data.position` | `integer` | Não | Ordem de exibição entre os funis ativos. | | `data.name` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.isDefault` | `boolean` | Não | | | `data.isArchived` | `boolean` | Não | | | `data.exitStageId` | `string` | Não | Aceita null. | | `data.pipelineType` | `string` | Não | Derivado de `behaviors`; mantido por compatibilidade. Valores: standard, recurring_clients. | | `data.behaviors` | `array` | Não | | | `data.attendanceQueueStageId` | `string` | Não | Aceita null. | | `data.stages` | `array` | Não | Etapas em ordem: ativas primeiro, seguidas das etapas finais de ganho e perda. | | `data.stages[].id` | `string` | Não | Identificador da etapa usado em `stageId` na API, por exemplo, em `POST /api/v1/deals`. | | `data.stages[].seq` | `integer` | Não | | | `data.stages[].order` | `integer` | Não | | | `data.stages[].name` | `string` | Não | | | `data.stages[].color` | `string` | Não | | | `data.stages[].description` | `string` | Não | Condição esperada para o negócio estar nesta etapa. Usada como contexto pela CIA. Aceita null. | | `data.stages[].isWon` | `boolean` | Não | | | `data.stages[].isLost` | `boolean` | Não | | | `data.stages[].isRequired` | `boolean` | Não | | | `data.stages[].requiredMilestoneFieldId` | `string` | Não | Aceita null. | | `data.stages[].dealCount` | `integer` | Não | Formato: int64. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/delete-pipeline-stage/ # Excluir etapa do funil `DELETE /api/v1/pipelines/{seq}/stages/{stageId}` Exclui uma etapa ativa sem uso. Responde `409` para uma etapa final, com negócios vinculados ou definida como saída/fila de atendimento do funil. Remova primeiro essa configuração, quando aplicável. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | | `stageId` | path | Sim | `string` | Identificador da etapa (`stages[].id` do funil). | ## Respostas ### 204 Sem conteúdo ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-pipeline-fields/ # Listar configuração de campos do funil `GET /api/v1/pipelines/{seq}/fields` Retorna como cada campo de negócio se comporta no funil, conforme a aba Campos do aplicativo. Os campos padrão (`value`, `name`, `email`, `phone`, `expectedCloseAt`) vêm primeiro; depois, os campos personalizados de negócio em ordem de exibição, inclusive os ocultos neste funil. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | ## Respostas ### 200 Sucesso: campos padrão primeiro, seguidos dos campos personalizados de negócio em ordem de exibição. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].field` | `string` | Não | ID do campo personalizado ou chave do campo padrão. | | `data[].kind` | `string` | Não | Valores: standard, custom. | | `data[].name` | `string` | Não | | | `data[].slug` | `string` | Não | Chave do valor em `customFields` do negócio; `null` para campo padrão. Aceita null. | | `data[].isVisible` | `boolean` | Não | Indica se o campo aparece no funil. `null` para campo padrão. Aceita null. | | `data[].isRequired` | `boolean` | Não | Sinaliza obrigatoriedade nos formulários do aplicativo, sem validação do servidor por si só. `null` para campo padrão. Aceita null. | | `data[].requiredStageIds` | `array` | Não | Etapas a partir das quais o campo é obrigatório no servidor. Lista vazia quando não há exigência. | | `data[].visibilityOverrideStageIds` | `array` | Não | Etapas que invertem `isVisible`. `null` para campo padrão. Aceita null. | | `data[].isSuggested` | `boolean` | Não | Sinaliza sugestão nos formulários do aplicativo em toda movimentação, com opção de pular. Sem exigência no servidor. Sempre `true` quando `isRequired` é verdadeiro. `null` para campo padrão. Aceita null. | | `data[].suggestedStageIds` | `array` | Não | Etapas onde o aplicativo sugere o preenchimento, com opção de pular e sem propagação. Não repete etapas de `requiredStageIds`. Lista vazia quando não há sugestão. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineFieldSettings" } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-pipeline-field/ # Consultar configuração de campo do funil `GET /api/v1/pipelines/{seq}/fields/{field}` Retorna a configuração de um campo neste funil. Campo desconhecido resulta em `404`. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | | `field` | path | Sim | `string` | Identificador de campo personalizado de negócio (`GET /api/v1/custom-fields?entity=deal`) ou uma chave padrão: `value`, `name`, `email`, `phone`, `expectedCloseAt`. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `PipelineFieldSettings` | Não | Configuração de um campo de negócio neste funil. Os identificadores seguem a ordem das etapas do funil. | | `data.field` | `string` | Não | ID do campo personalizado ou chave do campo padrão. | | `data.kind` | `string` | Não | Valores: standard, custom. | | `data.name` | `string` | Não | | | `data.slug` | `string` | Não | Chave do valor em `customFields` do negócio; `null` para campo padrão. Aceita null. | | `data.isVisible` | `boolean` | Não | Indica se o campo aparece no funil. `null` para campo padrão. Aceita null. | | `data.isRequired` | `boolean` | Não | Sinaliza obrigatoriedade nos formulários do aplicativo, sem validação do servidor por si só. `null` para campo padrão. Aceita null. | | `data.requiredStageIds` | `array` | Não | Etapas a partir das quais o campo é obrigatório no servidor. Lista vazia quando não há exigência. | | `data.visibilityOverrideStageIds` | `array` | Não | Etapas que invertem `isVisible`. `null` para campo padrão. Aceita null. | | `data.isSuggested` | `boolean` | Não | Sinaliza sugestão nos formulários do aplicativo em toda movimentação, com opção de pular. Sem exigência no servidor. Sempre `true` quando `isRequired` é verdadeiro. `null` para campo padrão. Aceita null. | | `data.suggestedStageIds` | `array` | Não | Etapas onde o aplicativo sugere o preenchimento, com opção de pular e sem propagação. Não repete etapas de `requiredStageIds`. Lista vazia quando não há sugestão. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PipelineFieldSettings" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-pipeline-field/ # Atualizar configuração de campo do funil `PATCH /api/v1/pipelines/{seq}/fields/{field}` Adiciona, oculta ou configura a obrigatoriedade de um campo no funil e retorna o resultado. Todas as propriedades são opcionais; omitir preserva o valor atual. As listas de etapas substituem as regras **somente deste funil**. As regras de outros funis permanecem iguais. Todo identificador de etapa deve pertencer a este funil, ou a API responde `400`. - `isVisible: true` inclui o campo no funil; `false` o oculta. Campos personalizados existentes começam ocultos em um novo funil. Um novo campo também começa oculto nos funis existentes. - `requiredStageIds` define a obrigatoriedade validada pelo servidor. Criar ou mover um negócio para uma dessas etapas, ou uma etapa posterior, exige o preenchimento. Caso contrário, responde `422 UNPROCESSABLE_ENTITY`, com os campos ausentes em `fieldErrors`, tanto pelo aplicativo quanto pela API. Uma regra na etapa de perda vale somente nela. Movimentações por automação são isentas. - `isRequired` marca o campo como obrigatório no funil para os formulários do aplicativo. Sozinho, não impõe uma validação no servidor: use `requiredStageIds` para exigir o preenchimento também por API. `isRequired: true` e uma lista `requiredStageIds` não vazia são incompatíveis e resultam em `400`. Alterar `isRequired` sem enviar a lista limpa as etapas obrigatórias. - `visibilityOverrideStageIds` define as etapas que invertem `isVisible`. Alterar `isVisible` sem enviar essa lista limpa as exceções. - `isSuggested` e `suggestedStageIds` representam o nível sugerido. O aplicativo solicita o preenchimento ao mover o negócio para a etapa, mas permite pular. O servidor não o exige e a sugestão não se propaga às etapas posteriores. Obrigatório implica sugerido e visível: ativar `isRequired` também ativa `isSuggested` e `isVisible`. Uma etapa nas duas listas permanece apenas em `requiredStageIds`. Desativar `isRequired` sem enviar `isSuggested` desativa também a sugestão. Ocultar um campo que permanece sugerido ou obrigatório resulta em `400`; envie também `isSuggested: false` e `isRequired: false`. `isSuggested: true` e uma lista `suggestedStageIds` não vazia também são incompatíveis. Alterar `isSuggested` sem enviar a lista limpa as etapas sugeridas. Campos padrão aceitam somente `requiredStageIds` e `suggestedStageIds`; outras propriedades resultam em `400`. Exige `settings.pipelines`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do funil no workspace (`seq`). | | `field` | path | Sim | `string` | Identificador de campo personalizado de negócio (`GET /api/v1/custom-fields?entity=deal`) ou uma chave padrão: `value`, `name`, `email`, `phone`, `expectedCloseAt`. | ## Corpo da requisição Content-Type: `application/json` ```json { "isVisible": true, "requiredStageIds": [ "stage-id-of-proposal" ] } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `isVisible` | `boolean` | Não | Somente campos personalizados. | | `isRequired` | `boolean` | Não | Somente campos personalizados. Não impõe exigência no servidor; consulte `requiredStageIds`. Incompatível com uma lista `requiredStageIds` não vazia; alterar limpa a lista, a menos que ela seja enviada. | | `requiredStageIds` | `array` | Não | Substitui as etapas deste funil que exigem o campo. `[]` limpa a lista. | | `visibilityOverrideStageIds` | `array` | Não | Somente campos personalizados. Substitui as etapas que invertem `isVisible` neste funil. | | `isSuggested` | `boolean` | Não | Somente campos personalizados. Sem exigência no servidor. Incompatível com uma lista suggestedStageIds não vazia. Alterar limpa a lista, salvo quando enviada. É verdadeiro enquanto isRequired for verdadeiro; desligar isRequired desliga a sugestão, a menos que isSuggested seja enviado. | | `suggestedStageIds` | `array` | Não | Substitui as etapas deste funil que sugerem o preenchimento. `[]` limpa a lista. Etapas também presentes em requiredStageIds permanecem apenas como obrigatórias. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `PipelineFieldSettings` | Não | Configuração de um campo de negócio neste funil. Os identificadores seguem a ordem das etapas do funil. | | `data.field` | `string` | Não | ID do campo personalizado ou chave do campo padrão. | | `data.kind` | `string` | Não | Valores: standard, custom. | | `data.name` | `string` | Não | | | `data.slug` | `string` | Não | Chave do valor em `customFields` do negócio; `null` para campo padrão. Aceita null. | | `data.isVisible` | `boolean` | Não | Indica se o campo aparece no funil. `null` para campo padrão. Aceita null. | | `data.isRequired` | `boolean` | Não | Sinaliza obrigatoriedade nos formulários do aplicativo, sem validação do servidor por si só. `null` para campo padrão. Aceita null. | | `data.requiredStageIds` | `array` | Não | Etapas a partir das quais o campo é obrigatório no servidor. Lista vazia quando não há exigência. | | `data.visibilityOverrideStageIds` | `array` | Não | Etapas que invertem `isVisible`. `null` para campo padrão. Aceita null. | | `data.isSuggested` | `boolean` | Não | Sinaliza sugestão nos formulários do aplicativo em toda movimentação, com opção de pular. Sem exigência no servidor. Sempre `true` quando `isRequired` é verdadeiro. `null` para campo padrão. Aceita null. | | `data.suggestedStageIds` | `array` | Não | Etapas onde o aplicativo sugere o preenchimento, com opção de pular e sem propagação. Não repete etapas de `requiredStageIds`. Lista vazia quando não há sugestão. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PipelineFieldSettings" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-tags/ # Listar etiquetas `GET /api/v1/tags` Todas as etiquetas do workspace, ordenadas por nome. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].id` | `string` | Não | | | `data[].name` | `string` | Não | | | `data[].color` | `string` | Não | | | `data[].createdAt` | `string` | Não | Formato: date-time. | | `data[].updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/create-tag/ # Criar etiqueta `POST /api/v1/tags` Cria uma etiqueta no workspace da chave. Nome já utilizado resulta em `409`. Exige `settings.tags`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Prioridade", "color": "#2563eb" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 80 caracteres. | | `color` | `string` | Sim | | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Tag` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.color` | `string` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-tag/ # Consultar etiqueta `GET /api/v1/tags/{id}` Retorna uma etiqueta do workspace. Uma etiqueta de outro workspace resulta em `404`. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da etiqueta. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Tag` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.color` | `string` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-tag/ # Atualizar etiqueta `PATCH /api/v1/tags/{id}` Substitui o nome e a cor da etiqueta. Ambos são obrigatórios: o corpo usa o mesmo esquema da criação, e um corpo parcial resulta em `400`. Exige `settings.tags`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da etiqueta. | ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Prioridade", "color": "#2563eb" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 80 caracteres. | | `color` | `string` | Sim | | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Tag` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.color` | `string` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/delete-tag/ # Excluir etiqueta `DELETE /api/v1/tags/{id}` Exclui uma etiqueta do workspace da chave. Exige `settings.tags`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da etiqueta. | ## Respostas ### 204 Sem conteúdo ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-custom-fields/ # Listar campos personalizados `GET /api/v1/custom-fields` Definições dos campos personalizados, com filtros opcionais de entidade e funil. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `entity` | query | Não | `string` | Por exemplo, deal ou contact. | | `pipelineId` | query | Não | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].id` | `string` | Não | | | `data[].entityType` | `string` | Não | | | `data[].name` | `string` | Não | | | `data[].slug` | `string` | Não | | | `data[].description` | `string` | Não | Aceita null. | | `data[].placeholder` | `string` | Não | Texto de exemplo exibido no campo vazio. Aceita null. | | `data[].fieldType` | `string` | Não | | | `data[].options` | `array` | Não | Opções de seleção. Em `select` e `multi_select`, ficam na definição. Em `members`, são calculadas a partir dos membros do workspace a cada leitura; `value` é o `userId` do membro. Aceita null. | | `data[].options[].value` | `string` | Não | | | `data[].options[].label` | `string` | Não | | | `data[].options[].color` | `string` | Não | Aceita null. | | `data[].options[].image` | `string` | Não | URL da foto. Somente para `members`. Aceita null. | | `data[].options[].inactive` | `boolean` | Não | Somente para `members`. Verdadeiro para membro desativado. Ele permanece na lista para resolver nomes de valores anteriores. Não o ofereça para novas escolhas nem altere valores já salvos por causa dessa marcação. | | `data[].config` | `object` | Não | Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null. | | `data[].config.event` | `EventFieldConfig` | Não | | | `data[].config.event.title` | `string` | Sim | Até 255 caracteres. | | `data[].config.event.description` | `string` | Não | Aceita null. Até 2000 caracteres. | | `data[].config.event.durationMinutes` | `integer` | Sim | Mínimo: 1. Máximo: 1440. | | `data[].config.event.conferenceMode` | `string` | Não | Valores: none, google_meet, custom_field. Aceita null. | | `data[].config.event.conferenceFieldSlug` | `string` | Não | Aceita null. | | `data[].config.event.recordWithBot` | `boolean` | Não | Aceita null. | | `data[].config.event.attendees` | `array` | Não | Aceita null. | | `data[].config.event.attendees[].type` | `string` | Não | Valores: lead_contact, deal_co_owner, member, contact, member_field. | | `data[].config.event.attendees[].userId` | `string` | Não | Aceita null. | | `data[].config.event.attendees[].contactId` | `string` | Não | Aceita null. | | `data[].config.event.attendees[].fieldSlug` | `string` | Não | Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null. | | `data[].config.event.attendees[].label` | `string` | Não | Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres. | | `data[].isRequired` | `boolean` | Não | | | `data[].apiOnly` | `boolean` | Não | Valores dos negócios são somente leitura no aplicativo e podem ser alterados por /api/v1. | | `data[].displayOrder` | `integer` | Não | | | `data[].section` | `string` | Não | Aceita null. | | `data[].pipelineConfig` | `object` | Não | Aceita null. | | `data[].createdAt` | `string` | Não | Formato: date-time. | | `data[].updatedAt` | `string` | Não | Formato: date-time. | | `data[].visibilityRule` | `object` | Não | Aceita null. | | `data[].visibilityRule.parentFieldId` | `string` | Sim | | | `data[].visibilityRule.values` | `array` | Sim | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDefinition" } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/create-custom-field/ # Criar campo personalizado `POST /api/v1/custom-fields` Cria a definição de um campo personalizado no workspace da chave. Exige `settings.custom_fields`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Segmento", "fieldType": "text" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 255 caracteres. | | `slug` | `string` | Não | Gerado a partir do nome quando omitido. Aceita null. Até 255 caracteres. | | `description` | `string` | Não | Aceita null. Até 1000 caracteres. | | `placeholder` | `string` | Não | Texto de exemplo exibido no campo vazio do aplicativo. Apenas visual; não é salvo como valor. Aceita null. Até 255 caracteres. | | `fieldType` | `string` | Sim | `members` apresenta os membros atuais do workspace; o valor salvo é um `userId`, e `options` enviado é descartado. `event` armazena data e hora e cria uma reunião na agenda do responsável, conforme `config.event`. Alterar o campo move a reunião; limpar o campo a exclui. Mover ou excluir a reunião no calendário ou no Google atualiza ou limpa o campo. Disponível apenas para campos de negócio. Valores: text, textarea, number, currency, boolean, date, datetime, select, multi_select, url, email, phone, file_upload, members, event. | | `options` | `array` | Não | Obrigatório para tipos com opções (`select`, `multi_select`). Ignorado para `members`. Aceita null. | | `config` | `object` | Não | Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null. | | `config.event` | `EventFieldConfig` | Não | | | `config.event.title` | `string` | Sim | Até 255 caracteres. | | `config.event.description` | `string` | Não | Aceita null. Até 2000 caracteres. | | `config.event.durationMinutes` | `integer` | Sim | Mínimo: 1. Máximo: 1440. | | `config.event.conferenceMode` | `string` | Não | Valores: none, google_meet, custom_field. Aceita null. | | `config.event.conferenceFieldSlug` | `string` | Não | Aceita null. | | `config.event.recordWithBot` | `boolean` | Não | Aceita null. | | `config.event.attendees` | `array` | Não | Aceita null. | | `config.event.attendees[].type` | `string` | Não | Valores: lead_contact, deal_co_owner, member, contact, member_field. | | `config.event.attendees[].userId` | `string` | Não | Aceita null. | | `config.event.attendees[].contactId` | `string` | Não | Aceita null. | | `config.event.attendees[].fieldSlug` | `string` | Não | Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null. | | `config.event.attendees[].label` | `string` | Não | Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres. | | `isRequired` | `boolean` | Não | Aceita null. | | `apiOnly` | `boolean` | Não | Quando verdadeiro, os valores do campo no negócio só podem ser alterados pela API pública; o aplicativo exibe o campo como somente leitura. Aceita null. | | `displayOrder` | `integer` | Não | Aceita null. Mínimo: 0. | | `section` | `string` | Não | Aceita null. Até 255 caracteres. | | `entityType` | `string` | Não | Padrão: `deal`. Aceita null. Até 50 caracteres. | | `visibilityRule` | `object` | Não | Aceita null. | | `visibilityRule.parentFieldId` | `string` | Sim | | | `visibilityRule.values` | `array` | Sim | | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `CustomFieldDefinition` | Não | | | `data.id` | `string` | Não | | | `data.entityType` | `string` | Não | | | `data.name` | `string` | Não | | | `data.slug` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.placeholder` | `string` | Não | Texto de exemplo exibido no campo vazio. Aceita null. | | `data.fieldType` | `string` | Não | | | `data.options` | `array` | Não | Opções de seleção. Em `select` e `multi_select`, ficam na definição. Em `members`, são calculadas a partir dos membros do workspace a cada leitura; `value` é o `userId` do membro. Aceita null. | | `data.options[].value` | `string` | Não | | | `data.options[].label` | `string` | Não | | | `data.options[].color` | `string` | Não | Aceita null. | | `data.options[].image` | `string` | Não | URL da foto. Somente para `members`. Aceita null. | | `data.options[].inactive` | `boolean` | Não | Somente para `members`. Verdadeiro para membro desativado. Ele permanece na lista para resolver nomes de valores anteriores. Não o ofereça para novas escolhas nem altere valores já salvos por causa dessa marcação. | | `data.config` | `object` | Não | Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null. | | `data.config.event` | `EventFieldConfig` | Não | | | `data.config.event.title` | `string` | Sim | Até 255 caracteres. | | `data.config.event.description` | `string` | Não | Aceita null. Até 2000 caracteres. | | `data.config.event.durationMinutes` | `integer` | Sim | Mínimo: 1. Máximo: 1440. | | `data.config.event.conferenceMode` | `string` | Não | Valores: none, google_meet, custom_field. Aceita null. | | `data.config.event.conferenceFieldSlug` | `string` | Não | Aceita null. | | `data.config.event.recordWithBot` | `boolean` | Não | Aceita null. | | `data.config.event.attendees` | `array` | Não | Aceita null. | | `data.config.event.attendees[].type` | `string` | Não | Valores: lead_contact, deal_co_owner, member, contact, member_field. | | `data.config.event.attendees[].userId` | `string` | Não | Aceita null. | | `data.config.event.attendees[].contactId` | `string` | Não | Aceita null. | | `data.config.event.attendees[].fieldSlug` | `string` | Não | Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null. | | `data.config.event.attendees[].label` | `string` | Não | Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres. | | `data.isRequired` | `boolean` | Não | | | `data.apiOnly` | `boolean` | Não | Valores dos negócios são somente leitura no aplicativo e podem ser alterados por /api/v1. | | `data.displayOrder` | `integer` | Não | | | `data.section` | `string` | Não | Aceita null. | | `data.pipelineConfig` | `object` | Não | Aceita null. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.visibilityRule` | `object` | Não | Aceita null. | | `data.visibilityRule.parentFieldId` | `string` | Sim | | | `data.visibilityRule.values` | `array` | Sim | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinition" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/upload-custom-field-file/ # Enviar arquivo de campo personalizado `POST /api/v1/custom-fields/upload` Envia um arquivo para um campo `file_upload` e retorna o comprovante de armazenamento. Depois, associe a `key` retornada à propriedade de um negócio. Disponível para qualquer chave válida: enviar o arquivo preenche um valor, sem alterar a definição do campo. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `multipart/form-data` ```json { "file": "" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `file` | `string` | Sim | Até 16 MB. Formato: binary. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `FileUploadReceipt` | Não | Comprovante do envio de arquivo; associe `key` ao valor de um campo `file_upload`. | | `data.key` | `string` | Não | | | `data.name` | `string` | Não | | | `data.size` | `integer` | Não | Formato: int64. | | `data.mimeType` | `string` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileUploadReceipt" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 413 Arquivo acima do limite da rota: 5 MB para foto de contato ou 16 MB para arquivo de campo personalizado. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 415 Arquivo vazio ou tipo de mídia não aceito pela rota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 503 O armazenamento recusou a operação ou excedeu o tempo de resposta. O arquivo não foi enviado; a operação pode ser repetida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/resolve-custom-field-file-url/ # Obter URL de arquivo de campo personalizado `GET /api/v1/custom-fields/file` Confirma que a chave de armazenamento pertence ao workspace da chave de API e retorna uma URL assinada válida por uma hora. O cliente baixa o arquivo diretamente por essa URL. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `key` | query | Sim | `string` | Chave de armazenamento do workspace retornada pelo envio. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `PresignedUrl` | Não | | | `data.url` | `string` | Não | Formato: uri. | | `data.expiresAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PresignedUrl" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-custom-field/ # Consultar campo personalizado `GET /api/v1/custom-fields/{id}` Retorna a definição de um campo de qualquer entidade pelo identificador. Fora do workspace, responde `404`. Disponível para qualquer chave válida. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do campo personalizado. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `CustomFieldDefinition` | Não | | | `data.id` | `string` | Não | | | `data.entityType` | `string` | Não | | | `data.name` | `string` | Não | | | `data.slug` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.placeholder` | `string` | Não | Texto de exemplo exibido no campo vazio. Aceita null. | | `data.fieldType` | `string` | Não | | | `data.options` | `array` | Não | Opções de seleção. Em `select` e `multi_select`, ficam na definição. Em `members`, são calculadas a partir dos membros do workspace a cada leitura; `value` é o `userId` do membro. Aceita null. | | `data.options[].value` | `string` | Não | | | `data.options[].label` | `string` | Não | | | `data.options[].color` | `string` | Não | Aceita null. | | `data.options[].image` | `string` | Não | URL da foto. Somente para `members`. Aceita null. | | `data.options[].inactive` | `boolean` | Não | Somente para `members`. Verdadeiro para membro desativado. Ele permanece na lista para resolver nomes de valores anteriores. Não o ofereça para novas escolhas nem altere valores já salvos por causa dessa marcação. | | `data.config` | `object` | Não | Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null. | | `data.config.event` | `EventFieldConfig` | Não | | | `data.config.event.title` | `string` | Sim | Até 255 caracteres. | | `data.config.event.description` | `string` | Não | Aceita null. Até 2000 caracteres. | | `data.config.event.durationMinutes` | `integer` | Sim | Mínimo: 1. Máximo: 1440. | | `data.config.event.conferenceMode` | `string` | Não | Valores: none, google_meet, custom_field. Aceita null. | | `data.config.event.conferenceFieldSlug` | `string` | Não | Aceita null. | | `data.config.event.recordWithBot` | `boolean` | Não | Aceita null. | | `data.config.event.attendees` | `array` | Não | Aceita null. | | `data.config.event.attendees[].type` | `string` | Não | Valores: lead_contact, deal_co_owner, member, contact, member_field. | | `data.config.event.attendees[].userId` | `string` | Não | Aceita null. | | `data.config.event.attendees[].contactId` | `string` | Não | Aceita null. | | `data.config.event.attendees[].fieldSlug` | `string` | Não | Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null. | | `data.config.event.attendees[].label` | `string` | Não | Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres. | | `data.isRequired` | `boolean` | Não | | | `data.apiOnly` | `boolean` | Não | Valores dos negócios são somente leitura no aplicativo e podem ser alterados por /api/v1. | | `data.displayOrder` | `integer` | Não | | | `data.section` | `string` | Não | Aceita null. | | `data.pipelineConfig` | `object` | Não | Aceita null. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.visibilityRule` | `object` | Não | Aceita null. | | `data.visibilityRule.parentFieldId` | `string` | Sim | | | `data.visibilityRule.values` | `array` | Sim | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinition" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/update-custom-field/ # Atualizar campo personalizado `PATCH /api/v1/custom-fields/{id}` Atualiza parcialmente a definição de um campo e retorna o resultado. Exige `settings.custom_fields`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do campo personalizado. | ## Corpo da requisição Content-Type: `application/json` ```json { "placeholder": "Informe o segmento da empresa" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Não | Aceita null. Até 255 caracteres. | | `description` | `string` | Não | Aceita null. Até 1000 caracteres. | | `placeholder` | `string` | Não | Omitir ou enviar nulo preserva o valor atual; texto em branco limpa o campo. Aceita null. Até 255 caracteres. | | `options` | `array` | Não | Aceita null. | | `config` | `object` | Não | Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null. | | `config.event` | `EventFieldConfig` | Não | | | `config.event.title` | `string` | Sim | Até 255 caracteres. | | `config.event.description` | `string` | Não | Aceita null. Até 2000 caracteres. | | `config.event.durationMinutes` | `integer` | Sim | Mínimo: 1. Máximo: 1440. | | `config.event.conferenceMode` | `string` | Não | Valores: none, google_meet, custom_field. Aceita null. | | `config.event.conferenceFieldSlug` | `string` | Não | Aceita null. | | `config.event.recordWithBot` | `boolean` | Não | Aceita null. | | `config.event.attendees` | `array` | Não | Aceita null. | | `config.event.attendees[].type` | `string` | Não | Valores: lead_contact, deal_co_owner, member, contact, member_field. | | `config.event.attendees[].userId` | `string` | Não | Aceita null. | | `config.event.attendees[].contactId` | `string` | Não | Aceita null. | | `config.event.attendees[].fieldSlug` | `string` | Não | Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null. | | `config.event.attendees[].label` | `string` | Não | Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres. | | `isRequired` | `boolean` | Não | Aceita null. | | `apiOnly` | `boolean` | Não | Define se os valores dos negócios só podem ser alterados por /api/v1. Aceita null. | | `displayOrder` | `integer` | Não | Aceita null. Mínimo: 0. | | `section` | `string` | Não | Aceita null. Até 255 caracteres. | | `visibilityRule` | `object` | Não | Substitui a regra. Omitir ou enviar nulo preserva a regra atual. Aceita null. | | `visibilityRule.parentFieldId` | `string` | Sim | | | `visibilityRule.values` | `array` | Sim | | | `clearVisibilityRule` | `boolean` | Não | Quando verdadeiro, remove a regra de visibilidade. Não envie junto com visibilityRule: isso resulta em 422. Aceita null. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `CustomFieldDefinition` | Não | | | `data.id` | `string` | Não | | | `data.entityType` | `string` | Não | | | `data.name` | `string` | Não | | | `data.slug` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.placeholder` | `string` | Não | Texto de exemplo exibido no campo vazio. Aceita null. | | `data.fieldType` | `string` | Não | | | `data.options` | `array` | Não | Opções de seleção. Em `select` e `multi_select`, ficam na definição. Em `members`, são calculadas a partir dos membros do workspace a cada leitura; `value` é o `userId` do membro. Aceita null. | | `data.options[].value` | `string` | Não | | | `data.options[].label` | `string` | Não | | | `data.options[].color` | `string` | Não | Aceita null. | | `data.options[].image` | `string` | Não | URL da foto. Somente para `members`. Aceita null. | | `data.options[].inactive` | `boolean` | Não | Somente para `members`. Verdadeiro para membro desativado. Ele permanece na lista para resolver nomes de valores anteriores. Não o ofereça para novas escolhas nem altere valores já salvos por causa dessa marcação. | | `data.config` | `object` | Não | Configuração por tipo de campo. Para event, informe event com título, duração e configuração da reunião. member_field usa fieldSlug para ler um membro a partir de um campo members do lead. Aceita null. | | `data.config.event` | `EventFieldConfig` | Não | | | `data.config.event.title` | `string` | Sim | Até 255 caracteres. | | `data.config.event.description` | `string` | Não | Aceita null. Até 2000 caracteres. | | `data.config.event.durationMinutes` | `integer` | Sim | Mínimo: 1. Máximo: 1440. | | `data.config.event.conferenceMode` | `string` | Não | Valores: none, google_meet, custom_field. Aceita null. | | `data.config.event.conferenceFieldSlug` | `string` | Não | Aceita null. | | `data.config.event.recordWithBot` | `boolean` | Não | Aceita null. | | `data.config.event.attendees` | `array` | Não | Aceita null. | | `data.config.event.attendees[].type` | `string` | Não | Valores: lead_contact, deal_co_owner, member, contact, member_field. | | `data.config.event.attendees[].userId` | `string` | Não | Aceita null. | | `data.config.event.attendees[].contactId` | `string` | Não | Aceita null. | | `data.config.event.attendees[].fieldSlug` | `string` | Não | Slug do campo members cujo usuário será convidado. Lido novamente quando o campo mudar. Aceita null. | | `data.config.event.attendees[].label` | `string` | Não | Rótulo usado pelo editor; não determina a identidade do convidado. Aceita null. Até 255 caracteres. | | `data.isRequired` | `boolean` | Não | | | `data.apiOnly` | `boolean` | Não | Valores dos negócios são somente leitura no aplicativo e podem ser alterados por /api/v1. | | `data.displayOrder` | `integer` | Não | | | `data.section` | `string` | Não | Aceita null. | | `data.pipelineConfig` | `object` | Não | Aceita null. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.visibilityRule` | `object` | Não | Aceita null. | | `data.visibilityRule.parentFieldId` | `string` | Sim | | | `data.visibilityRule.values` | `array` | Sim | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CustomFieldDefinition" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/delete-custom-field/ # Excluir campo personalizado `DELETE /api/v1/custom-fields/{id}` Exclui a definição de um campo e remove seus valores dos negócios do workspace. Cada negócio afetado recebe uma atividade `custom_field_changed` com o registro da remoção. Exige `settings.custom_fields`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador do campo personalizado. | ## Respostas ### 204 Sem conteúdo ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/list-users/ # Listar usuários `GET /api/v1/users` Membros ativos do workspace que podem ser atribuídos como responsáveis. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.members` | `array` | Não | | | `data.members[].userId` | `string` | Não | | | `data.members[].name` | `string` | Não | | | `data.members[].email` | `string` | Não | | | `data.members[].image` | `string` | Não | Aceita null. | | `data.members[].role` | `string` | Não | Papel do membro no workspace, por exemplo owner. | | `data.members[].id` | `string` | Não | ID do vínculo de membro no workspace. userId identifica o usuário. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/calendar/methods/list-calendar-window/ # Listar intervalo do calendário `GET /api/v1/calendar/events` Retorna itens das fontes solicitadas no intervalo, ordenados pelo início, e o status de cada fonte. Fontes indisponíveis são indicadas em `sources[]` (`not_connected`, `not_authorized`, `error`, `truncated`), sem falhar toda a requisição. **Visibilidade.** A chave representa o membro que a criou. Quem só vê seus próprios dados recebe sua própria agenda; `memberId` é ignorado. Quem vê todos os dados pode consultar outro membro, exceto um administrador ou o proprietário do workspace. Solicitar explicitamente a agenda desses membros resulta em `403`; sem `memberId`, seus itens são omitidos. O proprietário pode acessar todas as agendas. Reuniões às quais o membro foi convidado são retornadas, independentemente do proprietário da reunião. **Limitação.** O limite de itens por fonte e o status de `sources[]` são calculados antes do filtro de visibilidade. Assim, eventos invisíveis podem contribuir para um erro de limite (`422`), e uma fonte inteiramente filtrada pode retornar `ok` e uma lista vazia. **Google Calendar.** A conexão é pessoal. Consultar a agenda de outro membro retorna apenas seus itens nativos, sem os eventos da conexão Google desse membro. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `timeMin` | query | Sim | `string` | Início da janela de consulta, em ISO 8601 e UTC. | | `timeMax` | query | Sim | `string` | Fim do intervalo em ISO 8601 UTC. Aceita até 400 dias após timeMin; acima disso, responde `400`. | | `memberId` | query | Não | `string` | Agenda de outro membro, pelo identificador de membro do workspace. | | `provider` | query | Não | `array` | Filtro de fontes; pode ser repetido. | | `kind` | query | Não | `array` | Filtro de tipos de item; pode ser repetido. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | provider:kind:id, por exemplo, native:meeting:5f2c… | | `data.items[].provider` | `string` | Não | Valores: native, google. | | `data.items[].kind` | `string` | Não | Valores: meeting, task, cadence_task. | | `data.items[].readOnly` | `boolean` | Não | Não pode ser alterado por esta API; somente reuniões nativas permitem escrita. | | `data.items[].status` | `string` | Não | confirmed, tentative, cancelled. | | `data.items[].summary` | `string` | Não | | | `data.items[].description` | `string` | Não | Aceita null. | | `data.items[].location` | `string` | Não | Aceita null. | | `data.items[].start` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.items[].start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.items[].start.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.items[].end` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.items[].end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.items[].end.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.items[].attendees` | `array` | Não | | | `data.items[].attendees[].type` | `string` | Não | Valores: member, contact. | | `data.items[].attendees[].member` | `object` | Não | Aceita null. | | `data.items[].attendees[].member.id` | `string` | Não | | | `data.items[].attendees[].member.userId` | `string` | Não | | | `data.items[].attendees[].member.name` | `string` | Não | | | `data.items[].attendees[].member.email` | `string` | Não | | | `data.items[].attendees[].member.image` | `string` | Não | Aceita null. | | `data.items[].attendees[].member.role` | `string` | Não | | | `data.items[].attendees[].contact` | `object` | Não | Aceita null. | | `data.items[].attendees[].contact.id` | `string` | Não | | | `data.items[].attendees[].contact.displayName` | `string` | Não | | | `data.items[].attendees[].contact.email` | `string` | Não | Aceita null. | | `data.items[].attendees[].contact.phone` | `string` | Não | Aceita null. | | `data.items[].attendees[].removed` | `boolean` | Não | A identidade não existe mais; o convidado continua no histórico. | | `data.items[].attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. | | `data.items[].attendees[].organizer` | `boolean` | Não | | | `data.items[].attendees[].optional` | `boolean` | Não | | | `data.items[].owner` | `object` | Não | Nulo quando o membro proprietário saiu do workspace. Aceita null. | | `data.items[].owner.userId` | `string` | Não | | | `data.items[].owner.name` | `string` | Não | | | `data.items[].owner.email` | `string` | Não | | | `data.items[].owner.image` | `string` | Não | Aceita null. | | `data.items[].owner.role` | `string` | Não | Papel do membro no workspace, por exemplo owner. | | `data.items[].owner.id` | `string` | Não | ID do vínculo de membro no workspace. userId identifica o usuário. | | `data.items[].extendedProperties` | `object` | Não | Aceita null. | | `data.items[].conferenceUrl` | `string` | Não | Link da reunião, independentemente de sua origem. Aceita null. | | `data.items[].botEnabled` | `boolean` | Não | O bot de gravação está configurado para esta reunião. | | `data.items[].botStatus` | `string` | Não | Último estado informado pelo bot. Aceita null. | | `data.items[].created` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].updated` | `string` | Não | Formato: date-time. Aceita null. | | `data.sources` | `array` | Não | | | `data.sources[].provider` | `string` | Não | Valores: native, google. | | `data.sources[].kind` | `string` | Não | Valores: meeting, task, cadence_task. | | `data.sources[].status` | `string` | Não | Valores: ok, not_connected, not_authorized, truncated, error. | | `data.sources[].message` | `string` | Não | Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarSourceStatus" } } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/calendar/methods/create-calendar-event/ # Criar reunião `POST /api/v1/calendar/events` Cria uma reunião no calendário nativo com o membro da chave como proprietário. O proprietário nunca vem do corpo da requisição. `createConference` solicita um link do Google Meet e implica `syncToGoogle`. Ambas as opções exigem conexão Google com permissão de escrita. Se o Google falhar, a criação inteira falha. `recordWithBot` exige um link de conferência criado nesta chamada ou informado em `conferenceUrl`; o bot participa apenas do Google Meet ou Microsoft Teams. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "summary": "Apresentação da proposta", "start": { "dateTime": "2026-10-06T14:00:00-03:00", "timeZone": "America/Sao_Paulo" }, "end": { "dateTime": "2026-10-06T14:30:00-03:00", "timeZone": "America/Sao_Paulo" }, "allDay": false } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `summary` | `string` | Sim | Até 255 caracteres. | | `description` | `string` | Não | Aceita null. | | `location` | `string` | Não | Aceita null. Até 500 caracteres. | | `start` | `EventDateTime` | Sim | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `start.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `end` | `EventDateTime` | Sim | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `end.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `allDay` | `boolean` | Não | Aceita null. | | `status` | `string` | Não | confirmed (padrão), tentative, cancelled. Aceita null. | | `attendees` | `array` | Não | Cada entrada usa { type: member, memberId } ou { type: contact, contactId }. Identificador desconhecido resulta em `400`. Aceita null. | | `attendees[].type` | `string` | Não | Valores: member, contact. | | `attendees[].memberId` | `string` | Não | Aceita null. | | `attendees[].contactId` | `string` | Não | Aceita null. | | `attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. | | `attendees[].organizer` | `boolean` | Não | | | `attendees[].optional` | `boolean` | Não | | | `extendedProperties` | `object` | Não | Aceita null. | | `syncToGoogle` | `boolean` | Não | Sincroniza a reunião no Google Calendar do proprietário. Exige conexão com permissão de escrita. Aceita null. | | `createConference` | `boolean` | Não | Solicita um link do Google Meet. Implica syncToGoogle. Aceita null. | | `recordWithBot` | `boolean` | Não | Solicita gravação pelo bot. Requer link de Google Meet ou Microsoft Teams; caso contrário, retorna 400. Aceita null. | | `conferenceUrl` | `string` | Não | Link de reunião existente, quando não estiver criando uma conferência. Para gravação pelo bot, use Google Meet ou Microsoft Teams. Aceita null. Até 1000 caracteres. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `CalendarEvent` | Não | Formato único do calendário, utilizado por todos os itens, independentemente da fonte. | | `data.id` | `string` | Não | provider:kind:id, por exemplo, native:meeting:5f2c… | | `data.provider` | `string` | Não | Valores: native, google. | | `data.kind` | `string` | Não | Valores: meeting, task, cadence_task. | | `data.readOnly` | `boolean` | Não | Não pode ser alterado por esta API; somente reuniões nativas permitem escrita. | | `data.status` | `string` | Não | confirmed, tentative, cancelled. | | `data.summary` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.location` | `string` | Não | Aceita null. | | `data.start` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.start.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.end` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.end.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.attendees` | `array` | Não | | | `data.attendees[].type` | `string` | Não | Valores: member, contact. | | `data.attendees[].member` | `object` | Não | Aceita null. | | `data.attendees[].member.id` | `string` | Não | | | `data.attendees[].member.userId` | `string` | Não | | | `data.attendees[].member.name` | `string` | Não | | | `data.attendees[].member.email` | `string` | Não | | | `data.attendees[].member.image` | `string` | Não | Aceita null. | | `data.attendees[].member.role` | `string` | Não | | | `data.attendees[].contact` | `object` | Não | Aceita null. | | `data.attendees[].contact.id` | `string` | Não | | | `data.attendees[].contact.displayName` | `string` | Não | | | `data.attendees[].contact.email` | `string` | Não | Aceita null. | | `data.attendees[].contact.phone` | `string` | Não | Aceita null. | | `data.attendees[].removed` | `boolean` | Não | A identidade não existe mais; o convidado continua no histórico. | | `data.attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. | | `data.attendees[].organizer` | `boolean` | Não | | | `data.attendees[].optional` | `boolean` | Não | | | `data.owner` | `object` | Não | Nulo quando o membro proprietário saiu do workspace. Aceita null. | | `data.owner.userId` | `string` | Não | | | `data.owner.name` | `string` | Não | | | `data.owner.email` | `string` | Não | | | `data.owner.image` | `string` | Não | Aceita null. | | `data.owner.role` | `string` | Não | Papel do membro no workspace, por exemplo owner. | | `data.owner.id` | `string` | Não | ID do vínculo de membro no workspace. userId identifica o usuário. | | `data.extendedProperties` | `object` | Não | Aceita null. | | `data.conferenceUrl` | `string` | Não | Link da reunião, independentemente de sua origem. Aceita null. | | `data.botEnabled` | `boolean` | Não | O bot de gravação está configurado para esta reunião. | | `data.botStatus` | `string` | Não | Último estado informado pelo bot. Aceita null. | | `data.created` | `string` | Não | Formato: date-time. Aceita null. | | `data.updated` | `string` | Não | Formato: date-time. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/calendar/methods/get-calendar-event/ # Consultar reunião `GET /api/v1/calendar/events/{id}` Retorna uma reunião nativa. Identificadores de tarefa, etapa de cadência ou evento Google resultam em `422`; um identificador malformado resulta em `400`. **Visibilidade.** O proprietário e os convidados podem consultar a reunião. Fora desses casos, um membro limitado aos próprios dados recebe `403`. Quem vê todos os dados pode consultar reuniões de outros membros, exceto as de administradores ou do proprietário do workspace. O proprietário do workspace pode acessar todas. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador no formato provider:kind:id, por exemplo, native:meeting:5f2c… | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `CalendarEvent` | Não | Formato único do calendário, utilizado por todos os itens, independentemente da fonte. | | `data.id` | `string` | Não | provider:kind:id, por exemplo, native:meeting:5f2c… | | `data.provider` | `string` | Não | Valores: native, google. | | `data.kind` | `string` | Não | Valores: meeting, task, cadence_task. | | `data.readOnly` | `boolean` | Não | Não pode ser alterado por esta API; somente reuniões nativas permitem escrita. | | `data.status` | `string` | Não | confirmed, tentative, cancelled. | | `data.summary` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.location` | `string` | Não | Aceita null. | | `data.start` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.start.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.end` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.end.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.attendees` | `array` | Não | | | `data.attendees[].type` | `string` | Não | Valores: member, contact. | | `data.attendees[].member` | `object` | Não | Aceita null. | | `data.attendees[].member.id` | `string` | Não | | | `data.attendees[].member.userId` | `string` | Não | | | `data.attendees[].member.name` | `string` | Não | | | `data.attendees[].member.email` | `string` | Não | | | `data.attendees[].member.image` | `string` | Não | Aceita null. | | `data.attendees[].member.role` | `string` | Não | | | `data.attendees[].contact` | `object` | Não | Aceita null. | | `data.attendees[].contact.id` | `string` | Não | | | `data.attendees[].contact.displayName` | `string` | Não | | | `data.attendees[].contact.email` | `string` | Não | Aceita null. | | `data.attendees[].contact.phone` | `string` | Não | Aceita null. | | `data.attendees[].removed` | `boolean` | Não | A identidade não existe mais; o convidado continua no histórico. | | `data.attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. | | `data.attendees[].organizer` | `boolean` | Não | | | `data.attendees[].optional` | `boolean` | Não | | | `data.owner` | `object` | Não | Nulo quando o membro proprietário saiu do workspace. Aceita null. | | `data.owner.userId` | `string` | Não | | | `data.owner.name` | `string` | Não | | | `data.owner.email` | `string` | Não | | | `data.owner.image` | `string` | Não | Aceita null. | | `data.owner.role` | `string` | Não | Papel do membro no workspace, por exemplo owner. | | `data.owner.id` | `string` | Não | ID do vínculo de membro no workspace. userId identifica o usuário. | | `data.extendedProperties` | `object` | Não | Aceita null. | | `data.conferenceUrl` | `string` | Não | Link da reunião, independentemente de sua origem. Aceita null. | | `data.botEnabled` | `boolean` | Não | O bot de gravação está configurado para esta reunião. | | `data.botStatus` | `string` | Não | Último estado informado pelo bot. Aceita null. | | `data.created` | `string` | Não | Formato: date-time. Aceita null. | | `data.updated` | `string` | Não | Formato: date-time. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Requisição malformada ou parâmetro inválido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/calendar/methods/update-calendar-event/ # Atualizar reunião `PATCH /api/v1/calendar/events/{id}` Aplica somente os campos enviados. `start` e `end` são validados em conjunto com os valores salvos para impedir que a reunião termine antes de começar. Enviar `attendees` substitui toda a lista. Reuniões sincronizadas com o Google propagam a alteração; reuniões internas continuam internas. Somente `native:meeting` pode ser alterado nesta rota. Tarefas e etapas de cadência resultam em `422`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador no formato provider:kind:id, por exemplo, native:meeting:5f2c… | ## Corpo da requisição Content-Type: `application/json` ```json { "summary": "Apresentação da proposta revisada" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `summary` | `string` | Não | Aceita null. Até 255 caracteres. | | `description` | `string` | Não | Aceita null. | | `location` | `string` | Não | Aceita null. Até 500 caracteres. | | `start` | `object` | Não | Aceita null. | | `start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `start.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `end` | `object` | Não | Aceita null. | | `end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `end.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `allDay` | `boolean` | Não | Aceita null. | | `status` | `string` | Não | Aceita null. | | `attendees` | `array` | Não | Aceita null. | | `attendees[].type` | `string` | Não | Valores: member, contact. | | `attendees[].memberId` | `string` | Não | Aceita null. | | `attendees[].contactId` | `string` | Não | Aceita null. | | `attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. | | `attendees[].organizer` | `boolean` | Não | | | `attendees[].optional` | `boolean` | Não | | | `extendedProperties` | `object` | Não | Aceita null. | | `recordWithBot` | `boolean` | Não | Aceita null. | | `conferenceUrl` | `string` | Não | Aceita null. Até 1000 caracteres. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `CalendarEvent` | Não | Formato único do calendário, utilizado por todos os itens, independentemente da fonte. | | `data.id` | `string` | Não | provider:kind:id, por exemplo, native:meeting:5f2c… | | `data.provider` | `string` | Não | Valores: native, google. | | `data.kind` | `string` | Não | Valores: meeting, task, cadence_task. | | `data.readOnly` | `boolean` | Não | Não pode ser alterado por esta API; somente reuniões nativas permitem escrita. | | `data.status` | `string` | Não | confirmed, tentative, cancelled. | | `data.summary` | `string` | Não | | | `data.description` | `string` | Não | Aceita null. | | `data.location` | `string` | Não | Aceita null. | | `data.start` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.start.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.end` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. | | `data.end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. | | `data.end.dateTime` | `string` | Não | Formato: date-time. Aceita null. | | `data.end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. | | `data.attendees` | `array` | Não | | | `data.attendees[].type` | `string` | Não | Valores: member, contact. | | `data.attendees[].member` | `object` | Não | Aceita null. | | `data.attendees[].member.id` | `string` | Não | | | `data.attendees[].member.userId` | `string` | Não | | | `data.attendees[].member.name` | `string` | Não | | | `data.attendees[].member.email` | `string` | Não | | | `data.attendees[].member.image` | `string` | Não | Aceita null. | | `data.attendees[].member.role` | `string` | Não | | | `data.attendees[].contact` | `object` | Não | Aceita null. | | `data.attendees[].contact.id` | `string` | Não | | | `data.attendees[].contact.displayName` | `string` | Não | | | `data.attendees[].contact.email` | `string` | Não | Aceita null. | | `data.attendees[].contact.phone` | `string` | Não | Aceita null. | | `data.attendees[].removed` | `boolean` | Não | A identidade não existe mais; o convidado continua no histórico. | | `data.attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. | | `data.attendees[].organizer` | `boolean` | Não | | | `data.attendees[].optional` | `boolean` | Não | | | `data.owner` | `object` | Não | Nulo quando o membro proprietário saiu do workspace. Aceita null. | | `data.owner.userId` | `string` | Não | | | `data.owner.name` | `string` | Não | | | `data.owner.email` | `string` | Não | | | `data.owner.image` | `string` | Não | Aceita null. | | `data.owner.role` | `string` | Não | Papel do membro no workspace, por exemplo owner. | | `data.owner.id` | `string` | Não | ID do vínculo de membro no workspace. userId identifica o usuário. | | `data.extendedProperties` | `object` | Não | Aceita null. | | `data.conferenceUrl` | `string` | Não | Link da reunião, independentemente de sua origem. Aceita null. | | `data.botEnabled` | `boolean` | Não | O bot de gravação está configurado para esta reunião. | | `data.botStatus` | `string` | Não | Último estado informado pelo bot. Aceita null. | | `data.created` | `string` | Não | Formato: date-time. Aceita null. | | `data.updated` | `string` | Não | Formato: date-time. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/calendar/methods/delete-calendar-event/ # Excluir reunião `DELETE /api/v1/calendar/events/{id}` Remove a reunião do calendário nativo e do Google, quando sincronizada. Uma reunião já excluída no Google não impede o sucesso. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador no formato provider:kind:id, por exemplo, native:meeting:5f2c… | ## Respostas ### 204 Sem conteúdo ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/conversations/methods/send-message/ # Enviar mensagem `POST /api/v1/conversations/messages` Envia uma mensagem de WhatsApp pelo workspace da chave, com autoria do membro que a criou, e retorna a mensagem salva. `type` assume `text` por padrão. Informe `channelId` ou `senderPhoneNumberId` para escolher o canal; sem eles, usa o canal padrão do workspace. O caminho legado `POST /api/v1/messages` mantém o mesmo contrato e os mesmos requisitos. Novas integrações devem usar `/api/v1/conversations/messages`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "to": "5511999999999", "type": "text", "text": "Olá, Ana. Podemos conversar sobre a proposta?", "channelId": "ID_DO_CANAL" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `to` | `string` | Sim | Telefone do destinatário em E.164 ou no formato normalizado do workspace. | | `type` | `string` | Não | text, image, audio, video, document, template, … Aceita null. | | `text` | `string` | Não | Aceita null. | | `senderPhoneNumberId` | `string` | Não | Identificador do número de telefone do canal no provedor. Aceita null. | | `channelId` | `string` | Não | Identificador do canal de envio; tem prioridade sobre senderPhoneNumberId. Aceita null. | | `mediaAssetId` | `string` | Não | Identificador de mídia já armazenada no workspace. Aceita null. | | `mediaLink` | `string` | Não | URL pública usada pelo provedor para baixar a mídia. Aceita null. | | `caption` | `string` | Não | Aceita null. | | `filename` | `string` | Não | Aceita null. | | `mimeType` | `string` | Não | Aceita null. | | `templateName` | `string` | Não | Aceita null. | | `templateLanguageCode` | `string` | Não | Aceita null. | | `templateComponents` | `array` | Não | Aceita null. | | `quotedMessageId` | `string` | Não | Mensagem à qual se está respondendo. Aceita null. | | `voice` | `boolean` | Não | Somente áudio. Padrão: true, para entregar como mensagem de voz (ícone de microfone e forma de onda). Envie false para entregar como arquivo de áudio. Aceita null. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `SendMessageResponse` | Não | | | `data.id` | `string` | Não | | | `data.conversationId` | `string` | Não | | | `data.channelId` | `string` | Não | | | `data.externalId` | `string` | Não | Identificador da mensagem no provedor; nulo até a aceitação pelo provedor. Aceita null. | | `data.direction` | `string` | Não | Valores: inbound, outbound. | | `data.type` | `string` | Não | | | `data.status` | `string` | Não | | | `data.body` | `string` | Não | | | `data.errorMessage` | `string` | Não | Aceita null. | | `data.timestamp` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendMessageResponse" }, "message": { "type": "string" } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/conversations/methods/list-conversations/ # Listar conversas `GET /api/v1/conversations` Lista conversas visíveis ao membro da chave, por cursor e em ordem de atividade mais recente. Um membro limitado aos próprios dados só acessa suas conversas. Exige `whatsapp.view_conversations`. Os filtros all, unread, returned e internal consultam conversas abertas; closed consulta as fechadas. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | Cursor opaco retornado pela página anterior. | | `search` | query | Não | `string` | Busca sem diferenciar maiúsculas e minúsculas nos campos de contato e telefone. | | `filter` | query | Não | `string` | — | | `responsibleId` | query | Não | `string` | O negócio ativo do contato pertence a este identificador de usuário. | | `pipelineId` | query | Não | `string` | O negócio ativo do contato está neste identificador de funil. | | `stageId` | query | Não | `string` | O negócio ativo do contato está neste identificador de etapa. | | `source` | query | Não | `string` | O negócio ativo do contato tem esta origem. Valor desconhecido resulta em `400`. | | `channelIds` | query | Não | `array` | Identificadores dos canais de recebimento; repita o parâmetro ou separe por vírgulas. | | `sort` | query | Não | `string` | Ordenação por atividade. Mantenha o mesmo valor ao percorrer páginas com cursor. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].waId` | `string` | Não | | | `data.items[].sendTo` | `string` | Não | | | `data.items[].displayName` | `string` | Não | | | `data.items[].phone` | `string` | Não | | | `data.items[].contactId` | `string` | Não | Aceita null. | | `data.items[].channelId` | `string` | Não | Aceita null. | | `data.items[].channelName` | `string` | Não | Aceita null. | | `data.items[].lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].lastMessageText` | `string` | Não | | | `data.items[].lastMessageDirection` | `string` | Não | Valores: inbound, outbound. Aceita null. | | `data.items[].lastInboundAt` | `string` | Não | Última mensagem recebida do contato, agregada entre canais. Não use este valor para concluir que a janela de 24 horas está aberta em outro canal. Formato: date-time. Aceita null. | | `data.items[].unreadCount` | `integer` | Não | | | `data.items[].returning` | `boolean` | Não | | | `data.items[].internal` | `boolean` | Não | | | `data.items[].activeDealSeq` | `integer` | Não | Número sequencial do negócio aberto mais recente do contato. Aceita null. | | `data.items[].responsibleUserId` | `string` | Não | Responsável por esse negócio ativo. Aceita null. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.items[].updatedAt` | `string` | Não | Formato: date-time. | | `data.items[].contactInstagramId` | `string` | Não | Destino técnico do Instagram, no formato ig:, quando existir. Aceita null. | | `data.items[].avatarUrl` | `string` | Não | Aceita null. | | `data.items[].provider` | `string` | Não | Aceita null. | | `data.items[].lastMessageChannelId` | `string` | Não | Aceita null. | | `data.items[].lastMessageProvider` | `string` | Não | Aceita null. | | `data.items[].closed` | `boolean` | Não | Indica se a conversa está fechada. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationSummary" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/conversations/methods/list-conversation-messages/ # Listar mensagens da conversa `GET /api/v1/conversations/{conversationKey}/messages` Retorna o histórico da conversa paginado por cursor. Uma conversa fora da visibilidade do membro resulta em `404`. Exige `whatsapp.view_conversations`. **Sem `since`**, pagina para trás a partir das mensagens mais recentes, para abrir uma conversa. **Com `since`**, pagina para frente a partir do instante informado, para acompanhamento contínuo. Os itens de cada página vêm em ordem cronológica nos dois modos. Consulte primeiro sem `since`. Depois, use em `since` o horário da última mensagem recebida. O limite é **inclusivo**: mensagens com esse mesmo horário podem repetir. Remova duplicatas pelo identificador da mensagem. Ao percorrer várias páginas para frente, mantenha `since` junto de `cursor`. Um cursor enviado sem `since` volta ao modo de leitura para trás. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `conversationKey` | path | Sim | `string` | Identificador da conversa ou telefone que permita localizá-la. | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | Cursor opaco retornado pela página anterior. Mantenha `since` ao paginar para frente. | | `channelId` | query | Não | `string` | Restringe o histórico a um único canal. | | `since` | query | Não | `string` | Instante ISO 8601 UTC, por exemplo, 2026-08-25T03:14:00Z. Ativa a paginação para frente, com limite inclusivo. Uma data sem horário resulta em `400`. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].conversationId` | `string` | Não | | | `data.items[].channelId` | `string` | Não | Aceita null. | | `data.items[].externalId` | `string` | Não | Aceita null. | | `data.items[].direction` | `string` | Não | Valores: inbound, outbound. | | `data.items[].senderPhone` | `string` | Não | Aceita null. | | `data.items[].recipientPhone` | `string` | Não | Aceita null. | | `data.items[].body` | `string` | Não | | | `data.items[].previewText` | `string` | Não | | | `data.items[].type` | `string` | Não | | | `data.items[].status` | `string` | Não | | | `data.items[].read` | `boolean` | Não | | | `data.items[].timestamp` | `string` | Não | Formato: date-time. | | `data.items[].statusTimestamp` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].errorMessage` | `string` | Não | Aceita null. | | `data.items[].quotedText` | `string` | Não | Aceita null. | | `data.items[].quotedDirection` | `string` | Não | Valores: inbound, outbound. Aceita null. | | `data.items[].quotedMessageId` | `string` | Não | Aceita null. | | `data.items[].quotedType` | `string` | Não | Aceita null. | | `data.items[].quotedMedia` | `object` | Não | Aceita null. | | `data.items[].quotedMedia.mediaAssetId` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.status` | `string` | Não | Estado de ingestão da mídia armazenada. Aceita null. | | `data.items[].quotedMedia.mediaType` | `string` | Não | | | `data.items[].quotedMedia.contentType` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.caption` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.filename` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.sizeBytes` | `integer` | Não | Formato: int64. Aceita null. | | `data.items[].quotedMedia.durationMs` | `integer` | Não | Aceita null. | | `data.items[].quotedMedia.width` | `integer` | Não | Aceita null. | | `data.items[].quotedMedia.height` | `integer` | Não | Aceita null. | | `data.items[].quotedMedia.providerMediaId` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.providerMediaUrl` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.contentUrl` | `string` | Não | URL relativa para baixar o arquivo. Nula enquanto a mídia não estiver READY. A cópia do provedor para o armazenamento é assíncrona. Aceita null. | | `data.items[].sentByUserId` | `string` | Não | Aceita null. | | `data.items[].origin` | `string` | Não | Origem da mensagem: api, app, automation, agent ou outra. Aceita null. | | `data.items[].originLabel` | `string` | Não | Aceita null. | | `data.items[].media` | `object` | Não | Aceita null. | | `data.items[].media.mediaAssetId` | `string` | Não | Aceita null. | | `data.items[].media.status` | `string` | Não | Estado de ingestão da mídia armazenada. Aceita null. | | `data.items[].media.mediaType` | `string` | Não | | | `data.items[].media.contentType` | `string` | Não | Aceita null. | | `data.items[].media.caption` | `string` | Não | Aceita null. | | `data.items[].media.filename` | `string` | Não | Aceita null. | | `data.items[].media.sizeBytes` | `integer` | Não | Formato: int64. Aceita null. | | `data.items[].media.durationMs` | `integer` | Não | Aceita null. | | `data.items[].media.width` | `integer` | Não | Aceita null. | | `data.items[].media.height` | `integer` | Não | Aceita null. | | `data.items[].media.providerMediaId` | `string` | Não | Aceita null. | | `data.items[].media.providerMediaUrl` | `string` | Não | Aceita null. | | `data.items[].media.contentUrl` | `string` | Não | URL relativa para baixar o arquivo. Nula enquanto a mídia não estiver READY. A cópia do provedor para o armazenamento é assíncrona. Aceita null. | | `data.items[].content` | `object` | Não | Dados estruturados de tipos sem corpo de texto, como anúncio de origem, localização, cartão de contato ou alvo de reação. Aceita null. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.items[].editedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].deletedAt` | `string` | Não | Data da exclusão. O conteúdo pode permanecer no histórico de auditoria; a integração decide como exibi-lo. Formato: date-time. Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/list-cadences/ # Listar cadências `GET /api/v1/cadences` Catálogo de cadências do workspace, com funil, etapa e contadores de matrícula. Use o `id` retornado para matricular um negócio. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].id` | `string` | Não | | | `data[].pipelineId` | `string` | Não | | | `data[].pipelineSeq` | `integer` | Não | | | `data[].pipelineName` | `string` | Não | | | `data[].kind` | `string` | Não | entry \| stage_playbook | | `data[].stageId` | `string` | Não | Aceita null. | | `data[].stageName` | `string` | Não | Aceita null. | | `data[].stageColor` | `string` | Não | Aceita null. | | `data[].name` | `string` | Não | | | `data[].description` | `string` | Não | Aceita null. | | `data[].status` | `string` | Não | | | `data[].activeVersion` | `integer` | Não | | | `data[].trigger` | `string` | Não | Forma de início da cadência. | | `data[].stepCount` | `integer` | Não | | | `data[].dayCount` | `integer` | Não | | | `data[].channels` | `array` | Não | | | `data[].steps` | `array` | Não | Atividades da rotina em ordem, com dia, canal e descrição. Presentes na própria listagem para consultar a rotina sem uma requisição de detalhe por cadência. | | `data[].steps[].id` | `string` | Não | | | `data[].steps[].version` | `integer` | Não | | | `data[].steps[].dayNumber` | `integer` | Não | Dia da rotina em que a atividade ocorre. | | `data[].steps[].stepOrder` | `integer` | Não | Ordem da atividade dentro do dia. | | `data[].steps[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data[].steps[].quantity` | `integer` | Não | | | `data[].steps[].delayMinutes` | `integer` | Não | | | `data[].steps[].templateId` | `string` | Não | Aceita null. | | `data[].steps[].scriptId` | `string` | Não | Aceita null. | | `data[].steps[].messageRequired` | `boolean` | Não | | | `data[].steps[].description` | `string` | Não | Objetivo da atividade para a pessoa responsável pelo atendimento. Aceita null. | | `data[].steps[].guardrailPrompt` | `string` | Não | Aceita null. | | `data[].enrolledCount` | `integer` | Não | Aceita null. | | `data[].overdueCount` | `integer` | Não | Aceita null. | | `data[].wonCount` | `integer` | Não | Aceita null. | | `data[].lostCount` | `integer` | Não | Aceita null. | | `data[].createdAt` | `string` | Não | Formato: date-time. | | `data[].updatedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CadenceListItem" } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/list-cadence-enrollments/ # Listar matrículas da cadência `GET /api/v1/cadences/{cadenceId}/enrollments` Lista os leads matriculados por cursor. `status` aceita a situação da matrícula (`active`, `paused` e outras) ou o resultado (`won`, `lost`). `day`, `step` e `at` filtram uma posição da régua: `at=reached` inclui quem passou por ela; `at=ended`, quem terminou exatamente nela. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `cadenceId` | path | Sim | `string` | Identificador da cadência. | | `status` | query | Não | `string` | — | | `day` | query | Não | `integer` | — | | `step` | query | Não | `integer` | — | | `at` | query | Não | `string` | — | | `cursor` | query | Não | `string` | — | | `limit` | query | Não | `integer` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].enrollmentId` | `string` | Não | | | `data.items[].dealId` | `string` | Não | | | `data.items[].dealSeq` | `integer` | Não | Obsoleto. Identifique o negócio por `dealId`. | | `data.items[].dealName` | `string` | Não | | | `data.items[].responsibleUserId` | `string` | Não | | | `data.items[].responsibleName` | `string` | Não | Aceita null. | | `data.items[].trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.items[].stageId` | `string` | Não | Aceita null. | | `data.items[].status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.items[].startedAt` | `string` | Não | Formato: date-time. | | `data.items[].outcome` | `string` | Não | Resultado da rotina. Nulo indica que ainda está em andamento ou terminou sem uma regra correspondente. Permite distinguir o resultado dos estados completed, stopped_dnc e stopped_stage_end. Aceita null. | | `data.items[].outcomeLabel` | `string` | Não | Etapa do negócio quando a matrícula foi encerrada, não sua etapa atual. Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CadenceEnrollmentItem" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/get-deal-cadence/ # Consultar cadência do negócio `GET /api/v1/deals/{seq}/cadence` Retorna a instância de cadência do negócio e suas tarefas. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Número sequencial do negócio dentro do workspace. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealCadenceInstance` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.dealSeq` | `integer` | Não | | | `data.cadenceId` | `string` | Não | Aceita null. | | `data.trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.stageId` | `string` | Não | Aceita null. | | `data.cadenceVersion` | `integer` | Não | Aceita null. | | `data.status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.startedAt` | `string` | Não | Formato: date-time. | | `data.pausedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.resumedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stoppedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.pauseReason` | `string` | Não | Aceita null. | | `data.stopReason` | `string` | Não | Aceita null. | | `data.stageCadenceCompleted` | `boolean` | Não | | | `data.workspaceId` | `string` | Não | | | `data.tasks` | `array` | Não | | | `data.tasks[].id` | `string` | Não | | | `data.tasks[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data.tasks[].dayNumber` | `integer` | Não | | | `data.tasks[].stepOrder` | `integer` | Não | | | `data.tasks[].quantity` | `integer` | Não | | | `data.tasks[].attemptCount` | `integer` | Não | | | `data.tasks[].status` | `string` | Não | pending \| due \| done \| overdue \| skipped \| canceled \| blocked | | `data.tasks[].ownerUserId` | `string` | Não | | | `data.tasks[].dueAt` | `string` | Não | Formato: date-time. | | `data.tasks[].doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].overdueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].description` | `string` | Não | Aceita null. | | `data.tasks[].whatsappTemplateName` | `string` | Não | Aceita null. | | `data.tasks[].skipReason` | `string` | Não | Aceita null. | | `data.tasks[].attempts` | `array` | Não | Histórico de tentativas de execução da tarefa. | | `data.tasks[].attempts[].id` | `string` | Não | | | `data.tasks[].attempts[].attemptNumber` | `integer` | Não | | | `data.tasks[].attempts[].channel` | `string` | Não | | | `data.tasks[].attempts[].success` | `boolean` | Não | | | `data.tasks[].attempts[].providerMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].voiceCallId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].emailMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedByUserId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].errorMessage` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealCadenceInstance" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/enroll-deal-cadence/ # Matricular negócio em cadência `POST /api/v1/deals/{seq}/cadence/enroll` Matricula um negócio em uma cadência ativa de seu funil. Pode começar em um dia específico; dias anteriores não geram atividades. Substitui a cadência anterior do negócio. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Corpo da requisição Content-Type: `application/json` ```json { "cadenceId": "ID_DA_CADENCIA" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `cadenceId` | `string` | Sim | Identificador de uma cadência ativa do funil do negócio. | | `startDay` | `integer` | Não | Dia inicial da cadência. Dias anteriores não geram atividades. Use para matricular um lead que já avançou na rotina. Omitir começa pelo início. Aceita null. Mínimo: 0. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealCadenceInstance` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.dealSeq` | `integer` | Não | | | `data.cadenceId` | `string` | Não | Aceita null. | | `data.trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.stageId` | `string` | Não | Aceita null. | | `data.cadenceVersion` | `integer` | Não | Aceita null. | | `data.status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.startedAt` | `string` | Não | Formato: date-time. | | `data.pausedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.resumedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stoppedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.pauseReason` | `string` | Não | Aceita null. | | `data.stopReason` | `string` | Não | Aceita null. | | `data.stageCadenceCompleted` | `boolean` | Não | | | `data.workspaceId` | `string` | Não | | | `data.tasks` | `array` | Não | | | `data.tasks[].id` | `string` | Não | | | `data.tasks[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data.tasks[].dayNumber` | `integer` | Não | | | `data.tasks[].stepOrder` | `integer` | Não | | | `data.tasks[].quantity` | `integer` | Não | | | `data.tasks[].attemptCount` | `integer` | Não | | | `data.tasks[].status` | `string` | Não | pending \| due \| done \| overdue \| skipped \| canceled \| blocked | | `data.tasks[].ownerUserId` | `string` | Não | | | `data.tasks[].dueAt` | `string` | Não | Formato: date-time. | | `data.tasks[].doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].overdueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].description` | `string` | Não | Aceita null. | | `data.tasks[].whatsappTemplateName` | `string` | Não | Aceita null. | | `data.tasks[].skipReason` | `string` | Não | Aceita null. | | `data.tasks[].attempts` | `array` | Não | Histórico de tentativas de execução da tarefa. | | `data.tasks[].attempts[].id` | `string` | Não | | | `data.tasks[].attempts[].attemptNumber` | `integer` | Não | | | `data.tasks[].attempts[].channel` | `string` | Não | | | `data.tasks[].attempts[].success` | `boolean` | Não | | | `data.tasks[].attempts[].providerMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].voiceCallId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].emailMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedByUserId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].errorMessage` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealCadenceInstance" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/unenroll-deal-cadence/ # Remover negócio da cadência `POST /api/v1/deals/{seq}/cadence/unenroll` Interrompe a instância de cadência do negócio, cancela suas tarefas abertas e retorna a instância parada. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealCadenceInstance` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.dealSeq` | `integer` | Não | | | `data.cadenceId` | `string` | Não | Aceita null. | | `data.trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.stageId` | `string` | Não | Aceita null. | | `data.cadenceVersion` | `integer` | Não | Aceita null. | | `data.status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.startedAt` | `string` | Não | Formato: date-time. | | `data.pausedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.resumedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stoppedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.pauseReason` | `string` | Não | Aceita null. | | `data.stopReason` | `string` | Não | Aceita null. | | `data.stageCadenceCompleted` | `boolean` | Não | | | `data.workspaceId` | `string` | Não | | | `data.tasks` | `array` | Não | | | `data.tasks[].id` | `string` | Não | | | `data.tasks[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data.tasks[].dayNumber` | `integer` | Não | | | `data.tasks[].stepOrder` | `integer` | Não | | | `data.tasks[].quantity` | `integer` | Não | | | `data.tasks[].attemptCount` | `integer` | Não | | | `data.tasks[].status` | `string` | Não | pending \| due \| done \| overdue \| skipped \| canceled \| blocked | | `data.tasks[].ownerUserId` | `string` | Não | | | `data.tasks[].dueAt` | `string` | Não | Formato: date-time. | | `data.tasks[].doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].overdueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].description` | `string` | Não | Aceita null. | | `data.tasks[].whatsappTemplateName` | `string` | Não | Aceita null. | | `data.tasks[].skipReason` | `string` | Não | Aceita null. | | `data.tasks[].attempts` | `array` | Não | Histórico de tentativas de execução da tarefa. | | `data.tasks[].attempts[].id` | `string` | Não | | | `data.tasks[].attempts[].attemptNumber` | `integer` | Não | | | `data.tasks[].attempts[].channel` | `string` | Não | | | `data.tasks[].attempts[].success` | `boolean` | Não | | | `data.tasks[].attempts[].providerMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].voiceCallId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].emailMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedByUserId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].errorMessage` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealCadenceInstance" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/pause-deal-cadence/ # Pausar cadência do negócio `POST /api/v1/deals/{seq}/cadence/pause` Pausa a instância de cadência do negócio. Sem corpo, usa o motivo padrão. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Corpo da requisição Content-Type: `application/json` ```json { "reason": "Aguardando retorno do contato" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `reason` | `string` | Não | Motivo em texto livre. Sem corpo, pausa com o motivo padrão. Aceita null. Até 255 caracteres. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealCadenceInstance` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.dealSeq` | `integer` | Não | | | `data.cadenceId` | `string` | Não | Aceita null. | | `data.trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.stageId` | `string` | Não | Aceita null. | | `data.cadenceVersion` | `integer` | Não | Aceita null. | | `data.status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.startedAt` | `string` | Não | Formato: date-time. | | `data.pausedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.resumedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stoppedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.pauseReason` | `string` | Não | Aceita null. | | `data.stopReason` | `string` | Não | Aceita null. | | `data.stageCadenceCompleted` | `boolean` | Não | | | `data.workspaceId` | `string` | Não | | | `data.tasks` | `array` | Não | | | `data.tasks[].id` | `string` | Não | | | `data.tasks[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data.tasks[].dayNumber` | `integer` | Não | | | `data.tasks[].stepOrder` | `integer` | Não | | | `data.tasks[].quantity` | `integer` | Não | | | `data.tasks[].attemptCount` | `integer` | Não | | | `data.tasks[].status` | `string` | Não | pending \| due \| done \| overdue \| skipped \| canceled \| blocked | | `data.tasks[].ownerUserId` | `string` | Não | | | `data.tasks[].dueAt` | `string` | Não | Formato: date-time. | | `data.tasks[].doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].overdueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].description` | `string` | Não | Aceita null. | | `data.tasks[].whatsappTemplateName` | `string` | Não | Aceita null. | | `data.tasks[].skipReason` | `string` | Não | Aceita null. | | `data.tasks[].attempts` | `array` | Não | Histórico de tentativas de execução da tarefa. | | `data.tasks[].attempts[].id` | `string` | Não | | | `data.tasks[].attempts[].attemptNumber` | `integer` | Não | | | `data.tasks[].attempts[].channel` | `string` | Não | | | `data.tasks[].attempts[].success` | `boolean` | Não | | | `data.tasks[].attempts[].providerMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].voiceCallId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].emailMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedByUserId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].errorMessage` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealCadenceInstance" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/resume-deal-cadence/ # Retomar cadência do negócio `POST /api/v1/deals/{seq}/cadence/resume` Retoma a instância de cadência e retorna o resultado. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealCadenceInstance` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.dealSeq` | `integer` | Não | | | `data.cadenceId` | `string` | Não | Aceita null. | | `data.trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.stageId` | `string` | Não | Aceita null. | | `data.cadenceVersion` | `integer` | Não | Aceita null. | | `data.status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.startedAt` | `string` | Não | Formato: date-time. | | `data.pausedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.resumedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stoppedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.pauseReason` | `string` | Não | Aceita null. | | `data.stopReason` | `string` | Não | Aceita null. | | `data.stageCadenceCompleted` | `boolean` | Não | | | `data.workspaceId` | `string` | Não | | | `data.tasks` | `array` | Não | | | `data.tasks[].id` | `string` | Não | | | `data.tasks[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data.tasks[].dayNumber` | `integer` | Não | | | `data.tasks[].stepOrder` | `integer` | Não | | | `data.tasks[].quantity` | `integer` | Não | | | `data.tasks[].attemptCount` | `integer` | Não | | | `data.tasks[].status` | `string` | Não | pending \| due \| done \| overdue \| skipped \| canceled \| blocked | | `data.tasks[].ownerUserId` | `string` | Não | | | `data.tasks[].dueAt` | `string` | Não | Formato: date-time. | | `data.tasks[].doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].overdueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].description` | `string` | Não | Aceita null. | | `data.tasks[].whatsappTemplateName` | `string` | Não | Aceita null. | | `data.tasks[].skipReason` | `string` | Não | Aceita null. | | `data.tasks[].attempts` | `array` | Não | Histórico de tentativas de execução da tarefa. | | `data.tasks[].attempts[].id` | `string` | Não | | | `data.tasks[].attempts[].attemptNumber` | `integer` | Não | | | `data.tasks[].attempts[].channel` | `string` | Não | | | `data.tasks[].attempts[].success` | `boolean` | Não | | | `data.tasks[].attempts[].providerMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].voiceCallId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].emailMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedByUserId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].errorMessage` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealCadenceInstance" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/start-deal-cadence/ # Iniciar cadência do negócio `POST /api/v1/deals/{seq}/cadence/start` Inicia a instância de cadência e retorna o resultado. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealCadenceInstance` | Não | | | `data.id` | `string` | Não | | | `data.dealId` | `string` | Não | | | `data.dealSeq` | `integer` | Não | | | `data.cadenceId` | `string` | Não | Aceita null. | | `data.trackType` | `string` | Não | Valores: entry, stage_playbook, none. | | `data.stageId` | `string` | Não | Aceita null. | | `data.cadenceVersion` | `integer` | Não | Aceita null. | | `data.status` | `string` | Não | active \| paused \| completed \| stopped_dnc \| stopped_stage_end | | `data.startedAt` | `string` | Não | Formato: date-time. | | `data.pausedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.resumedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.stoppedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.pauseReason` | `string` | Não | Aceita null. | | `data.stopReason` | `string` | Não | Aceita null. | | `data.stageCadenceCompleted` | `boolean` | Não | | | `data.workspaceId` | `string` | Não | | | `data.tasks` | `array` | Não | | | `data.tasks[].id` | `string` | Não | | | `data.tasks[].channel` | `string` | Não | Valores: whatsapp, voice_call, email, research. | | `data.tasks[].dayNumber` | `integer` | Não | | | `data.tasks[].stepOrder` | `integer` | Não | | | `data.tasks[].quantity` | `integer` | Não | | | `data.tasks[].attemptCount` | `integer` | Não | | | `data.tasks[].status` | `string` | Não | pending \| due \| done \| overdue \| skipped \| canceled \| blocked | | `data.tasks[].ownerUserId` | `string` | Não | | | `data.tasks[].dueAt` | `string` | Não | Formato: date-time. | | `data.tasks[].doneAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].overdueAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.tasks[].description` | `string` | Não | Aceita null. | | `data.tasks[].whatsappTemplateName` | `string` | Não | Aceita null. | | `data.tasks[].skipReason` | `string` | Não | Aceita null. | | `data.tasks[].attempts` | `array` | Não | Histórico de tentativas de execução da tarefa. | | `data.tasks[].attempts[].id` | `string` | Não | | | `data.tasks[].attempts[].attemptNumber` | `integer` | Não | | | `data.tasks[].attempts[].channel` | `string` | Não | | | `data.tasks[].attempts[].success` | `boolean` | Não | | | `data.tasks[].attempts[].providerMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].voiceCallId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].emailMessageId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedByUserId` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].errorMessage` | `string` | Não | Aceita null. | | `data.tasks[].attempts[].executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealCadenceInstance" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/execute-cadence-task/ # Executar tarefa de cadência `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/execute` Envia a tarefa ao provedor do canal e retorna o resultado. **Esta operação envia de fato** WhatsApp, e-mail ou chamada externa e pode gerar cobrança no workspace. `idempotencyKey` é obrigatória; repetir a mesma chave retorna `duplicated: true`, sem novo envio. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | | `taskId` | path | Sim | `string` | Identificador da tarefa de cadência. | ## Corpo da requisição Content-Type: `application/json` ```json { "idempotencyKey": "envio-negocio-123-tarefa-456-v1", "message": "Olá, Ana. Podemos retomar a proposta?" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `idempotencyKey` | `string` | Sim | Chave escolhida pelo cliente para repetir o envio com segurança. Repetir a mesma chave retorna `duplicated: true`, sem novo envio. Informe-a em toda chamada, inclusive na primeira tentativa. Até 120 caracteres. | | `message` | `string` | Não | Corpo de uma etapa de WhatsApp. Aceita null. Até 4000 caracteres. | | `subject` | `string` | Não | Assunto de uma etapa de e-mail. Aceita null. Até 160 caracteres. | | `htmlBody` | `string` | Não | Corpo HTML de uma etapa de e-mail. Aceita null. Até 10000 caracteres. | | `textBody` | `string` | Não | Corpo em texto simples de uma etapa de e-mail. Aceita null. Até 4000 caracteres. | | `manualReferenceId` | `string` | Não | Referência da tentativa definida pelo cliente. Aceita null. Até 120 caracteres. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `TaskExecution` | Não | | | `data.ok` | `boolean` | Não | | | `data.duplicated` | `boolean` | Não | Verdadeiro quando a mesma execução já estava registrada. | | `data.taskStatus` | `string` | Não | | | `data.attemptNumber` | `integer` | Não | | | `data.attemptId` | `string` | Não | Aceita null. | | `data.providerMessageId` | `string` | Não | Aceita null. | | `data.voiceCallId` | `string` | Não | Aceita null. | | `data.emailMessageId` | `string` | Não | Aceita null. | | `data.idempotencyKey` | `string` | Não | Aceita null. | | `data.executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskExecution" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/skip-cadence-task/ # Pular tarefa de cadência `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/skip` Pula uma tarefa de cadência. Altera apenas o estado da tarefa, sem envio ao canal. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | | `taskId` | path | Sim | `string` | Identificador da tarefa de cadência. | ## Corpo da requisição Content-Type: `application/json` ```json { "reason": "Atividade tratada por outro canal" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `reason` | `string` | Sim | Motivo para pular a tarefa. Até 255 caracteres. | ## Respostas ### 204 Sem conteúdo ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/cadences/methods/complete-cadence-task-manually/ # Concluir tarefa de cadência manualmente `POST /api/v1/deals/{seq}/cadence/tasks/{taskId}/complete-manual` Marca a tarefa como concluída manualmente e retorna o resultado. Altera apenas o estado, sem envio ao canal. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | — | | `taskId` | path | Sim | `string` | Identificador da tarefa de cadência. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `TaskExecution` | Não | | | `data.ok` | `boolean` | Não | | | `data.duplicated` | `boolean` | Não | Verdadeiro quando a mesma execução já estava registrada. | | `data.taskStatus` | `string` | Não | | | `data.attemptNumber` | `integer` | Não | | | `data.attemptId` | `string` | Não | Aceita null. | | `data.providerMessageId` | `string` | Não | Aceita null. | | `data.voiceCallId` | `string` | Não | Aceita null. | | `data.emailMessageId` | `string` | Não | Aceita null. | | `data.idempotencyKey` | `string` | Não | Aceita null. | | `data.executedAt` | `string` | Não | Formato: date-time. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TaskExecution" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 409 Conflito de estado, como um negócio aberto duplicado para o contato/funil, ou limite do plano atingido (`QUOTA_EXCEEDED`), como na criação de um funil além da cota. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/list-automations/ # Listar automações `GET /api/v1/automations` Retorna todas as automações do workspace, das mais recentes às mais antigas. Não usa paginação. Os filtros são opcionais e combinados; valores desconhecidos de `scope` ou `triggerType` são ignorados. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `pipelineId` | query | Não | `string` | — | | `stageId` | query | Não | `string` | — | | `scope` | query | Não | `string` | — | | `triggerType` | query | Não | `string` | — | | `enabled` | query | Não | `boolean` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `array` | Não | | | `data[].id` | `string` | Não | | | `data[].name` | `string` | Não | | | `data[].version` | `integer` | Não | Versão da definição. A troca de enabled não incrementa a versão. | | `data[].enabled` | `boolean` | Não | | | `data[].triggerType` | `string` | Não | | | `data[].scope` | `string` | Não | Valores: global, pipeline, stage. | | `data[].pipelineId` | `string` | Não | Aceita null. | | `data[].stageId` | `string` | Não | Aceita null. | | `data[].outboundChannelId` | `string` | Não | Aceita null. | | `data[].respectBusinessHours` | `boolean` | Não | | | `data[].triggerWindow` | `object` | Não | Aceita null. | | `data[].conditions` | `object` | Não | Aceita null. | | `data[].triggerConfig` | `object` | Não | As credenciais de webhook (headerValue, password) são removidas. Aceita null. | | `data[].graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `data[].graphDefinition.version` | `integer` | Sim | Valores: 2. | | `data[].graphDefinition.nodes` | `array` | Sim | | | `data[].graphDefinition.nodes[].id` | `string` | Sim | | | `data[].graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `data[].graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `data[].graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `data[].graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `data[].graphDefinition.edges` | `array` | Não | | | `data[].graphDefinition.edges[].id` | `string` | Não | | | `data[].graphDefinition.edges[].source` | `string` | Sim | | | `data[].graphDefinition.edges[].target` | `string` | Sim | | | `data[].graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `data[].actions` | `array` | Não | | | `data[].actions[].id` | `string` | Não | ID da ação. As ações são substituídas na atualização, não alteradas individualmente. | | `data[].actions[].type` | `string` | Não | | | `data[].actions[].order` | `integer` | Não | | | `data[].actions[].config` | `object` | Não | O secret do webhook é removido. | | `data[].createdAt` | `string` | Não | Formato: date-time. | | `data[].updatedAt` | `string` | Não | Formato: date-time. | | `data[].secret` | `string` | Não | Presente somente na resposta de criação ou substituição que gerou o segredo. Nunca aparece na leitura. Salve-o: assina X-PipeFacil-Signature-256 e não pode ser consultado depois. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/create-automation/ # Criar automação `POST /api/v1/automations` Cria um fluxo a partir de `graphDefinition`, cuja `version` deve ser `2`. Valida todo o grafo antes de salvar e retorna os problemas encontrados em conjunto. Omitir `enabled` cria a automação **ativa**, pronta para reagir ao gatilho. Uma ação de webhook sem `secret` recebe um segredo gerado, mostrado uma única vez nesta resposta. Exige `automations.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Fluxo manual de exemplo", "triggerType": "manual", "scope": "global", "enabled": false, "graphDefinition": { "version": 2, "nodes": [ { "id": "inicio", "type": "trigger" }, { "id": "fim", "type": "end" } ], "edges": [ { "id": "inicio-fim", "source": "inicio", "target": "fim", "sourceHandle": "next" } ] } } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 255 caracteres. | | `triggerType` | `string` | Sim | Um dos valores de `GET /api/v1/automations/triggers`. Valores: deal_created, deal_stage_changed, deal_won, deal_lost, deal_assigned, message_received, conversation_closed, contact_no_reply, team_no_reply, field_filled, timer, instagram_comment_received, manual, webhook. | | `scope` | `string` | Sim | Valores: global, pipeline, stage. | | `pipelineId` | `string` | Não | Aceita null. | | `stageId` | `string` | Não | Aceita null. | | `outboundChannelId` | `string` | Não | Não existe rota pública para listar canais; obtenha o identificador por outro meio. Aceita null. | | `graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `graphDefinition.version` | `integer` | Sim | Valores: 2. | | `graphDefinition.nodes` | `array` | Sim | | | `graphDefinition.nodes[].id` | `string` | Sim | | | `graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `graphDefinition.edges` | `array` | Não | | | `graphDefinition.edges[].id` | `string` | Não | | | `graphDefinition.edges[].source` | `string` | Sim | | | `graphDefinition.edges[].target` | `string` | Sim | | | `graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `respectBusinessHours` | `boolean` | Não | Aceita null. | | `triggerWindow` | `object` | Não | Aceita null. | | `conditions` | `object` | Não | Aceita null. | | `triggerConfig` | `object` | Não | O formato depende de triggerType. field_filled usa {fieldSlug, fillMode}; timer aceita {mode: date_field, dateFieldSlug, offsetMinutes, onPastDate} ou {mode: recurring, cron}; contact_no_reply e team_no_reply usam {timeoutSeconds} entre 60 e 2592000; webhook usa {path, httpMethod, authentication e outras propriedades}. Aceita null. | | `enabled` | `boolean` | Não | Na criação, omitir significa **true**: o fluxo começa a reagir aos gatilhos. Na substituição, omitir preserva o estado atual. Aceita null. | | `actions` | `array` | Não | Ações do formato legado. Para novos fluxos, use graphDefinition. Aceita null. | | `actions[].type` | `string` | Não | Tipo de ação legado. | | `actions[].order` | `integer` | Não | | | `actions[].config` | `object` | Não | | | `webhookUrl` | `string` | Não | URL de webhook do formato legado. Aceita null. | | `webhookHeaders` | `object` | Não | Cabeçalhos de webhook do formato legado. Aceita null. | ## Respostas ### 201 Criado | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Automation` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.version` | `integer` | Não | Versão da definição. A troca de enabled não incrementa a versão. | | `data.enabled` | `boolean` | Não | | | `data.triggerType` | `string` | Não | | | `data.scope` | `string` | Não | Valores: global, pipeline, stage. | | `data.pipelineId` | `string` | Não | Aceita null. | | `data.stageId` | `string` | Não | Aceita null. | | `data.outboundChannelId` | `string` | Não | Aceita null. | | `data.respectBusinessHours` | `boolean` | Não | | | `data.triggerWindow` | `object` | Não | Aceita null. | | `data.conditions` | `object` | Não | Aceita null. | | `data.triggerConfig` | `object` | Não | As credenciais de webhook (headerValue, password) são removidas. Aceita null. | | `data.graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `data.graphDefinition.version` | `integer` | Sim | Valores: 2. | | `data.graphDefinition.nodes` | `array` | Sim | | | `data.graphDefinition.nodes[].id` | `string` | Sim | | | `data.graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `data.graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `data.graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `data.graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `data.graphDefinition.edges` | `array` | Não | | | `data.graphDefinition.edges[].id` | `string` | Não | | | `data.graphDefinition.edges[].source` | `string` | Sim | | | `data.graphDefinition.edges[].target` | `string` | Sim | | | `data.graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `data.actions` | `array` | Não | | | `data.actions[].id` | `string` | Não | ID da ação. As ações são substituídas na atualização, não alteradas individualmente. | | `data.actions[].type` | `string` | Não | | | `data.actions[].order` | `integer` | Não | | | `data.actions[].config` | `object` | Não | O secret do webhook é removido. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.secret` | `string` | Não | Presente somente na resposta de criação ou substituição que gerou o segredo. Nunca aparece na leitura. Salve-o: assina X-PipeFacil-Signature-256 e não pode ser consultado depois. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Automation" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/list-automation-triggers/ # Listar catálogo de gatilhos `GET /api/v1/automations/triggers` Retorna os gatilhos aceitos, agrupados por categoria, e os caminhos de campos válidos para condições. Consulte o catálogo antes de definir `triggerType` e os nós de condição de um fluxo. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `AutomationTriggerCatalog` | Não | | | `data.categories` | `array` | Não | | | `data.categories[].category` | `string` | Não | | | `data.categories[].label` | `string` | Não | | | `data.categories[].options` | `array` | Não | | | `data.categories[].options[].value` | `string` | Não | Valor aceito em triggerType. | | `data.categories[].options[].label` | `string` | Não | | | `data.categories[].options[].conditionFields` | `array` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationTriggerCatalog" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/get-automation/ # Consultar automação `GET /api/v1/automations/{id}` Retorna uma automação com seu grafo e suas ações. Remove os segredos de webhook das configurações de ações, nós e gatilho. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Automation` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.version` | `integer` | Não | Versão da definição. A troca de enabled não incrementa a versão. | | `data.enabled` | `boolean` | Não | | | `data.triggerType` | `string` | Não | | | `data.scope` | `string` | Não | Valores: global, pipeline, stage. | | `data.pipelineId` | `string` | Não | Aceita null. | | `data.stageId` | `string` | Não | Aceita null. | | `data.outboundChannelId` | `string` | Não | Aceita null. | | `data.respectBusinessHours` | `boolean` | Não | | | `data.triggerWindow` | `object` | Não | Aceita null. | | `data.conditions` | `object` | Não | Aceita null. | | `data.triggerConfig` | `object` | Não | As credenciais de webhook (headerValue, password) são removidas. Aceita null. | | `data.graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `data.graphDefinition.version` | `integer` | Sim | Valores: 2. | | `data.graphDefinition.nodes` | `array` | Sim | | | `data.graphDefinition.nodes[].id` | `string` | Sim | | | `data.graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `data.graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `data.graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `data.graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `data.graphDefinition.edges` | `array` | Não | | | `data.graphDefinition.edges[].id` | `string` | Não | | | `data.graphDefinition.edges[].source` | `string` | Sim | | | `data.graphDefinition.edges[].target` | `string` | Sim | | | `data.graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `data.actions` | `array` | Não | | | `data.actions[].id` | `string` | Não | ID da ação. As ações são substituídas na atualização, não alteradas individualmente. | | `data.actions[].type` | `string` | Não | | | `data.actions[].order` | `integer` | Não | | | `data.actions[].config` | `object` | Não | O secret do webhook é removido. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.secret` | `string` | Não | Presente somente na resposta de criação ou substituição que gerou o segredo. Nunca aparece na leitura. Salve-o: assina X-PipeFacil-Signature-256 e não pode ser consultado depois. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Automation" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/replace-automation/ # Substituir automação `PUT /api/v1/automations/{id}` Substitui toda a definição. Campos ausentes são redefinidos, as ações recebem novos identificadores e `version` é incrementada. A exceção é `enabled`: omitir preserva o estado atual. Para alterar somente o estado, use `PATCH /{id}/enabled`. Exige `automations.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | ## Corpo da requisição Content-Type: `application/json` ```json { "name": "Fluxo manual de exemplo", "triggerType": "manual", "scope": "global", "enabled": false, "graphDefinition": { "version": 2, "nodes": [ { "id": "inicio", "type": "trigger" }, { "id": "fim", "type": "end" } ], "edges": [ { "id": "inicio-fim", "source": "inicio", "target": "fim", "sourceHandle": "next" } ] } } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `name` | `string` | Sim | Até 255 caracteres. | | `triggerType` | `string` | Sim | Um dos valores de `GET /api/v1/automations/triggers`. Valores: deal_created, deal_stage_changed, deal_won, deal_lost, deal_assigned, message_received, conversation_closed, contact_no_reply, team_no_reply, field_filled, timer, instagram_comment_received, manual, webhook. | | `scope` | `string` | Sim | Valores: global, pipeline, stage. | | `pipelineId` | `string` | Não | Aceita null. | | `stageId` | `string` | Não | Aceita null. | | `outboundChannelId` | `string` | Não | Não existe rota pública para listar canais; obtenha o identificador por outro meio. Aceita null. | | `graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `graphDefinition.version` | `integer` | Sim | Valores: 2. | | `graphDefinition.nodes` | `array` | Sim | | | `graphDefinition.nodes[].id` | `string` | Sim | | | `graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `graphDefinition.edges` | `array` | Não | | | `graphDefinition.edges[].id` | `string` | Não | | | `graphDefinition.edges[].source` | `string` | Sim | | | `graphDefinition.edges[].target` | `string` | Sim | | | `graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `respectBusinessHours` | `boolean` | Não | Aceita null. | | `triggerWindow` | `object` | Não | Aceita null. | | `conditions` | `object` | Não | Aceita null. | | `triggerConfig` | `object` | Não | O formato depende de triggerType. field_filled usa {fieldSlug, fillMode}; timer aceita {mode: date_field, dateFieldSlug, offsetMinutes, onPastDate} ou {mode: recurring, cron}; contact_no_reply e team_no_reply usam {timeoutSeconds} entre 60 e 2592000; webhook usa {path, httpMethod, authentication e outras propriedades}. Aceita null. | | `enabled` | `boolean` | Não | Na criação, omitir significa **true**: o fluxo começa a reagir aos gatilhos. Na substituição, omitir preserva o estado atual. Aceita null. | | `actions` | `array` | Não | Ações do formato legado. Para novos fluxos, use graphDefinition. Aceita null. | | `actions[].type` | `string` | Não | Tipo de ação legado. | | `actions[].order` | `integer` | Não | | | `actions[].config` | `object` | Não | | | `webhookUrl` | `string` | Não | URL de webhook do formato legado. Aceita null. | | `webhookHeaders` | `object` | Não | Cabeçalhos de webhook do formato legado. Aceita null. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Automation` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.version` | `integer` | Não | Versão da definição. A troca de enabled não incrementa a versão. | | `data.enabled` | `boolean` | Não | | | `data.triggerType` | `string` | Não | | | `data.scope` | `string` | Não | Valores: global, pipeline, stage. | | `data.pipelineId` | `string` | Não | Aceita null. | | `data.stageId` | `string` | Não | Aceita null. | | `data.outboundChannelId` | `string` | Não | Aceita null. | | `data.respectBusinessHours` | `boolean` | Não | | | `data.triggerWindow` | `object` | Não | Aceita null. | | `data.conditions` | `object` | Não | Aceita null. | | `data.triggerConfig` | `object` | Não | As credenciais de webhook (headerValue, password) são removidas. Aceita null. | | `data.graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `data.graphDefinition.version` | `integer` | Sim | Valores: 2. | | `data.graphDefinition.nodes` | `array` | Sim | | | `data.graphDefinition.nodes[].id` | `string` | Sim | | | `data.graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `data.graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `data.graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `data.graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `data.graphDefinition.edges` | `array` | Não | | | `data.graphDefinition.edges[].id` | `string` | Não | | | `data.graphDefinition.edges[].source` | `string` | Sim | | | `data.graphDefinition.edges[].target` | `string` | Sim | | | `data.graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `data.actions` | `array` | Não | | | `data.actions[].id` | `string` | Não | ID da ação. As ações são substituídas na atualização, não alteradas individualmente. | | `data.actions[].type` | `string` | Não | | | `data.actions[].order` | `integer` | Não | | | `data.actions[].config` | `object` | Não | O secret do webhook é removido. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.secret` | `string` | Não | Presente somente na resposta de criação ou substituição que gerou o segredo. Nunca aparece na leitura. Salve-o: assina X-PipeFacil-Signature-256 e não pode ser consultado depois. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Automation" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/delete-automation/ # Excluir automação `DELETE /api/v1/automations/{id}` Exclui permanentemente a automação, sem restauração, e cancela execuções agendadas pendentes. Para preservar o fluxo, desative-o. Exige `automations.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | ## Respostas ### 204 Sem conteúdo ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/set-automation-enabled/ # Ativar ou desativar automação `PATCH /api/v1/automations/{id}/enabled` Altera somente `enabled`, preservando definição, versão e identificadores de ações. Desativar faz execuções na fila ou em espera serem ignoradas quando chega sua vez, mas não as cancela. Reativar antes do prazo permite a continuação. O corpo deve informar `enabled`; repetir a mesma requisição mantém o estado solicitado. Operação idempotente. Exige `automations.edit`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | ## Corpo da requisição Content-Type: `application/json` ```json { "enabled": false } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `enabled` | `boolean` | Sim | | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `Automation` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.version` | `integer` | Não | Versão da definição. A troca de enabled não incrementa a versão. | | `data.enabled` | `boolean` | Não | | | `data.triggerType` | `string` | Não | | | `data.scope` | `string` | Não | Valores: global, pipeline, stage. | | `data.pipelineId` | `string` | Não | Aceita null. | | `data.stageId` | `string` | Não | Aceita null. | | `data.outboundChannelId` | `string` | Não | Aceita null. | | `data.respectBusinessHours` | `boolean` | Não | | | `data.triggerWindow` | `object` | Não | Aceita null. | | `data.conditions` | `object` | Não | Aceita null. | | `data.triggerConfig` | `object` | Não | As credenciais de webhook (headerValue, password) são removidas. Aceita null. | | `data.graphDefinition` | `AutomationGraph` | Não | Grafo do fluxo: até 50 nós e 30 esperas, exatamente um nó trigger, sem ciclos e com todos os nós alcançáveis pelo gatilho. Cada tipo tem regras de saída: condition exige uma aresta branch_ por ramo; round_robin, uma rr_ por saída; end não permite saída. A validação retorna todos os problemas em conjunto. | | `data.graphDefinition.version` | `integer` | Sim | Valores: 2. | | `data.graphDefinition.nodes` | `array` | Sim | | | `data.graphDefinition.nodes[].id` | `string` | Sim | | | `data.graphDefinition.nodes[].type` | `string` | Sim | Valores: trigger, action, condition, wait, round_robin, end. | | `data.graphDefinition.nodes[].actionType` | `string` | Não | Valores: webhook, send_whatsapp, move_stage, add_tag, remove_tag, set_custom_field, wait, create_task, assign_responsible, add_co_owner, send_meta_conversion, create_lead, send_email, reply_instagram_comment, send_instagram_private_reply, hide_instagram_comment, cia_deal_analysis, create_calendar_event, close_conversation, stop_automations. Aceita null. | | `data.graphDefinition.nodes[].config` | `object` | Não | As propriedades obrigatórias dependem de actionType: webhook exige url; move_stage exige targetStageId; add_tag/remove_tag exigem tagIds não vazio; set_custom_field exige exatamente um entre fieldId e fieldSlug, além de value; assign_responsible exige userId; wait exige delaySeconds, com mínimo de 5. | | `data.graphDefinition.nodes[].condition` | `object` | Não | Aceita null. | | `data.graphDefinition.edges` | `array` | Não | | | `data.graphDefinition.edges[].id` | `string` | Não | | | `data.graphDefinition.edges[].source` | `string` | Sim | | | `data.graphDefinition.edges[].target` | `string` | Sim | | | `data.graphDefinition.edges[].sourceHandle` | `string` | Não | `next`, `fallback`, `branch_`, `rr_`, `btn_`, `replied`, `timeout` ou `text_reply`. | | `data.actions` | `array` | Não | | | `data.actions[].id` | `string` | Não | ID da ação. As ações são substituídas na atualização, não alteradas individualmente. | | `data.actions[].type` | `string` | Não | | | `data.actions[].order` | `integer` | Não | | | `data.actions[].config` | `object` | Não | O secret do webhook é removido. | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.updatedAt` | `string` | Não | Formato: date-time. | | `data.secret` | `string` | Não | Presente somente na resposta de criação ou substituição que gerou o segredo. Nunca aparece na leitura. Salve-o: assina X-PipeFacil-Signature-256 e não pode ser consultado depois. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Automation" }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/test-automation/ # Pré-visualizar entrega de webhook `POST /api/v1/automations/{id}/test` **Não envia nada.** Retorna URL, cabeçalhos e corpo que a primeira ação de webhook entregaria para um evento de exemplo `deal.stage_changed`, com uma assinatura real `X-PipeFacil-Signature-256` calculada pelo segredo atual. Use para verificar o receptor. Exige `automations.edit`, pois utiliza o segredo. Sem uma ação de webhook, responde `422`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `AutomationTest` | Não | Entrega que seria enviada. Nada é enviado por esta operação. | | `data.url` | `string` | Não | Aceita null. | | `data.headers` | `object` | Não | Inclui a assinatura real X-PipeFacil-Signature-256 do body. | | `data.body` | `string` | Não | Corpo serializado de um evento de exemplo deal.stage_changed. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationTest" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 422 Requisição válida que o recurso não pode atender, por exemplo, um identificador de calendário que não representa uma reunião nativa. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/list-automation-logs/ # Listar logs da automação `GET /api/v1/automations/{id}/logs` Logs dos nós executados, por cursor e dos mais recentes aos mais antigos. Cada entrada inclui `input` e `output`, permitindo entender o caminho escolhido. Os segredos são removidos em todos os níveis. `limit` padrão: 20; máximo: 100. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].runId` | `string` | Não | | | `data.items[].dealId` | `string` | Não | Aceita null. | | `data.items[].actionId` | `string` | Não | Aceita null. | | `data.items[].actionType` | `string` | Não | | | `data.items[].status` | `string` | Não | | | `data.items[].input` | `object` | Não | Aceita null. | | `data.items[].output` | `object` | Não | Aceita null. | | `data.items[].error` | `string` | Não | Aceita null. | | `data.items[].automationVersion` | `integer` | Não | | | `data.items[].chainId` | `string` | Não | Aceita null. | | `data.items[].triggerDepth` | `integer` | Não | | | `data.items[].startedAt` | `string` | Não | Formato: date-time. | | `data.items[].completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationLog" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/list-automation-deliveries/ # Listar entregas de webhook `GET /api/v1/automations/{id}/deliveries` Tentativas de entrega das ações de webhook, paginadas por cursor, com status HTTP e último erro. Não retorna o corpo da requisição nem o da resposta. `limit` padrão: 20; máximo: 50. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | — | | `status` | query | Não | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].dealId` | `string` | Não | Aceita null. | | `data.items[].eventType` | `string` | Não | | | `data.items[].status` | `string` | Não | Valores: queued, sent, failed, dead_letter. | | `data.items[].attempts` | `integer` | Não | | | `data.items[].responseStatusCode` | `integer` | Não | Aceita null. | | `data.items[].lastError` | `string` | Não | Aceita null. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationDelivery" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/list-automation-runs/ # Listar execuções da automação `GET /api/v1/automations/{id}/runs` Execuções paginadas por cursor, das mais recentes às mais antigas. Um `status` desconhecido resulta em `400`. Em uma execução `waiting`, o prazo é `nextAttemptAt`; `waitingForReply` distingue a espera por resposta da espera por tempo. `limit` padrão: 20; máximo: 100. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | | `status` | query | Não | `string` | — | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].runId` | `string` | Não | | | `data.items[].dealId` | `string` | Não | Aceita null. | | `data.items[].status` | `string` | Não | Valores: queued, running, waiting, completed, failed, dead_letter, skipped, cancelled. | | `data.items[].triggerType` | `string` | Não | Evento de origem (event_type). | | `data.items[].automationVersion` | `integer` | Não | Versão da definição preservada nesta execução. | | `data.items[].attempts` | `integer` | Não | | | `data.items[].lastError` | `string` | Não | Aceita null. | | `data.items[].currentNodeId` | `string` | Não | Aceita null. | | `data.items[].chainId` | `string` | Não | Aceita null. | | `data.items[].triggerDepth` | `integer` | Não | | | `data.items[].waitingForReply` | `boolean` | Não | Em uma execução waiting, indica se nextAttemptAt é o prazo de resposta em vez do fim de uma espera por tempo. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.items[].startedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].lastAttemptAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].nextAttemptAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRun" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 400 Falha de validação dos campos; `fieldErrors` contém os erros. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/automations/methods/get-automation-run/ # Consultar execução da automação `GET /api/v1/automations/{id}/runs/{runId}` Retorna a execução completa: a definição preservada no momento do disparo, o estado de cada nó e as etapas executadas com entradas e saídas. Essa cópia permite entender uma execução mesmo após alterações no fluxo. Remove segredos em todos os níveis. Uma execução de outra automação resulta em `404`. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | Identificador da automação. | | `runId` | path | Sim | `string` | Identificador da execução da automação. | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `AutomationRunDetail` | Não | | | `data.runId` | `string` | Não | | | `data.automationId` | `string` | Não | | | `data.automationName` | `string` | Não | Aceita null. | | `data.automationVersion` | `integer` | Não | | | `data.dealId` | `string` | Não | Aceita null. | | `data.dealSeq` | `integer` | Não | Número do negócio dentro do workspace. Nulo se não houver negócio ou se ele tiver sido excluído. Aceita null. | | `data.dealName` | `string` | Não | Aceita null. | | `data.status` | `string` | Não | | | `data.eventType` | `string` | Não | Aceita null. | | `data.attempts` | `integer` | Não | | | `data.lastError` | `string` | Não | Aceita null. | | `data.currentNodeId` | `string` | Não | Aceita null. | | `data.chainId` | `string` | Não | Aceita null. | | `data.triggerDepth` | `integer` | Não | | | `data.createdAt` | `string` | Não | Formato: date-time. | | `data.lastAttemptAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.nextAttemptAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.graph` | `object` | Não | Definição preservada no momento do disparo, para explicar a execução mesmo após alterações no fluxo. Segredos removidos. Aceita null. | | `data.nodes` | `array` | Não | Todos os nós do grafo preservado, com o estado alcançado. | | `data.nodes[].nodeId` | `string` | Não | | | `data.nodes[].nodeType` | `string` | Não | Aceita null. | | `data.nodes[].actionType` | `string` | Não | Aceita null. | | `data.nodes[].status` | `string` | Não | Valores: completed, failed, waiting, running, not_reached. | | `data.nodes[].input` | `object` | Não | Aceita null. | | `data.nodes[].output` | `object` | Não | Aceita null. | | `data.nodes[].error` | `string` | Não | Aceita null. | | `data.nodes[].startedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.nodes[].completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.steps` | `array` | Não | Somente os nós realmente executados, em ordem. | | `data.steps[].nodeId` | `string` | Não | | | `data.steps[].nodeType` | `string` | Não | Aceita null. | | `data.steps[].actionType` | `string` | Não | Aceita null. | | `data.steps[].status` | `string` | Não | Valores: completed, failed, waiting, running, not_reached. | | `data.steps[].input` | `object` | Não | Aceita null. | | `data.steps[].output` | `object` | Não | Aceita null. | | `data.steps[].error` | `string` | Não | Aceita null. | | `data.steps[].startedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.steps[].completedAt` | `string` | Não | Formato: date-time. Aceita null. | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AutomationRunDetail" }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/list-workspace-activities/ # Listar atividades do workspace `GET /api/v1/deals/activities` Página de atividades dos negócios visíveis ao membro da chave, pela mais recente. Os filtros de tipo e ator podem ser repetidos ou separados por vírgula. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `type` | query | Não | `array` | Filtro de tipo de atividade; pode ser repetido. | | `actorType` | query | Não | `array` | Filtro de tipo de autor; pode ser repetido. | | `actorUserId` | query | Não | `string` | — | | `limit` | query | Não | `integer` | — | | `cursor` | query | Não | `string` | — | ## Respostas ### 200 Sucesso | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].dealId` | `string` | Não | | | `data.items[].type` | `string` | Não | | | `data.items[].field` | `string` | Não | Aceita null. | | `data.items[].changes` | `object` | Não | Aceita null. | | `data.items[].metadata` | `object` | Não | Aceita null. | | `data.items[].occurredAt` | `string` | Não | Formato: date-time. | | `data.items[].actor` | `object` | Não | Resumo do autor: usuário ou sistema. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | | `message` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DealActivity" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "message": { "type": "string", "nullable": true } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/list-deal-messages/ # Listar mensagens do negócio `GET /api/v1/deals/{seq}/messages` Consulta o histórico de mensagens do contato vinculado ao negócio, respeitando a visibilidade do membro. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Sequência do negócio neste workspace. | | `limit` | query | Não | `integer` | Tamanho da página. | | `cursor` | query | Não | `string` | Cursor opaco da página anterior. | ## Respostas ### 200 Operação concluída. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `object` | Não | | | `data.items` | `array` | Não | | | `data.items[].id` | `string` | Não | | | `data.items[].conversationId` | `string` | Não | | | `data.items[].channelId` | `string` | Não | Aceita null. | | `data.items[].externalId` | `string` | Não | Aceita null. | | `data.items[].direction` | `string` | Não | Valores: inbound, outbound. | | `data.items[].senderPhone` | `string` | Não | Aceita null. | | `data.items[].recipientPhone` | `string` | Não | Aceita null. | | `data.items[].body` | `string` | Não | | | `data.items[].previewText` | `string` | Não | | | `data.items[].type` | `string` | Não | | | `data.items[].status` | `string` | Não | | | `data.items[].read` | `boolean` | Não | | | `data.items[].timestamp` | `string` | Não | Formato: date-time. | | `data.items[].statusTimestamp` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].errorMessage` | `string` | Não | Aceita null. | | `data.items[].quotedText` | `string` | Não | Aceita null. | | `data.items[].quotedDirection` | `string` | Não | Valores: inbound, outbound. Aceita null. | | `data.items[].quotedMessageId` | `string` | Não | Aceita null. | | `data.items[].quotedType` | `string` | Não | Aceita null. | | `data.items[].quotedMedia` | `object` | Não | Aceita null. | | `data.items[].quotedMedia.mediaAssetId` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.status` | `string` | Não | Estado de ingestão da mídia armazenada. Aceita null. | | `data.items[].quotedMedia.mediaType` | `string` | Não | | | `data.items[].quotedMedia.contentType` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.caption` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.filename` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.sizeBytes` | `integer` | Não | Formato: int64. Aceita null. | | `data.items[].quotedMedia.durationMs` | `integer` | Não | Aceita null. | | `data.items[].quotedMedia.width` | `integer` | Não | Aceita null. | | `data.items[].quotedMedia.height` | `integer` | Não | Aceita null. | | `data.items[].quotedMedia.providerMediaId` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.providerMediaUrl` | `string` | Não | Aceita null. | | `data.items[].quotedMedia.contentUrl` | `string` | Não | URL relativa para baixar o arquivo. Nula enquanto a mídia não estiver READY. A cópia do provedor para o armazenamento é assíncrona. Aceita null. | | `data.items[].sentByUserId` | `string` | Não | Aceita null. | | `data.items[].origin` | `string` | Não | Origem da mensagem: api, app, automation, agent ou outra. Aceita null. | | `data.items[].originLabel` | `string` | Não | Aceita null. | | `data.items[].media` | `object` | Não | Aceita null. | | `data.items[].media.mediaAssetId` | `string` | Não | Aceita null. | | `data.items[].media.status` | `string` | Não | Estado de ingestão da mídia armazenada. Aceita null. | | `data.items[].media.mediaType` | `string` | Não | | | `data.items[].media.contentType` | `string` | Não | Aceita null. | | `data.items[].media.caption` | `string` | Não | Aceita null. | | `data.items[].media.filename` | `string` | Não | Aceita null. | | `data.items[].media.sizeBytes` | `integer` | Não | Formato: int64. Aceita null. | | `data.items[].media.durationMs` | `integer` | Não | Aceita null. | | `data.items[].media.width` | `integer` | Não | Aceita null. | | `data.items[].media.height` | `integer` | Não | Aceita null. | | `data.items[].media.providerMediaId` | `string` | Não | Aceita null. | | `data.items[].media.providerMediaUrl` | `string` | Não | Aceita null. | | `data.items[].media.contentUrl` | `string` | Não | URL relativa para baixar o arquivo. Nula enquanto a mídia não estiver READY. A cópia do provedor para o armazenamento é assíncrona. Aceita null. | | `data.items[].content` | `object` | Não | Dados estruturados de tipos sem corpo de texto, como anúncio de origem, localização, cartão de contato ou alvo de reação. Aceita null. | | `data.items[].createdAt` | `string` | Não | Formato: date-time. | | `data.items[].editedAt` | `string` | Não | Formato: date-time. Aceita null. | | `data.items[].deletedAt` | `string` | Não | Data da exclusão. O conteúdo pode permanecer no histórico de auditoria; a integração decide como exibi-lo. Formato: date-time. Aceita null. | | `data.nextCursor` | `string` | Não | Aceita null. | | `data.hasMore` | `boolean` | Não | | ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/get-deal-property-file/ # Obter arquivo de um campo do negócio `GET /api/v1/deals/{seq}/properties/{slug}/file` Retorna o descritor do arquivo e uma URL de download válida por 24 horas, quando a assinatura do armazenamento estiver disponível. Não transfere os bytes do arquivo. Sem arquivo preenchido, retorna 404. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Sequência do negócio neste workspace. | | `slug` | path | Sim | `string` | Slug de um campo personalizado do tipo arquivo. | ## Respostas ### 200 Operação concluída. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `DealPropertyFile` | Não | | | `data.key` | `string` | Não | | | `data.name` | `string` | Não | | | `data.size` | `integer` | Não | Formato: int64. | | `data.mimeType` | `string` | Não | | | `data.downloadUrl` | `string` | Não | Aceita null. | | `data.downloadUrlExpiresAt` | `string` | Não | Formato: date-time. Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DealPropertyFile" } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/deals/methods/upload-deal-property-file/ # Enviar e vincular arquivo ao negócio `POST /api/v1/deals/{seq}/properties/{slug}/file` Envia o arquivo e grava seu descritor no campo do negócio. Exige permissão de editar negócios e um campo do tipo arquivo. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `seq` | path | Sim | `integer` | Sequência do negócio neste workspace. | | `slug` | path | Sim | `string` | Slug de um campo personalizado do tipo arquivo. | ## Corpo da requisição Content-Type: `multipart/form-data` ```json { "file": "" } ``` ### Campos | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `file` | `string` | Sim | Arquivo a enviar. Formato: binary. | ## Respostas ### 201 Operação concluída. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `FileUploadReceipt` | Não | Comprovante do envio de arquivo; associe `key` ao valor de um campo `file_upload`. | | `data.key` | `string` | Não | | | `data.name` | `string` | Não | | | `data.size` | `integer` | Não | Formato: int64. | | `data.mimeType` | `string` | Não | | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FileUploadReceipt" } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` --- Fonte: https://ajuda.matchsales.com.br/api/resources/reference/methods/get-user/ # Consultar membro `GET /api/v1/users/{id}` Retorna os dados de um usuário que é membro ativo deste workspace. ## Autenticação Envie a chave em `Authorization: Bearer pf_live_…`. ## Parâmetros | Nome | Local | Obrigatório | Tipo | Descrição | | --- | --- | --- | --- | --- | | `id` | path | Sim | `string` | ID do usuário, não o ID da associação ao workspace. | ## Respostas ### 200 Operação concluída. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `data` | `PublicUser` | Não | | | `data.id` | `string` | Não | | | `data.name` | `string` | Não | | | `data.email` | `string` | Não | | | `data.image` | `string` | Não | Aceita null. | ```json { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicUser" } } } ``` ### 401 Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 403 Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 404 Recurso não encontrado ou fora da visibilidade do membro. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ``` ### 429 Limite de requisições por workspace ou IP, ou limite de concorrência por workspace excedido. | Campo | Tipo | Obrigatório no objeto | Descrição | | --- | --- | --- | --- | | `error` | `string` | Sim | | | `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. | | `requestId` | `string` | Sim | | | `details` | `string` | Não | Aceita null. | | `fieldErrors` | `array` | Não | Aceita null. | | `fieldErrors[].field` | `string` | Não | | | `fieldErrors[].message` | `string` | Não | | ```json { "type": "object", "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "BAD_REQUEST", "VALIDATION_ERROR", "UNAUTHORIZED", "FORBIDDEN", "FEATURE_DISABLED", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "SERVICE_UNAVAILABLE" ] }, "requestId": { "type": "string" }, "details": { "type": "string", "nullable": true }, "fieldErrors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": [ "error", "code", "requestId" ] } ```