API quickstart

A Preview only key can check requests and make previews, and can never use a credit. It is a good first key for something you are still testing. Step 5 needs a Full access key.

Keep the file. Koutei does not store documents or the details you send, so it cannot give you the PDF again later.

Save it as koutei.mjs and run node koutei.mjs:

// Node.js 18 or later: fetch is built in. Save as koutei.mjs and run: node koutei.mjs
import { writeFile } from 'node:fs/promises'

const BASE_URL = 'https://kouteisystems.com'
const HEADERS = {
  Authorization: `Bearer ${process.env.KOUTEI_API_KEY}`,
  'Koutei-Version': '2026-10-01',
  'Content-Type': 'application/json',
}
const request = {
  template: 'invoice',
  mode: 'preview',
  reference: 'JOB-0017',
  fields: {
    seller_name: 'Aiko Tanaka Design',
    client_name: 'Northwind Pty Ltd',
    invoice_number: 'INV-0042',
    date: '2026-10-12',
    currency: 'ZAR',
    items: [
      {
        description: 'Brand workshop',
        quantity: 1,
        unit_price: '6000.00',
      },
      {
        description: 'Design hours',
        quantity: '7.5',
        unit_price: '850.00',
      },
    ],
  },
}

async function post(path, body, extraHeaders = {}) {
  const response = await fetch(BASE_URL + path, {
    method: 'POST',
    headers: { ...HEADERS, ...extraHeaders },
    body: JSON.stringify(body),
  })
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`)
  return response
}

// 1. Check the request. Nothing is made and no credit is used.
const check = await (await post('/api/v1/documents/validate', request)).json()
console.log('Totals:', check.totals)

// 2. Make a preview: free and watermarked.
const preview = await post('/api/v1/documents', request)
await writeFile('invoice-INV-0042-preview.pdf', Buffer.from(await preview.arrayBuffer()))

// 3. Make the final document: 1 credit. Sent again with the same Idempotency-Key, it is free.
const final = await post('/api/v1/documents', { ...request, mode: 'final' }, { 'Idempotency-Key': 'JOB-0017-invoice' })
await writeFile('invoice-INV-0042.pdf', Buffer.from(await final.arrayBuffer()))
console.log('Credit used:', final.headers.get('Koutei-Credit-Used'), '| Balance due:', final.headers.get('Koutei-Totals-Balance-Due'))

Save it as koutei.py and run python3 koutei.py:

# Python 3 with requests (pip install requests). Save as koutei.py and run: python3 koutei.py
import os

import requests

BASE_URL = "https://kouteisystems.com"
HEADERS = {
    "Authorization": "Bearer " + os.environ["KOUTEI_API_KEY"],
    "Koutei-Version": "2026-10-01",
}
request = {
    "template": "invoice",
    "mode": "preview",
    "reference": "JOB-0017",
    "fields": {
        "seller_name": "Aiko Tanaka Design",
        "client_name": "Northwind Pty Ltd",
        "invoice_number": "INV-0042",
        "date": "2026-10-12",
        "currency": "ZAR",
        "items": [
            {
                "description": "Brand workshop",
                "quantity": 1,
                "unit_price": "6000.00",
            },
            {
                "description": "Design hours",
                "quantity": "7.5",
                "unit_price": "850.00",
            },
        ],
    },
}


def post(path, body, extra_headers=None):
    response = requests.post(BASE_URL + path, json=body, headers={**HEADERS, **(extra_headers or {})}, timeout=60)
    if not response.ok:
        raise SystemExit(f"{response.status_code}: {response.text}")
    return response


# 1. Check the request. Nothing is made and no credit is used.
print("Totals:", post("/api/v1/documents/validate", request).json()["totals"])

# 2. Make a preview: free and watermarked.
with open("invoice-INV-0042-preview.pdf", "wb") as file:
    file.write(post("/api/v1/documents", request).content)

# 3. Make the final document: 1 credit. Sent again with the same Idempotency-Key, it is free.
final = post("/api/v1/documents", {**request, "mode": "final"}, {"Idempotency-Key": "JOB-0017-invoice"})
with open("invoice-INV-0042.pdf", "wb") as file:
    file.write(final.content)
print("Credit used:", final.headers["Koutei-Credit-Used"], "| Balance due:", final.headers["Koutei-Totals-Balance-Due"])

Save it as koutei.php and run php koutei.php:

<?php
// PHP 8 with the curl extension. Save as koutei.php and run: php koutei.php
const BASE_URL = 'https://kouteisystems.com';

$request = [
    'template' => 'invoice',
    'mode' => 'preview',
    'reference' => 'JOB-0017',
    'fields' => [
        'seller_name' => 'Aiko Tanaka Design',
        'client_name' => 'Northwind Pty Ltd',
        'invoice_number' => 'INV-0042',
        'date' => '2026-10-12',
        'currency' => 'ZAR',
        'items' => [
            [
                'description' => 'Brand workshop',
                'quantity' => 1,
                'unit_price' => '6000.00',
            ],
            [
                'description' => 'Design hours',
                'quantity' => '7.5',
                'unit_price' => '850.00',
            ],
        ],
    ],
];

function post(string $path, array $body, array $extraHeaders = []): array
{
    $headers = [];
    $curl = curl_init(BASE_URL . $path);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 60,
        CURLOPT_HTTPHEADER => array_merge([
            'Authorization: Bearer ' . getenv('KOUTEI_API_KEY'),
            'Koutei-Version: 2026-10-01',
            'Content-Type: application/json',
        ], $extraHeaders),
        CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
        CURLOPT_HEADERFUNCTION => function ($curl, $line) use (&$headers) {
            $parts = explode(':', $line, 2);
            if (count($parts) === 2) {
                $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
            }
            return strlen($line);
        },
    ]);
    $answer = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if ($answer === false || $status >= 400) {
        fwrite(STDERR, $status . ': ' . ($answer === false ? curl_error($curl) : $answer) . PHP_EOL);
        exit(1);
    }
    return [$answer, $headers];
}

// 1. Check the request. Nothing is made and no credit is used.
[$answer] = post('/api/v1/documents/validate', $request);
echo 'Totals: ' . json_encode(json_decode($answer, true)['totals']) . PHP_EOL;

// 2. Make a preview: free and watermarked.
[$pdf] = post('/api/v1/documents', $request);
file_put_contents('invoice-INV-0042-preview.pdf', $pdf);

// 3. Make the final document: 1 credit. Sent again with the same Idempotency-Key, it is free.
[$pdf, $headers] = post('/api/v1/documents', array_merge($request, ['mode' => 'final']), ['Idempotency-Key: JOB-0017-invoice']);
file_put_contents('invoice-INV-0042.pdf', $pdf);
echo 'Credit used: ' . $headers['koutei-credit-used'] . ' | Balance due: ' . $headers['koutei-totals-balance-due'] . PHP_EOL;