Package Exports

parasut-api-client

Readme

Parasut API Client

A comprehensive Node.js/TypeScript client for Paraşüt (API v4) - A cloud-based accounting and invoicing platform for small & medium sized businesses.

🚀 Features

✅ Full API Coverage - All endpoints from Parasut API v4
✅ Organized by business domains (invoices, contacts, products, etc.)
✅ Automatic token management and refresh
✅ Built with Axios for reliability

📦 Installation

npm install parasut-api-client

🔧 Quick Start

Basic Setup

import { ParasutClient } from 'parasut-api-client';

const client = new ParasutClient({
  xid: 'DUMMY_LOCAL_ID',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  username: 'YOUR_EMAIL',
  password: 'YOUR_PASSWORD',
  companyId: 'YOUR_COMPANY_ID', // If not provided, the first company in the companies list will be used.
  onTokenReceived: function(token, expiresAt, xid){}, // optional
  baseUrl: 'https://api.parasut.com' // Optional
});

await client.initialize();

Working with multiple clients

The xid parameter is used to identify a client. If you have multiple clusters running and you don't want to send multiple auth requests for each of them; or you want to may be cache the token in REDIS for later use/preserve across restarts etc, you can define an xid for your ease. When the authorization request is made, the onTokenReceived function will be triggered and you'd be able to use the token as you need.

const clientOne =  new ParasutClient({
  ...
  onTokenReceived: function(token, expiresAt, xid){
    // Cache with REDIS, for example.
    someRedisConnector.HSET(`parasut-cache-${xid}`, {token, expiresAt});
  }
});

const clientTwo =  new ParasutClient({
  ...,
  onTokenReceived: function(token, expiresAt, xid){
    // Trigger an event emitter perhaps?
    // Or update the cache for clientOne...
    clientOne.updateToken(token, expiresAt, xid);
  }
});

Working with Contacts

// List all contacts
const contacts = await client.contacts.list();

// Create a new contact
const newContact = await client.contacts.create({
  data: {
    type: 'contacts',
    attributes: {
      name: 'Acme Corp',
      email: 'info@acme.com',
      contact_type: 'company',
      supplier: true,
      customer: false
    }
  }
});

// Get a specific contact
const contact = await client.contacts.show('123');

// Update contact
const updatedContact = await client.contacts.update('123', {
  data: {
    type: 'contacts',
    attributes: {
      name: 'Updated Name'
    }
  }
});

Working with Sales Invoices

// List sales invoices
const invoices = await client.salesInvoice.list();

// Create a sales invoice
const invoice = await client.salesInvoice.create({
  data: {
    type: 'sales_invoices',
    attributes: {
      item_type: 'invoice',
      issue_date: '2025-01-15',
      currency: 'TRL',
      is_abroad: false,
      cash_sale: false,
      shipment_included: false
    },
    relationships: {
      contact: {
        data: { id: '123', type: 'contacts' }
      },
      details: {
        data: [{
          type: 'sales_invoice_details',
          attributes: {
            quantity: 1,
            unit_price: 100.00,
            vat_rate: 18,
            description: 'Service Fee'
          }
        }]
      }
    }
  }
});

// Get invoice PDF
const pdfUrl = await client.salesInvoice.getPdf('456');

Working with Products

// List products
const products = await client.products.list();

// Create a product
const product = await client.products.create({
  data: {
    type: 'products',
    attributes: {
      name: 'Premium Service',
      code: 'PREM001',
      vat_rate: 18,
      list_price: 150.00,
      currency: 'TRL',
      inventory_tracking: false
    }
  }
});

🏗️ API Modules

The client is organized into logical modules matching the Parasut API structure:

Module	Description	Key Operations
`client.companies`	Company management	list, show, update settings
`client.contacts`	Customers & vendors	CRUD operations, contact people
`client.products`	Product catalog	CRUD operations, inventory tracking
`client.salesInvoice`	Sales invoices	CRUD, PDF generation, payments
`client.salesOffer`	Sales offers	CRUD, convert to invoice
`client.purchaseBills`	Purchase bills	CRUD, payment management
`client.accounts`	Chart of accounts	CRUD, transactions
`client.transactions`	Financial transactions	Debit/credit operations
`client.stockMovements`	Inventory movements	Track stock changes
`client.warehouses`	Warehouse management	CRUD operations
`client.shipmentDocuments`	Shipment documents	İrsaliye management
`client.eInvoice`	E-Invoice operations	Turkish e-invoice system
`client.eArchive`	E-Archive operations	Turkish e-archive system
`client.bankFees`	Bank fees	Fee management
`client.salaries`	Salary management	Employee salary tracking
`client.employees`	Employee management	CRUD operations
`client.taxes`	Tax management	Tax calculations
`client.tags`	Tagging system	Organize resources
`client.webhooks`	Webhook management	Event notifications

🔐 Authentication

The client uses OAuth2 Password Grant flow as specified in the Parasut API documentation:

Automatic token management - Tokens are fetched and cached automatically
Token refresh - Expired tokens are refreshed transparently
Secure requests - All requests include proper Authorization: Bearer <token> headers

📋 TypeScript Support

All API resources are fully typed with TypeScript interfaces:

import { SalesInvoice, Contact, Product } from 'parasut-api-client';

// Full type safety and IntelliSense
const invoice: SalesInvoice = await client.salesInvoice.show('123');
const contact: Contact = await client.contacts.show(invoice.relationships?.contact?.data.id);

🚀 Advanced Usage

Pagination

// Get paginated results
const result = await client.contacts.list({
  page: 1,
  per_page: 50
});

console.log('Total pages:', result.meta?.total_pages);
console.log('Current page:', result.meta?.current_page);

Filtering and Sorting

// Filter and sort results
const invoices = await client.salesInvoice.list({
  filter: {
    issue_date: '2025-01-01..2025-01-31',
    contact_id: '123'
  },
  sort: '-issue_date',
  include: 'contact,details'
});

// Include related resources in response
const invoice = await client.salesInvoice.show('123', {
  include: 'contact,details,payments'
});

🛠️ Development

Building the Project

npm run build

Running Tests

npm test
npm run test:watch
npm run test:coverage

📚 Resources

📄 License

MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

For issues and questions:

📧 Create an issue on GitHub
📖 Check the Parasut API documentation
💬 Review existing issues for solutions