@conta-studio/sdk

Official Conta Studio TypeScript SDK — profile conta-studio-public, version 0.20.0.

Public APIs for marketplace orders/stock, invoices, documents, bank transactions, and webhooks.

Install

npm install @conta-studio/sdk

Requires Node.js 18+.

Quick start

import { ContaStudioSDK } from '@conta-studio/sdk';

const sdk = new ContaStudioSDK('https://conta-studio.com', {
  auth: { token: process.env.CONTA_API_KEY },
});

const result = await sdk.orders.create({ /* MarketplaceCreateOrderRequest */ });
await sdk.invoices.list({ … });

Create an API key in Conta Studio (Settings → API keys) with the scopes you need, then pass it as auth.token.

Docs

• Quickstart
• Invoices (read)
• Stock sync
• Webshop create order

API layout

Import ContaStudioSDK and call through nested properties. Request/response bodies use generated structs; query params are camelCase primitives.

| Call pattern | Example | |--------------|---------| | sdk.<service>.<method>() | sdk.invoices.list({ direction: 'incoming' }) | | sdk.<service>.<resource>.<method>() | sdk.stock.levels.list() |

Pass the company API key (csk_*) as auth.token. Wire JSON stays snake_case; the SDK maps camelCase ↔ snake_case.

Methods in this package

• sdk.documents.get('…') → GET /api/public/v1/documents/{id}
• sdk.documents.list({ … }) → GET /api/public/v1/documents
• sdk.invoices.get('…') → GET /api/public/v1/invoices/{id}
• sdk.invoices.list({ … }) → GET /api/public/v1/invoices
• sdk.orders.create({ /* MarketplaceCreateOrderRequest */ }) → POST /api/public/v1/orders
• sdk.orders.get('…') → GET /api/public/v1/orders/{id}
• sdk.orders.list({ … }) → GET /api/public/v1/orders
• sdk.orders.update('…', { /* MarketplaceUpdateOrderRequest */ }) → PUT /api/public/v1/orders/{id}
• sdk.orders.invoiceExempt.patch('…', { /* MarketplaceInvoiceExemptPatch */ }) → PATCH /api/public/v1/orders/{id}/invoice-exempt
• sdk.orders.paymentStatus.patch('…', { /* MarketplacePaymentStatusPatch */ }) → PATCH /api/public/v1/orders/{id}/payment-status
• sdk.products.create({ /* MarketplaceProductInput */ }) → POST /api/public/v1/products
• sdk.products.delete('…') → DELETE /api/public/v1/products/{id}
• sdk.products.get('…') → GET /api/public/v1/products/{id}
• sdk.products.list({ … }) → GET /api/public/v1/products
• sdk.products.update('…', { /* MarketplaceProductUpdateRequest */ }) → PUT /api/public/v1/products/{id}
• sdk.stock.adjustments.create({ /* MarketplaceStockAdjustRequest */ }) → POST /api/public/v1/stock/adjust
• sdk.stock.levels.list() → GET /api/public/v1/stock/levels
• sdk.stock.movements.list({ … }) → GET /api/public/v1/stock/movements
• sdk.stock.warehouses.list() → GET /api/public/v1/warehouses
• sdk.transactions.get('…') → GET /api/public/v1/transactions/{id}
• sdk.transactions.list() → GET /api/public/v1/transactions
• sdk.webhooks.subscriptions.create({ /* GatewayCreateWebhookRequest */ }) → POST /api/public/v1/webhooks
• sdk.webhooks.subscriptions.delete('…') → DELETE /api/public/v1/webhooks/{id}
• sdk.webhooks.subscriptions.list() → GET /api/public/v1/webhooks

Examples

Create a webshop order

TypeScript uses camelCase; the SDK serializes to snake_case on the wire.

import { ContaStudioSDK } from '@conta-studio/sdk';

const sdk = new ContaStudioSDK('https://conta-studio.com', {
  auth: { token: process.env.CONTA_API_KEY },
});

const order = await sdk.orders.create({
  extOrderId: 'WC-1042',
  customerName: 'Ion Popescu',
  currency: 'RON',
  total: 99.98,
  lines: [{ sku: 'SKU-001', name: 'Produs demo', qty: 2, unitPrice: 49.99, vatRate: 19 }],
});

List invoices

const sdk = new ContaStudioSDK('https://conta-studio.com', { auth: { token: process.env.CONTA_API_KEY } });
const body = await sdk.invoices.list({ direction: 'incoming' });
console.log(body.data);

Stock levels

const sdk = new ContaStudioSDK('https://conta-studio.com', { auth: { token: process.env.CONTA_API_KEY } });
const levels = await sdk.stock.levels.list();

Register a webhook

const sdk = new ContaStudioSDK('https://conta-studio.com', { auth: { token: process.env.CONTA_API_KEY } });
const created = await sdk.webhooks.subscriptions.create({
  url: 'https://example.com/hooks/conta',
  events: ['order.created', 'order.updated'],
});
// Store created.signingSecret once — it is not returned again.

Full API

Every operation in this profile is also available on typed service clients.

import { MarketplaceOrdersApi } from '@conta-studio/sdk';
import { createConfiguration } from '@conta-studio/sdk/entry';

const config = createConfiguration({
  baseUrl: 'https://conta-studio.com',
  accessToken: process.env.CONTA_API_KEY,
});
const orders = new MarketplaceOrdersApi(config);
await orders.listOrders({ limit: 10 });

License-gated endpoints return 402 LICENSE_INACTIVE, 403 FEATURE_NOT_IN_PLAN, or 429 QUOTA_EXCEEDED. The SDK forwards those responses as-is.

Services included

• marketplace (marketplace)
• api-gateway (gateway)

Authentication

Supported schemes: Company API key (Authorization: or Bearer )

Changelog

See CHANGELOG.md.