> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # Crie um cliente > Escolha Client ou MessagingClient, autentique e defina a versão da API, os timeouts e as novas tentativas. O SDK tem dois clientes. A maioria das integrações cria os dois com a mesma chave. | Cliente do SDK | Use para | | - | - | | `Client` | Gerenciar sua equipe e seus projetos: Números, webhooks, eventos, operações, Clientes, campanhas, públicos, cobrança e registros de chamadas. | | `MessagingClient` | Agir por meio de um Número: enviar mensagens, conectar Números com o QuickLink, gerenciar modelos, executar campanhas pelo slug do projeto e controlar chamadas. | Os dois clientes aceitam uma chave da equipe ou uma credencial de projeto: | Credencial | `Client` | `MessagingClient` | | - | - | - | | Chave da equipe (`pmfa_…`) | `{ type: "organizationApiKey" }` | `{ type: "apiKey" }` | | Credencial de projeto (`pmfa_pt_…`) | `{ type: "projectToken" }` mais `projectId` | `{ type: "projectToken" }` | Uma chave só alcança o que as permissões dela permitem. Cada página de tarefa lista as permissões que os métodos dela precisam. Veja [Chaves de API](/pt-br/console/api-keys) para saber como criar chaves. Os exemplos destes guias usam três clientes chamados `platform`, `project` e `messaging`, criados como mostrado abaixo. ## Crie um cliente de equipe ```typescript theme={null} import { Client } from "@polymorfa/sdk"; const platform = new Client({ credential: { type: "organizationApiKey", value: process.env.POLYMORFA_KEY! }, apiVersion: "2026-09-22", }); ``` Um cliente de equipe alcança todos os projetos da equipe. Métodos que agem sobre um projeto recebem um argumento `projectId`. ## Trabalhe dentro de um projeto Chame `project(projectId)` para obter um cliente vinculado a um projeto: ```typescript theme={null} const project = platform.project(""); const events = await project.events.list({ limit: 25 }); ``` Um cliente de projeto tem os recursos do nível de projeto: `events`, `webhooks`, `webhookDeliveries`, `operations`, `flows`, `sipTrunks`, `calls`, `quickLinkSettings`, `sessionConfiguration`, `usage` e `callRetention`. Recursos da equipe, como `projects`, `members`, `billing`, `customers` e `campaigns`, ficam no cliente de equipe. Com uma credencial de projeto, crie o cliente de projeto diretamente: ```typescript theme={null} import { Client } from "@polymorfa/sdk"; const project = new Client({ credential: { type: "projectToken", value: process.env.POLYMORFA_KEY! }, projectId: "", apiVersion: "2026-09-22", }); ``` A API verifica se a credencial pertence a esse projeto. ## Crie um cliente de mensagens ```typescript theme={null} import { MessagingClient } from "@polymorfa/sdk"; const messaging = new MessagingClient({ credential: { type: "apiKey", value: process.env.POLYMORFA_KEY! }, apiVersion: "2026-09-22", }); ``` Use `{ type: "projectToken", value }` para uma credencial de projeto. Os métodos de mensagens recebem o Número como primeiro argumento, por exemplo `messaging.messages.send("", ...)`. ## Opções do cliente Os dois clientes aceitam estas opções: | Opção | Padrão | Efeito | | - | - | - | | `apiVersion` | `2026-09-22` | Data do contrato da API enviada no cabeçalho `Polymorfa-Version`. | | `timeoutMs` | `30000` | Tempo limite de cada tentativa, em milissegundos. | | `maxNetworkRetries` | `2` | Novas tentativas automáticas para solicitações que podem ser repetidas com segurança. Veja [Erros e novas tentativas](/pt-br/sdks/typescript/errors#novas-tentativas-automáticas). | | `baseUrl` | `https://api.polymorfa.com` | Host da API. | | `fetch` | `fetch` global | Uma implementação personalizada de `fetch`. | ## Defina a versão da API `apiVersion` é a data do contrato da API, no formato `YYYY-MM-DD`. Ela é separada da versão do pacote. Fixe essa data para que uma nova versão da API não mude o formato das respostas sem você perceber. Leia [Versionamento da API](/api/versioning) para ver as datas compatíveis. Você pode substituí-la em uma solicitação: ```typescript theme={null} const numbers = await platform.sessions.list(undefined, { apiVersion: "2026-09-22" }); console.log(numbers.metadata.apiVersion); ``` ## Defina opções por solicitação Todo método recebe um último argumento opcional com opções por solicitação: ```typescript theme={null} const controller = new AbortController(); const sent = await messaging.messages.send( "", { conversation: { phoneNumber: "+15550001111" }, content: { text: "Your order shipped" } }, { idempotencyKey: "order-1042-shipped", timeoutMs: 10_000, maxNetworkRetries: 3, signal: controller.signal, headers: { "x-correlation-id": "order-1042" }, }, ); ``` | Opção | Efeito | | - | - | | `idempotencyKey` | Enviada como `Idempotency-Key`. Permite que o SDK tente novamente uma escrita sem executá-la duas vezes. | | `timeoutMs` | Substitui o timeout do cliente nesta solicitação. | | `maxNetworkRetries` | Substitui o número de novas tentativas do cliente nesta solicitação. | | `signal` | Cancela a solicitação. O SDK lança `PolymorfaCancelledError`. | | `headers` | Adiciona cabeçalhos à solicitação. | | `apiVersion` | Substitui a versão da API do cliente. | ## Leia uma resposta Métodos que retornam um único resultado resolvem para `{ data, metadata }`: ```typescript theme={null} const response = await messaging.sessions.retrieve(""); console.log(response.data.data.status); console.log(response.metadata.status, response.metadata.requestId); ``` * `data` é o corpo da resposta já interpretado. A maioria dos corpos envolve o resultado no próprio campo `data`, então você lê `response.data.data`. O tipo de retorno indica o formato de cada método. * `metadata` contém o `status` HTTP, o `requestId`, a `apiVersion` resolvida, o número de tentativas (`attempts`) e os `headers` da resposta. Inclua o `requestId` quando entrar em contato com o suporte. Listas de eventos, webhooks, entregas, operações, registros de chamadas e opt-outs de chamadas retornam um objeto de página em vez disso. Veja [Leia todas as páginas](/pt-br/sdks/typescript/errors#leia-todas-as-páginas). ## Entregue um token de cliente ao navegador Código de navegador e de apps móveis não pode guardar uma chave da equipe nem uma credencial de projeto. Emita um token de cliente de curta duração no seu servidor e envie-o ao navegador: ```typescript theme={null} const minted = await messaging.clientTokens.mint({ session: "", ephemeralId: "user_42", ttlSeconds: 900, }); console.log(minted.data.data.token, minted.data.data.expiresAt); ``` O token só pode usar ações que estejam ao mesmo tempo no teto fixado na emissão e nas regras de cliente atuais do Número. Passe `allow` para definir um teto explícito; sem ele, o token registra as ações configuradas na sessão naquele momento. Leia e altere as regras com `clientTokens.retrieveRules` e `clientTokens.updateRules`. A emissão precisa de todas estas permissões: `sessions:manage`, `messages:write`, `contacts:read`, `presence:read`, `presence:observe` e `mcp`. Veja [Tokens de cliente](/pt-br/console/client-tokens). ## Chame um endpoint sem método do SDK `raw.request` envia uma solicitação autenticada para qualquer caminho da API. Ele usa a credencial, a versão da API, o timeout e as configurações de novas tentativas do cliente: ```typescript theme={null} const updated = await platform.raw.request<{ data: unknown }>({ method: "PATCH", path: "/messaging/projects//campaigns/", body: { name: "October launch" }, idempotencyKey: "rename-october-campaign", }); console.log(updated.metadata.status, updated.data); ``` Um cliente de projeto restringe `raw.request` ao próprio projeto. ## Controles de gastos Use o transporte autenticado do cliente de equipe para ler limites ou mudar uma ordem. Leituras exigem `billing:read`; escritas exigem `billing:manage` e Pay-As-You-Go. Credenciais de projeto e de cliente não podem fazer essas solicitações. ```ts theme={null} const response = await platform.raw.request<{ data: { revision: number; projects: Array<{ id: string }> }; }>({ method: "GET", path: "/platform/billing/priorities" }); await platform.raw.request({ method: "PUT", path: "/platform/billing/priorities", body: { scope: "project", resourceIds: response.data.data.projects.map(project => project.id).reverse(), expectedRevision: response.data.data.revision, }, }); ``` Envie a lista completa, do mais alto para o mais baixo. Para ordenar Clientes ou números, use `scope: "customer"` ou `scope: "number"`, inclua `projectId` e passe todos os Clientes ativos ou números reais desse projeto. Uma alteração simultânea retorna um conflito; leia de novo antes de escolher uma nova ordem. Os [limites mensais](/api-reference/platform/billing/set-billing-limit) usam a própria revisão por recurso. `limitCredits: null` remove um limite; zero bloqueia novas cobranças. O serviço pago mantém seu período pago. Para painéis nativos de Clientes e números, use a [leitura de um recurso](/api-reference/platform/billing/get-resource-billing-controls) e o [salvamento combinado](/api-reference/platform/billing/set-resource-billing-controls) com `platform.raw.request`. Eles aceitam `scope: project`, `customer` ou `number` no caminho. Um salvamento combinado exige `limitCredits`, `priority`, `expectedBudgetRevision` e `expectedPriorityRevision`; um conflito mantém os dois valores inalterados. A prioridade do projeto tem precedência. Os números herdam a prioridade do Cliente; uma prioridade de número mais alta a substitui dentro do projeto. Os números atribuídos a um Cliente compartilham o limite mensal dele. As leituras dos diretórios de limites e prioridades aceitam `scope=project` para omitir os diretórios de Clientes e números. A criação inicial de um QuickLink real também aceita `billingControls: { limitCredits: 250, priority: 30 }` com uma credencial `billing:manage` da equipe. Os controles são aplicados antes da admissão do pareamento. Conexões de teste e suplementares rejeitam esses campos. Use a solicitação raw documentada até que uma versão do pacote inclua métodos tipados. ## Verifique o status da API `SystemClient` não precisa de credencial. Use-o em health checks: ```typescript theme={null} import { SystemClient } from "@polymorfa/sdk"; const system = new SystemClient(); const version = await system.version(); console.log(version.data.apiVersion, version.data.minSupportedVersion); ``` Ele também tem `status()`, `health()` e `ping()`. ## Recursos de cada cliente `Client` (equipe): | Propriedade | Abrange | | - | - | | `sessions` | Números: listar, iniciar, parar, Safe Mode, mudanças de plano. Veja [Números](/pt-br/sdks/typescript/numbers). | | `webhooks`, `webhookDeliveries` | Endpoints de webhook e suas entregas. Veja [Webhooks](/pt-br/sdks/typescript/webhooks). | | `events`, `operations` | Histórico de eventos e trabalho assíncrono. Veja [Eventos e operações](/pt-br/sdks/typescript/events). | | `customers` | Clientes e links de pareamento. Veja [Clientes](/pt-br/sdks/typescript/customers). | | `campaigns`, `audiences`, `optOuts` | Campanhas e seus públicos. Veja [Campanhas](/pt-br/sdks/typescript/campaigns). | | `calls`, `callRetention`, `sipTrunks`, `callPolicy`, `callOptOuts` | Registros de chamadas e controles de chamadas. Veja [Chamadas](/pt-br/sdks/typescript/calls). | | `quickLinkSettings`, `sessionConfiguration` | Configurações salvas do QuickLink e padrões da equipe para Números. | | `banSafe` | Saúde, achados, incidentes e claims do BanSafe. | | `billing`, `usage` | Saldo, transações, preços e uso medido. | | `projects`, `members`, `auditLogs`, `securityIncidents`, `sessionBans`, `organizations`, `media` | Administração da equipe e armazenamento de mídia. | | `raw` | Qualquer caminho da API. | `MessagingClient`: | Propriedade | Abrange | | - | - | | `messages`, `chats`, `media` | Enviar, editar e excluir mensagens; ler o histórico armazenado; baixar mídia. Veja [Mensagens](/pt-br/sdks/typescript/messages). | | `sessions`, `quickLinks` | Conectar Números e ler o status deles. Veja [Números](/pt-br/sdks/typescript/numbers). | | `templates` | Modelos de mensagem do projeto. Veja [Modelos](/pt-br/sdks/typescript/templates). | | `campaigns` | Campanhas endereçadas pelo slug do projeto. Veja [Campanhas](/pt-br/sdks/typescript/campaigns). | | `voip`, `calls` | Fazer, atender e encerrar chamadas. Veja [Chamadas](/pt-br/sdks/typescript/calls). | | `clientTokens` | Tokens de cliente para navegador e as regras que os limitam. | | `contacts`, `identities`, `users` | Contatos, consulta de identidade e códigos de segurança. | | `groups`, `channels`, `labels` | Grupos, canais e etiquetas de conversa do WhatsApp. | | `profile`, `privacy`, `presence`, `observationPolicies` | Perfil, privacidade e presença do próprio Número. | | `business`, `quickReplies` | Perfil, catálogo e respostas rápidas do app WhatsApp Business. | | `banSafe` | Configurações do Safe Mode. | | `testing` | Eventos de teste para Números de teste. | | `webhooks` | Registros de webhook por Número. | | `raw` | Qualquer caminho da API. | A [referência da API](/api/overview) documenta todos os endpoints por trás desses métodos. ### Ranking misto de financiamento Leia as prioridades de um projeto com `GET /platform/billing/priorities?projectId=PROJECT_UUID`. Reordene os Clientes e os números reais desse projeto juntos com `PUT /platform/billing/priorities`: ```json theme={null} { "scope": "resource", "projectId": "22222222-2222-4222-8222-222222222222", "resources": [ { "scope": "number", "resourceId": "33333333-3333-4333-8333-333333333333" }, { "scope": "customer", "resourceId": "44444444-4444-4444-8444-444444444444" } ], "expectedRevision": 5 } ``` Inclua todos os Clientes ativos e números reais do projeto selecionado. Use a revisão da leitura correspondente; alterações simultâneas retornam 409. Uma prioridade de número mais alta fica acima da prioridade do Cliente dentro do projeto. A prioridade do projeto e todos os limites de gastos continuam valendo. Use o método de solicitação raw do cliente publicado para essas chamadas. Chaves da organização e tokens de projeto são gerenciados por uma pessoa conectada ao [Console](/pt-br/console/api-keys). O SDK não tem recursos de gerenciamento de chaves. As operações de tokens de cliente continuam disponíveis. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.