Sankhya (Legado)

11 min

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

Acesso ao ambiente Sankhya: Ter um usuário com permissões administrativas ou de desenvolvedor para acessar o console de APIs.

Credenciais de Integração: Possuir as chaves AppKey e o Token de acesso (ou Bearer Token) gerados no ambiente Sankhya.

Definição de Parâmetros: Identificar se o seu tenant utiliza o padrão de cabeçalho Token ou Authorization: Bearer <token>.

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.

Observação: Caso seu ambiente utilize o padrão Bearer, use a chave Authorization com o valor Bearer <seu_token>.

(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.

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:

{
  "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

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:

CLIENTES > Consulta com filtros e paginação.

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

Segurança: restrinja o acesso às credenciais e faça rotação periódica do token.

Observabilidade: habilite logs de requisição/resposta e correle IDs de execução do fluxo.

Paginação: padronize limit e offset para grandes volumes.

Resiliência: implemente retries com backoff e circuit breaker em integrações críticas.

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/