Documentație API

Versionare API

Toate endpoint-urile sunt expuse pe canalul stabil sub prefixul /api/v1/. Folosește această cale pentru orice integrare nouă — îți garantăm compatibilitate cu versiunile anterioare în limitele SemVer pentru toată durata vieții v1.

Endpoint-urile vechi fără prefix (/api/...) continuă să răspundă identic, dar sunt depreciate și vor fi eliminate la 31 decembrie 2026. Răspunsurile lor includ antete Deprecation, Sunset și Link: rel="successor-version" care indică URL-ul echivalent v1.

# Canal stabil (recomandat)
curl https://forms.megapromoting.com/api/v1/questionnaires -b cookies.txt
# Raspuns: X-API-Version: v1

# Vechi (depreciat, eliminare 2026-12-31)
curl -i https://forms.megapromoting.com/api/questionnaires -b cookies.txt
# Antete raspuns:
#   Deprecation: true
#   Sunset: Wed, 31 Dec 2026 23:59:59 GMT
#   Link: </api/v1/questionnaires>; rel="successor-version"; type="application/json"

Politica completă (ciclu de viata, criterii pentru schimbari majore, ghid de migrare SDK) e în docs/API-VERSIONING.md.

Autentificare

Endpoint-urile autentificate folosesc cookie HTTP-only megaforms_token setat după înregistrare/autentificare. Pentru integrări server-la-server, autentificare programatica si păstrează cookie-ul în sesiunea ta.

# Autentificare programatica (folosește canalul stabil v1)
curl -X POST https://forms.megapromoting.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{"email":"you@example.com","password":"..."}'

# Foloseste cookie-ul pentru apeluri API
curl https://forms.megapromoting.com/api/v1/questionnaires -b cookies.txt

Pornire rapida — primul răspuns prin API

# 1. Pornește o sesiune nouă
curl -X POST https://forms.megapromoting.com/api/v1/public/q/SLUG/sessions \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ion","email":"ion@example.ro","loaded_at":1715789000000}'
# → { "sessionId": 42 }

# 2. Trimite un răspuns la întrebarea cu id=7
curl -X POST https://forms.megapromoting.com/api/v1/public/q/SLUG/sessions/42/answers \
  -H 'Content-Type: application/json' \
  -d '{"questionId":7,"answerText":"Răspuns text"}'
# → { "success": true, "isComplete": false, "progress": { "answered": 1, "total": 10 } }

# 3. Continuă cu fiecare răspuns. Când isComplete=true, sesiunea e finalizată
# automat și se declanșează webhook-ul session.completed.

Webhooks

Configurează webhook-uri în Setări → Webhook-uri. Fiecare livrare e semnată HMAC-SHA256 cu un secret per spatiu de lucru.

# Verificare semnătură în Node.js
const crypto = require('crypto');
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
const received = request.headers['x-megaforms-signature'];
if (expected !== received) throw new Error('Invalid signature');

# Evenimente disponibile
session.started      # Sesiune nouă creată
answer.submitted     # Răspuns nou la o întrebare
session.completed    # Sesiune finalizată (toate intrebarile raspunse)

Limite de rata

• •Sesiuni publice: 10 / IP / 15 min (configurabil per spatiu de lucru pe Business+)
• •Panou autentificat: 60 / min / utilizator (in-memory)
• •Transcriere vocala: Dependent de plan (Pro 1k min/lună, Business 5k, Agency 25k)

Paginare — bazata pe cursor

Toate endpoint-urile care returnează liste folosesc paginare bazata pe cursor (nu offset). Stabil sub modificări concurente, fără riscul de a sări sau dubla rânduri când datele se schimbă în timpul iterării.

# Prima pagină (limita max 100, implicita 25)
curl https://forms.megapromoting.com/api/v1/questionnaires?limit=25 -b cookies.txt

# Raspunsul include next_cursor:
# {
#   "data": [...25 elemente...],
#   "next_cursor": "eyJpZCI6MTI1LCJ0cyI6MTcxNTc4OTAwMH0",
#   "has_more": true
# }

# Pagină următoare cu cursor opac
curl "https://forms.megapromoting.com/api/v1/questionnaires?cursor=eyJpZCI6MTI1LCJ0cyI6MTcxNTc4OTAwMH0&limit=25" \
  -b cookies.txt

Important: cursor-ul e opac (codificat base64 cu semnatura interna). Nu încerca să-l interpretezi. Folosește-l strict pentru iterare inainte. Cursor-ele expiră după 24h de inactivitate.

Coduri de eroare — convenții standardizate

Toate erorile sunt JSON cu structura uniforma. Status HTTP corespunde cu severitatea, codul intern oferă detaliu specific.

// Structura uniforma raspuns eroare
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Field 'email' must be a valid email address",
    "field": "email",
    "trace_id": "req_abc123xyz"
  }
}

// Întotdeauna include trace_id când raportezi la support@megapromoting.com
// — putem găsi exact cererea ta în jurnale.

Pornire rapida în 3 limbaje (cURL + JS + Python)

Pornește o sesiune nouă în limba ta preferată:

cURL (baseline)

curl -X POST https://forms.megapromoting.com/api/v1/public/q/lead-b2b/sessions \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ion","email":"ion@example.ro","loaded_at":1715789000000}'

JavaScript (fetch, în browser sau Node 18+)

const res = await fetch('https://forms.megapromoting.com/api/v1/public/q/lead-b2b/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Ion',
    email: 'ion@example.ro',
    loaded_at: Date.now(),
  }),
});
const data = await res.json();
console.log(data.sessionId);

// Cu SDK oficial:
import { Megaforms } from 'megaforms-sdk';
const mf = new Megaforms({ baseUrl: 'https://forms.megapromoting.com' });
const session = await mf.public.startSession('lead-b2b', { name: 'Ion', email: 'ion@example.ro' });

Python (requests, 3.10+)

import requests, time

r = requests.post(
    'https://forms.megapromoting.com/api/v1/public/q/lead-b2b/sessions',
    json={
        'name': 'Ion',
        'email': 'ion@example.ro',
        'loaded_at': int(time.time() * 1000),
    },
    timeout=10,
)
r.raise_for_status()
session_id = r.json()['sessionId']
print(f'Session created: {session_id}')

Colectie Postman

Colectie v2.1 cu mediu configurabil pentru baseUrl + bearer token. Acoperă toate endpoint-urile /api/v1/* documentate în OpenAPI. Include:

• Script pre-cerere care injectează automat X-Csrf-Token din cookie
• Script de test post-cerere care validează structura răspunsului vs schema OpenAPI
• Variabilă dinamică {{newQuestionnaireId}} setată automat după Create
• Grupare în foldere per resursa (Auth, Questionnaires, Sessions, Webhooks, etc.)
• Exemple simulate pentru testare offline — răspuns generic fără server real

# Importa direct în Postman din URL:
File → Import → Link
https://forms.megapromoting.com/postman/megaforms.json

# Sau descarca local pentru CI/CD:
curl -O https://forms.megapromoting.com/postman/megaforms.json
newman run megaforms.json -e env-prod.json --reporters cli,json

SDK TypeScript — zero dependinte, ESM

SDK oficial publicat ca pachet npm megaforms-sdk. Generat automat din specificatia OpenAPI la fiecare publicare — niciodată desincronizat față de API-ul real. Caracteristici:

• Zero dependinte — folosește fetch nativ, fără axios/superagent
• ESM in primul rand, compatibil Node 18+, Deno 1.30+, Bun, Cloudflare Workers
• TypeScript strict — tipuri complete generate din schema OpenAPI
• Reincercare automata cu intarziere exponențială pe 429/503 (configurabil)
• Tree-shakeable — pachetul final <15KB dacă folosești doar 1-2 endpoint-uri

npm install megaforms-sdk
# sau
pnpm add megaforms-sdk
# sau
bun add megaforms-sdk

// Folosire:
import { Megaforms } from 'megaforms-sdk';

const mf = new Megaforms({
  baseUrl: 'https://forms.megapromoting.com',
  // Pentru endpoint-uri autentificate, autentifica programatic mai intai:
  // mf.auth.login({ email, password }) — seteaza cookie intern
  retry: { maxAttempts: 3, backoffMs: 1000 },
});

// Liste cu paginare automată
for await (const q of mf.questionnaires.iterAll()) {
  console.log(q.title);
}

// Ajutor verificare semnatura webhook inclus
import { verifyWebhookSignature } from 'megaforms-sdk/webhooks';
const valid = verifyWebhookSignature(rawBody, headerSignature, WEBHOOK_SECRET);

Specificatie OpenAPI — descarca & exploreaza

Specificatia noastra OpenAPI 3.1 e generata din cod (nu scrisa manual) la fiecare publicare in productie. Asta înseamnă: nu poate dezacorda de la realitate. Conține toate endpoint-urile /api/v1/*, scheme complete cerere/raspuns, exemple valide, coduri de eroare.

• JSON: /api/openapi (~180KB)
• YAML: /api/openapi?format=yaml (~140KB)
• Swagger UI gazduit: /api-docs/swagger
• Redoc gazduit: /api-docs/redoc

Specificatia e versionata cu antetul X-Spec-Version care urmează SemVer. MAJOR (1→2): schimbari majore. MINOR (1.x→1.y): adăugiri compatibile. PATCH (1.x.0→1.x.1): doar documentatie sau corectie tipuri.

Chei de idempotenta

Operațiile non-idempotente (POST care creează rânduri, plăți Stripe prin API, export GDPR) suportă antetul Idempotency-Key. Folosește un UUID v4 unic per operație logică. Repetarea cu aceeași cheie în 24h returnează același răspuns fără efect lateral dublu.

# Trimite plată o singură dată chiar dacă cererea e reincercata
curl -X POST https://forms.megapromoting.com/api/v1/billing/checkout \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c4e0e5a-1b8d-4a3f-9e2f-3d8b9c1a0e5f' \
  -b cookies.txt \
  -d '{"plan":"pro","interval":"monthly"}'

CORS & incorporare

Endpoint-urile publice (/api/v1/public/*) trimit Access-Control-Allow-Origin: * pentru integrarea prin incorporare pe orice domeniu. Endpoint-urile autentificate (/api/v1/...) au CORS restrictiv la lista de origini configurată în Setări → Origini permise per spatiu de lucru.

Pentru incorporari intre domenii, recomandăm scriptul nostru oficial: <script async src="https://forms.megapromoting.com/embed.js" data-form="lead-b2b"></script>. Gestionează CSP, sandbox iframe, postMessage cu fereastra parinte.

SDK & biblioteci client — alternative

Acum disponibil: specificatie OpenAPI 3.1. SDK-uri TypeScript / Python / Go vin în plan (sprint S13+).

Între timp, generează un client din OpenAPI cu:

# TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i https://forms.megapromoting.com/api/openapi \
  -g typescript-fetch -o ./megaforms-client

# Python
openapi-python-client generate --url https://forms.megapromoting.com/api/openapi