API do cliente

Se esta tradução divergir da versão em inglês, a versão em inglês prevalece.

A API Client é um serviço local dentro do aplicativo para automação avançada. Não é a API da nuvem pública e não deve ser exposta a redes não confiáveis.

Usos típicos

Use a API local quando desejar que um script confiável ou uma ferramenta local:

• acionar sincronização de deck;
• listar decks em nuvem ou locais;
• crie um baralho;
• buscar um baralho na nuvem;
• atualizar metadados do deck;
• excluir um baralho local;
• listar categorias;
• criar, atualizar, pesquisar ou excluir cartões;
• fazer upload ou excluir recursos do deck;
• integrar Cardary com um fluxo de trabalho pessoal.

Autenticação

Os endpoints protegidos exigem o estado de login do aplicativo e um segredo local por meio de:

• o cabeçalho X-API-SECRET; ou
• o parâmetro de consulta secreto.

Trate o segredo como uma credencial. Não cole-o em registros públicos, histórico do navegador, scripts compartilhados ou serviços remotos.

Grupos de endpoints

O aplicativo inclui grupos de endpoints para:

Grupo	Finalidade
Autenticação	Verifique o login e o estado de acesso à API local.
Sincronizar	Acione ou inspecione a sincronização do deck.
Convés	Liste, crie, busque, atualize e exclua decks.
Categorias	Leia a estrutura das categorias do deck.
Cartões	Pesquise, crie, atualize e exclua o conteúdo do cartão.
Recursos	Carregue e exclua mídia ou arquivos usados ​​pelos cartões.

As formas exatas da carga útil podem mudar com as versões do aplicativo. Verifique a implementação do aplicativo ao construir uma integração estrita.

Regras de segurança

• Use a API apenas em máquinas confiáveis.
• Não o vincule a redes públicas.
• Não compartilhe o segredo local.
• Teste primeiro em um deck pequeno.
• Sincronize antes e depois de grandes alterações automatizadas.
• Faça backup ou exporte decks importantes antes de atualizações em massa.
• Evite edições simultâneas da interface do usuário e de um script, a menos que você entenda o comportamento da sincronização.

Padrões de automação

Bons candidatos:

• criar um deck a partir de um pipeline de dados local;
• atualizar cartões de uma exportação CSV revisada;
• anexar imagens ou áudio gerados;
• acionar sincronização após uma importação controlada;
• cartões de pesquisa para verificações de qualidade locais.

Candidatos arriscados:

• excluir grandes conjuntos de cartões sem backup;
• reescrever campos em um deck sem visualização;
• upload de resultados de IA não revisados;
• executar scripts enquanto outro dispositivo edita o mesmo deck;
• expor a API através de um servidor remoto.

Solução de problemas

Problema	O que verificar
A solicitação não é autorizada	Estado de login e X-API-SECRET.
O deck não pode ser editado	Propriedade do deck, estado somente leitura e compatibilidade do tipo de deck.
O upload do recurso falha	Além de limites de anexos, caminho de arquivo, tamanho e rede.
A sincronização não atualiza outro dispositivo	Execute a sincronização em ambos os dispositivos e aguarde os recursos.
Erro de carga	Compare sua solicitação com a implementação atual do aplicativo.

Relacionado: Conta e sincronização e Importar cartões.