Recursos

Mapeamento por recurso: campos públicos → tabela/coluna canônica. Sempre que houver *, é uma allowlist; o que não está listado é rejeitado em entrada e não retornado em saída.

Convenções

• PII: dados pessoais (telefone, e-mail, anotação).
• Read: devolvido em GET.
• Write: aceito em POST/PATCH. * em vermelho na interface significa "não envie".
• Delete: o que realmente acontece ao chamar DELETE.

Account

GET/PATCH /v1/account · scope account:read / account:write

Nunca expostos: api_key, token, secret, webhook, prompt, stripe_customer_id, evolution, integracao_instance_id, whatsapp_api, instagram_api_token.

Subscription

GET /v1/subscription · scope subscription:read · somente leitura

Plano, status, trial_start, trial_end, current_period_start, current_period_end, canceled_at, ended_at. Nunca stripe_subscription_id ou stripe_customer_id.

Users

GET /v1/users, POST /v1/users/invitations, PATCH /v1/users/{id}, POST /v1/users/{id}/deactivate, POST /v1/users/{id}/reactivate · scopes users:read / users:write

Permite convidar somente profile_type = 'usuario'. Nunca promove para clinica/admin. Nunca troca clínica. Bloqueia desativar o último clinica ativo. Atualiza somente nome_completo.

Contacts

GET/POST /v1/contacts, GET/PATCH/DELETE /v1/contacts/{id}, POST /v1/contacts/{id}/move, POST /v1/contacts/{id}/follow-up/pause, POST /v1/contacts/{id}/follow-up/resume · scopes contacts:read / contacts:write / contacts:delete

Campos canônicos em português: nome, telefone, email, anotacoes, etapa_kanban_id, origem, servico_interesse. Aliases legados (name, phone, notes) não são expostos.

DELETE exige scope contacts:delete (alto risco, fora dos presets). Não cria cascata: se o contato tiver mensagens, agendamentos, follow-up, atribuições, prontuário ou logs, retorna 409 contact_has_history. Caso só tenha leads_tags, remove os vínculos e depois o contato.

Kanban

GET/POST /v1/kanban/stages, PATCH/DELETE /v1/kanban/stages/{id}, PUT /v1/kanban/stages/order · scopes kanban:read / kanban:write

• ordem: inteiro de 0 a 10.000.
• PUT /order: recebe todos os IDs ativos da clínica exatamente uma vez.
• DELETE ocupada: exige move_contacts_to_stage_id da mesma clínica e diferente da removida. Move todos e exclui em uma transação.

Follow-ups

Campanhas, templates, execuções e métricas · scopes followups:read / followups:write / followups:execute

• Campanha criada via API nasce inativa (ativo = false).
• activate e pause exigem followups:execute. Ativar exige pelo menos um template ativo.
• archive desativa campanha e templates, preserva follow_up_execucoes.
• Não há rota pública para criar/editar/apagar execução. Execuções são somente leitura.
• Criar/editar campanha não dispara a Edge Function processadora. O cron existente detecta campanhas ativas normalmente.
• Mídia (imagem_*) é somente leitura. V1 não cria upload nem duplica arquivos no Storage.

Ads

GET /v1/ads/contacts, GET/POST/PATCH/DELETE /v1/ads/rules · scopes ads:read / ads:write

/ads/contacts consulta leads.anuncio diretamente. Sem tabela nova. Os campos Meta (ad_name, ad_platform, ad_id etc) aparecem como null até a atribuição completa estar comprovada em produção. Detalhes em compatibilidade de atribuição.

custom_ads allowlist: ad_name, ad_phrase, ad_source, active. Delete físico somente se nenhum lead da clínica referencia o ad_name; senão marca active = false.

Links

GET/POST/PATCH/DELETE /v1/links/custom, /v1/links/tracking, GET /v1/links/contacts, GET /v1/links/metrics · scopes links:read / links:write

• tracking_links.slug: [a-z0-9-], 3–80, único na clínica/domínio.
• Delete de tracking com cliques preserva histórico e só desliga capture_enabled.
• Métricas agregadas não expõem client_ip ou client_user_agent.

Tags

GET/POST /v1/tags, PATCH/DELETE /v1/tags/{id}, PUT /v1/contacts/{id}/tags · scopes tags:read / tags:write

• PUT /contacts/{id}/tags aceita até 20 UUIDs, remove duplicatas, substitui o conjunto em transação.
• Delete em uso exige replacement_tag_id da mesma clínica e diferente.
• Campos whatsapp_label_id e whatsapp_owner nunca são expostos.

Services

GET/POST /v1/services, PATCH/DELETE /v1/services/{id} · scopes services:read / services:write

• preco_fixo para price_type = 'fixo'; preco_minimo/preco_maximo para 'faixa' com min <= max.
• tempo_medio_minutos: 5–480 ou nulo.
• DELETE é lógico: define ativo = false e nunca apaga agendamentos.

Appointments

GET/POST /v1/appointments, GET/PATCH/DELETE /v1/appointments/{id} · scopes appointments:read / appointments:write

• cliente_id precisa pertencer à clínica; usuario_id quando enviado precisa ser perfil ativo da clínica.
• data_fim > data_inicio.
• status em agendado|confirmado|realizado|pago|cancelado|nao_compareceu.
• DELETE grava status = 'cancelado' e preserva a linha para auditoria/métricas.

Fora da V1

Prontuários e dados clínicos, conteúdo de conversas (chat), envio de WhatsApp/Instagram, segredos de integrações (Evolution, Meta, Stripe), prompts, webhooks, upload de arquivos, alteração de assinatura.