Unofficial Tamamliyo API

TypeScript SDK for the Tamamliyo partner APIs. It wraps the public insurance endpoints into a typed, enum-driven client with built-in retries, request validation, and response parsing.

Features

• Automatic token header injection and configurable base URL/environment.
• Resilient HTTP layer with retries, timeouts, and backoff.
• Zod-based request/response validation covering Incoming Insurance, Foreign Health Insurance, and Transportation Insurance flows.
• Enumerations for common query modes (QueryType) and reusable schemas for geography lookups.
• Vitest + MSW test suite with coverage reporting.
• Ready-to-run examples and docs-driven API design (docs/*.md).

Installation

pnpm add @montarist/tamamliyo-api
# or
npm install @montarist/tamamliyo-api

Quick Start

import { ApiEnvironment, Client, QueryType } from '@montarist/tamamliyo-api';

const client = new Client({
  token: process.env.TAMAMLIYO_TOKEN!,
  environment: ApiEnvironment.Test, // defaults to production base URL
});

const quote = await client.incomingInsurance.createQuote({
  sorguTipi: QueryType.Passport,
  sigortaEttiren: {
    pasaportNo: 'X1234567',
    ad: 'Ada',
    soyad: 'Yilmaz',
    cinsiyet: 'K',
    uyruk: '33',
    babaAdi: 'Mehmet',
    dogumYeri: 'Paris',
    dogumTarihi: '1998-12-31',
  },
  sigortali: [
    {
      pasaportNo: 'X1234567',
      ad: 'Ada',
      soyad: 'Yilmaz',
      cinsiyet: 'K',
      uyruk: '33',
      babaAdi: 'Mehmet',
      dogumYeri: 'Paris',
      dogumTarihi: '1998-12-31',
      relationTypeId: 'F',
    },
  ],
  baslangicTarihi: '2024-05-01',
  bitisTarihi: '2024-05-15',
  email: '[email protected]',
  gsmNo: '5551234567',
  urunId: 110,
});

console.log(quote.data.teklifBilgileri.teklifId);

API Surface

Incoming Insurance

• createQuote
• makePayment
• createPolicy
• getQuoteDetails
• listCountries
• listProvinces
• listDistricts
• getPolicyPdf
• getReceiptPdf

Green Card Insurance

• getPrice
• createQuote
• makePayment
• createPolicy
• getPolicyPdf
• getCertificatePdf
• getReceiptPdf

Foreign Health Insurance

• getPrice
• createQuote
• makePayment
• createPolicy
• getQuoteDetails
• listProducts
• Geography + PDF helpers

Travel Health Insurance

• listProductCodes
• getPrice
• createQuote
• makePayment
• createPolicy
• getQuoteDetails
• listCountries
• listProvinces
• listDistricts
• getPolicyPdf
• getReceiptPdf
• Fast Track helpers (createFastTrackQuote, createFastTrackSale, confirmFastTrackPayment, listFastTrackPrices, listFastTrackAirports)

Transportation Insurance

• createRequest

Roadside Assistance

• createOrder
• getOrder
• downloadCertificate
• Reference data lookups (listProducts, listVehicleBrands, listVehicleModels, listVehicleYears, listCities, listTowns)

DASK Insurance

• createQuote
• makePayment
• createPolicy
• getPolicyPdf
• getReceiptPdf
• getQuoteDetails
• Property reference helpers (damage type, construction year, usage type, banks, UAVT hierarchy)

Traffic & Casco Requests

• createRequest

Configuration

const client = new Client({
  token: 'partner-token',
  environment: ApiEnvironment.Production,
  timeoutMs: 20_000,
  maxRetries: 2,
  concurrency: 4,
  userAgent: 'tamamliyo-sdk/0.1.0',
});

environment chooses between https://api.tamamliyo.com and https://api-test.tamamliyo.com. You can override baseUrl directly for custom deployments.

Development

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm test:e2e # requires environment variables (see below)

• Tests run via Vitest with MSW-powered mocks (pnpm test).
• Coverage reports appear under coverage/.
• Example scripts live under examples/.
• End-to-end tests hit the real Tamamliyo APIs when pnpm test:e2e runs. Configure credentials in .env.development (added to .gitignore).

E2E Environment Variables

Copy .env.development.example to .env.development (never commit) and fill in at least:

TAMAMLIYO_TOKEN=your_partner_token
# Optional overrides
TAMAMLIYO_BASE_URL=https://api-test.tamamliyo.com
TAMAMLIYO_E2E_TIMEOUT=30000
TAMAMLIYO_E2E_MAX_RETRIES=1
TAMAMLIYO_E2E_DEBUG=false

# Set to true to enable mutating tests (quote/order creation)
TAMAMLIYO_E2E_MUTATIONS=false

# Provide JSON payloads for mutating flows when enabling mutations
# Example:
# TAMAMLIYO_INCOMING_QUOTE_PAYLOAD={"sorguTipi":2,"sigortaEttiren":{...}}
# TAMAMLIYO_FOREIGN_QUOTE_PAYLOAD={...}
# TAMAMLIYO_TRAVEL_QUOTE_PAYLOAD={...}
# TAMAMLIYO_TRAVEL_FAST_TRACK_QUOTE_PAYLOAD={...}
# TAMAMLIYO_TRAVEL_FAST_TRACK_CONFIRM_PAYLOAD={...}
# TAMAMLIYO_GREEN_CARD_QUOTE_PAYLOAD={...}
# TAMAMLIYO_DASK_QUOTE_PAYLOAD={...}
# TAMAMLIYO_ROADSIDE_ORDER_PAYLOAD={...}
# TAMAMLIYO_TRANSPORTATION_REQUEST_PAYLOAD={...}
# TAMAMLIYO_TRAFFIC_REQUEST_PAYLOAD={...}
# TAMAMLIYO_GREEN_CARD_PRICE_PAYLOAD={"urunId":176}

Tip: Export JSON payloads carefully—they should mirror the official specs. The e2e suite skips mutating tests unless TAMAMLIYO_E2E_MUTATIONS=true and the corresponding payload env exists.

Documentation Sources

Implementation follows the markdown specs under docs/ (e.g., docs/01-incoming-insurances.md). Add new docs there and extend the SDK accordingly.

License

MIT