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

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:

1
Authorization: Bearer {{bearer_token}}
2
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:

1
POST {{base_url}}/simplificav2/atividade
2
Authorization: Bearer {{bearer_token}}
3
Content-Type: application/json
4
5
{
6
  "pessoa_id": 164272,
7
  "consultor_id": 52,
8
  "motivo_id": 1451,
9
  "descricao": "Entrar em contato para confirmar próximos passos.",
10
  "titulo": "Contato comercial"
11
}

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:

1
{
2
  "status": "sucesso",
3
  "mensagem": "Atividade criada com sucesso.",
4
  "data": {
5
    "id": 982
6
  }
7
}

Criar motivo de atividade

Método: POST
Endpoint: /simplificav2/atividade_motivo

Campos obrigatórios:

• motivo

Campo opcional:

• nenhum

Exemplo de chamada:

1
POST {{base_url}}/simplificav2/atividade_motivo
2
Authorization: Bearer {{bearer_token}}
3
Content-Type: application/json
4
5
{
6
  "motivo": "Retorno combinado"
7
}

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:

1
{
2
  "status": "sucesso",
3
  "mensagem": "Motivo de atividade criado com sucesso.",
4
  "data": {
5
    "id": 1451
6
  }
7
}

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:

1
PUT {{base_url}}/simplificav2/atividade_motivo/1451
2
Authorization: Bearer {{bearer_token}}
3
Content-Type: application/json
4
5
{
6
  "motivo": "Retorno reagendado",
7
  "ativo": "S"
8
}

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:

1
{
2
  "status": "sucesso",
3
  "mensagem": "Motivo de atividade atualizado com sucesso.",
4
  "data": {
5
    "id": 1451
6
  }
7
}

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:

1
POST {{base_url}}/simplificav2/atividade_follow_up
2
Authorization: Bearer {{bearer_token}}
3
Content-Type: application/json
4
5
{
6
  "pessoa_id": 164272,
7
  "consultor_id": 52,
8
  "data_follow_up": "2026-04-05",
9
  "hora_follow_up": "14:30",
10
  "motivo_id": 7,
11
  "atividade_id": 981,
12
  "obs": "Confirmar retorno combinado no WhatsApp."
13
}

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:

1
{
2
  "status": "sucesso",
3
  "mensagem": "Follow-up criado com sucesso.",
4
  "data": {
5
    "id": 321
6
  }
7
}

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:

1
POST {{base_url}}/simplificav2/atividade_follow_up/321/finalizar
2
Authorization: Bearer {{bearer_token}}
3
Content-Type: application/json
4
5
{}

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:

1
{
2
  "status": "sucesso",
3
  "mensagem": "Follow-up finalizado com sucesso.",
4
  "data": {
5
    "id": 321
6
  }
7
}

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:

1
POST {{base_url}}/simplificav2/atividade_follow_up/321/cancelar
2
Authorization: Bearer {{bearer_token}}
3
Content-Type: application/json
4
5
{}

Semântica desta operação:

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

Exemplo de resposta:

1
{
2
  "status": "sucesso",
3
  "mensagem": "Follow-up cancelado com sucesso.",
4
  "data": {
5
    "id": 321
6
  }
7
}

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.