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

# Create merchant



## OpenAPI

````yaml /api-reference/openapi.yaml post /merchants
openapi: 3.0.0
info:
  title: OpenFiskal fiscalization API
  description: >-
    OpenFiskal exposes a server-to-server fiscalization API for merchant
    onboarding,

    register setup, and operation handling.


    The `v1` contract uses server-issued resource versions and conditional

    writes through `If-Match` for safe concurrent mutation handling.
  version: 1.1.0
  contact: {}
  license:
    name: Proprietary
servers:
  - url: https://api.openfiskal.com/v1
    description: Production
  - url: https://sandbox.api.openfiskal.com/v1
    description: Sandbox
security: []
tags:
  - name: Merchants
    description: Create and manage merchant merchants.
  - name: Locations
    description: Create and manage merchant locations.
  - name: Registers
    description: Create and manage registers or terminals.
  - name: Operations
    description: Start, update, complete, cancel, list, and read operations.
paths:
  /merchants:
    post:
      tags:
        - Merchants
      summary: Create merchant
      operationId: MerchantsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMerchantDto'
      responses:
        '201':
          description: Merchant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
              examples:
                default:
                  summary: invalid_request
                  value:
                    code: invalid_request
                    message: The request body is malformed.
                    retryable: false
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
              examples:
                default:
                  summary: unauthorized
                  value:
                    code: unauthorized
                    message: Authentication failed.
                    retryable: false
        '403':
          description: >-
            Authenticated caller is not allowed to access the requested tenant,
            country, or merchant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
              examples:
                default:
                  summary: forbidden
                  value:
                    code: forbidden
                    message: The authenticated caller cannot access this resource.
                    retryable: false
        '422':
          description: Domain validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
              examples:
                default:
                  summary: regime_validation_failed
                  value:
                    code: regime_validation_failed
                    message: The payload violates regime-specific validation rules.
                    retryable: false
      security:
        - BearerAuth: []
components:
  schemas:
    CreateMerchantDto:
      type: object
      properties:
        legal_name:
          type: string
          example: Test GmbH
        country_code:
          type: string
          example: DEU
          minLength: 3
          maxLength: 3
          description: ISO 3166-1 alpha-3 country code for the legal entity (uppercase)
        address:
          $ref: '#/components/schemas/AddressDto'
        fiscal_identities:
          type: array
          description: Country-specific fiscal identities
          items:
            oneOf:
              - title: FiscalIdentityDEU
                allOf:
                  - $ref: '#/components/schemas/FiscalIdentityDeuDto'
              - title: FiscalIdentityAUT
                allOf:
                  - $ref: '#/components/schemas/FiscalIdentityAutDto'
              - title: FiscalIdentityITA
                allOf:
                  - $ref: '#/components/schemas/FiscalIdentityItaDto'
            discriminator:
              propertyName: country_code
              mapping:
                DEU:
                  $ref: '#/components/schemas/FiscalIdentityDeuDto'
                AUT:
                  $ref: '#/components/schemas/FiscalIdentityAutDto'
                ITA:
                  $ref: '#/components/schemas/FiscalIdentityItaDto'
      required:
        - legal_name
        - country_code
        - address
    Merchant:
      type: object
      properties:
        id:
          type: string
        legal_name:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-3 country code for the legal entity.
          minLength: 3
          maxLength: 3
          example: DEU
        status:
          type: string
          enum:
            - active
            - inactive
        address:
          $ref: '#/components/schemas/AddressResponse'
        fiscal_identities:
          type: array
          description: Country-specific fiscal identities.
          items:
            oneOf:
              - title: FiscalIdentityDEU
                allOf:
                  - $ref: '#/components/schemas/FiscalIdentityDeuDto'
              - title: FiscalIdentityAUT
                allOf:
                  - $ref: '#/components/schemas/FiscalIdentityAutDto'
              - title: FiscalIdentityITA
                allOf:
                  - $ref: '#/components/schemas/FiscalIdentityItaDto'
            discriminator:
              propertyName: country_code
              mapping:
                DEU:
                  $ref: '#/components/schemas/FiscalIdentityDeuDto'
                AUT:
                  $ref: '#/components/schemas/FiscalIdentityAutDto'
                ITA:
                  $ref: '#/components/schemas/FiscalIdentityItaDto'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - legal_name
        - country_code
        - status
        - address
        - fiscal_identities
        - created_at
        - updated_at
    ErrorDto:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          example: invalid_request
        message:
          type: string
          description: Human-readable explanation of the error.
        retryable:
          type: boolean
          description: Whether retrying the request is safe.
        details:
          type: object
          description: Additional structured context for the error.
          additionalProperties: true
      required:
        - code
        - message
        - retryable
    AddressDto:
      type: object
      properties:
        line1:
          type: string
          example: Musterstr. 1
        line2:
          type: string
          example: Apt 4
          nullable: true
        city:
          type: string
          example: Berlin
        postal_code:
          type: string
          example: '10115'
        country_code:
          type: string
          example: DEU
          minLength: 3
          maxLength: 3
          description: ISO 3166-1 alpha-3 (uppercase)
      required:
        - line1
        - city
        - postal_code
        - country_code
    FiscalIdentityDeuDto:
      type: object
      properties:
        country_code:
          type: string
          enum:
            - DEU
          example: DEU
        tax_number:
          type: string
          example: 21/815/08150
          description: Steuernummer
        vat_id:
          type: string
          example: DE123456789
          description: USt-IdNr
      required:
        - country_code
        - tax_number
        - vat_id
    FiscalIdentityAutDto:
      type: object
      properties:
        country_code:
          type: string
          enum:
            - AUT
          example: AUT
        vat_id:
          type: string
          example: ATU12345678
        tax_number:
          type: string
        legal_entity_id_type:
          type: string
          enum:
            - VAT_ID
            - TAX_ID
            - GLN
          example: VAT_ID
        gln:
          type: string
          description: >-
            13-digit Global Location Number, required when legal_entity_id_type
            is GLN
      required:
        - country_code
        - legal_entity_id_type
    FiscalIdentityItaDto:
      type: object
      properties:
        country_code:
          type: string
          enum:
            - ITA
          example: ITA
        tax_number:
          type: string
          example: '12345678901'
          description: >-
            Tax number (Codice Fiscale). 11 numeric digits or 16 alphanumeric
            characters. Example: 12345678901 or RSSMRA85T10A562S. For companies,
            this may be identical to the VAT number.
        vat_number:
          type: string
          example: IT12345678901
          description: VAT number (Partita IVA)
        legal_entity_type:
          type: string
          enum:
            - COMPANY
            - INDIVIDUAL
          example: COMPANY
          description: >-
            Select whether your organization is a company (Societa) or an
            individual (Persona fisica).
        fisconline_password:
          type: string
          description: Fisconline Password
        fisconline_pin:
          type: string
          description: Fisconline PIN
        fisconline_user:
          type: string
          description: >-
            Fisconline User - The Codice Fiscale of the person authorized to
            access the Agenzia delle Entrate portal on behalf of the business.
      required:
        - country_code
        - tax_number
        - vat_number
        - legal_entity_type
        - fisconline_password
        - fisconline_pin
        - fisconline_user
    AddressResponse:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
          nullable: true
        city:
          type: string
        postal_code:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-3 country code.
          minLength: 3
          maxLength: 3
          example: DEU
      required:
        - line1
        - city
        - postal_code
        - country_code
  securitySchemes:
    BearerAuth:
      scheme: bearer
      bearerFormat: API key
      type: http

````