http-sankhya 1.0.3 → 1.0.5

package/README.md

@@ -44,7 +44,7 @@ await sankhya.login();
 
 ### 1. loadRecords (Buscar Múltiplos Registros)
 
-Busca uma lista de registros com suporte a filtros, paginação e seleção de campos.
+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
 ```typescript
@@ -54,6 +54,12 @@ const produtos = await sankhya.loadRecords({
         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
@@ -72,6 +78,12 @@ const parceiros = await sankhya.loadRecords({
         }
     }
 });
+
+// Retorno Exemplo:
+// [
+//     { "CODPARC": "200", "NOMEPARC": "CLIENTE EXEMPLO", "CGC_CPF": "123.456.789-00", "EMAIL": "cliente@email.com" },
+//     { "CODPARC": "201", "NOMEPARC": "OUTRO CLIENTE", "CGC_CPF": "987.654.321-00", "EMAIL": "outro@email.com" }
+// ]
 ```
 
 #### Exemplo com Campos de Apresentação
@@ -85,13 +97,23 @@ const vendas = await sankhya.loadRecords({
         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).
+Busca um único registro específico, geralmente pela Chave Primária (PK). Este método utiliza o serviço `CRUDServiceProvider.loadRecord`.
 
 ```typescript
 const produto = await sankhya.loadRecord({
@@ -110,13 +132,21 @@ const produto = await sankhya.loadRecord({
 
 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. A biblioteca formata automaticamente o payload do objeto `localFields` para o padrão exigido pelo Sankhya.
+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.
@@ -136,6 +166,12 @@ const novoGrupo = await sankhya.saveRecord({
         }
     }
 });
+
+// Retorno Exemplo:
+// {
+//     "CODGRUPOPROD": "161000",
+//     "DESCRGRUPOPROD": "NOVO GRUPO 2024"
+// }
 ```
 
 #### Atualizar Registro Existente
@@ -152,17 +188,41 @@ const atualizacao = await sankhya.saveRecord({
         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.
+
+```json
+{
+    "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 Genérico (execService)
+### 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 `execService`.
+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.execService({
+const estoque = await sankhya.execServiceMge({
     serviceName: 'EstoqueSP.getEstoque',
     requestBody: {
         codProd: '1005',
@@ -175,7 +235,7 @@ const estoque = await sankhya.execService({
 Embora exista o método `.delete()`, algumas operações de exclusão no Sankhya são feitas via serviços específicos.
 
 ```typescript
-await sankhya.execService({
+await sankhya.execServiceMge({
     serviceName: 'CRUDServiceProvider.removeRecord',
     requestBody: {
         entity: {
@@ -186,6 +246,83 @@ await sankhya.execService({
         }
     }
 });
+
+// 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)
+```typescript
+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:
+
+```json
+{
+    "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
@@ -194,4 +331,5 @@ await sankhya.execService({
     - *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.

package/dist/Sankhya.d.ts

@@ -40,9 +40,51 @@ export declare class Sankhya {
     put(path: string, body?: Record<string, any>, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
     patch(path: string, body?: Record<string, any>, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
     delete(path: string, queryParam?: Record<string, any>, headers?: Record<string, any>): Promise<any>;
-    execService(options: ExecServiceOptions, outputType?: 'json' | 'xml'): Promise<any>;
+    execServiceMge(options: ExecServiceOptions, outputType?: 'json' | 'xml'): Promise<any>;
     loadRecords({ rootEntity, includePresentationFields, offsetPage, criteria, entity }: LoadRecordsOptions, outputType?: 'json' | 'xml'): Promise<any>;
     loadRecord({ rootEntity, includePresentationFields, criteria, entity, rows }: LoadRecordsOptions, outputType?: 'json' | 'xml'): Promise<any>;
     saveRecord({ rootEntity, includePresentationFields, localFields, key, entity }: SaveRecordOptions, outputType?: 'json' | 'xml'): Promise<any>;
+    /**
+     * Executa serviços diversos do Sankhya via endpoint mgecom.
+     * Recebe o serviceName e o requestBody em formato JSON simples,
+     * transformando automaticamente todos os valores primitivos para { "$": "valor" }.
+     *
+     * Endpoint: /gateway/v1/mgecom/service.sbr
+     *
+     * @example
+     * ```typescript
+     * // Exemplo: Inclusão de Pedido de Venda
+     * const nota = await sankhya.execServiceMgeCom('CACSP.incluirNota', {
+     *     nota: {
+     *         cabecalho: {
+     *             CODPARC: "3",
+     *             DTNEG: "03/07/2023",
+     *             CODTIPOPER: "1718",
+     *             CODTIPVENDA: "34",
+     *             CODVEND: "0",
+     *             CODEMP: "15",
+     *             TIPMOV: "P",
+     *             CODNAT: "10101002",
+     *             CODCENCUS: "10600200",
+     *             SERIE: "14"
+     *         },
+     *         itens: {
+     *             INFORMARPRECO: "True",
+     *             item: [
+     *                 {
+     *                     CODPROD: "6",
+     *                     QTDNEG: "1",
+     *                     CODLOCALORIG: "0",
+     *                     CODVOL: "SV",
+     *                     PERCDESC: "0",
+     *                     VLRUNIT: "81.75"
+     *                 }
+     *             ]
+     *         }
+     *     }
+     * });
+     * ```
+     */
+    execServiceMgeCom(serviceName: string, requestBody: Record<string, any>, outputType?: 'json' | 'xml'): Promise<any>;
     private isEmptyObject;
 }

package/dist/Sankhya.js

@@ -94,7 +94,7 @@ class Sankhya {
         return response.data;
     }
     // Sankhya Specific Methods
-    async execService(options, outputType = 'json') {
+    async execServiceMge(options, outputType = 'json') {
         // Standard Sankhya Service URL pattern: /mge/service.sbr?serviceName=...&outputType=json
         const { serviceName, requestBody } = options;
         // Construct the wrapper expected by Sankhya JSON API
@@ -110,7 +110,7 @@ class Sankhya {
         }, {});
     }
     async loadRecords({ rootEntity, includePresentationFields = 'N', offsetPage = 0, criteria = {}, entity = {} }, outputType = 'json') {
-        return this.execService({
+        return this.execServiceMge({
             serviceName: 'CRUDServiceProvider.loadRecords',
             requestBody: {
                 dataSet: {
@@ -125,7 +125,7 @@ class Sankhya {
         }, outputType);
     }
     async loadRecord({ rootEntity, includePresentationFields = 'N', criteria = {}, entity = {}, rows = {} }, outputType = 'json') {
-        return this.execService({
+        return this.execServiceMge({
             serviceName: 'CRUDServiceProvider.loadRecord',
             requestBody: {
                 dataSet: {
@@ -140,7 +140,7 @@ class Sankhya {
         }, outputType);
     }
     async saveRecord({ rootEntity, includePresentationFields = 'N', localFields = {}, key = {}, entity = {} }, outputType = 'json') {
-        return this.execService({
+        return this.execServiceMge({
             serviceName: 'CRUDServiceProvider.saveRecord',
             requestBody: {
                 dataSet: {
@@ -156,6 +156,59 @@ class Sankhya {
             outputType
         }, outputType);
     }
+    /**
+     * Executa serviços diversos do Sankhya via endpoint mgecom.
+     * Recebe o serviceName e o requestBody em formato JSON simples,
+     * transformando automaticamente todos os valores primitivos para { "$": "valor" }.
+     *
+     * Endpoint: /gateway/v1/mgecom/service.sbr
+     *
+     * @example
+     * ```typescript
+     * // Exemplo: Inclusão de Pedido de Venda
+     * const nota = await sankhya.execServiceMgeCom('CACSP.incluirNota', {
+     *     nota: {
+     *         cabecalho: {
+     *             CODPARC: "3",
+     *             DTNEG: "03/07/2023",
+     *             CODTIPOPER: "1718",
+     *             CODTIPVENDA: "34",
+     *             CODVEND: "0",
+     *             CODEMP: "15",
+     *             TIPMOV: "P",
+     *             CODNAT: "10101002",
+     *             CODCENCUS: "10600200",
+     *             SERIE: "14"
+     *         },
+     *         itens: {
+     *             INFORMARPRECO: "True",
+     *             item: [
+     *                 {
+     *                     CODPROD: "6",
+     *                     QTDNEG: "1",
+     *                     CODLOCALORIG: "0",
+     *                     CODVOL: "SV",
+     *                     PERCDESC: "0",
+     *                     VLRUNIT: "81.75"
+     *                 }
+     *             ]
+     *         }
+     *     }
+     * });
+     * ```
+     */
+    async execServiceMgeCom(serviceName, requestBody, outputType = 'json') {
+        const transformedBody = SankhyaHelper_1.SankhyaHelper.transformDeepFields(requestBody);
+        const payload = {
+            serviceName,
+            requestBody: transformedBody
+        };
+        const response = await this.post('/gateway/v1/mgecom/service.sbr', payload, {
+            serviceName,
+            outputType
+        }, { 'Content-Type': 'application/json' });
+        return SankhyaHelper_1.SankhyaHelper.flattenMgeComResponse(response);
+    }
     isEmptyObject(obj) {
         return obj != null &&
             obj.constructor === Object &&

package/dist/SankhyaHelper.d.ts

@@ -6,6 +6,22 @@ export declare class SankhyaHelper {
     static processResponse(response: any, options?: {
         serviceName?: string;
     }): any;
+    /**
+     * Remove recursivamente os wrappers { "$": "valor" } do retorno do Sankhya,
+     * retornando um JSON limpo e amigável.
+     * Utilizado para tratar retornos do endpoint mgecom (ex: CACSP.incluirNota).
+     */
+    static flattenMgeComResponse(obj: any): any;
+    /**
+     * Transforma recursivamente todos os valores primitivos (string/number) de um objeto
+     * para o formato Sankhya { "$": valor }, percorrendo objetos e arrays aninhados.
+     *
+     * Strings que são "irmãs" de arrays no mesmo objeto NÃO são encapsuladas,
+     * pois representam atributos XML (ex: INFORMARPRECO em "itens").
+     *
+     * Ex: { nota: { cabecalho: { CAMPO: "VALOR" } } } -> { nota: { cabecalho: { CAMPO: { "$": "VALOR" } } } }
+     */
+    static transformDeepFields(obj: any): any;
     /**
      * Transforma um objeto simples de chave/valor para o formato do Sankhya
      * Ex: { CAMPO: "VALOR" } -> { CAMPO: { "$": "VALOR" } }

package/dist/SankhyaHelper.js

@@ -22,6 +22,83 @@ class SankhyaHelper {
                 return response;
         }
     }
+    /**
+     * Remove recursivamente os wrappers { "$": "valor" } do retorno do Sankhya,
+     * retornando um JSON limpo e amigável.
+     * Utilizado para tratar retornos do endpoint mgecom (ex: CACSP.incluirNota).
+     */
+    static flattenMgeComResponse(obj) {
+        if (obj === null || obj === undefined) {
+            return obj;
+        }
+        // Se for um objeto com apenas a chave "$", extrai o valor
+        if (typeof obj === 'object' && !Array.isArray(obj) && '$' in obj && Object.keys(obj).length === 1) {
+            return obj.$;
+        }
+        // Se for array, aplica recursivamente em cada elemento
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.flattenMgeComResponse(item));
+        }
+        // Se for objeto, aplica recursivamente em cada propriedade
+        if (typeof obj === 'object') {
+            const result = {};
+            for (const key of Object.keys(obj)) {
+                result[key] = this.flattenMgeComResponse(obj[key]);
+            }
+            return result;
+        }
+        return obj;
+    }
+    /**
+     * Transforma recursivamente todos os valores primitivos (string/number) de um objeto
+     * para o formato Sankhya { "$": valor }, percorrendo objetos e arrays aninhados.
+     *
+     * Strings que são "irmãs" de arrays no mesmo objeto NÃO são encapsuladas,
+     * pois representam atributos XML (ex: INFORMARPRECO em "itens").
+     *
+     * Ex: { nota: { cabecalho: { CAMPO: "VALOR" } } } -> { nota: { cabecalho: { CAMPO: { "$": "VALOR" } } } }
+     */
+    static transformDeepFields(obj) {
+        // Campos com valor null ou undefined são tratados como placeholders (ex: PKs)
+        // e enviados como objeto vazio {} no formato Sankhya
+        if (obj === null || obj === undefined) {
+            return {};
+        }
+        // Se for string ou number, transforma para { "$": valor }
+        // (este caso é chamado recursivamente; a decisão de NÃO transformar
+        //  é feita no nível do objeto pai, abaixo)
+        if (typeof obj === 'string' || typeof obj === 'number') {
+            return { $: String(obj) };
+        }
+        // Se for array, aplica recursivamente em cada elemento
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.transformDeepFields(item));
+        }
+        // Se já estiver no formato { "$": ... }, mantém como está
+        if (typeof obj === 'object' && '$' in obj && Object.keys(obj).length === 1) {
+            return obj;
+        }
+        // Se for objeto, aplica recursivamente em cada propriedade
+        if (typeof obj === 'object') {
+            const keys = Object.keys(obj);
+            // Verifica se o objeto possui algum filho que é array.
+            // Se sim, strings neste nível são atributos XML e NÃO devem ser encapsuladas.
+            const hasArrayChild = keys.some(k => Array.isArray(obj[k]));
+            const transformed = {};
+            for (const key of keys) {
+                const value = obj[key];
+                if (hasArrayChild && (typeof value === 'string' || typeof value === 'number')) {
+                    // Atributo XML: mantém como string pura
+                    transformed[key] = value;
+                }
+                else {
+                    transformed[key] = this.transformDeepFields(value);
+                }
+            }
+            return transformed;
+        }
+        return obj;
+    }
     /**
      * Transforma um objeto simples de chave/valor para o formato do Sankhya
      * Ex: { CAMPO: "VALOR" } -> { CAMPO: { "$": "VALOR" } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-sankhya",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Biblioteca TypeScript para integração com ERP Sankhya",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",