A TypeScript SDK for the Cuéntica API, providing easy access to accounting and tax management features for freelancers and small businesses. For detailed API documentation, visit the Cuéntica API docs.
- Features
- Installation
- Quick Start
- Configuration
- API Reference
- Error Handling
- TypeScript Support
- Contributing
- Disclaimer
- License
- Full TypeScript support with comprehensive type definitions
- Promise-based API with async/await
- Built-in rate limiting handling and error management
- Debug logging support for troubleshooting
- Support for all Cuéntica API endpoints
- Environment variable configuration support
- ESM and CommonJS support
npm install cuenticaimport { CuenticaAPI } from "cuentica";
// Initialize the client using token directly
const api = new CuenticaAPI("your-api-token");
// Or using environment variable
const apiWithEnv = new CuenticaAPI(); // Will use CUENTICA_TOKEN env variable
// Basic usage example
async function example() {
try {
// Get company info
const company = await api.getCompany();
console.log(company);
// Get invoices for a date range
const invoices = await api.getInvoices({
initial_date: "2024-01-01",
end_date: "2024-12-31",
tags: ["important"],
});
console.log(invoices);
} catch (error) {
if (error instanceof RateLimitError) {
console.log("Rate limit exceeded, retry after:", error.resetTime);
} else {
console.error("Error:", error);
}
}
}The SDK supports two methods of authentication:
- Direct token initialization:
const api = new CuenticaAPI("your-api-token");- Environment variable:
// Set CUENTICA_TOKEN environment variable
process.env.CUENTICA_TOKEN = "your-api-token";
const api = new CuenticaAPI();The SDK uses the debug package for logging. Enable different logging levels by setting the DEBUG environment variable:
# Enable all logs
DEBUG=cuentica:* npm start
# Enable only request logs
DEBUG=cuentica:request npm start
# Enable only error logs
DEBUG=cuentica:error npm start// Get company information
const company = await api.getCompany();// List customers with pagination and search
const customers = await api.getCustomers({
page: 1,
page_size: 100,
q: "search term",
});
// Get a specific customer
const customer = await api.getCustomer(123);
// Create a new customer
const newCustomer = await api.createCustomer({
name: "John",
surname_1: "Doe",
email: "[email protected]",
});
// Update a customer
await api.updateCustomer(123, {
email: "[email protected]",
});
// Delete a customer
await api.deleteCustomer(123);// List invoices with filters
const invoices = await api.getInvoices({
initial_date: "2024-01-01",
end_date: "2024-12-31",
tags: ["important"],
customer: 123,
min_total_limit: 1000,
});
// Get invoice PDF
const pdfBlob = await api.getInvoicePdf(456);// List expenses with filters
const expenses = await api.getExpenses({
initial_date: "2024-01-01",
end_date: "2024-12-31",
provider: 789,
draft: false,
});
// Create a new expense with multiple lines
const newExpense = await api.createExpense({
provider: 789,
date: "2024-01-15",
document_type: "invoice",
expense_lines: [
{
description: "Office supplies",
base: 100,
tax: 21,
},
{
description: "Software license",
base: 50,
tax: 21,
},
],
});// List documents with filters
const documents = await api.getDocuments({
initial_date: "2024-01-01",
end_date: "2024-12-31",
assigned: true,
});
// Upload a document with attachment
const newDocument = await api.createDocument({
date: "2024-01-15",
attachment: {
filename: "invoice.pdf",
data: "base64-encoded-content",
},
});// List transfers with filters
const transfers = await api.getTransfers({
initial_date: "2024-01-01",
end_date: "2024-12-31",
payment_method: "wire_transfer",
});
// Create a bank transfer
const newTransfer = await api.createTransfer({
amount: 1000,
date: "2024-01-15",
origin_account: 123,
destination_account: 456,
payment_method: "wire_transfer",
});The SDK provides detailed error handling:
try {
await api.getInvoices();
} catch (error) {
if (error instanceof RateLimitError) {
// Rate limit exceeded - error.resetTime contains the time when the limit will reset
console.log(
"Rate limit exceeded, retry after:",
error.resetTime.toISOString()
);
} else {
// Handle other API errors
console.error("API error:", error.message);
}
}The API has the following rate limits:
- 600 requests per 5 minutes
- 7200 requests per day
When these limits are exceeded, the SDK throws a RateLimitError with the reset time.
The SDK includes comprehensive TypeScript definitions for all API endpoints and data structures:
import type {
Invoice,
Customer,
ListInvoicesParams,
RateLimitError,
} from "cuentica";
// Parameters are fully typed
const params: ListInvoicesParams = {
initial_date: "2024-01-01",
tags: ["important"],
customer: 123,
};Contributions are welcome! Please feel free to submit a Pull Request. When contributing, please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This is an independent, community-driven project and is not officially associated with or endorsed by Cuéntica. While the SDK aims to provide a reliable interface to Cuéntica's API, users should refer to the official Cuéntica API documentation for the most up-to-date API specifications.
MIT License. See LICENSE for details.