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, ações em lote sobre o mesmo filtro da listagem, a geração mensal a partir dos modelos de recorrência e de aniversário, e o envio de lembretes a partir de uma obrigação.
Base path
Todos os endpoints abaixo são montados sob o prefixo:
/api/v1/lembretesA URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/lembretes.
Escopos
A credencial 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 /{lembrete_id}, GET /obrigacoes/{obrigacao_id}/destinatarios |
lembretes:write | POST /, POST /geracoes, POST /obrigacoes/{obrigacao_id}, POST /cancelar-lote, POST /excluir-lote, PUT /{lembrete_id}, POST /{lembrete_id}/cancelar, DELETE /{lembrete_id} |
O escopo é derivado da rota: o prefixo /lembretes vira o recurso lembretes, e o método HTTP define a ação (read para GET; write para POST, PUT e DELETE).
Permissão adicional
Além do escopo, as rotas que criam, alteram ou excluem lembretes - e também GET /obrigacoes/{obrigacao_id}/destinatarios - exigem permissão adicional. Sem ela, só as consultas (GET /, GET /usuario/..., GET /cliente/..., GET /{lembrete_id}) são permitidas e a resposta às demais é 403 Forbidden.
Credenciais emitidas para o MCP devem ser restritas - nunca globais.
Endpoints
POST /lembretes/
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
{
"status": "success",
"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": "pendente",
"data_hora_criacao": "2026-05-03T09:15:00-03:00",
"tipo_midia": null,
"nome_arquivo": null
}
}Datetime naïve em data_hora_envio (sem offset ou Z), data/hora no passado, textos acima dos limites (contato até 20, mensagem até 1000, observacao até 500 caracteres) e demais validações de negócio retornam 422 Unprocessable Entity. Sujeita a limite de tentativas; ao exceder, 429 com Retry-After. Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /lembretes/geracoes
Gera, no mês corrente, os lembretes pendentes a partir dos modelos com recorrência ativa (modelos) e/ou dos modelos de aniversário dos sócios do mês (aniversarios). A geração roda inteira dentro da requisição e é idempotente: cada lembrete gerado tem uma chave única (modelo x cliente x telefone x obrigação x dia), então rodar de novo só cria o que falta. Os lembretes nascem com o usuário logado como autor.
Parâmetros
Sem parâmetros de rota ou query. O corpo é um GeracaoLembretesCreate.
Request
{
"tipos": ["modelos", "aniversarios"]
}Response 201 Created
{
"status": "success",
"message": "Geração de lembretes concluída",
"data": {
"criados": 37,
"modelos_processados": 6,
"aniversariantes": 4,
"pulados": {
"data_passada": 2,
"fora_do_mes": 0,
"sem_data": 0,
"sem_cliente": 0,
"sem_zap_contabil": 1,
"sem_contato": 3,
"sem_obrigacao": 0,
"vinculo_grupo": 1,
"ja_existentes": 12
},
"anexos_indisponiveis": 0,
"erros": []
}
}tipos vazio, com mais de dois itens ou com valor fora de modelos/aniversarios retorna 422 Unprocessable Entity. Modelos com vínculo por grupo são pulados (pulados.vinculo_grupo); modelo cujo anexo não foi encontrado ou é grande demais não é gerado e conta em anexos_indisponiveis, com a mensagem em erros (lista limitada a 20 mensagens). Sujeita a limite de tentativas; ao exceder, 429 com Retry-After. Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
GET /lembretes/obrigacoes/{obrigacao_id}/destinatarios
Leitura de apoio para a tela de envio a partir de uma obrigação: devolve a obrigação (com nomes resolvidos), os contatos do departamento da obrigação naquela empresa que têm telefone válido para envio (sem repetir telefone), o modelo vinculado à obrigação (se houver) e os valores das variáveis da obrigação, para a prévia da mensagem.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID da obrigação. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Destinatários recuperados com sucesso",
"data": {
"obrigacao": {
"id": 9001,
"id_cliente": 1234,
"departamento_id": 3,
"nome": "DAS",
"competencia": "04/2026",
"ent_dt_prazo": "2026-05-20",
"status": "Pendente",
"cliente_nome": "Padaria Central",
"departamento_nome": "Fiscal",
"modelo_vinculado": { "id": 15, "titulo": "Lembrete DAS" }
},
"contatos": [
{ "contato_id": 77, "nome": "João Silva", "telefone": "5511988887777" }
],
"modelo_vinculado": {
"id": 15,
"titulo": "Lembrete DAS",
"mensagem": "Olá {contato}, o {obrigacao} da {fantasia} vence em {prazo}."
},
"variaveis": {
"fantasia": "Padaria Central",
"razao": "Padaria Central LTDA",
"cnpj": "00.000.000/0001-00",
"departamento": "Fiscal",
"obrigacao": "DAS",
"prazo": "20/05/2026"
}
}
}O objeto obrigacao do exemplo está resumido - ele traz todos os campos de ObrigacaoListItem (ver Schemas). Obrigação inexistente retorna 404 Not Found. Obrigação sem departamento devolve contatos: []. Escopo: lembretes:read. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /lembretes/obrigacoes/{obrigacao_id}
Cria, numa chamada, um lembrete por destinatário de uma obrigação: os contatos escolhidos do departamento da obrigação (contato_ids) e telefones avulsos (telefones_extras). As variáveis da obrigação são resolvidas por destinatário (inclusive {contato}, que fica vazio para telefone extra). Os lembretes nascem pendentes com envio para o momento atual - o worker faz o envio.
Tudo é validado antes de gravar: contato fora do cliente ou do departamento da obrigação, contato sem telefone válido ou telefone extra inválido retornam 422 e nada é criado. Telefones repetidos são deduplicados (o primeiro vence). Repetir o envio para o mesmo telefone no mesmo minuto devolve o item como duplicado.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
obrigacao_id | int | path | sim | ID da obrigação. |
O corpo é um LembretesDaObrigacaoCreate.
Request
{
"mensagem": "Olá {contato}, o {obrigacao} da {fantasia} vence em {prazo}.",
"modelo_id": 15,
"contato_ids": [77],
"telefones_extras": ["11977776666"]
}Response 201 Created
{
"status": "success",
"message": "Lembretes criados",
"data": {
"criados": 2,
"itens": [
{
"telefone": "5511988887777",
"contato_nome": "João Silva",
"status": "criado",
"lembrete_id": 501
},
{
"telefone": "5511977776666",
"contato_nome": null,
"status": "criado",
"lembrete_id": 502
}
]
}
}Cada item de itens traz status igual a criado, duplicado, mensagem_longa (passou de 1000 caracteres depois de trocar as variáveis) ou mensagem_vazia. Sem nenhum destinatário, ou com mais de 20 destinatários após a deduplicação, a resposta é 422. Obrigação ou modelo (modelo_id) inexistente retorna 404 Not Found. Cliente da obrigação inativo retorna 409 Conflict e nenhum lembrete é criado. Sujeita a limite de tentativas; ao exceder, 429 com Retry-After. Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
GET /lembretes/
Lista lembretes com filtros, ordenação e paginação opcionais. Sem nenhum parâmetro, devolve todos. Cada item é um LembreteListItem (o LembreteRead mais cliente_nome e usuario_nome). O total do filtro, para paginar, vai no header de resposta X-Total-Count - o corpo continua sendo a lista. Lista vazia é um estado válido: retorna 200 OK com data: [] e a mensagem "Nenhum lembrete encontrado.".
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
status | str | query | não | Um de pendente, enfileirado, enviado, erro, cancelado. |
busca | str | query | não | Trecho da mensagem, observação, contato ou nome do cliente (máx. 200 caracteres). |
id_cliente | int | query | não | Filtra por cliente (>= 1). |
somente_meus | bool | query | não | Só os criados pelo usuário logado. Default false. |
envio_de | date | query | não | Envio a partir desta data (AAAA-MM-DD, inclusiva, horário de Brasília). |
envio_ate | date | query | não | Envio até esta data (AAAA-MM-DD, inclusiva, horário de Brasília). |
sort_by | str | query | não | Um de data_hora_envio, data_hora_criacao, status, cliente. Sem sort_by, ordena por id crescente. |
sort_dir | str | query | não | asc ou desc. Default desc. |
limit | int | query | não | Itens por página (1 a 500). Sem limite: todos. |
offset | int | query | não | Offset de paginação. Default 0. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"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": "pendente",
"data_hora_criacao": "2026-05-03T09:15:00-03:00",
"tipo_midia": null,
"nome_arquivo": null,
"cliente_nome": "Padaria Central",
"usuario_nome": "Maria Souza"
}
]
}envio_de maior que envio_ate retorna 422 Unprocessable Entity. Escopo: lembretes:read
POST /lembretes/cancelar-lote
Cancela, em lote, os lembretes ainda na fila (pendente ou enfileirado) que o filtro alcança. O filtro é o mesmo recorte da listagem (LembreteFiltro), para que o lote alcance exatamente o que a tela mostra. Processa até 1000 lembretes por chamada; o excedente volta em restantes e o cliente deve repetir a chamada.
Parâmetros
Sem parâmetros de rota ou query. O corpo é um LembreteFiltro - todos os campos opcionais; chave desconhecida retorna 422 (num lote, um filtro digitado errado viraria "todos").
Request
{
"id_cliente": 1234,
"envio_de": "2026-05-01",
"envio_ate": "2026-05-31"
}Response 200 OK
{
"status": "success",
"message": "Lembretes cancelados",
"data": {
"afetados": 8,
"restantes": 0
}
}Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /lembretes/excluir-lote
Exclui permanentemente, em lote, os lembretes que o filtro alcança, em qualquer status (inclusive o histórico enviado). Processa até 1000 lembretes por chamada; o excedente volta em restantes.
Parâmetros
Sem parâmetros de rota ou query. O corpo é um LembreteFiltroExclusao: o mesmo recorte de LembreteFiltro mais confirmar_tudo.
Request
{
"status": "erro",
"somente_meus": true
}Response 200 OK
{
"status": "success",
"message": "Lembretes excluídos",
"data": {
"afetados": 3,
"restantes": 0
}
}Exclusão sem filtro
Corpo sem nenhum filtro alcança todos os lembretes, de todos os usuários e em qualquer status. Por isso, sem filtro, a API exige "confirmar_tudo": true explícito - caso contrário retorna 422 Unprocessable Entity e nada é apagado.
Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
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
{
"status": "success",
"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": "pendente",
"data_hora_criacao": "2026-05-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
{
"status": "success",
"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": "pendente",
"data_hora_criacao": "2026-05-03T09:15:00-03:00",
"tipo_midia": null,
"nome_arquivo": null
}
]
}Escopo: lembretes:read
GET /lembretes/{lembrete_id}
Retorna um único lembrete pelo ID. Qualquer leitor com o escopo lê qualquer lembrete (a listagem já mostra todos). Quando não encontrado, 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
{
"status": "success",
"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": "pendente",
"data_hora_criacao": "2026-05-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. Enviar observacao como texto vazio limpa o campo. Quando data_hora_envio é alterado, o lembrete volta para o status pendente (reagendamento). 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
{
"status": "success",
"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": "pendente",
"data_hora_criacao": "2026-05-03T09:15:00-03:00",
"tipo_midia": null,
"nome_arquivo": null
}
}Lembrete inexistente retorna 404 Not Found; lembrete com status enviado, datetime naïve ou no passado, textos acima do limite e demais regras de negócio retornam 422 Unprocessable Entity. Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
POST /lembretes/{lembrete_id}/cancelar
Cancela um lembrete, mudando o status para cancelado. Lembretes com status enviado não podem ser cancelados.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
lembrete_id | int | path | sim | ID do lembrete a cancelar. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"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-05-03T09:15:00-03:00",
"tipo_midia": null,
"nome_arquivo": null
}
}Lembrete inexistente retorna 404 Not Found; lembrete já enviado retorna 422 Unprocessable Entity. Escopo: lembretes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
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. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
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). Máx. 20 caracteres. |
mensagem | str | sim | Texto da mensagem WhatsApp. Aceita emojis e quebras de linha. Máx. 1000 caracteres. |
observacao | str | null | não | Anotação interna - não vai para o WhatsApp. Máx. 500 caracteres. |
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. Máx. 500. |
LembreteUpdate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
mensagem | str | null | não | Máx. 1000 caracteres. |
observacao | str | null | não | Máx. 500 caracteres. Texto vazio limpa a observação. |
data_hora_envio | datetime | null | não | Timezone obrigatório. Ao alterar, o status volta para pendente. |
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: pendente, enfileirado, enviado, erro, cancelado. |
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. |
LembreteListItem
LembreteRead acrescido de:
| Campo | Tipo | Notas |
|---|---|---|
cliente_nome | str | null | Nome exibido do cliente. |
usuario_nome | str | null | Nome do usuário que criou. |
LembreteFiltro
Corpo de POST /cancelar-lote (e base de LembreteFiltroExclusao). Chave desconhecida retorna 422.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
status | str | null | não | Um de pendente, enfileirado, enviado, erro, cancelado. |
busca | str | null | não | Trecho da mensagem, observação, contato ou nome do cliente. Máx. 200. |
id_cliente | int | null | não | >= 1. |
somente_meus | bool | não | Só os lembretes criados pelo usuário logado. Default false. |
envio_de | date | null | não | Envio a partir desta data (inclusiva, data local de Brasília). |
envio_ate | date | null | não | Envio até esta data (inclusiva). Não pode ser anterior a envio_de. |
LembreteFiltroExclusao
LembreteFiltro acrescido de:
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
confirmar_tudo | bool | condicional | Obrigatório (true) quando nenhum filtro é informado. Default false. |
LembreteAcaoLoteResultado
| Campo | Tipo | Notas |
|---|---|---|
afetados | int | Lembretes cancelados ou excluídos nesta chamada. |
restantes | int | Alcançados pelo filtro além do teto de 1000 por chamada. |
GeracaoLembretesCreate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
tipos | list[str] | sim | 1 ou 2 itens: modelos (recorrências ativas) e/ou aniversarios (sócios aniversariantes do mês). |
Resumo da geração
data de POST /geracoes:
| Campo | Tipo | Notas |
|---|---|---|
criados | int | Lembretes criados nesta execução. |
modelos_processados | int | Modelos com recorrência ativa lidos (só com modelos). |
aniversariantes | int | Sócios aniversariantes do mês (só com aniversarios). |
pulados | dict[str, int] | Contagem por motivo: data_passada, fora_do_mes, sem_data, sem_cliente, sem_zap_contabil, sem_contato, sem_obrigacao, vinculo_grupo, ja_existentes. |
anexos_indisponiveis | int | Modelos não gerados por anexo ausente ou grande demais. |
erros | list[str] | Mensagens de erro (até 20, sem repetição). |
DestinatariosRead
| Campo | Tipo | Notas |
|---|---|---|
obrigacao | ObrigacaoListItem | A obrigação com cliente_nome, departamento_nome e modelo_vinculado (id, titulo). |
contatos | list[ContatoDestinatario] | contato_id, nome e telefone (telefone de envio). Sem e-mail, documento ou nascimento. |
modelo_vinculado | ModeloDestinatario | null | id, titulo e mensagem do modelo vinculado à obrigação. |
variaveis | VariaveisObrigacao | fantasia, razao, cnpj, departamento, obrigacao e prazo (DD/MM/AAAA), todas str. |
ObrigacaoListItem traz os campos de obrigação id, id_cliente, departamento_id, acessorias_ent_id, nome, tipo, competencia, protocolo, ent_dt_prazo, ent_dt_prazo_tecnico, ent_dt_atraso, ent_dt_entrega, ent_multa, status, ent_guia_lida, ent_last_dh, resp_prazo, resp_entrega, legacy_uuid, data_hora_criacao e data_hora_atualizacao, além de cliente_nome, departamento_nome e modelo_vinculado. Veja também Obrigações.
LembretesDaObrigacaoCreate
Chave desconhecida retorna 422; strings têm espaços das pontas removidos.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
mensagem | str | sim | 1 a 1000 caracteres. Aceita as variáveis da obrigação e {contato}. |
modelo_id | int | null | não | Modelo de origem (>= 1); entra na observação do lembrete. Inexistente retorna 404. |
contato_ids | list[int] | não | Até 20 IDs de contatos do departamento da obrigação. Default []. |
telefones_extras | list[str] | não | Até 10 telefones avulsos (DDD + número com 10 ou 11 dígitos, ou já com o 55; máx. 30 caracteres cada). Normalizados com o 55 na frente. Default []. |
LembretesDaObrigacaoResultado
| Campo | Tipo | Notas |
|---|---|---|
criados | int | Quantos itens terminaram como criado. |
itens | list[ItemLembreteResultado] | Por destinatário: telefone, contato_nome (ou null), status e lembrete_id (ou null). |
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.
Ações em lote
POST /cancelar-lote e POST /excluir-lote recebem os filtros da listagem, nunca uma lista de IDs. Cada chamada processa no máximo 1000 lembretes; quando restantes for maior que zero, repita a chamada com o mesmo filtro.
- Toda resposta segue o envelope
{ "status": "success", "message": ..., "data": ... }; erros de validação e de negócio retornam odetailpadrão do FastAPI com o status HTTP correspondente.