http-sankhya 1.0.2 → 1.0.4

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,31 +166,63 @@ const novoGrupo = await sankhya.saveRecord({
         }
     }
 });
+
+// Retorno Exemplo:
+// {
+//     "CODGRUPOPROD": "161000",
+//     "DESCRGRUPOPROD": "NOVO GRUPO 2024"
+// }
 ```
 
-#### Atualizar Registro Existente (Upsert)
-Para atualizar, inclua a Chave Primária nos `localFields`. O comportamento exato depende da entidade Sankhya, mas geralmente atua como "Upsert" (Atualiza se existe, cria se não).
+#### 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.
 
 ```typescript
 const atualizacao = await sankhya.saveRecord({
     rootEntity: 'GrupoProduto',
     localFields: {
-        CODGRUPOPROD: "20310006", // PK existente
-        DESCRGRUPOPROD: "NOME ATUALIZADO", // Campo a alterar
+        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.
+
+```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',
@@ -173,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: {
@@ -184,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
@@ -192,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

@@ -16,6 +16,7 @@ export interface SaveRecordOptions {
     rootEntity: string;
     includePresentationFields?: 'S' | 'N';
     localFields?: Record<string, any>;
+    key?: Record<string, any>;
     entity?: Record<string, any>;
 }
 export interface ExecServiceOptions {
@@ -39,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, entity }: SaveRecordOptions, 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: {
@@ -139,15 +139,16 @@ class Sankhya {
             outputType
         }, outputType);
     }
-    async saveRecord({ rootEntity, includePresentationFields = 'N', localFields = {}, entity = {} }, outputType = 'json') {
-        return this.execService({
+    async saveRecord({ rootEntity, includePresentationFields = 'N', localFields = {}, key = {}, entity = {} }, outputType = 'json') {
+        return this.execServiceMge({
             serviceName: 'CRUDServiceProvider.saveRecord',
             requestBody: {
                 dataSet: {
                     rootEntity,
                     includePresentationFields,
                     dataRow: {
-                        localFields: SankhyaHelper_1.SankhyaHelper.transformLocalFields(localFields)
+                        localFields: SankhyaHelper_1.SankhyaHelper.transformLocalFields(localFields),
+                        key: SankhyaHelper_1.SankhyaHelper.transformLocalFields(key)
                     },
                     entity
                 }
@@ -155,6 +156,58 @@ 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
+        };
+        return this.post('/gateway/v1/mgecom/service.sbr', payload, {
+            serviceName,
+            outputType
+        }, {});
+    }
     isEmptyObject(obj) {
         return obj != null &&
             obj.constructor === Object &&

package/dist/SankhyaHelper.d.ts

@@ -6,6 +6,12 @@ export declare class SankhyaHelper {
     static processResponse(response: any, options?: {
         serviceName?: string;
     }): any;
+    /**
+     * Transforma recursivamente todos os valores primitivos (string/number) de um objeto
+     * para o formato Sankhya { "$": valor }, percorrendo objetos e arrays aninhados.
+     * 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,37 @@ class SankhyaHelper {
                 return response;
         }
     }
+    /**
+     * Transforma recursivamente todos os valores primitivos (string/number) de um objeto
+     * para o formato Sankhya { "$": valor }, percorrendo objetos e arrays aninhados.
+     * Ex: { nota: { cabecalho: { CAMPO: "VALOR" } } } -> { nota: { cabecalho: { CAMPO: { "$": "VALOR" } } } }
+     */
+    static transformDeepFields(obj) {
+        if (obj === null || obj === undefined) {
+            return obj;
+        }
+        // Se for string ou number, transforma para { "$": valor }
+        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 transformed = {};
+            for (const key of Object.keys(obj)) {
+                transformed[key] = this.transformDeepFields(obj[key]);
+            }
+            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.2",
+  "version": "1.0.4",
   "description": "Biblioteca TypeScript para integração com ERP Sankhya",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",