# API libraries

You can call the Ha Tang REST API from any language with a plain HTTP client. This page lists the official libraries that make it easier, and shows how to generate a typed client from the OpenAPI spec for languages without an official SDK.

## Node.js: `@hatang/sdk`

The official server SDK covers Email, Support, Products, CRM, Payments and e-invoices, with TypeScript types for every request and response.

```bash
npm install @hatang/sdk
```

```ts
import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY, {
  baseUrl: "https://api.hatang.dev",
  // environment: "development", // Payments only; sent as Hatang-Environment
});

const { data, error } = await hatang.emails.send({
  from: "Shop <hello@shop.vn>",
  to: "customer@example.com",
  subject: "Welcome",
  html: "<p>Welcome to the shop!</p>",
});
```

What to know:

- **Results, not exceptions.** Every method resolves to `{ data, error }` and never throws for API errors. `error` has the usual `statusCode`, `name` and `message` ([Errors](https://hatang.dev/docs/guides/getting-started/errors.md)). A network failure gives `statusCode: 0`.
- **Configuration.** Pass the key and options to the constructor, or set `HATANG_API_KEY`, `HATANG_BASE_URL` and `HATANG_ENVIRONMENT`. Always set the base URL to `https://api.hatang.dev`.
- **Namespaces** follow the API: `emails`, `batch`, `domains`, `templates`, `contacts`, `contactProperties`, `audiences`, `segments`, `topics`, `broadcasts`, `automations`, `events`, `apiKeys`, `webhooks`, `logs`, `usage`, `chat`, `payments` and `einvoices`.
- **Idempotency.** Methods that create things take an `{ idempotencyKey }` option ([Idempotency](https://hatang.dev/docs/guides/getting-started/idempotency.md)).
- **Webhook helpers.** `verifyWebhook` and `constructWebhookEvent` check webhook signatures; `verifyIpn` and `constructIpnEvent` check Payments IPN calls ([Webhooks](https://hatang.dev/docs/guides/getting-started/webhooks.md)).
- **React Email.** Pass a `react` element to `emails.send` and the SDK renders it to HTML and plain text (install `@react-email/render` and `react` alongside).

The [Node.js SDK guide](https://hatang.dev/docs/guides/sdks/node.md) covers every namespace with examples.

## Chat SDKs for web and mobile

The chat SDKs run in your visitors' browsers and apps. They connect to the chat gateway with a public site id (and an app key on mobile), never with an API key.

| Platform | Package |
|---|---|
| Website | `https://chat.hatang.dev/widget.js` |
| React / Next.js | `@hatang/chat-react` |
| WordPress | Ha Tang Chat plugin |
| Flutter | `hatang_chat` |
| React Native / Expo | `@hatang/chat-react-native` |
| iOS (Swift) | `HatangChat` |
| Android (Kotlin) | `dev.hatang:chat` |

The [SDK overview](https://hatang.dev/docs/guides/sdks/overview.md) links the guide for each, the supported versions and the [realtime protocol](https://hatang.dev/docs/reference/realtime-protocol.md) they share.

## Other languages

There is no official server SDK for PHP, Python or Go yet. Two good options:

- **Call the REST API directly.** Every guide in this hub has cURL, Python and PHP samples. The API is plain JSON over HTTPS with a Bearer token.
- **Generate a client** from the OpenAPI spec, as below.

## The OpenAPI spec

The REST API is described by an OpenAPI 3.1 document, generated from the same code that serves the API:

| Spec | URL |
|---|---|
| REST API | `https://api.hatang.dev/openapi.json` |
| Chat gateway | `https://chat.hatang.dev/openapi.json` |

Browse it in the [REST API reference](https://hatang.dev/docs/reference/api.md) and the [chat gateway reference](https://hatang.dev/docs/reference/chat-gateway.md), or import it into an API client such as Postman or Insomnia to try calls by hand.

### Generate a client

Point a generator at the spec URL. Some examples:

```bash
# TypeScript types (use them with openapi-fetch or your own fetch wrapper)
npx openapi-typescript https://api.hatang.dev/openapi.json -o hatang.d.ts

# Python
pipx run openapi-python-client generate --url https://api.hatang.dev/openapi.json

# Many languages, including PHP, Java, Kotlin, C# and Ruby
npx @openapitools/openapi-generator-cli generate \
  -i https://api.hatang.dev/openapi.json -g php -o ./hatang-php
```

> **Note**
>
> The spec uses OpenAPI 3.1. Check that your generator supports 3.1; some only handle 3.0 fully. Regenerate the client when you upgrade, as new endpoints and fields are added to the spec as they ship.

Generated clients send what you give them, so remember the shared rules: the `Authorization: Bearer` header, `Idempotency-Key` on sends and payments, [pagination](https://hatang.dev/docs/guides/getting-started/pagination.md) with `after`, and retries on `429` ([Rate limits](https://hatang.dev/docs/guides/getting-started/rate-limits.md)).

## Next steps

- [Node.js SDK](https://hatang.dev/docs/guides/sdks/node.md)
- [SDK overview](https://hatang.dev/docs/guides/sdks/overview.md)
- [REST API reference](https://hatang.dev/docs/reference/api.md)

Source: https://hatang.dev/docs/guides/getting-started/api-libraries