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/lembretes

A 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:

EscopoOperações permitidas
lembretes:readGET /, GET /usuario/{usuario_id}, GET /cliente/{id_cliente}, GET /{lembrete_id}, GET /obrigacoes/{obrigacao_id}/destinatarios
lembretes:writePOST /, 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âmetroTipoLocalObrigatórioDescrição
obrigacao_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
obrigacao_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
statusstrquerynãoUm de pendente, enfileirado, enviado, erro, cancelado.
buscastrquerynãoTrecho da mensagem, observação, contato ou nome do cliente (máx. 200 caracteres).
id_clienteintquerynãoFiltra por cliente (>= 1).
somente_meusboolquerynãoSó os criados pelo usuário logado. Default false.
envio_dedatequerynãoEnvio a partir desta data (AAAA-MM-DD, inclusiva, horário de Brasília).
envio_atedatequerynãoEnvio até esta data (AAAA-MM-DD, inclusiva, horário de Brasília).
sort_bystrquerynãoUm de data_hora_envio, data_hora_criacao, status, cliente. Sem sort_by, ordena por id crescente.
sort_dirstrquerynãoasc ou desc. Default desc.
limitintquerynãoItens por página (1 a 500). Sem limite: todos.
offsetintquerynãoOffset 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âmetroTipoLocalObrigatórioDescrição
usuario_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID 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âmetroTipoLocalObrigatórioDescrição
lembrete_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
lembrete_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
lembrete_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
lembrete_idintpathsimID 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

CampoTipoObrigatórioObservações
id_clienteint | nullnãoVincula o lembrete a um cliente. Quando null, fica como envio avulso.
contatostrsimTelefone destino no padrão WhatsApp (ex: 5511988887777). Máx. 20 caracteres.
mensagemstrsimTexto da mensagem WhatsApp. Aceita emojis e quebras de linha. Máx. 1000 caracteres.
observacaostr | nullnãoAnotação interna - não vai para o WhatsApp. Máx. 500 caracteres.
data_hora_enviodatetime | nullnãoCom timezone obrigatório (validador rejeita naïve). Omitir = envio imediato.
tipo_midiastr | nullcondicionalUm de image, video, audio, voice, document. Obrigatório quando arquivo_base64 é informado.
arquivo_base64str | nullnãoConteúdo da mídia em base64.
nome_arquivostr | nullcondicionalNome com extensão (ex: boleto.pdf). Obrigatório quando arquivo_base64 é informado. Máx. 500.

LembreteUpdate

CampoTipoObrigatórioObservações
mensagemstr | nullnãoMáx. 1000 caracteres.
observacaostr | nullnãoMáx. 500 caracteres. Texto vazio limpa a observação.
data_hora_enviodatetime | nullnãoTimezone obrigatório. Ao alterar, o status volta para pendente.

LembreteRead

CampoTipoNotas
idintIdentificador do lembrete.
usuario_idintOperador que criou o registro.
id_clienteint | nullCliente vinculado, se houver.
contatostrTelefone destino.
mensagemstrConteúdo enviado.
observacaostr | nullAnotação interna.
data_hora_enviodatetimeSempre normalizado para America/Sao_Paulo na resposta.
statusstrCiclo de vida: pendente, enfileirado, enviado, erro, cancelado.
data_hora_criacaodatetimeTimestamp de criação (TZ Brasília).
tipo_midiastr | nullTipo da mídia, quando aplicável.
nome_arquivostr | nullNome do arquivo enviado, quando aplicável.

LembreteListItem

LembreteRead acrescido de:

CampoTipoNotas
cliente_nomestr | nullNome exibido do cliente.
usuario_nomestr | nullNome do usuário que criou.

LembreteFiltro

Corpo de POST /cancelar-lote (e base de LembreteFiltroExclusao). Chave desconhecida retorna 422.

CampoTipoObrigatórioObservações
statusstr | nullnãoUm de pendente, enfileirado, enviado, erro, cancelado.
buscastr | nullnãoTrecho da mensagem, observação, contato ou nome do cliente. Máx. 200.
id_clienteint | nullnão>= 1.
somente_meusboolnãoSó os lembretes criados pelo usuário logado. Default false.
envio_dedate | nullnãoEnvio a partir desta data (inclusiva, data local de Brasília).
envio_atedate | nullnãoEnvio até esta data (inclusiva). Não pode ser anterior a envio_de.

LembreteFiltroExclusao

LembreteFiltro acrescido de:

CampoTipoObrigatórioObservações
confirmar_tudoboolcondicionalObrigatório (true) quando nenhum filtro é informado. Default false.

LembreteAcaoLoteResultado

CampoTipoNotas
afetadosintLembretes cancelados ou excluídos nesta chamada.
restantesintAlcançados pelo filtro além do teto de 1000 por chamada.

GeracaoLembretesCreate

CampoTipoObrigatórioObservações
tiposlist[str]sim1 ou 2 itens: modelos (recorrências ativas) e/ou aniversarios (sócios aniversariantes do mês).

Resumo da geração

data de POST /geracoes:

CampoTipoNotas
criadosintLembretes criados nesta execução.
modelos_processadosintModelos com recorrência ativa lidos (só com modelos).
aniversariantesintSócios aniversariantes do mês (só com aniversarios).
puladosdict[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_indisponiveisintModelos não gerados por anexo ausente ou grande demais.
erroslist[str]Mensagens de erro (até 20, sem repetição).

DestinatariosRead

CampoTipoNotas
obrigacaoObrigacaoListItemA obrigação com cliente_nome, departamento_nome e modelo_vinculado (id, titulo).
contatoslist[ContatoDestinatario]contato_id, nome e telefone (telefone de envio). Sem e-mail, documento ou nascimento.
modelo_vinculadoModeloDestinatario | nullid, titulo e mensagem do modelo vinculado à obrigação.
variaveisVariaveisObrigacaofantasia, 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.

CampoTipoObrigatórioObservações
mensagemstrsim1 a 1000 caracteres. Aceita as variáveis da obrigação e {contato}.
modelo_idint | nullnãoModelo de origem (>= 1); entra na observação do lembrete. Inexistente retorna 404.
contato_idslist[int]nãoAté 20 IDs de contatos do departamento da obrigação. Default [].
telefones_extraslist[str]nãoAté 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

CampoTipoNotas
criadosintQuantos itens terminaram como criado.
itenslist[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 o detail padrão do FastAPI com o status HTTP correspondente.