OpenRegister Documentație
⌘ K
Verificăm API-ul v1
Developer APIStable v1

O singură schemă pentru registre din țări diferite.

Căutați companii în JSON normalizat și reveniți, când este necesar, la câmpurile naționale, fișierul și hash-ul sursei primare.

Obține o cheie API Trimite prima cerere ↓
PROVENANCE TRACE
  1. 01
    SOURCE FILEregistry.csv
  2. 02
    INTEGRITYsha256 verified
  3. 03
    NORMALIZElegal_entity
  4. 04
    RESPONSEGET /entities/{id}
BASE URLhttps://md.hanta.io/api/v1

Pornire rapidă

De la cheie la date în trei pași

Toate endpointurile de date folosesc același contract de autentificare. Nu este necesar un SDK; este suficient un client HTTP obișnuit.

  1. 1

    Creați cheia

    Deschideți contul API, denumiți mediul și salvați imediat secretul — nu va mai fi afișat.

    Deschide contul API →
  2. 2

    Trimiteți cheia în antet

    Folosiți X-API-Key sau Bearer. Consola API conține deja URL-ul și parametrii corecți.

  3. 3

    Salvați ID-ul cererii

    Răspunsul conține X-Request-ID. Transmiteți-l echipei de suport pentru analiza unei cereri concrete.

Autentificare

Cheia API aparține mediului

Creați chei separate pentru producție, staging și analiză. Cheia acționează în numele contului și consumă cota lunară comună.

Recomandat

X-API-Key

X-API-Key: or_live_…
Variantă compatibilă

Bearer token

Authorization: Bearer or_live_…
Cheia rămâne numai la dumneavoastră.

OpenRegister păstrează doar un hash SHA-256. Nu includeți secretul în query string, pachetul frontend, loguri sau depozite publice.

Registry APIX-API-Key

Integrări server și cereri de date.

Account APIClerk session

Cont, chei și administrarea abonamentului.

Stripe webhookStripe-Signature

Numai evenimente semnate de Stripe.

Paginare

Pagini cu dimensiune previzibilă

Căutarea este sortată după denumire și ID stabil. Folosiți valorile din meta, fără a calcula numărul de pagini în client.

page1…N

Numărul paginii solicitate.

pageSize1…100

Implicit sunt returnate 25 de înregistrări.

meta.totalinteger

Numărul de înregistrări pentru filtrul curent.

meta.pageCountinteger

Numărul paginilor disponibile.

Limite și cote

Două contoare pentru fiecare cerere

Limita pe minut protejează API-ul de vârfuri, iar cota lunară limitează volumul planului. Ambele contoare sunt returnate după fiecare cerere de date reușită.

HeaderValoare
X-RateLimit-LimitLimita cererilor pe minut.
X-RateLimit-RemainingCereri rămase în fereastra curentă.
X-RateLimit-ResetTimestamp Unix pentru resetarea ferestrei.
X-Monthly-Quota-LimitCota perioadei de facturare.
X-Monthly-Quota-RemainingCereri rămase în perioadă.
X-Monthly-Quota-ResetData noii perioade în format ISO 8601.
Ați primit 429?Citiți Retry-After, adăugați o întârziere aleatorie și repetați cererea.

Erori

Același format pentru toate endpointurile

Procesați error.code programatic și afișați message în loguri. requestId leagă eroarea de cererea de pe server.

ERROR · 401 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or revoked",
    "requestId": "69a27c71-44ab-4c0c-a95d-1a1ea8da24cc",
    "docs": "https://md.hanta.io/docs/api"
  }
}
400invalid_request

Parametrul sau UUID-ul are un format incorect.

401api_key_required

Lipsește antetul cu cheia API.

401invalid_api_key

Cheia este necunoscută, revocată sau deteriorată.

404entity_not_found

Nu a fost găsită o înregistrare cu acest ID OpenRegister.

429rate_limit_exceeded

Limita pe minut a cheii a fost epuizată.

429monthly_quota_exceeded

Cota perioadei de facturare a fost epuizată.

Versionare

Versiunea este fixată în URL

Contractul stabil curent este /api/v1. În v1 putem adăuga câmpuri nullable și endpointuri noi, dar nu eliminăm câmpuri și nu le schimbăm tipul fără o versiune nouă.

Contract prelucrabil automatOpenAPI 3.1 JSON
Descarcă ↗

Referință API

Endpointuri Registry API

Toate cele trei endpointuri necesită o cheie API și returnează antete pentru limite. Apăsați „Arată exemplul” pentru a deschide o cerere pregătită în consolă.

GET/countries

Lista țărilor

Registre disponibile în prezent și registre planificate.

API key application/json

Nu sunt necesari parametri.

GET/entities

Căutare companii

Căutare după denumire sau IDNO, cu filtre și paginare stabilă.

API key application/json

Parametri

qstring

Fragment din denumire sau numărul de înregistrare, fără diferențiere între majuscule și minuscule.

countrystring

Cod de țară ISO 3166-1 din două litere.

legalFormstring

Valoarea națională exactă a formei juridice.

activitystring

Valoarea sau codul exact al activității.

activityTypeunlicensed | licensed

Lista activității: unlicensed sau licensed.

pageinteger

Numărul paginii. Valoare implicită: 1.

pageSizeinteger

Dimensiunea paginii între 1 și 100. Valoare implicită: 25.

GET/entities/{id}

Înregistrarea completă a companiei

Câmpuri normalizate, înregistrare națională și proveniența sursei.

API key application/json

Parametri

iduuidobligatoriu

ID-ul OpenRegister din rezultatul căutării.

Referință API

Obiectul Entity

Câmpurile normalizate sunt identice pentru toate țările. Structura națională rămâne în registry și sourceData, astfel încât țările noi nu modifică contractul comun.

iduuid

Identificator OpenRegister stabil.

countryCodestring

Codul jurisdicției ISO 3166-1 alpha-2.

canonicalNamestring

Denumire pentru căutare și afișare.

statusstring

Starea normalizată a înregistrării.

legalFormstring | null

Forma juridică națională.

registryobject

Câmpuri naționale tipizate și interpretate.

sourceDataobject

Câmpuri originale fără pierderi sau redenumiri.

registrationsarray

Numere de înregistrare și stări locale.

provenanceobject | null

Fișier, hash, data importului și URL-ul sursei primare.

Planuri API

Preț fix, fără costuri suplimentare

Când cota este epuizată, API-ul oprește cererile cu 429 — nu apar facturi neașteptate.

GET/api/v1/planspublic

Free

€0/ lună

Pentru prototipuri și evaluarea API-ului

  • 1.000 cereri / perioadă
  • 60 cereri / minut
  • 1 chei API active

Pro

Popular
€29/ lună

Pentru integrări în producție

  • 100.000 cereri / perioadă
  • 600 cereri / minut
  • 5 chei API active

Business

€99/ lună

Pentru volume mari și mai multe medii

  • 1.000.000 cereri / perioadă
  • 3.000 cereri / minut
  • 20 chei API active

Endpointuri de cont

Cont, utilizare și chei API

Aceste endpointuri deservesc contul API și folosesc un token de sesiune Clerk sau un cookie de sesiune. Cheia Registry API nu este valabilă pentru ele.

GET /api/v1/account

Plan, utilizare, starea facturării și chei active.

GET /api/v1/auth/me

Profilul utilizatorului Clerk curent.

GET /api/v1/api-keys

Lista cheilor active fără secrete.

POST /api/v1/api-keys

Creează o cheie și returnează o singură dată secretul complet.

DELETE /api/v1/api-keys/{id}

Revocă o cheie a contului curent.

Starea serviciului

GET/api/v1/health/live

Procesul rulează și acceptă cereri HTTP.

GET/api/v1/health/ready

Aplicația și PostgreSQL sunt pregătite pentru trafic.

Facturare Stripe

Checkout și abonament

Planurile plătite sunt contractate prin Stripe Checkout. Facturile, metoda de plată, schimbarea planului și anularea sunt disponibile în Stripe Customer Portal din contul API.

1CheckoutCrearea abonamentului
→
2WebhookVerificarea stării
→
3EntitlementsLimite API noi

Accesul se modifică numai după un eveniment webhook Stripe semnat, nu după redirecționarea din Checkout.

Endpointuri de facturare

GET /api/v1/plans

Catalog public de planuri și drepturi.

POST /api/v1/billing/checkout

Creează o sesiune Stripe Checkout.

POST /api/v1/billing/portal

Creează o sesiune Stripe Customer Portal.

POST /api/v1/billing/webhook

Endpoint intern cu antetul Stripe-Signature.

Evenimente acceptate
checkout.session.completedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedcustomer.subscription.pausedcustomer.subscription.resumed

ID-ul evenimentului este salvat înainte de procesare, astfel încât relivrarea este sigură. Un eveniment mai vechi nu suprascrie starea mai nouă a abonamentului.

Se încarcă autentificarea…