Overview - api.dwf.ro

Documentație API DWF
Introducere
API-ul DWF îți permite să accesezi programatic datele despre branduri, proiecte și informațiile financiare gestionate în platforma DWF. Poți folosi API-ul pentru a construi rapoarte personalizate, a automatiza fluxuri de lucru și a integra datele DWF în propriile aplicații.
API-ul oferă acces liber și nerestricționat la toate datele agenției tale din platformă, pentru toate brandurile și proiectele gestionate.
Capabilități principale
Acestea sunt principalele seturi de date pe care le poți obține prin endpoint-urile API DWF v1.0:

Date la nivel de brand: detalii despre branduri, lista brandurilor active, status, persoane de contact, informații generale și metadate.
Date la nivel de proiect: detalii despre proiecte, status, echipa alocată, deadline-uri, livrabile, istoric, precum și date agregate la nivel de proiect.
Date financiare: informații despre bugete, facturare, încasări, plăți, profitabilitate pe proiect și pe brand, precum și rapoarte financiare agregate la nivel de agenție.

Cum începi
Loghează-te în contul tău DWF și obține cheia unică de API din secțiunea My Account.

Consultă Quick Start Guide pentru a învăța cum faci primul apel către API.
Citește Ghidul de autentificare pentru a înțelege cum autentifici corect cererile API.

Biblioteci și SDK-uri
API-ul DWF folosește protocolul HTTP, ceea ce îl face compatibil cu aproape orice limbaj de programare. Toate răspunsurile sunt returnate implicit în format JSON.
(Lista bibliotecilor client oficiale va fi completată pe măsură ce vor fi publicate.)
Changelog
Aceasta este prima versiune a API-ului DWF v1.0. Pagina de Changelog va fi actualizată pe măsură ce vor fi dezvoltate funcționalități și îmbunătățiri noi.

Ghid de autentificare
Poți testa API-urile direct în pagina de documentație a fiecărui endpoint, apăsând pe Try it out.
Pentru a autentifica cererile cu cheia ta API, poți seta variabila de mediu Authorization cu API Key-ul tău. În bara laterală Try it out, apasă pe Go to set value.
Alternativ, mergi la tab-ul Auth. La Type, selectează API Key, și adaugă în Headers cheia Authorization cu valoarea API Key-ului tău.
Dacă folosești orice alt tool pentru a testa API-urile, adaugă cheia Authorization în header-ul cererii, având ca valoare API Key-ul tău (vezi exemplul cURL din Quick Start Guide).

Quick Start Guide
Acest ghid îți arată rapid cum să faci prima cerere către API.
Obține cheia API
Mai întâi, ai nevoie de o cheie API:

Loghează-te în contul tău DWF (https://app.dwf.ro)
Mergi la My Account
Copiază API Token-ul pentru a-l folosi în cererile tale

Notă: Dacă apeși pe „Regenerate API Token", cheia actuală va fi suprascrisă și vei pierde accesul dacă tu sau alți utilizatori o folosiți în acel moment.
Fă o cerere
Poți folosi orice tool care suportă request-response HTTP pentru a face cereri API, sau le poți testa direct în pagina de documentație a fiecărui endpoint, folosind opțiunea Try it out. Hai să vedem ambele variante.
Pentru acest exemplu, să folosim cURL dintr-un Command Line Interface (CLI) precum Terminal, pentru a face o cerere de obținere a brandurilor:
curl --request GET
--url https://api.dwf.ro/v1/brands
--header 'Accept: application/json'
--header 'Authorization: YOUR_API_KEY_HERE'
Aceasta va returna lista brandurilor gestionate într-un cont DWF care folosește API Key-ul respectiv.
Componentele cererii:

--request GET – face o cerere de tip GET
--url – URL-ul endpoint-ului API
--header – adaugă header-ul Authorization cu cheia ta API

Procesează răspunsul
API-ul va returna un răspuns JSON, de exemplu:
json{
"brand_info": {
"id": "12345",
"name": "Brand Example",
"status": "active",
"date_created": "2024-03-15",
"account_manager": "Ana Popescu",
"projects_count": 8,
"financial_summary": {
"total_budget": 120000,
"invoiced": 85000,
"collected": 72000,
"currency": "RON"
}
}
}
Alternativ, în pagina de documentație a endpoint-ului, apasă pe Try it out:

Autentifică cererea cu cheia ta API, conform Ghidului de autentificare.
Introdu ID-urile necesare (brand, proiect etc.) în tab-ul Params.
Apasă pe Send.

Și gata! Tocmai ai făcut prima cerere API. Analizează răspunsul și apoi consultă restul documentației pentru a vedea ce mai poți construi.
Bune practici

Păstrează cheia API privată – nu o distribui public.
Nu include cheia direct în cod pe care îl distribui – folosește variabile de mediu.
Regenerează periodic cheia pentru securitate sporită.
Limitează accesul cheii API doar la endpoint-urile necesare, dacă e posibil.

Revocarea cheilor API
Dacă API Key-ul tău este compromis, îl poți revoca regenerând API Token-ul din secțiunea My Account din DWF. Acest lucru invalidează imediat cheia curentă, blocând cererile ulterioare cu acea cheie.
Pentru orice alte probleme de autentificare, contactează echipa de suport.
Obținerea ID-urilor pentru branduri și proiecte
ID-urile unice pentru brandurile și proiectele tale pot fi obținute fie din URL-urile specifice din platformă, fie din răspunsurile endpoint-urilor API.
Brand ID
Pentru a obține ID-ul unui brand din platformă:

Loghează-te în contul tău DWF (https://app.dwf.ro)
Deschide brandul dorit din lista de branduri.
URL-ul platformei conține Brand ID-ul.
De exemplu: https://app.dwf.ro/brands/12345/overview – în acest exemplu, Brand ID-ul este 12345.

Pentru a obține Brand ID-ul prin API, fă un apel la endpoint-ul Get Brands. Răspunsul va conține detaliile brandurilor solicitate, inclusiv ID-urile acestora, pe care le poți folosi în alte cereri.
Project ID
Pentru a obține ID-ul unui proiect din platformă:

Loghează-te în contul tău DWF (https://app.dwf.ro)
Deschide brandul dorit și selectează proiectul.
URL-ul platformei pentru proiect conține Project ID-ul.
De exemplu: https://app.dwf.ro/brands/12345/projects/67890 – în acest exemplu, Project ID-ul este 67890.

Pentru a obține Project ID-ul prin API, fă un apel la endpoint-ul Get Projects. Răspunsul va conține detaliile proiectelor solicitate, inclusiv ID-urile acestora.

Limite de utilizare (Rate Limits)
Există limite de cereri pentru a preveni abuzul și a asigura o utilizare echitabilă.
Depășirea limitelor va genera răspunsuri HTTP 429. Dacă ai nevoie de limite mai mari, contactează echipa de suport.
Limite și cote
LimităNumăr de cereriNumăr maxim de cereri pe secundă10Număr maxim de rânduri pe cerere (Request Quota)1000Cotă zilnică (Daily Quota)10 000
Depășirea limitelor
Dacă depășești rate limit-urile, vei primi un răspuns 429 Too Many Requests.
Daily Quota Exceeded
json{
"error": {
"message": "Daily quota exceeded",
"details": [
"You have exceeded the allowed daily requests"
]
}
}
Detalii: acest mesaj indică faptul că cererea depășește limita zilnică de cereri. Reîncearcă după o pauză.
Rate Limit Exceeded
json{
"error": {
"message": "Rate limit exceeded",
"details": [
"You have exceeded the allowed requests per second"
]
}
}
Detalii: acest mesaj indică faptul că cererea depășește limita de cereri pe secundă. Reîncearcă după o scurtă pauză.
Ai nevoie de limite mai mari?
Limitele implicite acoperă majoritatea scenariilor normale de utilizare. Dar dacă ai nevoie de limite mai mari, contactează echipa de suport.
Oferă detalii despre:

Scenariul tău specific de utilizare
Endpoint-urile pe care le folosești
Limitele mărite de care ai nevoie

Vom analiza cererea și vom ajusta limitele acolo unde este cazul.

Erori
API-ul DWF folosește codurile standard HTTP pentru a indica succesul sau eșecul cererilor.
Coduri de status HTTP
CodDescriere200Succes400Bad request – cererea a fost malformată sau îi lipsește un parametru obligatoriu401Unauthorized – cheie API invalidă sau lipsă403Forbidden – cheia API nu are acces la resursa solicitată404Not found – resursa solicitată nu există429Too many requests – limita de rate sau cota zilnică a fost depășită500Internal server error – eroare neașteptată pe serverul API50xErori specifice diverselor endpoint-uri
Formatul răspunsului de eroare
Răspunsurile de eroare sunt returnate în format JSON:
json{
"error": {
"message": "Rate limit exceeded",
"details": [
"You have exceeded the allowed requests per second"
]
}
}
Obiectul error conține:

message – un mesaj general de eroare
details – detalii specifice despre eroare

Erori frecvente
401 Unauthorized
json{
"error": {
"message": "Invalid authentication",
"details": [
"The API key provided is invalid"
]
}
}
Detalii: există o problemă cu cheia API:

cheia API lipsește din cerere
cheia este invalidă sau incorectă
cheia este expirată sau revocată

Verifică dacă trimiți cheia API corectă în header-ul Authorization.
403 Forbidden
json{
"error": {
"message": "Forbidden access",
"details": [
"Your API key does not have access to the requested data"
]
}
}
Detalii: cheia API folosită nu are acces la operațiunea solicitată. Asigură-te că cheia are permisiunile necesare.
404 Not Found
json{
"error": {
"message": "Data not found",
"details": [
"The requested data does not exist."
]
}
}
Detalii: obiectul specificat în cerere nu există. De exemplu, ai solicitat un brand sau un proiect care nu se află în contul tău DWF.
429 Too Many Requests
Daily Quota Exceeded
json{
"error": {
"message": "Daily quota exceeded",
"details": [
"You have exceeded the allowed daily requests"
]
}
}
Rate Limit Exceeded
json{
"error": {
"message": "Rate limit exceeded",
"details": [
"You have exceeded the allowed requests per second"
]
}
}
500 Internal Server Error
json{
"error": {
"message": "Internal server error",
"details": [
"The server encountered an error while processing your requests"
]
}
}
Detalii: a apărut o eroare neașteptată pe serverul API. Reîncearcă cererea mai târziu. Dacă problema persistă, contactează echipa de suport.
50X Erori specifice endpoint-urilor
Poți întâlni erori specifice anumitor endpoint-uri – acestea sunt listate și explicate pe pagina fiecărui endpoint.

Changelog
Versiunea 1.0 (curentă)
Data lansării: (de completat)
Aceasta este prima versiune a API-ului DWF v1.0.

Contact
Ai nevoie de ajutor cu API-ul sau ai alte întrebări? Contactează echipa de suport DWF prin chat-ul din platforma DWF sau pe email.