API Dokumentácia

Rýchly štart

Vygenerujte QR kód jedným príkazom:

curl -X POST https://api.easy-square.sk/api/v1/pay-by-square/qr-code \
  -H "Content-Type: application/json" \
  -H "X-Api-Email: vas@email.sk" \
  -H "X-Api-Key: esq_vas_api_kluc" \
  -d '{
    "beneficiaryName": "Firma s.r.o.",
    "iban": "SK7700000000000000000000",
    "amount": 100.00
  }' \
  --output qr-code.png

Výsledok: PNG obrázok s Pay by Square QR kódom pripravený na tlač alebo vloženie do faktúry.

Poznámka: Príklady v dokumentácii používajú testovacie údaje (fiktívny IBAN, názov firmy). Pred nasadením do produkcie nahraďte všetky hodnoty reálnymi údajmi.

Autentifikácia

Každý request vyžaduje dva hlavičky:

Hlavička	Popis
`X-Api-Email`	Email použitý pri registrácii
`X-Api-Key`	API kľúč získaný po registrácii

API kľúč sa zobrazí jednorazovo po úspešnej registrácii. Uložte si ho bezpečne — nedá sa zobraziť znova.

Generovanie QR kódu

POST /api/v1/pay-by-square/qr-code
Content-Type: application/json

Vráti PNG alebo JPEG obrázok s Pay by Square QR kódom.

Platobné údaje

Parameter	Typ	Povinný	Popis
`beneficiaryName`	string	áno	Meno príjemcu (max 70 znakov)
`iban`	string	áno	IBAN účet príjemcu (15-34 znakov)
`amount`	number	áno	Suma v EUR (0.01 – 999 999 999.99)
`currency`	string	nie	Mena, ISO 4217 kód (3 znaky, napr. `EUR`, `CZK`). Predvolená `EUR`
`variableSymbol`	string	nie	Variabilný symbol (max 10 číslic)
`constantSymbol`	string	nie	Konštantný symbol (max 4 číslice)
`specificSymbol`	string	nie	Špecifický symbol (max 10 číslic)
`paymentNote`	string	nie	Poznámka k platbe (max 140 znakov)
`dueDate`	string	nie	Dátum splatnosti (YYYY-MM-DD)
`bic`	string	nie	BIC/SWIFT kód banky (max 11 znakov)
`beneficiaryAddressLine1`	string	nie	Adresa príjemcu — ulica (max 70)
`beneficiaryAddressLine2`	string	nie	Adresa príjemcu — mesto (max 70)

Branding (voliteľné)

Parameter	Typ	Predvolená	Popis
`type`	string	`PAY`	`PAY` (modrý) alebo `INVOICE` (oranžový)
`position`	string	`BOTTOM`	Pozícia loga: `TOP`, `BOTTOM`, `LEFT`, `RIGHT`
`colorScheme`	string	`MEDIUM`	Farebná schéma: `LIGHT`, `MEDIUM`, `GRAY`, `DARK`
`withFrame`	boolean	`true`	Dekoratívny rámik s logom Pay by Square
`size`	integer	`256`	Veľkosť v pixeloch (64 – 960, krok 64)
`outputFormat`	string	`PNG`	Formát: `PNG`, `JPEG` alebo `JPG`

Odpoveď

Úspech (200): Binárny obrázok (image/png alebo image/jpeg)

Chyba: JSON s popisom problému:

{
  "status": 429,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Denný limit 100 QR kódov prekročený, skúste zajtra"
}

Príklady — generovanie QR kódu

Python

import requests

response = requests.post(
    "https://api.easy-square.sk/api/v1/pay-by-square/qr-code",
    headers={
        "X-Api-Email": "vas@email.sk",
        "X-Api-Key": "esq_vas_api_kluc",
    },
    json={
        "beneficiaryName": "Firma s.r.o.",
        "iban": "SK7700000000000000000000",
        "amount": 100.00,
        "variableSymbol": "2024001",
    },
)

if response.status_code == 200:
    with open("qr-code.png", "wb") as f:
        f.write(response.content)
    print("QR kód uložený do qr-code.png")
else:
    print(f"Chyba: {response.json()}")

JavaScript (Node.js)

const fs = require("fs");

const response = await fetch(
  "https://api.easy-square.sk/api/v1/pay-by-square/qr-code",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Email": "vas@email.sk",
      "X-Api-Key": "esq_vas_api_kluc",
    },
    body: JSON.stringify({
      beneficiaryName: "Firma s.r.o.",
      iban: "SK7700000000000000000000",
      amount: 100.0,
      variableSymbol: "2024001",
    }),
  }
);

if (response.ok) {
  const buffer = Buffer.from(await response.arrayBuffer());
  fs.writeFileSync("qr-code.png", buffer);
  console.log("QR kód uložený do qr-code.png");
} else {
  console.error("Chyba:", await response.json());
}

PHP

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.easy-square.sk/api/v1/pay-by-square/qr-code',
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Email: vas@email.sk',
        'X-Api-Key: esq_vas_api_kluc',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'beneficiaryName' => 'Firma s.r.o.',
        'iban' => 'SK7700000000000000000000',
        'amount' => 100.00,
        'variableSymbol' => '2024001',
    ]),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    file_put_contents('qr-code.png', $response);
    echo "QR kód uložený do qr-code.png";
} else {
    echo "Chyba: " . $response;
}

C# (.NET)

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post,
    "https://api.easy-square.sk/api/v1/pay-by-square/qr-code");

request.Headers.Add("X-Api-Email", "vas@email.sk");
request.Headers.Add("X-Api-Key", "esq_vas_api_kluc");

request.Content = JsonContent.Create(new
{
    beneficiaryName = "Firma s.r.o.",
    iban = "SK7700000000000000000000",
    amount = 100.00,
    variableSymbol = "2024001"
});

var response = await client.SendAsync(request);

if (response.IsSuccessStatusCode)
{
    var bytes = await response.Content.ReadAsByteArrayAsync();
    await File.WriteAllBytesAsync("qr-code.png", bytes);
    Console.WriteLine("QR kód uložený do qr-code.png");
}
else
{
    var error = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"Chyba: {error}");
}

Java

HttpClient client = HttpClient.newHttpClient();

String json = """
    {
        "beneficiaryName": "Firma s.r.o.",
        "iban": "SK7700000000000000000000",
        "amount": 100.00,
        "variableSymbol": "2024001"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.easy-square.sk/api/v1/pay-by-square/qr-code"))
    .header("Content-Type", "application/json")
    .header("X-Api-Email", "vas@email.sk")
    .header("X-Api-Key", "esq_vas_api_kluc")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<byte[]> response = client.send(request,
    HttpResponse.BodyHandlers.ofByteArray());

if (response.statusCode() == 200) {
    Files.write(Path.of("qr-code.png"), response.body());
    System.out.println("QR kód uložený do qr-code.png");
} else {
    System.out.println("Chyba: " + new String(response.body()));
}

Zostatok kvóty

GET /api/v1/pay-by-square/quota

Vráti informáciu o zostávajúcej dennej kvóte pre aktuálneho používateľa.

curl https://api.easy-square.sk/api/v1/pay-by-square/quota \
  -H "X-Api-Email: vas@email.sk" \
  -H "X-Api-Key: esq_vas_api_kluc"

Odpoveď:

{
  "remaining": 87,
  "limit": 100,
  "used": 13
}

Príklady — zostatok kvóty