Como Criar um Agendamento via API

Atualizado em 11 de mar. de 2026

Perguntar ao ChatGPT sobre este tutorial

Neste tutorial, você vai criar um agendamento na plataforma usando a API REST do Meu Atendimento Virtual. O processo consiste em montar a requisição com os dados do evento — como data, hora, participantes e status — e enviá-la ao endpoint de criação. Para consultar a referência completa dos endpoints disponíveis, acesse a documentação oficial da API.

I – Definindo os dados do agendamento

A requisição exige um JSON no corpo. Os campos obrigatórios são status, start e attendees. Os demais são opcionais.

{
  "status": "PENDING",
  "calendar": "chave-do-calendario",
  "start": "2026-04-10T09:00:00.000Z",
  "end": "2026-04-10T09:30:00.000Z",
  "attendees": [
    {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "11999999999",
      "cpf": "123.456.789-00",
      "profession": "Engenheiro",
      "birthday": "1990-05-15",
      "place_of_birth": "São Paulo"
    }
  ],
  "summary": "Consulta inicial",
  "location": "Sala 3",
  "description": "Atendimento de rotina com avaliação completa."
}

status (obrigatório): define a situação do agendamento no momento da criação. Os valores aceitos são:

Valor	Significado
`ATTENDED`	Atendido
`CANCELED`	Cancelado
`CANCELED_CLIENT`	Cancelado pelo cliente
`CANCELED_GOOGLE`	Cancelado via Google Agenda
`CONFIRMED`	Confirmado
`CONFIRMED_CLIENT`	Confirmado pelo cliente
`DECLINED`	Recusado
`IN_PROGRESS`	Em atendimento
`NO_SHOW`	Não compareceu
`PENDING`	Pendente de confirmação
`PENDING_COMPANIONS`	Aguardando preenchimento de acompanhantes
`PENDING_FORM`	Aguardando preenchimento de formulário
`PENDING_PAYMENT`	Aguardando confirmação de pagamento
`RESCHEDULED`	Reagendado

Para novos agendamentos, o valor mais comum é PENDING.

start (obrigatório): data e hora de início no formato ISO 8601 (ex.: 2026-04-10T09:00:00.000Z).

attendees (obrigatório): lista de participantes. Cada participante exige ao menos o campo name. Os campos email, phone, cpf, profession, birthday e place_of_birth são opcionais e seguem os mesmos limites de caracteres do endpoint de clientes. Se o participante já estiver cadastrado, o campo key será retornado na resposta com a client_key correspondente.

Os demais campos do corpo são opcionais:

calendar: chave do calendário em que o agendamento será criado.
end: data e hora de término no formato ISO 8601.
summary: resumo do agendamento. Máximo de 1.000 caracteres.
location: local do atendimento. Máximo de 1.000 caracteres.
description: descrição detalhada. Máximo de 10.000 caracteres.

II – Enviando a requisição

Envie uma requisição HTTP POST para:

POST https://painel.meuatendimentovirtual.com.br/api/v1/agendamentos/

Configure os seguintes cabeçalhos, usando a chave de API disponível nas configurações da plataforma:

accept: application/json
Authorization: Bearer <sua-chave-de-api>
Content-Type: application/json

Exemplo com cURL:

curl -X POST https://painel.meuatendimentovirtual.com.br/api/v1/agendamentos/ \
-H "accept: application/json" \
-H "Authorization: Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999" \
-H "Content-Type: application/json" \
-d '{
  "status": "PENDING",
  "calendar": "chave-do-calendario",
  "start": "2026-04-10T09:00:00.000Z",
  "end": "2026-04-10T09:30:00.000Z",
  "attendees": [
    {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "11999999999"
    }
  ],
  "summary": "Consulta inicial",
  "location": "Sala 3"
}'

Exemplo em Python:

import requests

url = "https://painel.meuatendimentovirtual.com.br/api/v1/agendamentos/"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer ba08ab41bd58e9b9f82b4d2788b3cd9999ee9999",
    "Content-Type": "application/json"
}
data = {
    "status": "PENDING",
    "calendar": "chave-do-calendario",
    "start": "2026-04-10T09:00:00.000Z",
    "end": "2026-04-10T09:30:00.000Z",
    "attendees": [
        {
            "name": "João Silva",
            "email": "joao@example.com",
            "phone": "11999999999"
        }
    ],
    "summary": "Consulta inicial",
    "location": "Sala 3"
}

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

III – Verificando a resposta

Uma criação bem-sucedida retorna o status 201 Created com os dados do agendamento:

{
  "key": "agend789",
  "status": "PENDING",
  "calendar": "chave-do-calendario",
  "start": "2026-04-10T09:00:00.000Z",
  "end": "2026-04-10T09:30:00.000Z",
  "attendees": [
    {
      "key": "xfrh3456s",
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "11999999999",
      "cpf": null,
      "profession": null,
      "birthday": null,
      "place_of_birth": null
    }
  ],
  "summary": "Consulta inicial",
  "location": "Sala 3",
  "description": null
}

O campo key retornado identifica o agendamento na plataforma. O campo key dentro de cada item de attendees corresponde à client_key do participante, que pode ser usada em outros endpoints da API.

IV – Erros comuns

400 Bad Request: verifique se status, start e attendees estão presentes e se o valor de status é um dos valores permitidos. Datas fora do formato ISO 8601 também causam este erro.
401 Unauthorized: a chave de API está ausente ou incorreta no cabeçalho Authorization. Acesse as configurações da plataforma para copiar a chave correta.

Para entender como criar e configurar agendamentos diretamente pela interface da plataforma, consulte o tutorial Como Criar e Configurar Agendamentos. Para cadastrar participantes antecipadamente e obter suas chaves, veja Como Criar um Cliente via API.