--- title: Sankhya (Legado) slug: sankhya-legado docTags: createdAt: 2024-01-22T17:27:19.469Z --- ## Introdução O conector **Sankhya** integra a **Fluid** à API do **Sankhya**, permitindo automatizar cadastros, consultas e atualizações de dados (clientes, produtos, pedidos e outros). ## Pré-requisitos 1. **Acesso ao ambiente Sankhya:** Ter um usuário com permissões administrativas ou de desenvolvedor para acessar o console de APIs. 2. **Credenciais de Integração:** Possuir as chaves **AppKey** e o **Token** de acesso (ou Bearer Token) gerados no ambiente Sankhya. 3. **Definição de Parâmetros:** Identificar se o seu tenant utiliza o padrão de cabeçalho `Token` ou `Authorization: Bearer `. 4. **Configuração de Rede:** Certificar-se de que a URL base do Sankhya está acessível para a Fluid (verificar necessidade de Proxy/Whitelist). *** ## Como configurar no painel da Fluid - Acesse **Conexões > Nova conexão > Sankhya**. - Em **Autenticação HTTP**, selecione a opção **API Key**. - Em **Definir parâmetros em**, escolha a opção **Cabeçalho (Header)**. - Em **Chaves**, adicione os seguintes parâmetros: - **AppKey** → Insira o valor da sua AppKey registrada no Sankhya. - **Token** → Insira o valor do token de acesso. :::hint{type="info"} Observação: Caso seu ambiente utilize o padrão Bearer, use a chave Authorization com o valor Bearer \. ::: - **(Opcional) Requisição:** Deixe sem preenchimento no cadastro da conexão. Os passos do conector definem Verbo, URL, Corpo e Cabeçalhos para cada operação. - **(Opcional) Cache:** Mantenha desabilitado por padrão. Ative somente para consultas; defina expiração e caminho no response para armazenamento. - **(Opcional) Opções avançadas e Proxy:** Configure apenas se sua rede exigir. - Clique em **Salvar conexão** e utilize o botão **Testar** para validar a comunicação. *** ## Campos de entrada (conexão) | Campo | Obrigatório | Onde informar | Descrição | | ----------- | -------------- | --------------- | ----------------------------------------------------------------------------- | | **Token** | Sim | Chaves (Header) | Token de acesso do Sankhya. Preferir token de serviço com permissões mínimas. | | **AppKey** | Sim | Chaves (Header) | Chave do aplicativo registrada na plataforma Sankhya. | | **Usuário** | Quando exigido | Corpo do passo | Utilizado apenas em ambientes que requerem sessão por login direto. | | **Senha** | Quando exigido | Corpo do passo | Utilizado apenas em ambientes que requerem sessão por login direto. | :::hint{type="info"} **Nota**: Verbo, URL, Corpo e Cabeçalhos específicos são definidos por passo conforme o recurso/ação. ::: ## Campos de saída O passo **Sankhya** retorna o corpo de resposta da API do Sankhya. Estrutura comum: ```javascript { "status": "success|error", "data": { /* objeto ou lista retornada pelo recurso */ }, "errors": [ { "code": "...", "message": "..." } ] } ``` A estrutura exata pode variar por recurso/versão da API. Utilize o **Transform** da Fluid para normalizar o retorno conforme seu domínio. ## Recursos e operações Lista consolidada dos recursos suportados e suas operações. | Recurso | Operações | | --------------------------------------- | ------------------ | | BAIRRO | Cadastro, Consulta | | BANCO | Consulta | | CENTRO DE RESULTADOS | Consulta | | CIDADE | Cadastro, Consulta | | CFOP | Consulta | | CLIENTES | Consulta | | CONTATO CLIENTES | Cadastro, Consulta | | COMO FAZER ALTERAÇÃO/INCLUSÃO DE DADOS? | altera/inclui | | COMO FAZER CONSULTA DE DADOS? | consulta | | TABELA DE PREÇO | Consulta | | USUÁRIO | Consulta | | CONSULTA DE HISTÓRICO DE LOGS | Consulta | | EMPRESA | Consulta | | ENDEREÇO | Cadastro, Consulta | | ESTOQUE | Consulta | | FORNECEDORES | Cadastro, Consulta | | KIT DE PRODUTOS | Cadastro, Consulta | | MOTORISTA | Cadastro, Consulta | | INCLUSÃO E ALTERAÇÃO DO ITEM DO PEDIDO | Inclusão/alteração | | NATUREZA | Consulta | | PEDIDOS | Cadastro, Consulta | :::hint{type="info"} **Observação**: Recursos e escopos dependem da habilitação no seu ambiente Sankhya. ::: ## Exemplo de uso Aguardando exemplos reais para publicação. Assim que fornecidos, serão incluídos os cenários mínimos: 1. **CLIENTES > Consulta** com filtros e paginação. 2. **PEDIDOS > Cadastro** com itens (arrays) e observações. ## Possíveis erros | Código/Tipo | Causa provável | Ação sugerida | | ------------------------- | -------------------------------------------------- | ---------------------------------------------------------- | | 401 Não autorizado | Token/AppKey inválidos ou expirados | Revogue e gere novo token. Confira usuário/senha e AppKey. | | 403 Proibido | Usuário sem permissão para o recurso | Ajuste perfis no Sankhya ou solicite liberação do módulo. | | 404 Não encontrado | Recurso/registro inexistente | Valide chaves (ex.: código do cliente) e filtros. | | 409 Conflito | Duplicidade em cadastro | Inclua lógica de upsert/consulta prévia. | | 422 Dados inválidos | Esquema incompatível, campos obrigatórios ausentes | Aplique validação JSON no passo e corrija o payload. | | 429 Limite de requisições | Rate limit do ambiente | Implemente retries exponenciais e backoff. | | 5xx Erro no provedor | Indisponibilidade momentânea | Re-tente, acione monitoramento e fallback. | ## Boas práticas 1. **Segurança**: restrinja o acesso às credenciais e faça rotação periódica do token. 2. **Observabilidade**: habilite logs de requisição/resposta e correle IDs de execução do fluxo. 3. **Paginação**: padronize limit e offset para grandes volumes. 4. **Resiliência**: implemente retries com backoff e circuit breaker em integrações críticas. 5. **Normalização**: use o Transformer da Fluid para mapear campos Sankhya → domínio do seu negócio. ## Validações e conformidade - O passo suporta **corpo dinâmico**, **template** e **validação JSON** para objetos e arrays aninhados. - Recomenda-se validar tipos, obrigatoriedade e formatos (datas, CNPJ/CPF, CEP) antes do envio. ## Referências - API oficial Sankhya: [https://developer.sankhya.com.br/](https://developer.sankhya.com.br/)