Gerador de eventos fake em iCal

Arquivos ICS e RFC 5545: o formato universal de agenda

Um arquivo .ics é texto puro no formato iCalendar definido pela RFC 5545 (2009, substituindo a antiga RFC 2445). É a língua franca que faz um convite criado no Google Agenda aparecer corretamente no Apple Calendar, Outlook, Thunderbird e Fantastical sem ninguém combinar um protocolo de rede — todo cliente de calendário relevante lê e escreve a mesma gramática baseada em texto. Um gerador de ICS mock é útil para QA de parsers de email, para popular agendas de desenvolvimento com dados realistas e para testar workflows acionados por webhook que importam eventos de terceiros.

O arquivo ICS mínimo viável tem um wrapper VCALENDAR com um ou mais blocos VEVENT. A gramática é orientada a linhas, cada linha segue CHAVE:VALOR ou CHAVE;PARAM=valor:VALOR e toda chave é maiúscula. Propriedades obrigatórias no VEVENT: UID (identificador global único — normalmente uuid@seudominio), DTSTAMP (quando o registro foi criado) e DTSTART. A maioria dos eventos também inclui DTEND ou DURATION, SUMMARY, DESCRIPTION e LOCATION.

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//YourApp//Calendar 1.0//EN
BEGIN:VEVENT
UID:[email protected]
DTSTAMP:20240501T120000Z
DTSTART:20240515T100000Z
DTEND:20240515T110000Z
SUMMARY:Team Standup
DESCRIPTION:Daily sync
LOCATION:Zoom Meeting Room
ORGANIZER;CN=Alice:mailto:[email protected]
ATTENDEE;ROLE=REQ-PARTICIPANT:mailto:[email protected]
END:VEVENT
END:VCALENDAR

Convites por email, anexos e a propriedade METHOD

O caso de uso mais comum é o convite de reunião enviado como anexo de email com tipo MIME text/calendar; method=REQUEST. Gmail, Outlook e Apple Mail reconhecem o anexo e renderizam botões "Sim/Talvez/Não" inline, que escrevem uma resposta de volta como arquivo METHOD:REPLY. Outros métodos incluem PUBLISH (feed de calendário sem RSVP), CANCEL (para remover um evento já enviado), REFRESH, COUNTER e DECLINECOUNTER. Para um link "Adicionar ao calendário" em uma página de marketing, PUBLISH é a escolha certa.

Fusos horários, recorrência e CalDAV

Fuso horário é a propriedade que mais geradores erram. Três opções existem: sufixo UTC Z (DTSTART:20240515T130000Z) — sem ambiguidade mas perde a intenção local do usuário; parâmetro TZID (DTSTART;TZID=America/Sao_Paulo:20240515T100000) — preferido para eventos atrelados a um lugar; e hora local flutuante (sem Z, sem TZID) — apenas para casos do tipo "todo dia às 9 da manhã onde você estiver". O Brasil aboliu o horário de verão em 2019, então todos os fusos brasileiros agora ficam fixos em UTC-3 ano inteiro; arquivos ICS antigos com BRST ainda podem circular.

Eventos recorrentes usam a propriedade RRULE: RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12 descreve "segunda/quarta/sexta por doze ocorrências". Exceções vão em EXDATE, datas adicionais em RDATE. O CalDAV (RFC 4791) é o protocolo HTTP companheiro que permite clientes sincronizarem agendas com um servidor (ler, escrever, consultar) — é o que Apple Calendar, Thunderbird Lightning e DAVx5 usam por baixo dos panos. Calendários assinados são apenas uma URL .ics pública que os clientes refetcham periodicamente (de 15 minutos a várias horas, configurável por cliente).

Armadilhas de codificação e escolha de biblioteca

O formato é anterior ao JSON e mostra isso. Linhas com mais de 75 octetos precisam ser dobradas: quebrar com CRLF seguido por um espaço no início da continuação. Vírgulas, ponto e vírgulas, contrabarras e quebras de linha dentro de valores precisam ser escapados como \, \; \\ e \n. Quebras de linha são CRLF, não LF — o Outlook já recusou arquivos só com LF. Bibliotecas maduras cuidam disso para você: ical.js (browser e Node), node-ical, icalendar (Python), iCal4j (Java) e vobject (Python). Escrever o formato à mão tudo bem para geradores triviais; pare de escrever à mão no momento em que precisar de expansão de RRULE ou conversão de TZID.

Perguntas frequentes

Dá para anexar um .ics em convite de email? Sim. Use MIME text/calendar; method=REQUEST e Gmail/Outlook/Apple Mail renderizam botões de RSVP inline.

Como funcionam eventos recorrentes? Use a propriedade RRULE com FREQ (DAILY, WEEKLY, MONTHLY, YEARLY), opcionalmente BYDAY, BYMONTHDAY, COUNT ou UNTIL. Adicione EXDATE para exceções.

Fuso horário é obrigatório? Recomendado para clareza. Use Z para UTC, TZID para eventos atrelados a um local físico, hora flutuante só para lembretes de "hábito pessoal".

Posso reutilizar o mesmo UID? Sim — é assim que você atualiza ou cancela um evento. Envie um novo VEVENT com o mesmo UID e um SEQUENCE maior, com METHOD:REQUEST para atualização ou METHOD:CANCEL para remover.