# Trabalhando com datas e horários

{% hint style="info" %}
O MaviBot funciona com os seguintes formatos de DATA e HORA:

para datas – **"dd.mm.aaaa"**
\
para hora – **"HH:MM"**
{% endhint %}

### Variáveis

Para trabalhar com datas e hora, você pode usar as seguintes variáveis:

**current\_date** - data atual no formato dd.mm.aaaa, com base no fuso horário do projeto\
**next\_day** - data de amanhã no formato dd.mm.aaaa; útil para agendar mensagens\
**current\_time** - hora atual no formato hh:mm, com base no fuso horário do projeto\
**weekday** - dia da semana como número: segunda-feira = 1, terça-feira = 2, etc.

**Acesso rápido às descrições das funções:**

* [Adicionar tempo ao tempo](#how-to-add-time-to-time) 
* [Comparar tempo](#how-to-compare-time) 
* [Definir intervalos de tempo](#how-to-set-time-intervals) 
* [Calcular o tempo até o dia D ](#how-to-find-out-how-much-time-is-left-until-day-d)
* [Encontrar o próximo aniversário](#how-to-find-out-the-next-birthday) 
* [Obter a data de um dia específico da semana ](#how-to-get-the-date-of-a-specific-weekday)
* [Obter a data de um dia específico do mês](#how-to-get-the-date-of-a-specific-day-of-month) 
* [Verificar se está dentro do horário de trabalho](#how-to-check-if-the-current-time-is-within-working-hours)

### Como adicionar tempo ao tempo 

{% hint style="info" %}
Você pode comparar datas e horas usando operadores lógicos da mesma forma que números.
{% endhint %}

**addYear() | addMonth() | addDays() | addMinutes()**

<details>

<summary>Descrição</summary>

**addYear(date, years\_to\_add) -** calcula uma nova data adicionando o número especificado de anos à data fornecida, levando em conta os anos bissextos. Use número negativo para subtrair anos.

**addMonth(date, months\_to\_add)** - calcula uma nova data adicionando o número especificado de meses à data fornecida, levando em conta os anos bissextos. Use número negativo para subtrair meses.

**addDays(date, days\_to\_add) -** adiciona o número especificado de dias à data. Use número negativo para subtrair dias. Exemplo: `addDays(current_date, 20)` ou `addDays('20.08.2019', -99)`

**addMinutes(time, minutes\_to\_add) -** adiciona o número especificado de minutos à hora. Use número negativo para subtrair minutos. Exemplo: `addMinutes(current_time, 20)` ou `addMinutes('20:08', -30)`

**'date' + days** - adiciona o número especificado de dias à data

**'time' + minutes** - adiciona o número especificado de minutos à hora

</details>

<details>

<summary>Exemplos</summary>

Exemplo de adicionar uma certa quantidade de anos a uma data:

<div data-with-frame="true"><figure><img src="/files/0b94a2c0ad55b8833414b5f85e27ced1830672b6" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/f013f4c19bd528936310bf717d35abbcf7f791f0" alt="" width="375"><figcaption></figcaption></figure></div>

Exemplo de adicionar uma certa quantidade de meses a uma data:

<div data-with-frame="true"><figure><img src="/files/37418b22f66e5fb752186be8550e81819de9b40a" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/128322184fea797886093ffc800b9b22cbc8857f" alt="" width="375"><figcaption></figcaption></figure></div>

Exemplo de uso de uma operação matemática simples — adicionando dias a uma data e minutos a uma hora:

<div data-with-frame="true"><figure><img src="/files/6cfd65c3c5ed2ce866874adf6335a1b90a5d9a5a" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/b4d98ac9b4126c7db55c7d590b457840d14f9d57" alt="" width="375"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`count = 2`\
`date = '29.02.2020'`\
`x = addYear(date, count)`\
`y = addYear('31.12.2021', -1*count)`

`count = 10`\
`date = '30.04.2019'`\
`x = addMonth(date, count)`\
`y = addMonth('31.12.2020', -1*count)`

`count = 10`\
`date = '30.04.2019'`\
`x = addMonth(date, count)`\
`y = addMonth('31.12.2020', -1*count)`

</details>

### Como comparar tempo&#x20;

<details>

<summary>Descrição</summary>

Você pode comparar datas e horas usando operadores lógicos da mesma forma que números:
\
maior que > , menor que <
\
igual a == , diferente de !=
\
maior ou igual a >= , menor ou igual a <=

As condições de comparação também podem ser combinadas usando os operadores lógicos AND e OR.

{% hint style="warning" %}
**As condições de comparação devem ser logicamente consistentes**, ou seja, você não pode criar condições como a == 1 e a != 1, já que um valor não pode ser igual e diferente de 1 ao mesmo tempo.
{% endhint %}

As condições de comparação são inseridas no **"Variável"** .

<div data-with-frame="true"><figure><img src="/files/8d6a1b86495d002a0b97274126ca7115b512b44b" alt="" width="563"><figcaption></figcaption></figure></div>

Certifique-se de usar atrasos ao especificar condições de comparação em uma seta.

<div data-with-frame="true"><figure><img src="/files/2ab99d438311449be207c15406d5b6d8cd9ced5f" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Exemplo</summary>

`'01.09.2020'`` `*`< '11.10.2020'`*&#x20;

*`'11.10.2020' >=`*` ``current_date`

`current_date == date`

`current_time >= '18:00'`&#x20;

`current_time <= '21:00'`

</details>

### &#x20;Como definir intervalos de tempo

<details>

<summary>Descrição</summary>

Uma função muito útil para trabalhar com intervalos de tempo é:

**time\_interval('start\_time', 'end\_time')**

A função retorna lógico **True** ou **Falso**.

Use essa função em blocos como condição no campo **"Variável para comparar"** ou dentro de uma calculadora usando IF().

{% hint style="info" %}
A função permite verificar se **a hora atual** se enquadra no intervalo especificado.
{% endhint %}

</details>

<details>

<summary>Exemplo</summary>

`time_interval('10:00','19:00') - verifica o intervalo de tempo das 10h às 19h`

`time_interval('19:00','07:00') - verifica o intervalo de tempo das 19h às 7h`

`time_interval('18.10.2021 10:00','25.10.2021 23:59:59') - verifica o intervalo de tempo entre datas diferentes`

`time_interval('#{current_date} 10:00','#{date} 19:00') - verifica o intervalo de tempo definido usando variáveis`

Vamos dar uma olhada mais de perto no primeiro exemplo. A função funciona da seguinte forma:

Se o usuário enviar uma mensagem contendo a palavra "time" durante o período de 10:00 a 19:00, a condição retorna true; caso contrário, retorna false.

Isso permite criar respostas diferentes dependendo do horário da solicitação do cliente.
\
Por exemplo, se a hora atual estiver entre 10:00 e 19:00, o cliente receberá:
&#x20;***"Um gerente responderá em breve."***

Em qualquer outro horário, ele receberá:
&#x20;***"O gerente está indisponível no momento; você receberá uma resposta durante o horário comercial a partir das 10:00."***

No campo Calculadora, insira:

`response = if(time_interval('10:00','19:00'), "Um gerente responderá em breve", "O gerente está indisponível no momento; você receberá uma resposta durante o horário comercial a partir das 10:00")`

No campo "Mensagem", insira: `#{response}`

<div data-with-frame="true"><figure><img src="/files/2f3324fd5db17e178c98c0ca84a181ed569a4758" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/75601c1321c9b5f17bb5aae5abed6b071442397a" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`response = if(time_interval('10:00','19:00'), "Um gerente responderá em breve", "O gerente está indisponível no momento; você receberá uma resposta durante o horário comercial a partir das 10:00")`

</details>

### Como descobrir quanto tempo falta até o dia D

<details>

<summary>Exemplo</summary>

<div data-with-frame="true"><figure><img src="/files/77cf9b555dd1bde2b9e1a6d91abd9e26bc13b3d3" alt="" width="563"><figcaption></figcaption></figure></div>

Para calcular quanto tempo falta até o dia D:

Defina a data e a hora do momento-alvo até o qual você deseja fazer a contagem regressiva.

`date_D = 10.10.2021 time_D = 12:00`

Converta isso para o formato **timestamp** :

`timestampD = convert_datetime("#{date_D} #{time_D}", "%d.%m.%Y %H:%M", "%s")`

Capture a hora atual em **timestamp** :

`timestamp0 = #{timestamp}`

Arredonde os valores obtidos para números inteiros:&#x20;

`timeD = int(#{timestampD}) time0 = int(#{timestamp0})`

Calcule a diferença em segundos:

`time = timeD - time0`

Divida pelo número de segundos em um dia e arredonde o resultado:

`full_days = time/86400`&#x20;

`days = int(#{full_days})`

Calcule quantos segundos restam do dia parcial:

`c = days*86400`&#x20;

`d = time - c`

Calcule a quantas horas isso corresponde e arredonde o valor:

`e = d/3600 hours = int(e)`

Calcule quantos segundos restam das horas parciais:

`g = hours*3600`&#x20;

`h = d - g`

Converta isso em minutos e arredonde o valor:&#x20;

`i = h/60`&#x20;

`minutes = int(i)`

Calcule quantos segundos restam:

`k = minutes*60`&#x20;

`seconds = h - k`

E exiba o tempo no **"Texto da mensagem"** “Broadcast para clientes dos blocos”

Tempo restante até o início: #{days} dias #{hours} horas #{minutes} minutos e #{seconds} segundos

Aqui está o código para inserir no **"Calculadora"** “Broadcast para clientes dos blocos”

```
timestampD = convert_datetime("#{date_D} #{time_D}", "%d.%m.%Y %H:%M", "%s")
timestamp0 = #{timestamp}
timeD = int(#{timestampD})
time0 = int(#{timestamp0})
time = timeD - time0
full_days = time/86400
days = int(#{days})
c = days*86400
d = time - c
e = d/3600
hours = int(e)
g = hours*3600 
h = d - g
i = h/60 
minutes = int(i)
k = minutes*60 
seconds = h - k
```

<figure><img src="/files/81f4bc78dc9698e7e2e759f81f98d2f4745ae518" alt="" width="563"><figcaption></figcaption></figure>

O **Calculadora** também suporta subtrair datas e horas sem conversão de tipo. Por exemplo:

`'11.12.2021' - '8.12.2021'  retorna 3 (dias)`

`'11:12' - '3:45'  retorna 447 (minutos)`

</details>

### Como descobrir o próximo aniversário &#x20;

<details>

<summary>Descrição</summary>

Para fazer o bot enviar felicitações de aniversário, você pode usar a função:

**birthdate(date)** - retorna o próximo aniversário com base na data de nascimento da pessoa: `reminder = birthdate('28.04.1994')`&#x20;

</details>

### Como obter a data de um dia específico da semana

<details>

<summary>Descrição</summary>

Se você tiver envios recorrentes em dias específicos da semana, pode obter a data de um dia da semana para agendar o envio.

**weekday\_date(weekday, b)** - retorna a data do dia da semana especificado mais próximo. Ela recebe **dois parâmetros**:

**O primeiro parâmetro é o** número do dia da semana a encontrar (de 1 a 7, onde 1 = segunda-feira, 7 = domingo).

**O segundo parâmetro** indica se **deve retornar a data de hoje se o dia da semana especificado for hoje**. Esse parâmetro é opcional e, por padrão, é False.

Vamos ver um exemplo para entender como o segundo parâmetro funciona:

Você quer agendar uma mensagem para ser enviada na quinta-feira.

Mas e se o cliente acabou de se cadastrar na quinta-feira?

A mensagem deve ser enviada nesta quinta-feira ou na próxima?

O segundo parâmetro definido como False significa que a mensagem será enviada apenas na próxima quinta-feira (ignorando hoje).

O segundo parâmetro definido como True significa que a mensagem será enviada nesta quinta-feira, se hoje for quinta-feira (incluindo o dia do cadastro).

No nosso exemplo, o usuário se cadastra na quinta-feira, 13.02.2025, e queremos enviar a mensagem na próxima quinta-feira.
&#x20;Portanto, o valor retornado será "20.02.2025".

Por exemplo, `weekday_date(4)` retornará '20.02.2025'.

Se você quiser que o dia atual conte apenas até um certo horário, pode usar esta construção:

`weekday_date(4, current_time < '13:00')`, onde a condição pode ser substituída por qualquer condição de que você precise.

<mark style="color:verde;">**Veja um exemplo de como usar a função:**</mark>

Exemplo de uso da função no campo "Data de envio" de uma conexão

<div data-with-frame="true"><figure><img src="/files/0942dcd336afa40a64c82a160a7709bc1141e00b" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

### Como obter a data de um dia específico do mês

<details>

<summary>Descrição</summary>

Se você tiver ações recorrentes em um dia específico do mês, pode obter a data da ocorrência mais próxima desse dia para agendar seu envio.

**month\_date(date, b)** - retorna a data mais próxima do mês para o número de dia especificado. Ela recebe **dois parâmetros**:

**date** - número do dia do mês a encontrar (de 1 a 31)

**b** - parâmetro opcional; indica se deve retornar a data de hoje se ela corresponder ao dia especificado. O padrão é False.

Se você informar 31, mas o mês atual tiver apenas 30 dias, a função retornará o último dia do mês (por exemplo, o dia 30).

Por exemplo:

Se hoje for 05.04.2022 e você chamar t = month\_date(1), o resultado será 01.05.2022 - o 1º dia do mês mais próximo após hoje.

</details>

### Como verificar se a hora atual está dentro do horário de trabalho

<details>

<summary>Descrição</summary>

Por exemplo, a empresa funciona das 9:00 às 18:00 e fica fechada aos sábados e domingos. Vamos construir as verificações passo a passo:

1. Verifique se a hora está dentro do horário de trabalho: current\_time >= '9:00' **E** current\_time <= '18:00'&#x20;
2. Verifique se a hora está fora do horário de trabalho: current\_time < '9:00' **OU** current\_time > '18:00'
3. Verifique se hoje é um dia útil (não é sábado nem domingo): weekday != 6 AND weekday != 7
4. Combine as condições para escrever durante o horário de trabalho: current\_time >= '9:00' **E** current\_time <= '18:00' **E** weekday != 6 **E** weekday != 7
5. Combine as condições para escrever fora do horário de trabalho: current\_time < '9:00' **OU** current\_time > '18:00' **OU** weekday == 6 **OU** weekday == 7

</details>

<details>

<summary>Exemplo</summary>

<div data-with-frame="true"><figure><img src="/files/e8660595a7dcc1177cead185c5db808fd953f206" alt=""><figcaption></figcaption></figure></div>

</details>

### Como converter data e hora

<details>

<summary>Exemplo</summary>

O formato de data e hora usado varia entre sistemas, e é possível que um dos recursos integrados retorne um horário em um formato que o MaviBot não reconheça. Você precisará convertê-lo.&#x20;

**convert\_datetime(date, fin, f\_out) -** converte data e hora

Há três parâmetros:

* String de data de entrada
* String de formato de entrada
* String de formato de saída

Exemplo: \
`convert_datetime("2011-11-03", "%Y-%m-%d", "%Y/%m/%d") на saída будет 2011/11/03`

Esta função converte a data recebida em **timestamp**.

\#{current\_date} #{current\_time} - converte para "06.01.2025 11:45" — como não há informação sobre segundos ou microssegundos, o timestamp resultante tem zeros após a vírgula decimal.

Por exemplo: 1736144700.000000

Se você incluir milissegundos após a vírgula decimal,

`convert_datetime("06.01.2025 19:26:35.123456", "%d.%m.%Y %H:%M:%S.%f", "%s.%f")`

o resultado será: `1736166395.123456`

**get\_datetime(format)** - uma função para obter a hora atual em um formato específico.
\
A função recebe um parâmetro — uma string que especifica o formato de saída desejado.

{% hint style="info" %} <mark style="color:$primary;">Importante!</mark> A resposta da função será (segunda-feira, terça-feira, etc.).\
\
Exemplo: <mark style="color:laranja;">get\_datetime("%A") a saída será quarta-feira</mark>
{% endhint %}

Descrição dos parâmetros da string de formato, que são especificados na função como strings entre aspas:

<table data-header-hidden><thead><tr><th width="177.33333333333331">Diretiva</th><th>Valor</th><th>Exemplo</th></tr></thead><tbody><tr><td><code>%a</code></td><td>Nome abreviado do dia da semana</td><td>dom, seg ...</td></tr><tr><td><code>%A</code></td><td>Nome completo do dia da semana</td><td>segunda-feira, terça-feira, …, domingo </td></tr><tr><td><code>%w</code></td><td>Dia da semana como número decimal, onde 0 é domingo e 6 é sábado</td><td>0, 1, …, 6</td></tr><tr><td><code>%d</code></td><td>Dia do mês como número decimal com zero à esquerda</td><td>01, 02, …, 31</td></tr><tr><td><code>%b</code></td><td>Nome abreviado do mês</td><td>jan, fev, …, dez</td></tr><tr><td><code>%B</code></td><td>Nome completo do mês</td><td>janeiro, fevereiro, março, etc.</td></tr><tr><td><code>%m</code></td><td>Mês como número decimal com zero à esquerda</td><td>01, 02, …, 12</td></tr><tr><td><code>%y</code></td><td>Ano como número de dois dígitos</td><td>00, 01, …, 99</td></tr><tr><td><code>%Y</code></td><td>Ano como número de quatro dígitos</td><td>0001, 0002, …, 2013, 2014, …, 9998, 9999</td></tr><tr><td><code>%H</code></td><td>Hora (formato 24 horas) como número de dois dígitos com zero à esquerda</td><td>00, 01, …, 23</td></tr><tr><td><code>%I</code></td><td>Hora (formato 12 horas) como número de dois dígitos com zero à esquerda</td><td>01, 02, …, 12</td></tr><tr><td><code>%p</code></td><td>Indicador de AM ou PM</td><td>AM, PM (en_US);am, pm (de_DE)</td></tr><tr><td><code>%M</code></td><td>Minutos como número de dois dígitos com zero à esquerda</td><td>00, 01, …, 59</td></tr><tr><td><code>%S</code></td><td>Segundos como número de dois dígitos com zero à esquerda</td><td>00, 01, …, 59</td></tr><tr><td><code>%f</code></td><td>Microssegundos como número de seis dígitos com zero à esquerda</td><td>000000, 000001, …, 999999</td></tr><tr><td><code>%z</code></td><td>Fuso horário UTC no formato <code>±HHMM[SS[.ffffff]]</code> (string vazia se o objeto for ingênuo).</td><td>(vazio), +0000, -0400, +1030, +063415, -030712.345216</td></tr><tr><td><code>%Z</code></td><td>Nome do fuso horário (string vazia se o objeto for ingênuo).</td><td>(vazio), UTC, GMT</td></tr><tr><td><code>%j</code></td><td>Dia do ano como número de três dígitos com zero à esquerda</td><td>001, 002, …, 366</td></tr><tr><td><code>%U</code></td><td>Número da semana do ano (com domingo como primeiro dia da semana) como número decimal com zero à esquerda. Todos os dias do novo ano anteriores ao primeiro domingo são considerados semana zero.</td><td>00, 01, …, 53</td></tr><tr><td><code>%W</code></td><td>Número da semana do ano (com segunda-feira como primeiro dia da semana) como número decimal. Todos os dias do novo ano anteriores à primeira segunda-feira são considerados semana zero.</td><td>00, 01, …, 53</td></tr><tr><td><code>%%</code></td><td>Símbolo <code>'%'</code></td><td>%</td></tr><tr><td><code>%s</code></td><td>timestamp</td><td>1607926200</td></tr></tbody></table>

Todos os demais símbolos representam a si mesmos.

{% hint style="info" %}
Você pode obter o timestamp atual usando: **convert\_datetime("#{current\_date} #{current\_time}", "%d.%m.%Y %H:%M", "%s")**
{% endhint %}

</details>

### Exibir a data atual no formato "dd nome do mês"

<details>

<summary>Exemplo</summary>

Para exibir a data no formato "dd nome do mês", use a função ***current\_date\_eng()***.&#x20;

*Se você precisar adicionar uma certa quantidade de dias a esta data, deve especificar o número necessário de dias como parâmetro na função.*

Por exemplo, se a data de hoje for 3 de abril, então a função retornará:

current\_date\_eng() - 3 de abril

current\_date\_eng(2) - 5 de abril

current\_date\_eng(-2) - 1º de abril

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/pt/chatbot/functions/calculadora/date.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.