http-sankhya

Uma biblioteca TypeScript para interagir com a API do ERP Sankhya. Esta biblioteca simplifica a autenticação, o tratamento de respostas e a formatação de payloads para operações CRUD comuns.

Instalação

Certifique-se de ter as dependências instaladas:

npm install axios

Uso

Inicialização

Importe a classe Sankhya e inicialize-a com sua configuração.

import { Sankhya } from './src/Sankhya'; // Ajuste o caminho conforme necessário

const config = {
    urlBase: 'https://api.sandbox.sankhya.com.br', // URL Base da API do Sankhya
    clientId: 'seu-client-id',
    clientSecret: 'seu-client-secret',
    token: 'seu-token' // Opcional: Se você já tiver um token
};

const sankhya = new Sankhya(config);

Autenticação

Autentique-se na API para obter um token de sessão.

await sankhya.login();

Nota: A implementação de login utiliza um fluxo de bearer token ou credenciais enviadas via header, dependendo da configuração. Certifique-se de que seu backend suporta o endpoint de autenticação configurado.

Métodos e Exemplos

1. loadRecords (Buscar Múltiplos Registros)

Busca uma lista de registros com suporte a filtros, paginação e seleção de campos.

Exemplo Básico

const produtos = await sankhya.loadRecords({
    rootEntity: 'GrupoProduto', // Nome da Tabela/Entidade no Sankhya
    criteria: {
        expression: "ATIVO = 'S'" // Filtro SQL-like
    }
});

Exemplo com Paginação e Seleção de Campos

Para otimizar a performance, solicite apenas os campos necessários (fieldset) e use offsetPage para paginar.

const parceiros = await sankhya.loadRecords({
    rootEntity: 'Parceiro',
    offsetPage: 1, // Página 1 (0-indexada ou conforme API)
    criteria: {
        expression: "TIPPESSOA = 'F'"
    },
    entity: {
        fieldset: {
            list: "CODPARC,NOMEPARC,CGC_CPF,EMAIL" // Campos desejados
        }
    }
});

Exemplo com Campos de Apresentação

Se precisar dos valores formatados (lookup), ative includePresentationFields.

const vendas = await sankhya.loadRecords({
    rootEntity: 'CabecalhoNota',
    includePresentationFields: 'S', // Retorna descrições de chaves estrangeiras
    criteria: {
        expression: "DTNEG >= '01/01/2024'"
    }
});

2. loadRecord (Buscar Registro Único)

Busca um único registro específico, geralmente pela Chave Primária (PK).

const produto = await sankhya.loadRecord({
    rootEntity: 'Produto',
    rows: {
        row: {
            CODPROD: { "$": "1005" } // Chave Primária
        }
    },
    entity: {
        fieldset: {
            list: "*" // Retorna todos os campos
        }
    }
});

console.log(produto);
// Saída: { CODPROD: "1005", DESCRPROD: "PRODUTO TESTE", ... }

3. saveRecord (Criar ou Atualizar Registro)

Cria ou atualiza registros. A biblioteca formata automaticamente o payload do objeto localFields para o padrão exigido pelo Sankhya.

Criar Novo Registro

Para criar, omita a Chave Primária (se for auto-incremental) ou passe os valores necessários.

const novoGrupo = await sankhya.saveRecord({
    rootEntity: 'GrupoProduto',
    localFields: {
        DESCRGRUPOPROD: "NOVO GRUPO 2024",
        ATIVO: "S",
        // Outros campos obrigatórios...
    },
    // Opcional: Retornar campos criados (ex: ID gerado)
    entity: {
        fieldset: {
            list: "CODGRUPOPROD,DESCRGRUPOPROD"
        }
    }
});

Atualizar Registro Existente

Para atualizar um registro existente, você deve fornecer a propriedade key contendo a chave primária do registro. Isso instrui o Sankhya a realizar um update na linha específica.

const atualizacao = await sankhya.saveRecord({
    rootEntity: 'GrupoProduto',
    localFields: {
        DESCRGRUPOPROD: "NOME ATUALIZADO", // Campos a alterar
        ATIVO: "N"
    },
    key: {
        CODGRUPOPROD: "20310006" // Chave Primária (PK) para identificação do registro
    }
});

4. Execução de Serviço Genérico (execService)

Para endpoints que não sejam CRUD padrão (ex: executar Stored Procedures, ações de workflow, ou consultas de metadados), use execService.

Exemplo: Consultar Estoque (Serviço Hipotético)

const estoque = await sankhya.execService({
    serviceName: 'EstoqueSP.getEstoque',
    requestBody: {
        codProd: '1005',
        codEmp: '1'
    }
});

Exemplo: Deletar Registro de Forma Personalizada

Embora exista o método .delete(), algumas operações de exclusão no Sankhya são feitas via serviços específicos.

await sankhya.execService({
    serviceName: 'CRUDServiceProvider.removeRecord',
    requestBody: {
        entity: {
            rootEntity: 'Parceiro',
            pk: {
                CODPARC: { "$": "999" }
            }
        }
    }
});

Funcionalidades

• Tratamento de Resposta: Simplifica a resposta aninhada do Sankhya.
  • LoadRecords: Retorna Array<Objeto>.
  • LoadRecord: Retorna Objeto único (lida com ausência de metadados).
• Transformação de Payload: O método saveRecord aceita objetos simples JS (ex: { CAMPO: "Valor" }) e os converte automaticamente para { CAMPO: { "$": "Valor" } }.
• Tipagem TypeScript: Suporte completo a interfaces para garantir segurança de tipo no desenvolvimento.