> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Segurança e erros

> Proteja as credenciais de parceiro, isole os clientes e trate falhas do SDK

## Proteger as chaves de parceiro

As chaves de parceiro autorizam operações em todo o projeto. Armazene-as em um gerenciador de
segredos do lado do servidor ou em uma variável de ambiente criptografada e injete-as somente em
processos de backend confiáveis.

> [!WARNING]
>
> Nunca envie uma chave de parceiro ao seu frontend como configuração, resposta de API, parâmetro
> de consulta ou variável de ambiente renderizada. O seu backend deve expor endpoints
> restritos que autorizem o cliente conectado antes de chamar o Social media studio.

Use chaves `pk_test_` durante o desenvolvimento e chaves `pk_live_` somente em produção.
Mantenha os projetos de teste e de produção separados, faça a rotação das chaves periodicamente e revogue uma chave
imediatamente se ela puder ter sido exposta.

## Autorizar cada operação de cliente

O SDK autentica o seu aplicativo, não o cliente que usa o seu produto.
Antes de cada chamada ao SDK:

1. Autentique o cliente no seu aplicativo.
2. Resolva, no seu servidor, o `endUserId` do Social media studio armazenado para o cliente.
3. Verifique se os IDs de conexão e de post solicitados pertencem a esse cliente.
4. Chame o SDK usando esses IDs resolvidos pelo servidor.

Nunca aceite um `endUserId` arbitrário vindo de um navegador e o repasse sem
verificar a propriedade no seu banco de dados.

## Escopos de chave

As chaves de parceiro podem ser restritas às capacidades de que um serviço precisa:

| Recurso | Escopo de leitura | Escopo de escrita |
| - | - | - |
| Usuários finais | `end_users:read` | `end_users:write` |
| Conexões | `connections:read` | `connections:write` |
| Sessões de conexão | `connect_sessions:read` | `connect_sessions:write` |
| Posts | `posts:read` | `posts:write` |
| Mídia | — | `media:write` |
| Webhooks | `webhooks:read` | `webhooks:write` |

Use chaves separadas e com o mínimo de privilégios para serviços independentes sempre que possível.

## Tratar erros do SDK

Toda requisição de API malsucedida lança `SoMePlatformError`:

```ts theme={null}
import {
  SoMePlatformError,
  SoMePlatformClient,
} from "@social-media-scheduler/sdk";

try {
  await soMe.posts.get(endUserId, postId);
} catch (error) {
  if (error instanceof SoMePlatformError) {
    logger.error("Social media studio request failed", {
      status: error.status,
      details: error.details,
    });
  }
  throw error;
}
```

| Status | Significado | Tratamento recomendado |
| - | - | - |
| `0` | Erro de rede, falha de DNS ou tempo limite da requisição | Tente novamente com espera crescente quando for seguro |
| `400` | Entrada inválida, incompatibilidade de plataforma ou URL de retorno não permitida | Corrija a requisição; não tente novamente sem alterá-la |
| `401` | Chave de parceiro ausente, inválida, expirada ou revogada | Pare e faça a rotação ou a substituição da chave |
| `403` | A chave não tem um escopo necessário | Use uma chave com os escopos corretos |
| `404` | O recurso não existe neste projeto/usuário final | Reconcilie os IDs armazenados |
| `409` | O espaço de trabalho do cliente não está pronto | Tente novamente depois de resolver o estado informado |
| `429` | Limite de taxa atingido | Respeite a orientação de nova tentativa e use espera exponencial |
| `5xx` | Falha temporária do serviço do Social media studio | Tente novamente com espera exponencial limitada |

Na criação de posts, as novas tentativas só são seguras quando você reutiliza a mesma chave de
idempotência. Não repita cegamente outras operações de escrita, a menos que o seu aplicativo consiga
confirmar o resultado delas.

## Logs

Registre o contexto da requisição, como o ID do seu cliente, o ID do usuário final, a operação, o status
HTTP e a chave de idempotência. Não registre chaves de parceiro completas, segredos de webhook,
tokens OAuth, URLs de envio pré-assinadas nem metadados sensíveis de clientes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.