SAP E-Beyanname Integration Architecture

A robust SAP E-Beyanname architecture is more than a REST call. Every step from the source accounting record to GİB’s status response and accrual document should remain traceable. The design must accommodate scope changes, route errors to the right owner, and avoid uncontrolled duplication during reprocessing.

Recommended end-to-end flow

A practical processing chain is:

SAP sources → data selection → declaration mapping → internal checks → internal approval → GİB channel → status and document archive

Recording a transaction identifier, timestamp, and responsible user at each boundary makes it easier to explain which SAP document produced a declaration line.

1. SAP source layer

Depending on the declaration, the source can include SAP FI accounting documents, general-ledger balances, tax codes, customer and supplier master data, and relevant payroll or tax sources. Source selection should answer:

Which company codes and ledgers are in scope?
How are document date, posting date, and tax period separated?
How are cancellations, reversals, and corrections handled?
What happens to an existing declaration when its source record changes?

Do not collapse source extraction and declaration mapping into one irreversible transformation. Keep the source snapshot, mapping result, and submission payload as separate audit layers.

2. Mapping and version management

GİB fields and validation rules can change by declaration and period. A mapping record should therefore contain more than a source and target field:

Declaration and tax code
Effective start and end dates
GİB declaration or schema version
Transformation and rounding rule
Required-field condition
Person approving the rule change

Test a new mapping version with historical, boundary, and error scenarios before production use.

3. Validation layer

Separating controls into three groups simplifies operations:

Technical checks: required fields, types, lengths, and formats.
Reconciliation checks: tax base and rate, account balances, carried-forward VAT, and totals.
Business-rule checks: period, taxpayer liability, contract, duplicates, and special approval.

Do not turn GİB’s 400 format/validation, 401 authentication, 403 authorization, and 422 business-rule responses into the same user message. Use the GİB error response and SAP correction guide for routing patterns.

4. Internal approval

Separate GİB filing authority from internal preparation and review. A minimum role model can include:

Preparer: selects sources and runs initial checks.
Reviewer: investigates reconciliations and exceptions.
Approver: completes internal approval.
Submitter: initiates the authorized GİB transaction.

If one person must carry multiple roles, document the exception and review it periodically.

5. GİB integration gateway

GİB’s integration guide requires approved real IP addresses, environment-specific service addresses, and a separate API key for each environment. Do not place the API key in source code, browser code, or logs. Link at least these attributes to the secure operational record:

Environment and target service
Declaration and period
GİB declaration identifier
Request time and result status
GİB message code and trace identifier when available

Mask API keys, personal data, and unnecessary declaration content in logs.

Which channel the gateway connects to can vary by declaration and period; see GİB e-Beyan REST API vs. BDP on the roles of the two channels.

6. Status and document archive

Represent draft, erroneous, pending approval, approved, or cancelled as a state model with permitted transitions—not as unrelated text values. GİB’s user documentation makes correction and document retrieval dependent on the declaration status.

Archive approved declarations, accruals, and error files with the declaration identifier, period, company code, document type, and integrity information. Confirm retention periods and access rights against the organization’s tax, information-security, and records-management policies.

Complete the SAP E-Beyanname implementation checklist before development. Review the interactive workflow in the interactive simulation of the Fenikstech SAP E-Beyanname solution.

Official sources

This article was reviewed against the official sources on 23 July 2026.