# API e conectores

Crie credenciais com permissões explícitas e configure consultas a sistemas externos.

Versão 1.0.0

**Integrações → API** reúne Chaves de API, Conectores, Mapeamentos, Testar API, Atividade e o guia disponível na interface. Administração exige Master. A API externa é REST; não representa um servidor MCP nem uma conversa com IA.

## Criar e manter uma chave

1. Em Chaves de API, use **+ Chave**.
2. Informe Nome, validade e limite por minuto.
3. Marque explicitamente as permissões necessárias aos recursos utilizados.
4. Salve e guarde o segredo exibido uma única vez no sistema que fará a integração.

A validade deve estar no futuro e em até 366 dias. O limite aceita de uma a 1.000 requisições por minuto, com padrão 120. Ao atingir o limite, o consumidor precisa respeitar o tempo de nova tentativa informado.

**Substituir** emite nova chave e revoga a anterior; atualize consumidores e vínculos de conectores/webhooks. **Revogar** interrompe seu uso. Não há edição livre do segredo existente. Credencial de serviço pertence à empresa e não deve ser distribuída como login pessoal de colaboradores.

## Configurar um conector

Use **+ Conector**, escolha destino externo, tabela/recurso, chave de escrita, mapeamento de entrada e caminhos da lista/cursor na resposta. Defina horários ou intervalo e fuso. O conector começa inativo para permitir conferência.

Autorização externa não é devolvida na edição; deixar o campo vazio preserva o segredo salvo. Testar faz uma consulta real ao destino e valida a resposta sem persistir registros nem avançar o cursor. Ativar permite a execução agendada conforme a configuração do serviço.

O destino precisa ser HTTPS público compatível. Endereços locais/privados, redirecionamentos e respostas fora dos limites são recusados. Cada página remota comporta até 100 linhas; cursor sem avanço ou resposta incompatível gera erro. Falha de uma página não deve ser tratada como sincronização concluída.

## Mapeamento, identidade e repetição

Escolha os campos aceitos pelo destino. Vendas usa Pedido; outros registros podem usar código externo durável com espaço de nomes. O sistema não deduz identidade pelo nome. Configuração do módulo, validações, registros pagos e fechamentos continuam valendo.

Uma repetição deve conservar a identificação da operação e seu conteúdo. Alterar conteúdo, mapeamento ou contexto pode gerar conflito. Para coleções e exportações, continue pelo cursor devolvido até o fim; uma primeira página não representa todos os dados.

## Testar e acompanhar

**Testar API** usa a sessão Master, não simula as permissões de uma chave. A validação executa o domínio em transação revertida; IDs apresentados na prévia não são registros salvos nem reservas. Conferir um exemplo de mapeamento apenas transforma campos e é um teste diferente.

Atividade mostra horário, origem, método, recurso, resposta e duração, sem corpos ou segredos. Erro de autorização exige conferir chave/permissões; conflito exige rever identidade/versão; erro de entrada exige corrigir os campos. Não repita uma gravação com nova identidade antes de conferir o resultado anterior.

## Disponibilidade

Gestão e testes ficam no web. O aplicativo usa sua sessão pessoal nas funções nativas e não oferece administração de chaves/conectores. A disponibilidade local do conector não significa homologação com um ERP específico; confira seu contrato e resultado de teste.