Atendimento: Modelo-Grupo de Carteira

Endpoints da WebApiAlcance para gerenciar os vínculos entre modelos de mensagem e grupos de carteiras - a associação que define qual modelo de mensagem se aplica a um determinado grupo de carteira dentro de um departamento. Cobrem criação, listagem com filtros e paginação, detalhamento por ID, atualização parcial e exclusão.

Base path

/api/v1/modelo-grupo-carteira

Escopos necessários

• modelo_grupo_carteira:read - listagem e detalhamento
• modelo_grupo_carteira:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /modelo-grupo-carteira vira o recurso modelo_grupo_carteira (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

POST /modelo-grupo-carteira/

Cria um novo vínculo entre um modelo de mensagem e um grupo de carteira dentro de um departamento.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ModeloGrupoCarteiraCreate): modelo_id, grupo_carteira_id e departamento_id, todos obrigatórios.

Request

{
  "modelo_id": 4,
  "grupo_carteira_id": 12,
  "departamento_id": 2
}

Response 201 Created

{
  "success": true,
  "message": "Vínculo criado com sucesso",
  "data": {
    "modelo_id": 4,
    "grupo_carteira_id": 12,
    "departamento_id": 2,
    "id": 87,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Dados inválidos retornam 422 Unprocessable Entity com detail descrevendo o erro. Escopo: modelo_grupo_carteira:write

GET /modelo-grupo-carteira/

Lista os vínculos cadastrados, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum vínculo encontrado.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculos recuperados com sucesso",
  "data": [
    {
      "modelo_id": 4,
      "grupo_carteira_id": 12,
      "departamento_id": 2,
      "id": 87,
      "legacy_uuid": null,
      "data_hora_criacao": "2026-07-03T10:15:00"
    }
  ]
}

Escopo: modelo_grupo_carteira:read

GET /modelo-grupo-carteira/{vinculo_id}

Detalha um vínculo pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculo recuperado com sucesso",
  "data": {
    "modelo_id": 4,
    "grupo_carteira_id": 12,
    "departamento_id": 2,
    "id": 87,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Escopo: modelo_grupo_carteira:read

PUT /modelo-grupo-carteira/{vinculo_id}

Atualiza um vínculo existente. O body é um ModeloGrupoCarteiraUpdate com campos parciais - somente o que vier preenchido é alterado. O modelo_id não é atualizável.

Parâmetros

Request (ModeloGrupoCarteiraUpdate - todos os campos opcionais)

{
  "grupo_carteira_id": 15,
  "departamento_id": 3
}

Response 200 OK

{
  "success": true,
  "message": "Vínculo atualizado com sucesso",
  "data": {
    "modelo_id": 4,
    "grupo_carteira_id": 15,
    "departamento_id": 3,
    "id": 87,
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T10:15:00"
  }
}

Vínculo inexistente retorna 404 Not Found; demais erros de validação retornam 422 Unprocessable Entity. Escopo: modelo_grupo_carteira:write

DELETE /modelo-grupo-carteira/{vinculo_id}

Remove um vínculo pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Vínculo removido com sucesso",
  "data": null
}

Escopo: modelo_grupo_carteira:write

Schemas

ModeloGrupoCarteiraCreate

ModeloGrupoCarteiraUpdate

Todos os campos são opcionais; apenas os enviados são atualizados.

ModeloGrupoCarteiraRead

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• modelo_id não é atualizável via PUT - o ModeloGrupoCarteiraUpdate só aceita grupo_carteira_id e departamento_id. Para trocar o modelo, remova o vínculo e crie outro.
• Relaciona-se com Grupo de Carteiras, que define os agrupamentos de clientes por responsável.