Primeiros passos

Em cinco minutos você sai do painel com um token e faz a primeira chamada à API.

O que dá para integrar

A API pública (public-v1) cobre o dia a dia do salão:

Área	O que a API faz
Catálogo	Lista e consulta serviços e profissionais
Agenda	Consulta horários livres; lista, consulta, cria, remarca e cancela agendamentos; muda o status (confirmar, chegou, em atendimento, concluído, não compareceu)
Clientes	Busca, consulta, cadastra e edita clientes
Comandas	Lista e consulta comandas
Relatórios	Faturamento e recebimentos de um período

Além da API, há os webhooks (o Pega Vez avisa o seu sistema quando algo acontece) e o servidor MCP (para agentes de IA). Os campos de cada endpoint estão na referência da API.

Fica de fora, de propósito: gerenciar tokens e webhooks, cobrança e assinatura, equipe e perfis, configurações do salão. Isso continua só no painel.

Endpoints do public-v1

Todos ficam em https://api.pegavez.com.br/api/salons/{salonId}. A coluna Permissão é a que o token precisa (veja Autenticação e permissões).

Método	Caminho	Operação	Permissão
GET	/services	ListServices — serviços, com busca, categoria e status	qualquer membro
GET	/services/{serviceId}	GetService — um serviço	qualquer membro
GET	/professionals	ListProfessionals — profissionais	agenda.view (com escopo “próprio”, só o próprio)
GET	/professionals/{professionalId}	GetProfessional — um profissional	agenda.view (com escopo “próprio”, só o próprio)
GET	/availability	GetStaffAvailability — horários livres por profissional	agenda.view
GET	/appointments	ListAppointments — agendamentos, com filtros e paginação	agenda.view
POST	/appointments	CreateAppointment — cria (entra confirmado); aceita Idempotency-Key	agenda.edit
GET	/appointments/{appointmentId}	GetAppointment — um agendamento	agenda.view
POST	/appointments/{appointmentId}/reschedule	RescheduleAppointment — outro horário e/ou profissional	agenda.edit
POST	/appointments/{appointmentId}/confirm	ConfirmAppointment — solicitado → confirmado	agenda.edit
POST	/appointments/{appointmentId}/arrive	MarkAppointmentArrived — cliente chegou	agenda.edit
POST	/appointments/{appointmentId}/start	StartAppointment — em atendimento	agenda.edit
POST	/appointments/{appointmentId}/complete	CompleteAppointment — concluído	agenda.edit
POST	/appointments/{appointmentId}/cancel	CancelAppointment — cancela (pelo cliente ou pelo salão)	agenda.edit
POST	/appointments/{appointmentId}/no-show	MarkAppointmentNoShow — não compareceu	agenda.edit
GET	/customers	ListCustomers — clientes, com busca e paginação	customers.view
POST	/customers	CreateCustomer — cadastra; aceita Idempotency-Key	customers.edit
GET	/customers/{customerId}	GetCustomer — detalhe com indicadores	customers.view
PUT	/customers/{customerId}	UpdateCustomer — edita o cadastro	customers.edit
GET	/orders	ListOrders — comandas, com filtros e paginação	checkout.operate
GET	/orders/{orderId}	GetOrder — uma comanda com itens e pagamentos	checkout.operate
GET	/reports/revenue	GetRevenueReport — faturamento do período	reports.view
GET	/reports/receipts	GetReceiptsReport — recebimentos do período	reports.view

O documento OpenAPI completo está em /public-v1.json, pronto para gerar um cliente na sua linguagem.

Plano necessário

A integração é um recurso dos planos Equipe e Negócio. Durante o teste de 90 dias o salão tem tudo do Negócio, então já dá para integrar. No plano Solo, toda chamada com token (API e MCP) responde:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "title": "Disponível a partir do plano Equipe.",
  "status": 403,
  "code": "plan_feature",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Se a assinatura do salão ficar inativa, a conta entra em modo somente leitura: as consultas (GET) continuam e o resto responde 403 com code: "account_blocked". Veja Erros.

1. Crie um token no painel

1. Entre no painel do salão em pegavez.com.br com um usuário que tenha a permissão Gerenciar integrações (o perfil Dono tem por padrão).
2. Vá em Configurações → Integrações e clique em Novo token.
3. Dê um nome que diga onde o token vai ser usado (ex.: “Site — agendamento” ou “Planilha de comissões”).
4. Escolha as permissões. Marque só o que a integração precisa: o token nunca passa das permissões de quem o criou, e algumas permissões nunca podem ir para um token (veja Autenticação e permissões).
5. Escolha a validade (o padrão é 1 ano).
6. Copie o token. Ele começa com pv_ e aparece uma única vez: o Pega Vez guarda só um hash dele. Se perder, revogue e crie outro.

Guarde o token num cofre de segredos ou numa variável de ambiente do servidor. Nunca o coloque em código que roda no navegador ou no celular do cliente, nem em URL.

2. Ache o salonId

Toda rota da API traz o identificador do salão (um UUID) no caminho: /api/salons/{salonId}/.... Ele aparece na barra de endereço do painel, logo depois de /admin/:

https://pegavez.com.br/admin/3f6c2b1e-8d4a-4c4e-9b7a-2a5d0e9f1c11/agenda
                             └──────────── salonId ─────────────┘

O token só vale para o salão em que foi criado. Pedir outro salonId responde 404.

3. Faça a primeira chamada

Exporte o token e o salonId e liste os serviços ativos:

export PEGAVEZ_TOKEN="pv_..."
export SALON_ID="3f6c2b1e-8d4a-4c4e-9b7a-2a5d0e9f1c11"

curl -s "https://api.pegavez.com.br/api/salons/$SALON_ID/services?status=Active" \
  -H "Authorization: Bearer $PEGAVEZ_TOKEN"

Depois, consulte os horários livres de um dia para um serviço (para mais de um serviço ou profissional, repita o parâmetro: serviceIds=...&serviceIds=...):

curl -s -G "https://api.pegavez.com.br/api/salons/$SALON_ID/availability" \
  -H "Authorization: Bearer $PEGAVEZ_TOKEN" \
  --data-urlencode "date=2026-11-03" \
  --data-urlencode "serviceIds=SERVICE_ID"

A resposta traz, por profissional, os inícios livres (slots) com o offset do salão.

E crie um agendamento com um cliente novo (a Idempotency-Key evita agendar duas vezes se a rede falhar e você repetir o pedido; veja Idempotência):

curl -s "https://api.pegavez.com.br/api/salons/$SALON_ID/appointments" \
  -H "Authorization: Bearer $PEGAVEZ_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "professionalId": "PROFESSIONAL_ID",
    "startsAt": "2026-11-03T14:00:00-03:00",
    "serviceIds": ["SERVICE_ID"],
    "newCustomer": { "name": "Maria Souza", "phone": "+5511999998888" }
  }'

A resposta é 201 Created com o agendamento (status Confirmed) e o header Location. Para um cliente já cadastrado, mande customerId no lugar de newCustomer.

Os campos de cada endpoint, com exemplos de requisição e resposta, estão na referência da API.

Próximos passos

• Autenticação e permissões: o que o token pode e não pode fazer.
• Erros: trate 401, 403, 409 e 429 desde o começo.
• Webhooks: em vez de consultar a agenda de tempos em tempos, receba os eventos.