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.

Cria um lembrete WhatsApp vinculado ao usuário autenticado (usuario_id). Aceita texto puro ou mídia codificada em base64. Quando data_hora_envio é informado, o envio é agendado; se omitido, a mensagem é enviada imediatamente.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (LembreteCreate): contato e mensagem (obrigatórios), id_cliente, observacao, data_hora_envio, tipo_midia, arquivo_base64 e nome_arquivo (opcionais). Quando arquivo_base64 é informado, tipo_midia e nome_arquivo passam a ser obrigatórios.

Request

{
  "id_cliente": 1234,
  "contato": "5511988887777",
  "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
  "observacao": "Disparo automático - fluxo DAS mensal.",
  "data_hora_envio": "2026-05-20T10:00:00-03:00"
}

Response 201 Created

{
  "success": true,
  "message": "Lembrete criado com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 42,
    "id_cliente": 1234,
    "contato": "5511988887777",
    "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
    "observacao": "Disparo automático - fluxo DAS mensal.",
    "data_hora_envio": "2026-05-20T10:00:00-03:00",
    "status": "agendado",
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "tipo_midia": null,
    "nome_arquivo": null
  }
}

Datetime naïve em data_hora_envio (sem offset ou Z) e demais validações de negócio retornam 422 Unprocessable Entity. Escopo: lembretes:write

`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. Lista vazia é um estado válido: retorna 200 OK com data: [] e a mensagem "Nenhum lembrete encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. Retorna um array de LembreteRead.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lembretes recuperados com sucesso",
  "data": [
    {
      "id": 1,
      "usuario_id": 42,
      "id_cliente": 1234,
      "contato": "5511988887777",
      "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
      "observacao": "Disparo automático - fluxo DAS mensal.",
      "data_hora_envio": "2026-05-20T10:00:00-03:00",
      "status": "agendado",
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "tipo_midia": null,
      "nome_arquivo": null
    }
  ]
}

Escopo: lembretes:read

`GET /lembretes/usuario/{usuario_id}`

Lista lembretes criados pelo usuário responsável informado (operador interno da contabilidade). Sem resultados, retorna 200 OK com data: [] e a mensagem "Nenhum lembrete encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`usuario_id`	`int`	path	sim	ID do usuário responsável (operador).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lembretes recuperados com sucesso",
  "data": [
    {
      "id": 1,
      "usuario_id": 42,
      "id_cliente": 1234,
      "contato": "5511988887777",
      "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
      "observacao": "Disparo automático - fluxo DAS mensal.",
      "data_hora_envio": "2026-05-20T10:00:00-03:00",
      "status": "agendado",
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "tipo_midia": null,
      "nome_arquivo": null
    }
  ]
}

Escopo: lembretes:read

`GET /lembretes/cliente/{id_cliente}`

Lista lembretes vinculados a um cliente específico - útil para timeline de comunicação WhatsApp por cliente. Sem resultados, retorna 200 OK com data: [] e a mensagem "Nenhum lembrete encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	path	sim	ID do cliente vinculado ao lembrete.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lembretes recuperados com sucesso",
  "data": [
    {
      "id": 1,
      "usuario_id": 42,
      "id_cliente": 1234,
      "contato": "5511988887777",
      "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
      "observacao": "Disparo automático - fluxo DAS mensal.",
      "data_hora_envio": "2026-05-20T10:00:00-03:00",
      "status": "agendado",
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "tipo_midia": null,
      "nome_arquivo": null
    }
  ]
}

Escopo: lembretes:read

`GET /lembretes/{lembrete_id}`

Retorna um único lembrete pelo ID. Quando não encontrado (ou pertencente a outro usuário), retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lembrete_id`	`int`	path	sim	ID interno do lembrete.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lembrete encontrado com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 42,
    "id_cliente": 1234,
    "contato": "5511988887777",
    "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
    "observacao": "Disparo automático - fluxo DAS mensal.",
    "data_hora_envio": "2026-05-20T10:00:00-03:00",
    "status": "agendado",
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "tipo_midia": null,
    "nome_arquivo": null
  }
}

Escopo: lembretes:read

`PUT /lembretes/{lembrete_id}`

Atualiza mensagem, observacao e/ou data_hora_envio de um lembrete ainda não enviado. O body é um LembreteUpdate com campos parciais - somente o que vier preenchido é alterado. A regra de timezone explícito vale também para o PUT.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lembrete_id`	`int`	path	sim	ID do lembrete.

Request (LembreteUpdate - todos os campos opcionais)

{
  "mensagem": "Olá! Lembrete atualizado: o boleto do DAS vence amanhã.",
  "data_hora_envio": "2026-05-21T09:00:00-03:00"
}

Response 200 OK

{
  "success": true,
  "message": "Lembrete atualizado com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 42,
    "id_cliente": 1234,
    "contato": "5511988887777",
    "mensagem": "Olá! Lembrete atualizado: o boleto do DAS vence amanhã.",
    "observacao": "Disparo automático - fluxo DAS mensal.",
    "data_hora_envio": "2026-05-21T09:00:00-03:00",
    "status": "agendado",
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "tipo_midia": null,
    "nome_arquivo": null
  }
}

Lembrete inexistente retorna 404 Not Found; datetime naïve e demais regras de negócio retornam 422 Unprocessable Entity. Escopo: lembretes:write

`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.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lembrete_id`	`int`	path	sim	ID do lembrete agendado a cancelar.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Lembrete cancelado com sucesso",
  "data": {
    "id": 1,
    "usuario_id": 42,
    "id_cliente": 1234,
    "contato": "5511988887777",
    "mensagem": "Olá! Lembrete: vence hoje o boleto do DAS de abril/2026.",
    "observacao": "Disparo automático - fluxo DAS mensal.",
    "data_hora_envio": "2026-05-20T10:00:00-03:00",
    "status": "cancelado",
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "tipo_midia": null,
    "nome_arquivo": null
  }
}

Lembrete inexistente retorna 404 Not Found; lembrete que não pode ser cancelado retorna 422 Unprocessable Entity. Escopo: lembretes:write

`DELETE /lembretes/{lembrete_id}`

Remove permanentemente o registro do lembrete da base.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`lembrete_id`	`int`	path	sim	ID do lembrete.

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo de resposta.

Lembrete inexistente retorna 404 Not Found. Escopo: lembretes:write

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.

Schemas

`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.

`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.

Lembretes WhatsApp

Base path

Escopos

Endpoints

`POST /lembretes/`

`GET /lembretes/`

`GET /lembretes/usuario/{usuario_id}`

`GET /lembretes/cliente/{id_cliente}`

`GET /lembretes/{lembrete_id}`

`PUT /lembretes/{lembrete_id}`

`POST /lembretes/{lembrete_id}/cancelar`

`DELETE /lembretes/{lembrete_id}`

Schemas

`LembreteCreate`

`LembreteRead`

Exemplo POST

Notas