fatura

The SMS verification process follows a two-step pattern involving an Operation ID (OID):

1. Initiation: Call sendSignSMSCode(token, phone). This triggers the SMS and returns an OID.
2. Verification: Call verifySignSMSCode(token, smsCode, operationId), passing the OID received in the first step to validate the user's input.

☢️ WARNING: Signing a draft invoice creates a legally binding financial transaction. Use with caution.

To sign an invoice, you must first use findInvoice(token, draftInvoice) to retrieve the necessary signing information (such as the document number) from the draft list. The object returned by findInvoice should be passed to signDraftInvoice.

// 1. Find the invoice to get signing details
const invoiceToSign = await client.findInvoice(token, draftInvoice);

// 2. Sign the invoice
await client.signDraftInvoice(token, invoiceToSign);

When initializing a client with createFaturaClient, you must explicitly specify the environment to prevent mixing test data with live production data. The library supports two environments:

• PROD: Connects to https://earsivportal.efatura.gov.tr (Live environment)
• TEST: Connects to https://earsivportaltest.efatura.gov.tr (Testing environment)

import { createFaturaClient } from "fatura";

const prodClient = createFaturaClient("PROD");
const testClient = createFaturaClient("TEST");

To start the local development environment for the website, run the development command using your preferred package manager. Once running, the application will be accessible at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Install the fatura package using npm. This package requires Node.js 18 or higher.

npm install fatura

After installation, import createFaturaClient from fatura to initialize the client. You must provide an environment string (e.g., "TEST" or "PROD") to the constructor.

Warning: Do not initiate financial transactions in a PROD environment without proper validation; use the TEST environment for initial verification.

import { createFaturaClient } from "fatura";

const client = createFaturaClient("TEST");

To add the fatura package to your Node.js or TypeScript project, use npm to install it.

npm install fatura

Messages returned from the GİB API can arrive in two different formats depending on the endpoint:

1. Object format: { type: string; text: string } (used by most endpoints).
2. String format: A plain string like "Genel Sistem Hatası: ..." (used by some dispatch errors).

When processing messages in an ApiResponse, ensure your logic can handle both types.

export type GibApiMessage = string | { type: string; text: string };

Use the getUserData method to fetch portal profile data. The method accepts a token and returns a Promise that resolves to a UserData object containing the user's profile information.

getUserData(token: string): Promise<UserData>

Use createDraftInvoice to initiate the invoice process by creating a draft. It requires an authentication token and an invoiceDetails object. It returns a Promise that resolves to a DraftInvoice object.

const draft = await client.createDraftInvoice(token, invoiceDetails);

Use getInvoiceHTML to retrieve the HTML output of either a signed or a draft invoice. The method returns a Promise that resolves to a string containing the HTML content.

getInvoiceHTML(token: string, uuid: string, options: { signed: boolean }): Promise<string>