Sankhya

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

Para conectar o Sankhya à Fluid, certifique-se de possuir os seguintes itens e acessos:

Acesso à Área do Desenvolvedor Sankhya: Necessário para gerar o client_id e o client_secret da sua aplicação.

Credenciais do Gateway: Acesso à tela Configurações Gateway dentro do Sankhya Om (ou sistemas do Grupo Sankhya) para obter o X-Token.

Permissões de Usuário: O usuário vinculado às chaves deve ter permissões ativas no Sankhya para os recursos que serão manipulados (ex.: clientes, pedidos).

Definição de Ambiente: Identificar se a conexão será feita em ambiente de testes (Sandbox) ou em operação real (Produção).

Como configurar no painel da Fluid

Acesse Conexões > Nova conexão > Sankhya.

Em Chaves, adicione:

ID do Client → valor do client_id

Chave Secreta do Cliente → valor do client_secret

X-Token → Token obtido na tela Configurações Gateway do Sankhya Om (ou de outros sistemas do Grupo Sankhya)

Ambiente → Tipo de ambiente: Sandbox ou Produção

Observação: client_id e client_secret podem ser gerados na Área do Desenvolvedor da Sankhya.

(Opcional) Opções avançadas e Proxy: configure apenas se sua rede exigir.

Clique em Salvar conexão e utilize Testar para validar.

Campos de entrada (conexão)

Campo	Obrigatório	Origem do Dado	Descrição
ID do Client	Sim	Área do Desenvolvedor Sankhya	O identificador único (client_id) da sua aplicação.
Chave Secreta	Sim	Área do Desenvolvedor Sankhya	A senha de acesso (client_secret) da sua aplicação.
X-Token	Sim	Configurações Gateway (Sankhya Om)	Token de autenticação para comunicação com o Gateway.
Ambiente	Sim	Seleção no sistema	Define o destino das requisições: Sandbox ou Produção.

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/