Changelog e compatibilidade

Política de compatibilidade do public-v1

A API pública tem uma versão: public-v1. Dentro dela, prometemos não quebrar integrações que sigam as regras abaixo.

Mudanças aditivas — podem acontecer a qualquer momento, sem versão nova:

• endpoints novos;
• campos novos nas respostas;
• parâmetros e campos opcionais novos nas requisições;
• valores novos em enums;
• eventos de webhook novos e campos novos no data dos eventos;
• ferramentas MCP novas;
• códigos de erro (code) novos e textos de erro diferentes.

Para isso não quebrar a sua integração: ignore campos que você não conhece, trate valores de enum desconhecidos, não dependa da ordem dos campos no JSON nem do texto das mensagens.

Mudanças que quebram — só numa versão nova (public-v2):

• remover endpoint, campo ou parâmetro;
• mudar o tipo ou o formato de um campo;
• tornar obrigatório um campo ou parâmetro que era opcional;
• mudar o significado de um campo ou de um status.

Essas regras são conferidas automaticamente no build da API: o documento OpenAPI publicado na referência é comparado com a versão anterior, e uma mudança que quebra não passa.

Quando uma versão nova sair, a anterior continua funcionando por um período de transição anunciado aqui, com antecedência.

Changelog

v1 — 2026-10-26

Primeira versão da integração do Pega Vez (public-v1), para os planos Equipe e Negócio (e o teste de 90 dias).

Tokens e acesso

• Tokens de integração por salão (pv_...), criados e revogados só no painel, com permissões escolhidas entre as de quem cria, validade opcional (padrão de 1 ano), último uso e até 50 tokens ativos por salão.
• Permissão efetiva = interseção token × membro atual; integrations.manage, billing.manage, staff.manage e roles.manage nunca vão num token.
• Host https://api.pegavez.com.br, só com token Bearer (/api/salons/{salonId}/..., /mcp e /health).
• Limite de 600 requisições por minuto por token (API e MCP somados), com 429 e Retry-After; token que não autentica: 60 por minuto por IP (IPv6 pela rede /64).
• Desativar o membro que criou o token revoga o token de vez.
• Plano Solo responde 403 plan_feature; conta bloqueada fica somente leitura (403 account_blocked nas escritas).

API REST — 23 endpoints (lista, referência):

• serviços e profissionais (listar e consultar);
• horários livres da equipe;
• agendamentos: listar, consultar, criar, remarcar, cancelar, confirmar, chegou, iniciar, concluir e não compareceu;
• clientes: buscar, consultar, cadastrar e editar;
• comandas: listar e consultar;
• relatórios de faturamento e de recebimentos.

E ainda:

• Idempotency-Key em CreateAppointment e CreateCustomer (24 h; idempotency_key_invalid, idempotency_in_progress, idempotency_unknown_result, idempotency_mismatch; Idempotency-Replayed: true na repetição).
• Erros em Problem Details, com mensagens em português e code estável nos casos que pedem tratamento.

Webhooks

• Eventos appointment.created, appointment.rescheduled, appointment.cancelled, appointment.status_changed, order.closed, order.cancelled e customer.created, mais o ping do envio de teste.
• Assinatura Pegavez-Signature (HMAC-SHA256 com segredo whsec_...), headers Pegavez-Event-Id e Pegavez-Event-Type.
• Prazo de 10 s por envio (com o corpo da resposta); 8 tentativas em até 24 h; desativação automática falhando sem parar (sem intervalo de mais de 25 h entre falhas) há 24 h com 20+ falhas seguidas, ou há 3 dias; “enviar teste” com sucesso zera as falhas; histórico de entregas de 30 dias no painel; até 10 webhooks por salão.

MCP

• Servidor em https://api.pegavez.com.br/mcp (Streamable HTTP, sem sessão, token Bearer) com 15 ferramentas: 9 de leitura e 6 de escrita.

Ainda não

• OAuth (para conectar assistentes sem colar token) e client credentials.
• Gerenciar tokens e webhooks pela API.