Lembretes WhatsApp

Agendamento e envio de mensagens WhatsApp Business para clientes da Alcance. Suporta texto puro e mídia (imagem, vídeo, áudio, voz e documento) com envio imediato ou agendado.

Base path

Todos os endpoints abaixo são montados sob o prefixo:

/api/v1/lembretes

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

Escopos

A API Key utilizada precisa conter pelo menos um dos escopos abaixo, conforme a operação:

Escopo	Operações permitidas
`lembretes:read`	`GET /`, `GET /usuario/{usuario_id}`, `GET /cliente/{id_cliente}`, `GET /{id}`
`lembretes:write`	`POST /`, `PUT /{id}`, `POST /{id}/cancelar`, `DELETE /{id}`

API Keys emitidas para o MCP devem ser restritas — nunca globais.

Endpoints

`POST /lembretes/`

Cria um lembrete. Aceita texto puro ou mídia codificada em base64. Quando data_hora_envio é informado, o envio é agendado (Celery); se omitido, a mensagem é enviada imediatamente.

Status sucesso: 201 Created
Body: LembreteCreate
Retorno: LembreteRead envelopado em success_response

`GET /lembretes/`

Lista todos os lembretes do tenant. Sem paginação no endpoint — recomenda-se filtrar pelos endpoints específicos abaixo quando o volume cresce.

Retorno: array de LembreteRead

`GET /lembretes/usuario/{usuario_id}`

Lista lembretes criados pelo usuário responsável informado (operador interno da contabilidade).

Path param: usuario_id: int
Retorno: array de LembreteRead

`GET /lembretes/cliente/{id_cliente}`

Lista lembretes vinculados a um cliente específico — útil para timeline de comunicação WhatsApp por cliente.

Path param: id_cliente: int
Retorno: array de LembreteRead

`GET /lembretes/{lembrete_id}`

Retorna um único lembrete pelo id.

Path param: lembrete_id: int
Retorno: LembreteRead

`PUT /lembretes/{lembrete_id}`

Atualiza mensagem, observacao e/ou data_hora_envio de um lembrete ainda não enviado. A regra de timezone explícito vale também para o PUT.

Path param: lembrete_id: int
Body: LembreteUpdate (todos os campos opcionais)

`POST /lembretes/{lembrete_id}/cancelar`

Cancela um lembrete agendado. Não funciona em lembretes já enviados ou com status final. Operação idempotente do ponto de vista do scheduler.

Path param: lembrete_id: int

`DELETE /lembretes/{lembrete_id}`

Remove permanentemente o registro do lembrete da base.

Status sucesso: 204 No Content
Path param: lembrete_id: int

O MCP não expõe o endpoint DELETE. Exclusão segue restrita a chamadas diretas autenticadas com escopo lembretes:write e fora do alcance de clientes IA.

Schema `LembreteCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int \| null`	não	Vincula o lembrete a um cliente. Quando `null`, fica como envio avulso.
`contato`	`str`	sim	Telefone destino no padrão WhatsApp (ex: `5511988887777`).
`mensagem`	`str`	sim	Texto da mensagem WhatsApp. Aceita emojis e quebras de linha.
`observacao`	`str \| null`	não	Anotação interna — não vai para o WhatsApp.
`data_hora_envio`	`datetime \| null`	não	Com timezone obrigatório (validador rejeita naïve). Omitir = envio imediato.
`tipo_midia`	`str \| null`	condicional	Um de `image`, `video`, `audio`, `voice`, `document`. Obrigatório quando `arquivo_base64` é informado.
`arquivo_base64`	`str \| null`	não	Conteúdo da mídia em base64.
`nome_arquivo`	`str \| null`	condicional	Nome com extensão (ex: `boleto.pdf`). Obrigatório quando `arquivo_base64` é informado.

Schema `LembreteRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do lembrete.
`usuario_id`	`int`	Operador que criou o registro.
`id_cliente`	`int \| null`	Cliente vinculado, se houver.
`contato`	`str`	Telefone destino.
`mensagem`	`str`	Conteúdo enviado.
`observacao`	`str \| null`	Anotação interna.
`data_hora_envio`	`datetime`	Sempre normalizado para `America/Sao_Paulo` na resposta.
`status`	`str`	Ciclo de vida: `agendado`, `enviado`, `cancelado`, `falha`, etc.
`data_hora_criacao`	`datetime`	Timestamp de criação (TZ Brasília).
`tipo_midia`	`str \| null`	Tipo da mídia, quando aplicável.
`nome_arquivo`	`str \| null`	Nome do arquivo enviado, quando aplicável.

Exemplo POST

Lembrete agendado para 20/05/2026 às 10h (horário de Brasília), vinculado ao cliente 1234:

{
  "id_cliente": 1234,
  "contato": "5511988887777",
  "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026. Qualquer dúvida, estamos à disposição.",
  "observacao": "Disparo automático — fluxo DAS mensal.",
  "data_hora_envio": "2026-05-20T10:00:00-03:00"
}

Para envio imediato basta omitir data_hora_envio. Para anexar boleto PDF, incluir tipo_midia: "document", arquivo_base64 e nome_arquivo: "das-abr-2026.pdf".

Notas

Timezone obrigatório

data_hora_envio exige timezone explícito (ex: 2026-05-20T10:00:00-03:00). Datetime naïve — sem offset nem Z — é rejeitado pelo validador com erro 422 antes mesmo de chegar no scheduler.

Envio com mídia

Para anexar arquivo, os três campos tipo_midia, arquivo_base64 e nome_arquivo precisam estar presentes juntos. Valores aceitos de tipo_midia: image, video, audio, voice, document.