> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x-mart.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create fiscal_group



## OpenAPI

````yaml api-reference/openapi.json POST /admin/fiscal-groups
openapi: 3.0.1
info:
  title: Api V3 documentación
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.artisn.desarrollo-redbrand.com/api
  - url: https://api.kfc-group.desarrollo-redbrand.com
  - url: https://{apiId}.execute-api.{region}.amazonaws.com/{stage}
    description: API Gateway (PRIVATE; invocación típica vía VPC endpoint).
    variables:
      apiId:
        default: '{api-id}'
        description: ID del API REST desplegado.
      region:
        default: us-east-1
      stage:
        default: dev
        description: Mismo valor que parámetro EnvironmentName del stack.
security:
  - bearerAuth: []
paths:
  /admin/fiscal-groups:
    post:
      tags:
        - Admin
      summary: Crear fiscal_group
      operationId: createFiscalGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FiscalGroupCreate'
            example:
              externalId: 3s-group-8891
              name: KFC ABC MARUM (SP)
              uf: SP
              taxRegime: Simples
              stores:
                - store_id: store_101
                  store_name: KFC Paulista
                - store_id: store_102
                  store_name: KFC Campinas
              taxMatrix:
                '21069090':
                  NCM: '21069090'
                  CEST: 17.047.00
                  CST_ICMS: '00'
                  ICMS_rate: 18
                  CST_PIS: '01'
                  PIS_rate: 1.65
                  CST_COFINS: '01'
                  COFINS_rate: 7.6
                  CFOP: '5102'
                '22021000':
                  NCM: '22021000'
                  CEST: 03.007.00
                  CST_ICMS: '00'
                  ICMS_rate: 18
                  CST_PIS: '01'
                  PIS_rate: 1.65
                  CST_COFINS: '01'
                  COFINS_rate: 7.6
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiscalGroup'
        '400':
          description: Body inválido o campos requeridos ausentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '409':
          description: Violación de unicidad (Postgres 23505)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
        '500':
          description: Error interno
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorMessage'
components:
  schemas:
    FiscalGroupCreate:
      type: object
      required:
        - externalId
        - name
        - uf
        - taxRegime
        - stores
        - taxMatrix
      properties:
        externalId:
          type: string
        name:
          type: string
        uf:
          type: string
        taxRegime:
          type: string
        stores:
          $ref: '#/components/schemas/StoresJson'
        taxMatrix:
          $ref: '#/components/schemas/TaxMatrixJson'
    FiscalGroup:
      type: object
      additionalProperties: true
      description: Propiedades en camelCase según respuesta Drizzle/JSON.
      properties:
        id:
          type: string
          format: uuid
        externalId:
          type: string
        name:
          type: string
        uf:
          type: string
        taxRegime:
          type: string
        stores:
          $ref: '#/components/schemas/StoresJson'
        taxMatrix:
          $ref: '#/components/schemas/TaxMatrixJson'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ApiErrorMessage:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        error:
          type: string
    StoresJson:
      type: array
      description: >
        Arreglo JSON persistido en `fiscal_groups.stores`. Debe incluir al menos
        un objeto con `store_id`

        para que `findFiscalGroupByStoreId` pueda resolver la tienda desde
        `payload.store.id`.
      items:
        $ref: '#/components/schemas/FiscalGroupStoreEntry'
    TaxMatrixJson:
      type: object
      description: >
        Mapa código NCM → reglas (`tax_matrix` en BD). Claves típicamente
        numéricas de 8 dígitos (string).

        El motor usa `taxMatrix[ncm]` tras resolver el NCM del catálogo de
        producto.
      additionalProperties:
        $ref: '#/components/schemas/TaxMatrixEntry'
    FiscalGroupStoreEntry:
      type: object
      description: Elemento del arreglo JSON `stores` (asociación tienda ↔ grupo fiscal).
      required:
        - store_id
      properties:
        store_id:
          type: string
          description: >-
            Identificador de tienda; el motor fiscal busca coincidencia por este
            valor (string).
        store_name:
          type: string
          description: Nombre legible (opcional, no usado en el cálculo de impuestos).
    TaxMatrixEntry:
      type: object
      description: >-
        Reglas por NCM; misma forma que `src/types/fiscal.ts`
        (`TaxMatrixEntry`).
      properties:
        NCM:
          type: string
          description: Código NCM (suele coincidir con la clave del mapa).
        CEST:
          type: string
          nullable: true
        CST_ICMS:
          type: string
        ICMS_rate:
          type: number
        ICMS_reduction:
          type: number
          nullable: true
        CST_PIS:
          type: string
        PIS_rate:
          type: number
        CST_COFINS:
          type: string
        COFINS_rate:
          type: number
        CFOP:
          type: string
        FCP_rate:
          type: number
          nullable: true
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````