Como Criar uma Agenda (Calendário) Via API

Resumo #

A API da plataforma eAgenda permite criar agendas (calendários) de forma programática, configurando horários, serviços, modos de agendamento e permissões. Este guia prático detalha como enviar uma requisição HTTP POST para o endpoint /api/v3/calendars/ e processar a resposta. Para mais detalhes, consulte a documentação oficial da API da eAgenda.

Preparação do Ambiente #

Antes de começar, você precisará:

• Chave de API: Acesse o painel da eAgenda para obter seu token Bearer.
• Ferramenta para requisições HTTP: Use cURL, Postman ou bibliotecas como requests (Python) ou axios (JavaScript).
• Configuração do cabeçalho: A autenticação é feita via Bearer Token. Configure o cabeçalho Authorization: Bearer <seu-token> e defina Content-Type: application/json.

Dica: Consulte a seção de autenticação na documentação da API para configurar o token corretamente: https://eagenda.com.br/api/v3/documents/#overview.

Definição dos Dados da Agenda #

Para criar uma agenda, envie um objeto JSON no corpo da requisição com os seguintes campos:

{
  "calendar_name": "string",
  "slug": "string",
  "is_internal": boolean,
  "service_list": [
    {
      "service_key": "uuid"
    }
  ],
  "time_config": {
    "opening_hours": [
      {
        "week_day": "string",
        "opening_time": "time",
        "closing_time": "time",
        "max_people": integer
      }
    ],
    "slot_interval": "string",
    "duration": "string",
    "minimum_notice": integer,
    "maximum_notice": integer,
    "start_date": "date",
    "end_date": "date"
  },
  "online_meeting_platform": "string",
  "max_people": integer,
  "request_email": boolean,
  "email_required": boolean,
  "request_phone": boolean,
  "phone_required": boolean,
  "max_companions": integer,
  "max_services": integer,
  "count_companions": boolean,
  "appointment_mode": "string",
  "owner_user": "email",
  "account_slug": "string"
}

calendar_name (obrigatório) #

• Descrição: Nome da agenda.
• Restrições: Mínimo de 1 caractere.
• Impacto: Identifica a agenda no sistema.
• Exemplo: “Agenda Principal”

slug (opcional) #

• Descrição: Nome do link para a agenda.
• Restrições: Máximo de 250 caracteres, padrão ^[-a-zA-Z0-9_]+$.
• Impacto: Define um identificador amigável para a URL da agenda.
• Exemplo: “agenda-principal”

is_internal (obrigatório) #

• Descrição: Indica se a agenda é de uso interno (somente administradores).
• Impacto: Restringe o acesso a administradores se true.
• Exemplo: false

service_list (opcional) #

• Descrição: Lista de serviços associados à agenda.
• Estrutura: Array de objetos, cada um com service_key (UUID).
• Como obter: Use o endpoint de listagem de serviços (/api/v3/services/).
• Impacto: Define os serviços disponíveis para agendamento.
• Exemplo:[ { "service_key": "19730681-29f0-4000-848c-34869ad83880" } ]

time_config (obrigatório) #

• Descrição: Configurações de horários e agendamento.
• Estrutura: Objeto com:
  • opening_hours: Lista de horários de funcionamento por dia da semana.
    • week_day: Dia da semana (ex.: “1” para segunda-feira, até “7” para domingo).
    • opening_time: Horário de abertura (formato HH:MM:SS).
    • closing_time: Horário de fechamento (formato HH:MM:SS).
    • max_people: Número máximo de pessoas por horário (mín. 0, máx. 2147483647).
    • Exemplo:[ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ]
  • slot_interval: Intervalo entre opções de agendamento (ex.: “00:15:00” para 15 minutos).
  • duration: Duração padrão do agendamento (ex.: “00:30:00”).
  • minimum_notice: Tempo mínimo de aviso para agendar (em horas).
  • maximum_notice: Tempo máximo de aviso para agendar (em dias).
  • start_date: Data de início para agendamentos (formato YYYY-MM-DD).
  • end_date: Data de término para agendamentos (formato YYYY-MM-DD).
• Exemplo:{ "opening_hours": [ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ], "slot_interval": "00:15:00", "duration": "00:30:00", "minimum_notice": 2, "maximum_notice": 30, "start_date": "2025-06-01", "end_date": "2025-12-31" }

online_meeting_platform (opcional) #

• Descrição: Provedor de videoconferência.
• Valores possíveis: meet, teams, zoom, other.
• Impacto: Define a plataforma para reuniões online.
• Exemplo: “meet”

max_people (obrigatório) #

• Descrição: Número máximo de pessoas por horário.
• Impacto: Limita a capacidade de agendamento.
• Exemplo: 10

request_email (opcional) #

• Descrição: Solicitar e-mail de contato.
• Impacto: Inclui campo de e-mail no formulário de agendamento se true.
• Exemplo: true

email_required (opcional) #

• Descrição: E-mail obrigatório para agendar.
• Impacto: Exige e-mail se true.
• Exemplo: false

request_phone (opcional) #

• Descrição: Solicitar telefone de contato.
• Impacto: Inclui campo de telefone no formulário de agendamento se true.
• Exemplo: true

phone_required (opcional) #

• Descrição: Telefone obrigatório para agendar.
• Impacto: Exige telefone se true.
• Exemplo: false

max_companions (opcional) #

• Descrição: Número máximo de acompanhantes por agendamento.
• Restrições: Mínimo de 0, padrão 0.
• Impacto: Limita o número de acompanhantes.
• Exemplo: 2

max_services (opcional) #

• Descrição: Número máximo de serviços por agendamento.
• Restrições: Mínimo de 0, padrão 0.
• Impacto: Limita os serviços selecionáveis.
• Exemplo: 3

count_companions (opcional) #

• Descrição: Contar acompanhantes no total de pessoas.
• Impacto: Inclui acompanhantes na contagem de max_people se true.
• Exemplo: false

appointment_mode (opcional) #

• Descrição: Modo de agendamento.
• Valores possíveis: hybrid, online, on_site, off_site.
• Impacto: Define se o agendamento é presencial, online ou híbrido.
• Exemplo: “hybrid”

owner_user (opcional) #

• Descrição: E-mail do usuário responsável pela agenda.
• Impacto: Vincula a agenda a um responsável.
• Exemplo: “responsavel@example.com”

account_slug (opcional) #

• Descrição: Slug da conta ou subconta.
• Restrições: Mínimo de 1 caractere, padrão ^[-a-zA-Z0-9_]+$.
• Como obter: Use o endpoint de listagem de contas.
• Impacto: Vincula a agenda a uma conta específica.
• Exemplo: “minha-conta”

Nota: Os campos obrigatórios são calendar_name, is_internal, time_config e max_people. Os demais são opcionais, mas recomendados para maior controle.

Envio da Requisição para Criar uma Agenda #

Para criar uma agenda, envie uma requisição HTTP POST para o endpoint:

https://eagenda.com.br/api/v3/calendars/

Configuração da Requisição #

• Método: POST
• Cabeçalhos:
  • accept: application/json
  • Authorization: Bearer <seu-token>
  • Content-Type: application/json
• Corpo da requisição: JSON com os dados da agenda.

Exemplo de Requisição com cURL #

curl -X POST https://eagenda.com.br/api/v3/calendars/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "calendar_name": "Agenda Principal",
  "slug": "agenda-principal",
  "is_internal": false,
  "service_list": [
    {
      "service_key": "19730681-29f0-4000-848c-34869ad83880"
    }
  ],
  "time_config": {
    "opening_hours": [
      {
        "week_day": "1",
        "opening_time": "08:00:00",
        "closing_time": "17:00:00",
        "max_people": 10
      }
    ],
    "slot_interval": "00:15:00",
    "duration": "00:30:00",
    "minimum_notice": 2,
    "maximum_notice": 30,
    "start_date": "2025-06-01",
    "end_date": "2025-12-31"
  },
  "online_meeting_platform": "meet",
  "max_people": 10,
  "request_email": true,
  "email_required": false,
  "request_phone": true,
  "phone_required": false,
  "max_companions": 2,
  "max_services": 3,
  "count_companions": false,
  "appointment_mode": "hybrid",
  "owner_user": "responsavel@example.com",
  "account_slug": "minha-conta"
}'

Exemplo em Python (usando requests) #

import requests

url = "https://eagenda.com.br/api/v3/calendars/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "calendar_name": "Agenda Principal",
    "slug": "agenda-principal",
    "is_internal": False,
    "service_list": [
        {
            "service_key": "19730681-29f0-4000-848c-34869ad83880"
        }
    ],
    "time_config": {
        "opening_hours": [
            {
                "week_day": "1",
                "opening_time": "08:00:00",
                "closing_time": "17:00:00",
                "max_people": 10
            }
        ],
        "slot_interval": "00:15:00",
        "duration": "00:30:00",
        "minimum_notice": 2,
        "maximum_notice": 30,
        "start_date": "2025-06-01",
        "end_date": "2025-12-31"
    },
    "online_meeting_platform": "meet",
    "max_people": 10,
    "request_email": True,
    "email_required": False,
    "request_phone": True,
    "phone_required": False,
    "max_companions": 2,
    "max_services": 3,
    "count_companions": False,
    "appointment_mode": "hybrid",
    "owner_user": "responsavel@example.com",
    "account_slug": "minha-conta"
}

response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())

Verificação da Resposta #

A API retornará uma resposta com o status da criação da agenda. Verifique os seguintes pontos:

• Código de status HTTP:
  • 201 Created: Agenda criada com sucesso.
  • 400 Bad Request: Erro nos dados enviados (verifique o JSON).
  • 401 Unauthorized: Token inválido ou ausente.
• Corpo da resposta: Contém detalhes da agenda criada, como:{ "calendar_key": "19730681-29f0-4000-8d78-94e4d6116180", "calendar_name": "Agenda Principal", "slug": "agenda-principal", "is_active": false, "is_internal": false, "service_list": [ { "service_key": "19730681-29f0-4000-848c-34869ad83880", "service_name": "Consulta Médica" } ], "appointment_link": "https://eagenda.com.br/agenda-principal", "time_config": { "opening_hours": [ { "week_day": "1", "opening_time": "08:00:00", "closing_time": "17:00:00", "max_people": 10 } ], "slot_interval": "00:15:00", "duration": "00:30:00", "minimum_notice": 2, "maximum_notice": 30, "start_date": "2025-06-01", "end_date": "2025-12-31" }, "online_meeting_platform": "meet", "max_people": 10, "request_email": true, "email_required": false, "request_phone": true, "phone_required": false, "max_companions": 2, "max_services": 3, "count_companions": false, "appointment_mode": "hybrid", "owner_user": "responsavel@example.com", "address": { "postal_code": "12345-678", "street": "Rua Exemplo", "neighborhood": "Centro", "number": "123", "complement": "Sala 101", "city": { "name": "São Paulo", "state_name": "São Paulo", "state_code": "SP", "country_code": "BR" } }, "account_slug": "minha-conta" }

A agenda será registrada no sistema e estará pronta para receber agendamentos, respeitando as configurações definidas.

Conclusão #

Com este tutorial, você aprendeu como criar uma agenda (calendário) via API da eAgenda, configurando horários, serviços e permissões de forma eficiente. Essa integração é ideal para gerenciar agendamentos em diferentes contextos, como atendimentos presenciais, online ou híbridos. Para mais funcionalidades, como listagem ou edição de agendas, consulte a documentação completa da API da eAgenda.

Entre em Contato ou Saiba Mais #

Estamos à disposição para ajudar! Acesse nossos canais oficiais:

📞 WhatsApp : Clique aqui para nos enviar uma mensagem
🌐 Plataforma eAgenda : Conheça o eAgenda
🏢 Nossa Empresa : Mupi Systems – Soluções Inovadoras
📧 E-mail : contato@mupisystems.com.br
📚 Tutoriais e Documentação : Acesse nossos guias e tutoriais