Prezentare generala a API-ului
URL de baza
https://api.paylinks.ro/api/v1
Toate endpoint-urile sunt relative la acest URL de baza.
Autentificare
Endpoint-urile protejate necesita un token JWT de tip bearer:
Authorization: Bearer <token>
Vezi Autentificare pentru a afla cum obtii un token.
Headere
| Header | Obligatoriu | Descriere |
|---|---|---|
Authorization | Da (protejat) | Bearer <JWT token> |
Content-Type | Da (POST/PUT/PATCH) | application/json |
X-Currency | Nu | RON, EUR sau GBP (implicit: RON) |
Formatul sumelor
Toate sumele monetare sunt in unitati minore (bani pentru RON, centi pentru EUR/GBP):
| Afisare | Valoare API | Moneda |
|---|---|---|
| 49.99 RON | 4999 | RON |
| 10.00 EUR | 1000 | EUR |
| 1.50 GBP | 150 | GBP |
1 RON = 100 bani. Trimite si asteapta intotdeauna numere intregi.
Monede
PayLinks suporta trei monede:
- RON — Leul romanesc (implicit)
- EUR — Euro
- GBP — Lira sterlina
Seteaza moneda prin header-ul X-Currency.
Paginare
Majoritatea endpoint-urilor de listare folosesc paginare bazata pe cursor:
# Prima pagina
curl "https://api.paylinks.ro/api/v1/paylinks?limit=20"
# Pagina urmatoare (foloseste nextCursor din raspunsul anterior)
curl "https://api.paylinks.ro/api/v1/paylinks?limit=20&cursor=eyJpZCI6Ij..."
Exemplu de format raspuns pentru endpoint-uri cu cursor:
{
"items": [...],
"nextCursor": "cuid_or_cursor"
}
| Parametru | Tip | Implicit | Max |
|---|---|---|---|
limit | integer | 50 | 100 |
cursor | string | — | — |
Unele endpoint-uri (dispute) folosesc paginare bazata pe offset cu parametrii limit si offset.
Formatul erorilor
Toate erorile urmeaza un format consistent:
{
"error": {
"message": "Human-readable error description",
"code": "OPTIONAL_ERROR_CODE"
}
}
Coduri de status HTTP comune
| Status | Semnificatie |
|---|---|
200 | Succes |
201 | Creat |
400 | Cerere invalida / eroare de validare |
401 | Neautorizat (token lipsa sau invalid) |
403 | Interzis (permisiuni insuficiente) |
404 | Resursa negasita |
500 | Eroare interna de server |
Limitarea ratei
API-ul aplica limitare de rata per IP si per utilizator. Daca depasesti limita, vei primi un raspuns 429 Too Many Requests. Asteapta si reincearca cu backoff exponential.
Module API
| Modul | Descriere |
|---|---|
| Auth | Magic link si Google OAuth |
| PayLinks | Creaza si gestioneaza link-uri de plata |
| Tranzactii | Istoric tranzactii si rambursari |
| Clienti | Segmente de clienti |
| Analitice | Date despre venituri si MRR |
| Stripe | Stripe Connect, plati, sold |
| Dispute | Dispute la plati |
| Setari | Setari cont |
| Abonamente | Abonamente recurente |
| Achizitii | Achizitiile cumparatorilor |
| Broadcast-uri si abonati | |
| Incarcari | Incarcari de fisiere |
| Admin | Endpoint-uri doar pentru admin |
| Public | Endpoint-uri publice de checkout |