API Documentation

RESTful API for integrating GibirNegari with your existing systems. Available for Enterprise customers.

🏢 Enterprise Feature

The GibirNegari API is available exclusively for Enterprise plan customers. It allows you to integrate GibirNegari with your existing ERP, CRM, e-commerce, or custom systems.

Interested in API access? Contact our sales team to discuss your integration needs.

Quick Start

1. Get Your API Key

Once your Enterprise account is activated, navigate to:

Dashboard → Settings → API Keys → Generate New Key

⚠️ Security: Store your API key securely. Never commit it to version control or expose it in client-side code.

2. Make Your First Request

All API requests require authentication via the Authorization header:

curl -X GET https://api.gibir-negari.com/v1/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentication

API Key Authentication

Include your API key in the Authorization header with the Bearer scheme:

Authorization: Bearer gn_live_1234567890abcdef

API Key Types

Live Keys (gn_live_...)

Use in production. Access real data and perform actual operations.

Test Keys (gn_test_...)

Use in development. Access sandbox data without affecting production.

Base URL & Versioning

API Endpoints

•

Production:

https://api.gibir-negari.com/v1

•

Sandbox:

https://api-sandbox.gibir-negari.com/v1

The API is versioned via the URL path (/v1). We maintain backward compatibility within major versions.

Core Endpoints

Transactions

GET/transactions

List all transactions with optional filters.

GET /v1/transactions?type=sales&startDate=2024-01-01&endDate=2024-01-31&limit=50

Response:
{
  "data": [
    {
      "id": "txn_abc123",
      "type": "sales",
      "date": "2024-01-15",
      "amount": 11500.00,
      "vat": 1500.00,
      "total": 13000.00,
      "customer": "ABC Trading PLC",
      "status": "posted"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150
  }
}

POST/transactions

Create a new transaction (sales or purchase).

POST /v1/transactions

Request Body:
{
  "type": "sales",
  "date": "2024-01-15",
  "customer": "ABC Trading PLC",
  "items": [
    {
      "description": "Product A",
      "quantity": 10,
      "unitPrice": 1000.00,
      "vat": 1500.00
    }
  ],
  "paymentMethod": "cash"
}

Response:
{
  "id": "txn_abc123",
  "status": "created",
  "message": "Transaction created successfully"
}

GET/transactions/:id

Retrieve a specific transaction by ID.

PUT/transactions/:id

Update an existing transaction (only if not posted to GL).

DELETE/transactions/:id

Delete a transaction (only if not posted to GL).

Reports

GET/reports/balance-sheet

Generate Balance Sheet report.

GET /v1/reports/balance-sheet?date=2024-01-31

Response:
{
  "date": "2024-01-31",
  "assets": {
    "current": 500000.00,
    "fixed": 1000000.00,
    "total": 1500000.00
  },
  "liabilities": {
    "current": 200000.00,
    "longTerm": 300000.00,
    "total": 500000.00
  },
  "equity": {
    "capital": 800000.00,
    "retainedEarnings": 200000.00,
    "total": 1000000.00
  }
}

GET/reports/profit-loss

Generate Profit & Loss statement.

GET/reports/vat-return

Generate VAT return report for a specific period.

Customers & Vendors

GET/customers

List all customers.

POST/customers

Create a new customer.

GET/vendors

List all vendors/suppliers.

POST/vendors

Create a new vendor.

Rate Limits

To ensure fair usage and system stability, API requests are rate-limited based on your plan:

Enterprise Plan

1,000 requests per hour

Custom Plans

Contact sales for higher limits

Rate Limit Headers: Each response includes X-RateLimit-Limit,X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Error Handling

HTTP Status Codes

200Success - Request completed successfully

201Created - Resource created successfully

400Bad Request - Invalid request parameters

401Unauthorized - Invalid or missing API key

403Forbidden - API key doesn't have required permissions

404Not Found - Resource doesn't exist

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: customer",
    "field": "customer",
    "documentation": "https://docs.gibir-negari.com/api#transactions"
  }
}

Webhooks

Event Notifications

Webhooks allow you to receive real-time notifications when events occur in your GibirNegari account.

Configure webhook endpoints in: Dashboard → Settings → Webhooks

•

transaction.created

Fired when a new transaction is created

•

transaction.posted

Fired when a transaction is posted to General Ledger

•

tax.filed

Fired when a tax return is filed with eTax portal

Webhook Payload Example

POST https://your-server.com/webhooks/gibir-negari

Headers:
X-GibirNegari-Signature: sha256=abc123...
Content-Type: application/json

Body:
{
  "event": "transaction.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "txn_abc123",
    "type": "sales",
    "amount": 11500.00,
    "customer": "ABC Trading PLC"
  }
}

SDKs & Libraries

Official SDKs make integration easier by handling authentication, error handling, and request formatting.

Node.js / TypeScript

npm install @gibir-negari/node

Python

pip install gibir-negari

PHP

composer require gibir-negari/php

Java

Contact api-support@gibir-negari.com for Java SDK access

Need Help with API Integration?

Our Enterprise support team is here to help you integrate GibirNegari with your systems.

📧 API Support

api-support@gibir-negari.com

Response within 4 hours for Enterprise customers

📚 API Reference

api-docs.gibir-negari.com

Complete API reference with interactive examples