Atendimento: Modelos de Aniversário

Endpoints da WebApiAlcance para gerenciar modelos de mensagem de aniversário - templates de felicitação usados nos disparos automáticos de aniversário para clientes da Alcance. Cada modelo guarda um título, o texto da mensagem (com variáveis de substituição), a lista de empresas às quais se aplica e o horário de envio. Cobrem criação, listagem paginada, detalhamento por ID, atualização e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/modelos-aniversario

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/modelos-aniversario.

Escopos necessários

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

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

Endpoints

`POST /modelos-aniversario/`

Cria um novo modelo de mensagem de aniversário.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ModeloAniversarioCreate): titulo (obrigatório), mensagem (obrigatório), variaveis, empresa_ids e horario_envio (opcionais).

Request

{
  "titulo": "Feliz Aniversário - Padrão",
  "mensagem": "Olá {nome}, a equipe da Alcance deseja um feliz aniversário! 🎉",
  "variaveis": ["nome"],
  "empresa_ids": [1, 4, 7],
  "horario_envio": "09:00:00"
}

Response 201 Created

{
  "success": true,
  "message": "Modelo de aniversário criado com sucesso",
  "data": {
    "id": 8,
    "titulo": "Feliz Aniversário - Padrão",
    "mensagem": "Olá {nome}, a equipe da Alcance deseja um feliz aniversário! 🎉",
    "variaveis": ["nome"],
    "empresa_ids": [1, 4, 7],
    "horario_envio": "09:00:00",
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:12:00-03:00",
    "data_hora_atualizacao": "2026-07-03T09:12:00-03:00"
  }
}

Em caso de dados inválidos, retorna 422 Unprocessable Entity com detail descrevendo o erro.

Escopo: modelos_aniversario:write

`GET /modelos-aniversario/`

Lista os modelos de aniversário cadastrados, com paginação por limit/offset. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum modelo de aniversário encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`limit`	`int`	query	não	Limite de itens por página. Default `100`, entre `1` e `500`.
`offset`	`int`	query	não	Offset de paginação. Default `0`, mínimo `0`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelos recuperados com sucesso",
  "data": [
    {
      "id": 8,
      "titulo": "Feliz Aniversário - Padrão",
      "mensagem": "Olá {nome}, a equipe da Alcance deseja um feliz aniversário! 🎉",
      "variaveis": ["nome"],
      "empresa_ids": [1, 4, 7],
      "horario_envio": "09:00:00",
      "legacy_uuid": null,
      "data_hora_criacao": "2026-07-03T09:12:00-03:00",
      "data_hora_atualizacao": "2026-07-03T09:12:00-03:00"
    }
  ]
}

Escopo: modelos_aniversario:read

`GET /modelos-aniversario/{modelo_id}`

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

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`modelo_id`	`int`	path	sim	ID interno do modelo

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelo recuperado com sucesso",
  "data": {
    "id": 8,
    "titulo": "Feliz Aniversário - Padrão",
    "mensagem": "Olá {nome}, a equipe da Alcance deseja um feliz aniversário! 🎉",
    "variaveis": ["nome"],
    "empresa_ids": [1, 4, 7],
    "horario_envio": "09:00:00",
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:12:00-03:00",
    "data_hora_atualizacao": "2026-07-03T09:12:00-03:00"
  }
}

Escopo: modelos_aniversario:read

`PUT /modelos-aniversario/{modelo_id}`

Atualiza um modelo existente. O body é um ModeloAniversarioUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`modelo_id`	`int`	path	sim	ID do modelo

Request (ModeloAniversarioUpdate - todos os campos opcionais)

{
  "titulo": "Feliz Aniversário - Revisado",
  "mensagem": "Parabéns, {nome}! Que seu dia seja especial. 🎂",
  "empresa_ids": [1, 4],
  "horario_envio": "10:30:00"
}

Response 200 OK

{
  "success": true,
  "message": "Modelo atualizado com sucesso",
  "data": {
    "id": 8,
    "titulo": "Feliz Aniversário - Revisado",
    "mensagem": "Parabéns, {nome}! Que seu dia seja especial. 🎂",
    "variaveis": ["nome"],
    "empresa_ids": [1, 4],
    "horario_envio": "10:30:00",
    "legacy_uuid": null,
    "data_hora_criacao": "2026-07-03T09:12:00-03:00",
    "data_hora_atualizacao": "2026-07-03T14:05:00-03:00"
  }
}

Quando o modelo não é encontrado, retorna 404 Not Found; demais erros de validação retornam 422 Unprocessable Entity.

Escopo: modelos_aniversario:write

`DELETE /modelos-aniversario/{modelo_id}`

Remove um modelo de aniversário pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`modelo_id`	`int`	path	sim	ID do modelo

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Modelo removido com sucesso",
  "data": null
}

Escopo: modelos_aniversario:write

Schemas

`ModeloAniversarioCreate`

Campo	Tipo	Obrigatório	Observações
`titulo`	`str`	sim	Título do modelo. Máximo `255` caracteres.
`mensagem`	`str`	sim	Texto da mensagem de aniversário. Aceita variáveis de substituição (ex: `{nome}`).
`variaveis`	`List \| null`	não	Lista de variáveis disponíveis para o template.
`empresa_ids`	`List \| null`	não	Lista de IDs de empresas às quais o modelo se aplica.
`horario_envio`	`str \| null`	não	Horário de envio no formato `HH:MM:SS`. Máximo `8` caracteres.

`ModeloAniversarioUpdate`

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

Campo	Tipo	Observações
`titulo`	`str \| null`	Novo título. Máximo `255` caracteres.
`mensagem`	`str \| null`	Novo texto da mensagem.
`variaveis`	`List \| null`	Nova lista de variáveis.
`empresa_ids`	`List \| null`	Nova lista de IDs de empresas.
`horario_envio`	`str \| null`	Novo horário de envio (`HH:MM:SS`). Máximo `8` caracteres.

`ModeloAniversarioRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do modelo.
`titulo`	`str`	Título do modelo.
`mensagem`	`str`	Texto da mensagem de aniversário.
`variaveis`	`List \| null`	Variáveis disponíveis no template.
`empresa_ids`	`List \| null`	Empresas às quais o modelo se aplica.
`horario_envio`	`str \| null`	Horário de envio (`HH:MM:SS`).
`legacy_uuid`	`str \| null`	UUID de origem em sistema legado, quando aplicável.
`data_hora_criacao`	`datetime`	Timestamp de criação do registro.
`data_hora_atualizacao`	`datetime`	Timestamp da última atualização.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
A listagem (GET /modelos-aniversario/) é a única rota paginada - use limit e offset para percorrer grandes volumes.
Os campos variaveis e empresa_ids são listas livres (JSON), permitindo evoluir o conteúdo dos templates sem alterar o schema.
Os campos legacy_uuid, data_hora_criacao e data_hora_atualizacao são somente leitura - retornados no ModeloAniversarioRead, nunca aceitos na criação ou atualização.