> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplificagestao.com.br/llms.txt.
> For full documentation content, see https://docs.simplificagestao.com.br/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplificagestao.com.br/_mcp/server.

# Atividades e follow-ups · criar e agir

# Atividades e follow-ups · criar e agir

Esta é a primeira prova de conceito de escrita privada para atividades, motivos de atividade e follow-ups.

Os cadastros auxiliares de CRM ficaram em uma página separada:

* [`Cadastros CRM · criar e atualizar`](/private-operations-crm-cadastros)

Escopo atual:

* `POST /simplificav2/atividade`
* `POST /simplificav2/atividade_motivo`
* `PUT /simplificav2/atividade_motivo/{id}`
* `POST /simplificav2/atividade_follow_up`
* `POST /simplificav2/atividade_follow_up/{id}/finalizar`
* `POST /simplificav2/atividade_follow_up/{id}/cancelar`

## Como acessar

Use o token privado da empresa no cabeçalho:

```http
Authorization: Bearer {{bearer_token}}
Content-Type: application/json
```

Onde encontrar:

* no Simplifica, abra o menu do usuário;
* acesse `Token API`;
* copie o token privado da empresa.

## Quando usar

Estas rotas servem para integrações privadas, automações e agentes de IA que precisam:

* registrar uma nova atividade;
* manter motivos de atividade da empresa;
* agendar um follow-up;
* encerrar ou cancelar um follow-up existente sem depender da interface do sistema.

## Regras gerais

* todas as chamadas usam JSON;
* cada chamada opera em um único registro;
* o recurso `atividade` concentra leitura (`GET`) e criação (`POST`);
* o recurso `atividade_motivo` concentra leitura (`GET`), criação (`POST`) e atualização (`PUT`);
* o mesmo recurso `atividade_follow_up` concentra leitura (`GET`) e escrita (`POST`);
* use `GET /simplificav2/atividade` e `GET /simplificav2/atividade_motivo` para conferir o resultado das demais escritas;
* use `GET /simplificav2/atividade_follow_up` para conferir o resultado depois da escrita;
* o cancelamento desta prova de conceito não gera atividade automática;
* a finalização segue a semântica operacional atual do domínio: encerra o follow-up por inativação e registra log `X`.

## Criar atividade

**Método:** `POST`\
**Endpoint:** `/simplificav2/atividade`

Campos obrigatórios:

* `pessoa_id`
* `consultor_id`
* `motivo_id`
* `descricao`

Campo opcional:

* `titulo`

Exemplo de chamada:

```http
POST {{base_url}}/simplificav2/atividade
Authorization: Bearer {{bearer_token}}
Content-Type: application/json

{
  "pessoa_id": 164272,
  "consultor_id": 52,
  "motivo_id": 1451,
  "descricao": "Entrar em contato para confirmar próximos passos.",
  "titulo": "Contato comercial"
}
```

Validações principais:

* `pessoa_id`, `consultor_id` e `motivo_id` precisam existir no escopo da empresa autenticada;
* o motivo informado precisa estar ativo;
* `descricao` é obrigatória.

Exemplo de resposta:

```json
{
  "status": "sucesso",
  "mensagem": "Atividade criada com sucesso.",
  "data": {
    "id": 982
  }
}
```

## Criar motivo de atividade

**Método:** `POST`\
**Endpoint:** `/simplificav2/atividade_motivo`

Campos obrigatórios:

* `motivo`

Campo opcional:

* nenhum

Exemplo de chamada:

```http
POST {{base_url}}/simplificav2/atividade_motivo
Authorization: Bearer {{bearer_token}}
Content-Type: application/json

{
  "motivo": "Retorno combinado"
}
```

Validações principais:

* `motivo` é obrigatório;
* o motivo nasce sempre ativo;
* o nome do motivo não pode duplicar outro motivo da mesma empresa.

Exemplo de resposta:

```json
{
  "status": "sucesso",
  "mensagem": "Motivo de atividade criado com sucesso.",
  "data": {
    "id": 1451
  }
}
```

## Atualizar motivo de atividade

**Método:** `PUT`\
**Endpoint:** `/simplificav2/atividade_motivo/{id}`

Parâmetros da rota:

* `id`: identificador do motivo de atividade que será atualizado.

Campos permitidos:

* `motivo`
* `ativo`

Exemplo de chamada:

```http
PUT {{base_url}}/simplificav2/atividade_motivo/1451
Authorization: Bearer {{bearer_token}}
Content-Type: application/json

{
  "motivo": "Retorno reagendado",
  "ativo": "S"
}
```

Validações principais:

* envie pelo menos um campo para atualização;
* `ativo`, quando enviado, deve ser `S` ou `N`;
* use `ativo = N` para inativar e `ativo = S` para reativar;
* o novo nome não pode duplicar outro motivo da mesma empresa.

Observação:

* não existe rota de exclusão para esse cadastro auxiliar;
* quando for necessário excluir, isso deve ser feito pela interface do sistema;
* por API, o comportamento previsto é ativar ou inativar o registro.

Exemplo de resposta:

```json
{
  "status": "sucesso",
  "mensagem": "Motivo de atividade atualizado com sucesso.",
  "data": {
    "id": 1451
  }
}
```

## Criar follow-up

**Método:** `POST`\
**Endpoint:** `/simplificav2/atividade_follow_up`

Campos obrigatórios:

* `pessoa_id`
* `consultor_id`
* `data_follow_up`
* `hora_follow_up`

Campos opcionais:

* `motivo_id`
* `atividade_id`
* `obs`

Exemplo de chamada:

```http
POST {{base_url}}/simplificav2/atividade_follow_up
Authorization: Bearer {{bearer_token}}
Content-Type: application/json

{
  "pessoa_id": 164272,
  "consultor_id": 52,
  "data_follow_up": "2026-04-05",
  "hora_follow_up": "14:30",
  "motivo_id": 7,
  "atividade_id": 981,
  "obs": "Confirmar retorno combinado no WhatsApp."
}
```

Validações principais:

* `data_follow_up` deve estar no formato `YYYY-MM-DD`;
* `hora_follow_up` aceita `HH24:MI` ou `HH24:MI:SS`;
* a data e hora precisam ser futuras;
* `pessoa_id`, `consultor_id` e `atividade_id`, quando informado, precisam existir no escopo da empresa autenticada.

Exemplo de resposta:

```json
{
  "status": "sucesso",
  "mensagem": "Follow-up criado com sucesso.",
  "data": {
    "id": 321
  }
}
```

## Finalizar follow-up

**Método:** `POST`\
**Endpoint:** `/simplificav2/atividade_follow_up/{id}/finalizar`

Parâmetros da rota:

* `id`: identificador do follow-up que será finalizado.

Exemplo de chamada:

```http
POST {{base_url}}/simplificav2/atividade_follow_up/321/finalizar
Authorization: Bearer {{bearer_token}}
Content-Type: application/json

{}
```

Semântica desta operação:

* a rota segue o comportamento operacional atual do domínio;
* o follow-up é encerrado por inativação;
* o log recebe status `X`;
* esta operação não promete alterar o campo `finalizado` para um valor específico.

Exemplo de resposta:

```json
{
  "status": "sucesso",
  "mensagem": "Follow-up finalizado com sucesso.",
  "data": {
    "id": 321
  }
}
```

## Cancelar follow-up

**Método:** `POST`\
**Endpoint:** `/simplificav2/atividade_follow_up/{id}/cancelar`

Parâmetros da rota:

* `id`: identificador do follow-up que será cancelado.

Exemplo de chamada:

```http
POST {{base_url}}/simplificav2/atividade_follow_up/321/cancelar
Authorization: Bearer {{bearer_token}}
Content-Type: application/json

{}
```

Semântica desta operação:

* grava `finalizado = C`;
* registra log `C`;
* não cria atividade automática nesta prova de conceito.

Exemplo de resposta:

```json
{
  "status": "sucesso",
  "mensagem": "Follow-up cancelado com sucesso.",
  "data": {
    "id": 321
  }
}
```

## Erros esperados

* `400`: JSON inválido.
* `401`: token inválido ou sem empresa associada.
* `404`: follow-up não encontrado no escopo da empresa.
* `404`: motivo de atividade não encontrado no escopo da empresa.
* `409`: transição de estado não permitida.
* `409`: conflito de nome já existente para motivo de atividade.
* `422`: regra funcional inválida, como data/hora no passado, campo obrigatório ausente ou referência fora do escopo da empresa.
* `500`: erro interno inesperado.