API do Cliente
O PowerPortalsPro publica uma superfície JSON-sobre-HTTP sob /api/* a qual qualquer aplicativo de página única pode chamar — o cliente Blazor WebAssembly na caixa de entrada usa para fazer backup IPowerPortalsProService e IAuthService, mas os mesmos endpoints são igualmente utilizáveis a partir de uma interface React, Vue ou vanilla JS hospedada ao lado (ou até mesmo cross-origin de) o servidor. Esta página é a referência completa: cada endpoint que pode ser chamado por cliente, com um exemplo de solicitação e resposta.
Para quem é isso
Se você está construindo um app Blazor e consumindo o framework via
IPowerPortalsProService, não precisa chamar esses endpoints diretamente — a implementação do cliente faz isso por você. Esta página documenta a superfície para equipes que escrevem um SPA que não seja Blazor, ou que conectam um cliente HTTP personalizado, contra o mesmo servidor.
Ativando os endpoints
UsePowerPortalsProWebServer faz a ligação dos endpoints de dados (CRUD da tabela, FetchXML, metadados, arquivos, localização, administração). MapAuthEndpoints<TUser> Liga a superfície de autenticação voltada para SPA — chame explicitamente se seu host precisar de autenticação por cookies de um SPA.
Ambas as chamadas são no-ops quando o recurso não está em uso, então conecte-as uma Program.cs vez, independentemente do modo de interatividade que o host use.
O tipo Rotas — fonte única de verdade
PowerPortalsPro.Web.Common.Routes expõe todo caminho de endpoint como uma propriedade fortemente tipada. Tanto o cliente de entrada quanto qualquer SPA externo baseado em C# devem referenciar essas constantes em vez de escrever manualmente as cadeias, de modo que uma renomeação do lado do servidor aparece como um erro de compilação em vez de um 404 em tempo de execução. Clientes JavaScript/TypeScript obviamente precisarão fazer os caminhos em linha, mas o lado C# de Routes permanece a referência canônica para o que são esses caminhos.
Routes.Api cobre os endpoints de dados e administradores; Routes.Api.Auth cobre o login / cadastro; Routes.Api.Auth.Manage cobre as operações de gerenciamento de contas do usuário logado.
Modelo de autenticação — cookies, não tokens
A autenticação é baseada em cookies do navegador. Não existe uma etapa de emissão do JWT. Um SPA chama /api/auth/login, o servidor define o .AspNetCore.Identity.Application cookie na resposta, e o navegador o anexa em cada requisição subsequente — incluindo chamadas de dados sob /api/table/*. Do JavaScript, isso significa fetch(..., { credentials: 'include' }) que a cada chamada (ou axios.defaults.withCredentials = true); sem ele, o cookie é descartado e o servidor retorna 401. Todos os exemplos abaixo incluem isso.
SPAs de origem cruzada
Se o SPA e o servidor estiverem em origens diferentes, o servidor deve enviar
Access-Control-Allow-Origin: <spa-origin>(não*) eAccess-Control-Allow-Credentials: true, e o SPA deve usarcredentials: 'include'. Hospedagem de mesma origem (o SPA servido do mesmo local que a API) evita o problema completamente.
A forma do recorde
Todo endpoint de dados que lê ou escreve uma linha troca o mesmo TableRecord envelope. properties é um mapa do nome lógico da coluna → um objeto valor tipado cujo $type discriminador identifica o tipo da coluna. permissions é uma máscara bit-flag (Read 1, Create 2, Write 4, Delete 8, Append 16, AppendTo 32) que descreve o que o usuário atual pode fazer com a linha. Nas escritas você só precisa enviar as colunas que está mudando.
Os $type valores espelham o tipo de atributo do Dataverse: 0 Booleano, 2 DateTime, 3 Decimal, 4 Double, 5 Integer, 6 Lookup, 8 Money, 11 Choice, 14 String, 15 Uniqueidentifier, 40 MultiSelectChoice, 41 File, 42 Image. As consultas adicionam name + tableName; número, dinheiro e valores de data carregam um Dataverse formattedValueformatado por .
Respostas de erro
Chamadas falhadas retornam o RFC 9457 application/problem+json. A implementação do cliente na caixa de entrada reidrata o tipo original de exceção CLR dos detalhes do problema, de modo que o lado do servidor projeta a superfície como a mesma exceção no cliente; para non-.NET SPAs, os type campos / title / detail status / são o handle padrão.
Referência de ponto final
Cada endpoint abaixo mostra o método e o caminho, o que ele faz, uma solicitação de exemplo (como chamada de navegador fetch ) e uma resposta de exemplo. Segmentos de caminho em {braces} são marcadores de posição. A menos que indicado o contrário, uma resposta 2xx é o caso de sucesso e as falhas retornam como problem+json.
Discos & CRUD
Crear, ler, atualizar e excluir registros únicos, além de consultas FetchXML arbitrárias e lotes transacionais. Respaldado por UsePowerPortalsProWebServer; toda leitura e escrita aplica ao consumidor ITablePermissionHandler / ITableRecordPermissionHandler interceptadores e a qualquer registrado IFetchXmlBuilderInterceptor.
POST /api/table/{tableLogicalName}
Cria uma nova linha na tabela nomeada. Envie um TableRecord que carrega as colunas para set; a resposta retorna o id do novo registro.
Pedido
Resposta
GET /api/table/{tableLogicalName}/{recordId}
Lê uma única linha por id. O parâmetro opcional ?columns= de consulta (nomes lógicos separados por vírgulas) restringe a projeção — omita-o para recuperar o conjunto padrão de colunas da tabela.
Pedido
Resposta
PATCH /api/table/{tableLogicalName}/{recordId}
Atualiza uma linha existente. Apenas as colunas presentes em properties estão escritas, então envie apenas os valores alterados.
Pedido
Resposta
DELETE /api/table/{tableLogicalName}/{recordId}
Exclui a linha por id.
Pedido
Resposta
GET /api/retrieveMultiple?fetchXml=…
Executa uma consulta FetchXML arbitrária e retorna as linhas correspondentes mais as informações de paginação. Codifice o FetchXML na fetchXml string de consulta — de C#, Routes.Api.GetRetrieveMultipleRoute(fetchXml) faz isso para você.
Pedido
Resposta
POST /api/executeMultiple?returnResponses=true|false
Executa um lote de requisições heterogêneas (Criar / Atualizar / Deletar / Associar / Dissociar) em uma única transação de banco de dados — se alguma falhar, todo o lote reverte. O corpo é um array JSON de OrganizationRequest objetos discriminados por $type. Passe ?returnResponses=false para pular a criação da lista de respostas por pedido.
Pedido
Resposta
Grades e mapas
Endpoints de consulta compostos por servidor. Em vez de fazer o cliente construir FetchXML, você passa um view id (ou seu próprio FetchXML) além de busca / ordenação / paginação, e o servidor resolve as colunas, aplica permissões e executa a consulta — o mesmo caminho de fonte única de verdade que o MainGrid e os componentes do gráfico usam.
POST /api/grids/data
Carrega uma página de dados de grade. Forneça um viewId ou seu próprio fetchXml, além de filtros opcionais searchTextde paginação sortse coluna. A resposta contém as linhas, as definições de colunas resolvidas e a máscara de permissões da tabela do chamador.
Pedido
Resposta
POST /api/charts/data
As cargas agregaram dados de cartas moldadas para os componentes de cartografia. Aceita uma configuração agregada, um viewId, ou raw fetchXml, mais o mapeamento de colunas de rótulos / valores / séries; retorna rótulos e conjuntos de dados no estilo Chart.js.
Pedido
Resposta
Metadados e permissões
Buscas somente leitura para metadados de tabela e visualização, a máscara de permissões do usuário atual e configurações em toda a organização. Todos são armazenados em cache do lado do servidor, então chamadas repetidas são baratas.
GET /api/tableMetadata/{tableLogicalName}
Retorna os metadados de uma tabela — colunas (com tipos, rótulos e restrições), colunas de id / nome / imagem primárias e relacionamentos.
Pedido
Resposta
GET /api/permissions/table/{tableLogicalName}
Retorna a máscara combinada TableSecurityPermission do usuário atual para a tabela como um único inteiro (sinalizadores de bit: Leitura 1, Criação 2, Escrita 4, Exclusão 8, Anexo 16, Anexo 32).
Pedido
Resposta
GET /api/viewMetadata/{viewId}
Retorna os metadados de uma visualização salva pelo seu GUID — seu FetchXML, colunas de layout e flags de visualização. A rota requer um GUID, que é como ela é desambiguada da rota de todas as visões abaixo.
Pedido
Resposta
GET /api/viewMetadata/{tableLogicalName}
Retorna todas as visualizações salvas para uma tabela. Compartilha o /api/viewMetadata/ prefixo com a rota by-id — um segmento não-GUID (nome lógico de tabela) cai aqui.
Pedido
Resposta
GET /api/organizationSettings
Retorna configurações organizacionais provenientes do registro da organização Dataverse: a moeda padrão, a lista de extensões de arquivos bloqueadas e o tamanho máximo de upload em bytes.
Pedido
Resposta
Arquivos
Leia o conteúdo das colunas de arquivos e imagens. Cargas binárias são retornadas codificadas base64 dentro do JSON; A includeData flag permite que você busque apenas metadados (por exemplo, para renderizar uma lista de download) sem transferir bytes.
GET /api/files/{tableLogicalName}/{recordId}/{columnName}?includeData=…
Retorna os metadados do arquivo de uma coluna de arquivo/imagem em um registro. Com ?includeData=true o conteúdo base64 é incorporado; com false apenas o nome e o tamanho retornam.
Pedido
Resposta
POST /api/files/{tableLogicalName}/{columnName}/batch?includeData=…
Obtém metadados de arquivos (e, opcionalmente, conteúdo) para muitos registros da mesma tabela / coluna em uma única viagem de ida e volta — o corpo é um array JSON de GUIDs de registros. Usado pelo Download Selected do FileGrid para que o cliente não dispare N chamadas separadas.
Pedido
Resposta
POST /api/files/createFileArchive
Zipa os valores escolhidos da coluna do arquivo para um conjunto de registros do lado do servidor. Retorna o fluxo bruto application/zip por padrão, ou — com responseFormat: 1 — um envelope JSON contendo o arquivo base64. POST (não GET) para que listas de IDs grandes não atinjam limites de comprimento de URL.
Pedido
Resposta
Fibrados de localização
Cordas localizadas para front-ends que não são Blazor. A /api/localizedStrings rota retorna toda a árvore para uma cultura; as /localizations/* rotas servem pacotes com impressão digital, imutáveis em cache (padrão, por tabela, por visualização) para carregamento incremental eficiente — esses são públicos e não exigem o cookie de autenticação.
GET /api/localizedStrings/{culture}
Retorna a árvore completa de strings localizadas para uma cultura como um objeto aninhado — strings de framework, overrides de app, etiquetas de tabela e escolha.
Pedido
Resposta
GET /localizations/version
Retorna o manifesto de localização — apenas a lista de locais suportados. Servia sem cache para que uma nova versão fosse detectada no próximo carregamento da página. Público.
Pedido
Resposta
GET /localizations/{locale}/thumbprints
Retorna as impressões digitais de conteúdo para um local: o pacote padrão mais cada tabela e visualização carregadas. Os clientes buscam esses pacotes e depois solicitam apenas os pacotes cuja impressão digital foi alterada. Público.
Pedido
Resposta
GET /localizations/default/{filename} · /tables/{tableName}/{filename} · /views/{viewId}/{filename}
As três famílias de bundles — padrão (strings de corte transversal), por tabela (strings de uma tabela mais as escolhas globais referenciadas por suas colunas) e por visualização. O nome do arquivo é {locale}.{thumbprint}.json e cada um é servido public, immutable, max-age=31536000, então uma impressão digital estável é um acerto garantido no cache. Público.
Pedido
Resposta
Cultura
Muda a cultura ativa do navegador ao escrever o cookie de cultura.
GET /Culture/{culture}?redirectUri=…
Define o cookie de cultura e 302-redireciona para redirectUri. Navegue até ele (carregamento total da página) em vez de buscar, assim o Set-Cookie redirecionamento e entra em efeito. Público.
Pedido
Resposta
Admin — gerenciamento de cache
Inspeção e invalidação do cache do servidor. Todos os três endpoints são bloqueados por [Authorize(Roles = "SystemAdmin")] — apenas um administrador logado pode chamá-los.
GET /api/caches
Lista os nomes de todos os caches registrados do lado do servidor. Requer o papel de Administrador de Sistema.
Pedido
Resposta
POST /api/caches/clear
Limpa todos os caches do lado do servidor e retorna um resultado por cache (se foi bem-sucedido e quanto tempo levou). Requer o papel de Administrador de Sistema.
Pedido
Resposta
POST /api/caches/{cacheName}/clear
Limpa um único cache nomeado (o nome vem do endpoint da lista). Retorna 404 se nenhum cache com esse nome estiver registrado. Requer o papel de Administrador de Sistema.
Pedido
Resposta
Autenticação
Login, cadastro e ciclo de vida da conta, respaldados por MapAuthEndpoints<TUser>. Baseado em cookies: um login bem-sucedido configura o cookie da aplicação ASP.NET Core Identity, e toda chamada posterior autentica ao reintroduzi-lo. A maioria retorna um result enum em HTTP 200 em vez de sinalizar o resultado através do código de status.
POST /api/auth/login
Faz login com e-mail + senha. O result enum distingue sucesso, um segundo fator obrigatório, credenciais ruins, um e-mail não confirmado e bloqueio. Em caso de sucesso, o cookie de autenticação é definido na resposta.
Pedido
Resposta
POST /api/auth/login/2fa
Completa um login retornado RequiresTwoFactor enviando o código do autenticador (ou de recuperação). rememberMachine Define o cookie do navegador confiável para que logins futuros neste navegador pulem o segundo fator.
Pedido
Resposta
POST /api/auth/logout
Limpa o cookie de autenticação, encerrando a sessão.
Pedido
Resposta
POST /api/auth/register
Cria uma nova conta local. Dependendo da configuração, o resultado é um e-mail de confirmação enviado, um login imediato ou um conflito com um e-mail existente. Falhas de senha fraca e outras validações retornam como 400 problem+json.
Pedido
Resposta
POST /api/auth/forgot-password
Inicia uma redefinição de senha enviando um link de redefinição por e-mail. Sempre devolve 200 sem saber se o endereço existe ou não, então não pode ser usado para sondar e-mails registrados.
Pedido
Resposta
POST /api/auth/reset-password
Completa um reset usando o token do e-mail mais a nova senha. result distingue sucesso, um token inválido/expirado e uma senha rejeitada (com as mensagens de validação em errors).
Pedido
Resposta
POST /api/auth/confirm-email
Confirma um e-mail recém-registrado usando o ID de usuário e o token do link de confirmação.
Pedido
Resposta
POST /api/auth/resend-email-confirmation
Reenvia o link de confirmação por e-mail. Assim como o esquecido de senha, ele sempre retorna 200 sem o corpo para evitar vazar quais endereços estão registrados.
Pedido
Resposta
GET /api/auth/options
components.PowerPortalsPro.Demo.Client.Customizations.Pages.ClientApi.ClientApiPage.ep-auth-options-desc
Pedido
Resposta
GET /api/auth/external-login?provider=…&returnUrl=…
Inicia o fluxo OAuth para um provedor. Ele retorna um desafio 302 ao provedor, então navegue o navegador até ele (não busque) — um SPA deve definir window.location.href.
Pedido
Resposta
GET /api/auth/external-login/pending
Após o retorno do OAuth, faz snapshots do login externo em voo: o provedor, as reivindicações da identidade e — quando o e-mail corresponde a mais de uma identidade de portal — a lista de candidatos para escolher. Retorna o 204 quando não há login pendente.
Pedido
Resposta
POST /api/auth/external-login/confirm
Conclui um login externo pela primeira vez para uma nova conta confirmando o e-mail para o associado. Resolve para um login, um e-mail de confirmação, sem pendência ou falha.
Pedido
Resposta
POST /api/auth/external-login/select
Conclui um login externo quando a identidade corresponde a múltiplas identidades do portal, escolhendo qual delas (Contato ou UsuárioSistema) usar para entrar.
Pedido
Resposta
GET /api/auth/me
Snapshot do diretor atual — id, nome, e-mail, funções e a tabela de apoio (contact vs. systemuser), além de qualquer identidade alternativa de irmão. Retorna uma forma anônima (isAuthenticated: false) em vez de 401 quando não há cookie presente, então um SPA pode chamá-la na primeira pintura sem desviar no código de status.
Pedido
Resposta
POST /api/auth/switch-identity
Troca o cookie atual pela identidade alternativa do usuário (o pareamento Contact↔SystemUser apareceu em /api/auth/me). O corpo JSON é um objeto vazio.
Pedido
Resposta
Gerenciamento de contas
As operações de autoatendimento do usuário logado sob /api/auth/manage/* — perfil, senha, e-mail, dois fatores, logins externos vinculados e dados pessoais. Todos exigem uma sessão autenticada e espelham as páginas clássicas /Account/Manage do Razor do framework.
GET /api/auth/manage/profile
Retorna o perfil do usuário (nome, celular, e-mail) lido do contato vinculado do Dataverse, além dos flags de status de Identidade (e-mail confirmado, tem senha, 2FA ativado, somente leitura).
Pedido
Resposta
POST /api/auth/manage/profile
Atualiza o nome/sobrenome e o celular no contato vinculado. Retorna 200 em caso de sucesso; As identidades suportadas pelo usuário do SystemUser, são somente leitura e recebem 403.
Pedido
Resposta
POST /api/auth/manage/password/set
Adiciona uma senha local para uma conta que não tem uma (por exemplo, uma conta que só permite login externo). Mensagens de validação, se houver, retornam em errors.
Pedido
Resposta
POST /api/auth/manage/password/change
Altera a senha local; É necessário a senha atual. result Distingue sucesso, senha atual errada e senha nova rejeitada.
Pedido
Resposta
POST /api/auth/manage/email/change
Inicia uma alteração de e-mail enviando um link de confirmação para o novo endereço. A mudança só entra em vigor quando esse link for seguido.
Pedido
Resposta
POST /api/auth/manage/email/send-confirmation
Reenvia o link de confirmação do e-mail atual do usuário. sent é falso quando o e-mail já está confirmado.
Pedido
Resposta
GET /api/auth/manage/2fa
Retorna o estado da 2FA — se um autenticador está registrado, se a 2FA está ativada, se o navegador é lembrado e quantos códigos de recuperação restam.
Pedido
Resposta
GET /api/auth/manage/authenticator/setup
Retorna a chave compartilhada e otpauth:// o URI para a tela de registro do código QR. Pare-o com o endpoint de verificação para finalizar a ativação da 2FA.
Pedido
Resposta
POST /api/auth/manage/authenticator/verify
Verifica um código do app autenticador e ativa a 2FA. Na primeira inscrição, a resposta também retorna o conjunto inicial de códigos de recuperação.
Pedido
Resposta
POST /api/auth/manage/authenticator/reset
Gira a chave autenticadora. Isso também desativa a 2FA, então o usuário deve se reinscrever.
Pedido
Resposta
POST /api/auth/manage/2fa/disable
Desativa o 2FA da conta.
Pedido
Resposta
POST /api/auth/manage/2fa/recovery-codes/generate
Regenera os códigos de recuperação, substituindo qualquer conjunto existente, e retorna os novos códigos.
Pedido
Resposta
POST /api/auth/manage/2fa/forget-browser
Remove o cookie do dispositivo confiável deste navegador, então 2FA será necessário novamente no próximo login aqui.
Pedido
Resposta
GET /api/auth/manage/external-logins
Lista os logins externos atualmente vinculados à conta.
Pedido
Resposta
GET /api/auth/manage/login-info
Uma visão combinada dos caminhos de login do usuário — logins externos vinculados mais se uma senha local está definida — usada para decidir se remover um login bloquearia o acesso do usuário.
Pedido
Resposta
GET /api/auth/manage/external-logins/link?provider=…
Inicia o fluxo OAuth que vincula um provedor adicional à conta logada. Retorna um desafio 302, então navegue até ele em vez de buscar.
Pedido
Resposta
GET /api/auth/manage/external-logins/link/callback
O retorno OAuth para o fluxo de link. O provedor redireciona o navegador para aqui; O servidor anexa o login e redireciona 302 para o returnUrl original fornecido. Você não liga diretamente.
Pedido
Resposta
POST /api/auth/manage/external-logins/remove
Desvincula um login externo por provedor + chave de provedor.
Pedido
Resposta
GET /api/auth/manage/personal-data
Exporta os dados pessoais do usuário — todas [PersonalData] as propriedades mais seus logins externos vinculados — para download no estilo GDPR.
Pedido
Resposta
POST /api/auth/manage/personal-data/delete
Exclui permanentemente a conta do usuário e o desconecta. Requer a senha atual quando a conta tem uma; Passe null por contas apenas externas. result Distingue sucesso, senha errada e o caso em que uma senha é necessária, mas não foi fornecida.
Pedido
Resposta
Veja também
Documentação relacionada:
IPowerPortalsProService — o wrapper C# ao redor desses endpoints — o que seus componentes Blazor injetam quando não precisam emitir HTTP bruto por conta própria.Login SystemUser — Contexto sobre o porquê/api/auth/mede relatóriostableName: "systemuser"para alguns diretores etableName: "contact"para outros.