{ "openapi": "3.1.0", "info": { "title": "Ajungem.ro API", "version": "v1", "summary": "Bursa de transport Ajungem.ro — lotul 1: contract și citire.", "description": "Doar rute de citire în lotul 1 (docs/plan-api-dezvoltatori.md). Publicarea, ofertarea și webhook-urile urmează în loturile 2–3. Fără telefoane sau alte date de contact în niciun răspuns, nici după acceptarea unei oferte — acelea rămân exclusiv în site.", "contact": { "name": "Ajungem.ro", "url": "https://ajungem.ro/contact" } }, "servers": [{ "url": "https://api.ajungem.ro/v1", "description": "Producție" }], "security": [{ "ApiKey": [] }, {}], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ajk_live_… / test_ajk_…", "description": "Cheie API, trimisă ca `Authorization: Bearer ajk_live_…`. Cheile `test_ajk_` sunt refuzate în producție (sandboxul complet e planificat)." } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "requestId"], "properties": { "code": { "type": "string", "example": "rate_limited" }, "message": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" } } } }, "requestId": { "type": "string", "example": "req_abc123" } } } } }, "Listing": { "type": "object", "properties": { "ref": { "type": "string" }, "category": { "type": "string", "enum": ["car", "move", "parcel", "freight", "assistance"] }, "fromCity": { "type": "string" }, "fromCountry": { "type": "string" }, "toCity": { "type": "string" }, "toCountry": { "type": "string" }, "dateType": { "type": "string", "enum": ["asap", "exact", "flexible"] }, "dateFrom": { "type": ["string", "null"], "format": "date" }, "dateTo": { "type": ["string", "null"], "format": "date" }, "description": { "type": ["string", "null"] }, "budget": { "type": ["string", "null"], "description": "valoare zecimală, ca șir" }, "currency": { "type": "string" }, "urgent": { "type": "boolean" }, "needsInvoice": { "type": "boolean" }, "paymentDays": { "type": ["integer", "null"] }, "weightKg": { "type": ["integer", "null"] }, "volumeM3": { "type": ["string", "null"] }, "truckTypes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["published", "closed", "expired", "cancelled", "hidden"] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "estimatedCost": { "type": ["string", "null"] }, "distanceKm": { "type": ["integer", "null"] }, "url": { "type": "string", "format": "uri" }, "transportStage": { "type": ["string", "null"], "description": "doar pentru participanții autorizați" }, "stageUpdatedAt": { "type": ["string", "null"], "format": "date-time" } } }, "Offer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "listingRef": { "type": "string" }, "price": { "type": "string" }, "currency": { "type": "string" }, "availableDate": { "type": ["string", "null"], "format": "date" }, "message": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["sent", "accepted", "declined", "withdrawn", "expired"] }, "expiresAt": { "type": ["string", "null"], "format": "date-time" }, "revisions": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "carrier": { "type": "object", "description": "profil public minimal — niciodată contact", "properties": { "name": { "type": "string" }, "isCompany": { "type": "boolean" }, "verified": { "type": "boolean" } } } } }, "Vehicle": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fromCountry": { "type": "string" }, "fromCity": { "type": ["string", "null"] }, "toCountry": { "type": "string" }, "toCity": { "type": ["string", "null"] }, "dateFrom": { "type": "string", "format": "date" }, "dateTo": { "type": "string", "format": "date" }, "vehicle": { "type": "string" }, "capacity": { "type": ["string", "null"] }, "seats": { "type": ["integer", "null"] }, "volumeM3": { "type": ["string", "null"] }, "payloadT": { "type": ["string", "null"] }, "pallets": { "type": ["integer", "null"] }, "via": { "type": ["string", "null"] }, "note": { "type": ["string", "null"] }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "companyId": { "type": ["string", "null"], "format": "uuid" }, "displayName": { "type": "string" } } }, "Company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "cui": { "type": "string" }, "city": { "type": ["string", "null"] }, "county": { "type": ["string", "null"] }, "country": { "type": "string" }, "registry": { "type": "string", "enum": ["anaf", "vies"] }, "anafStatus": { "type": "string" }, "verificationStatus": { "type": "string" }, "arrVerified": { "type": "boolean" }, "cmrVerified": { "type": "boolean" }, "vehicleTypes": { "type": "array", "items": { "type": "string" } }, "rating": { "type": ["number", "null"] }, "reviewCount": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } }, "Place": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "county": { "type": "string" }, "slug": { "type": "string" } } }, "EventType": { "type": "object", "properties": { "type": { "type": "string" }, "permission": { "type": "string" }, "status": { "type": "string", "enum": ["planned", "live"] }, "description": { "type": "string" }, "apiVersion": { "type": "string" } } } }, "parameters": { "cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursorul primit la pagina anterioară. Legat de filtre, de mediu și de titular (cheia sau adresa); expiră în 15 minute." }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } } } }, "paths": { "/listings": { "get": { "summary": "Caută anunțuri publicate", "description": "Public; fără cheie, cursorul se leagă de adresă. Cel mult 20 rezultate pe pagină.", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "fromCountry", "in": "query", "schema": { "type": "string" } }, { "name": "toCountry", "in": "query", "schema": { "type": "string" } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "weightMax", "in": "query", "schema": { "type": "integer" } }, { "name": "volumeMax", "in": "query", "schema": { "type": "number" } }, { "name": "truckTypes", "in": "query", "schema": { "type": "string" }, "description": "listă separată prin virgulă" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "Pagina cerută", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": ["string", "null"] } } } } } }, "429": { "description": "Prea multe cereri", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/listings/{ref}": { "get": { "summary": "Un anunț, după codul lui", "description": "Proiecție publică pentru oricine; `transportStage` apare doar celor autorizați.", "parameters": [{ "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Anunțul", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Listing" } } } } } }, "404": { "description": "Nu există", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/listings/mine": { "get": { "summary": "Anunțurile titularului cheii", "security": [{ "ApiKey": ["listings:read"] }], "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }], "responses": { "200": { "description": "Pagina cerută" }, "401": { "description": "Fără cheie bună" } } } }, "/listings/{ref}/offers": { "get": { "summary": "Ofertele primite la un anunț al titularului", "description": "Doar beneficiarul anunțului; un transportator nu vede ofertele concurenților.", "security": [{ "ApiKey": ["offers:read"] }], "parameters": [{ "name": "ref", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }], "responses": { "200": { "description": "Pagina cerută" }, "404": { "description": "Nu există sau nu e al titularului" } } } }, "/offers/mine": { "get": { "summary": "Ofertele trimise de titularul cheii", "security": [{ "ApiKey": ["offers:read"] }], "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }], "responses": { "200": { "description": "Pagina cerută" } } } }, "/offers/{id}": { "get": { "summary": "O ofertă, pentru cei doi participanți", "security": [{ "ApiKey": ["offers:read"] }], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Oferta" }, "404": { "description": "Nu există sau nu ai acces" } } } }, "/vehicles": { "get": { "summary": "Vehicule libere publicate pe platformă", "description": "Fără vehicule preluate din grupuri Facebook — filtrul de sursă se aplică înaintea paginării.", "parameters": [ { "name": "fromCountry", "in": "query", "schema": { "type": "string" } }, { "name": "toCountry", "in": "query", "schema": { "type": "string" } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "vehicle", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "Pagina cerută", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": ["string", "null"] } } } } } } } } }, "/vehicles/{id}": { "get": { "summary": "Un vehicul liber, dacă e de pe platformă", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Vehiculul" }, "404": { "description": "Nu există sau e din import Facebook" } } } }, "/vehicles/mine": { "get": { "summary": "Vehiculele libere ale titularului cheii", "security": [{ "ApiKey": ["vehicles:read"] }], "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }], "responses": { "200": { "description": "Pagina cerută" } } } }, "/places": { "get": { "summary": "Căutare de localități", "parameters": [{ "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }], "responses": { "200": { "description": "Localități potrivite", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } } } } } } } } } }, "/cost-estimate": { "get": { "summary": "Estimare de cost pentru o rută", "description": "O informație, nu un preț recomandat: platforma nu fixează tarife.", "parameters": [ { "name": "fromCountry", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "toCountry", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "vehicle", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "price", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string", "enum": ["RON", "EUR"] } } ], "responses": { "200": { "description": "Estimarea" }, "404": { "description": "Localitate necunoscută" } } } }, "/companies/{id}": { "get": { "summary": "Profilul public al unei firme", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Firma", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Company" } } } } } }, "404": { "description": "Nu există" } } } }, "/events/types": { "get": { "summary": "Catalogul de evenimente (webhook-uri planificate)", "description": "Toate intrările sunt `status: planned` în lotul 1 — nimic nu se livrează încă.", "responses": { "200": { "description": "Catalogul", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } } } } } } } } } } }