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. Este método utiliza o serviço CRUDServiceProvider.loadRecords.

Exemplo Básico

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

// Retorno Exemplo:
// [
//     { "CODGRUPOPROD": "100", "DESCRGRUPOPROD": "GERAL", "ATIVO": "S" },
//     { "CODGRUPOPROD": "101", "DESCRGRUPOPROD": "MATERIA PRIMA", "ATIVO": "S" }
// ]

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
        }
    }
});

// Retorno Exemplo:
// [
//     { "CODPARC": "200", "NOMEPARC": "CLIENTE EXEMPLO", "CGC_CPF": "123.456.789-00", "EMAIL": "[email protected]" },
//     { "CODPARC": "201", "NOMEPARC": "OUTRO CLIENTE", "CGC_CPF": "987.654.321-00", "EMAIL": "[email protected]" }
// ]

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'"
    }
});

// Retorno Exemplo:
// [
//     {
//         "NUNOTA": "100",
//         "DTNEG": "01/01/2024",
//         "CODPARC": "200",
//         "Parceiro_NOMEPARC": "CLIENTE EXEMPLO"
//     }
// ]

2. loadRecord (Buscar Registro Único)

Busca um único registro específico, geralmente pela Chave Primária (PK). Este método utiliza o serviço CRUDServiceProvider.loadRecord.

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", ... }

// Retorno Exemplo Completo:
// {
//     "CODPROD": "1005",
//     "DESCRPROD": "PRODUTO TESTE",
//     "ATIVO": "S",
//     "PRECO": "50.00"
// }

3. saveRecord (Criar ou Atualizar Registro)

Cria ou atualiza registros. Este método é específico para manipulações que utilizam o serviço CRUDServiceProvider.saveRecord. 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"
        }
    }
});

// Retorno Exemplo:
// {
//     "CODGRUPOPROD": "161000",
//     "DESCRGRUPOPROD": "NOVO GRUPO 2024"
// }

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
    }
});

#### Retorno Exemplo (Sucesso)
Tanto na criação quanto na atualização, a biblioteca processa a resposta e retorna um objeto limpo com os campos solicitados no `fieldset`.

```json
{
    "CODGRUPOPROD": "160700",
    "DESCRGRUPOPROD": "NOME ATUALIZADO",
    "ATIVO": "N"
}

Retorno Exemplo (Falha)

Caso ocorra algum erro (status '0'), a biblioteca retorna o objeto de resposta original contendo a mensagem de erro.

{
    "serviceName": "CRUDServiceProvider.saveRecord",
    "status": "0",
    "pendingPrinting": "false",
    "transactionId": "123456789",
    "statusMessage": "Erro: O registro já existe ou violação de restrição de integridade."
}

---

### 4. Execução de Serviço Mge (execServiceMge)

Para endpoints que não sejam CRUD padrão (ex: executar Stored Procedures, ações de workflow, ou consultas de metadados), use `execServiceMge`. Este método utiliza o endpoint `/gateway/v1/mge/service.sbr`.

#### Exemplo: Consultar Estoque (Serviço Hipotético)
```typescript
const estoque = await sankhya.execServiceMge({
    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.execServiceMge({
    serviceName: 'CRUDServiceProvider.removeRecord',
    requestBody: {
        entity: {
            rootEntity: 'Parceiro',
            pk: {
                CODPARC: { "$": "999" }
            }
        }
    }
});

// Retorno Exemplo:
// {
//     "serviceName": "CRUDServiceProvider.removeRecord",
//     "status": "1",
//     "pendingPrinting": "false",
//     "transactionId": "123456789",
//     "responseBody": {}
// }

5. Execução de Serviço MgeCom (execServiceMgeCom)

Para serviços diversos do Sankhya que utilizam o endpoint mgecom (/gateway/v1/mgecom/service.sbr), como inclusão de notas, operações comerciais, etc. Este método recebe o serviceName e o requestBody em formato JSON simples e transforma automaticamente todos os valores primitivos (strings/números) para o formato { "$": "valor" } exigido pelo Sankhya.

Nota: Diferente do execServiceMge que usa /gateway/v1/mge/service.sbr, este método envia as requisições para /gateway/v1/mgecom/service.sbr.

Exemplo: Incluir Pedido de Venda / Nota (CACSP.incluirNota)

const nota = await sankhya.execServiceMgeCom('CACSP.incluirNota', {
    nota: {
        cabecalho: {
            CODPARC: "3",
            DTNEG: "03/07/2023",
            CODTIPOPER: "1718",
            CODTIPVENDA: "34",
            CODVEND: "0",
            CODEMP: "15",
            TIPMOV: "V", // V = Venda | C=Compra | D=Devolução | etc.
            CODNAT: "10101002",
            CODCENCUS: "10600200",
            SERIE: "14"
        },
        itens: {
            INFORMARPRECO: "True",
            item: [
                {
                    CODPROD: "6",
                    QTDNEG: "1",
                    CODLOCALORIG: "0",
                    CODVOL: "SV",
                    PERCDESC: "0",
                    VLRUNIT: "81.75"
                }
            ]
        }
    }
});

A biblioteca transforma automaticamente o payload acima para o formato exigido pelo Sankhya antes do envio:

{
    "serviceName": "CACSP.incluirNota",
    "requestBody": {
        "nota": {
            "cabecalho": {
                "CODPARC": { "$": "3" },
                "DTNEG": { "$": "03/07/2023" },
                "CODTIPOPER": { "$": "1718" }
            },
            "itens": {
                "INFORMARPRECO": { "$": "True" },
                "item": [
                    {
                        "CODPROD": { "$": "6" },
                        "QTDNEG": { "$": "1" },
                        "CODVOL": { "$": "SV" }
                    }
                ]
            }
        }
    }
}

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" } }.
• Transformação Profunda de Payload: O método execServiceMgeCom transforma recursivamente todos os valores primitivos de um objeto JSON aninhado para o formato { "$": "valor" }, incluindo arrays e sub-objetos.
• Tipagem TypeScript: Suporte completo a interfaces para garantir segurança de tipo no desenvolvimento.