Fiecare cerere poartă antetul Authorization: Bearer gc_live_… (sau gc_test_…). Adresa de bază este https://gocargo.ro/api/v1. Doar HTTPS.

• Cheile le creează și le revocă doar administratorul firmei. Cheia se afișează o singură dată; noi păstrăm doar amprenta ei (SHA-256).
• Opțional: restricție pe IP-uri (IP sau CIDR), dată de expirare și semnătură HMAC obligatorie.
• La creare și la revocare, adminii primesc email. Folosirea de pe un IP nou vă apare în notificări.
• Fiecare răspuns are X-Request-Id; trimiteți-l când ne cereți ajutor.

O cerere fără permisiunea necesară primește 403 scope_missing.

• Antete la fiecare răspuns: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Peste limită: 429 cu Retry-After (secunde).
• Cota lunară a firmei se vede în X-Quota-Limit și X-Quota-Remaining; o consumă toate cheile, inclusiv cele de test. Pachete suplimentare și licențe comerciale: prețuri API.
• Uz propriu: webhook-urile ajung doar pe domeniile firmei (primul se înregistrează automat). Pentru softuri care conectează alte firme sau pentru alte burse e nevoie de o licență comercială.
• Corpul unei cereri: maximum 1 MB. Cel mult 20 de chei active pe firmă.
• Liste paginate cu cursor: ?limit=100&cursor=…, răspuns {data, next_cursor}. Pentru sincronizare folosiți updated_since.
• Până la 100 de încărcături într-o cerere, cu rezultat pe fiecare element:

curl -X POST https://gocargo.ro/api/v1/loads/bulk \
  -H "Authorization: Bearer $GOCARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [ {...}, {...} ]}'

# Răspuns: fiecare element are rezultatul lui
{"results": [
  {"index": 0, "ok": true, "ref": "GC1A2B3C4D"},
  {"index": 1, "ok": false, "error": {"code": "invalid_request", "message": "..."}}
]}

Pe orice POST trimiteți antetul Idempotency-Key cu o valoare unică (ex. un UUID). Dacă rețeaua cade și reîncercați cu aceeași valoare, primiți exact același răspuns, fără o a doua încărcătură. Răspunsul se păstrează 24 de ore. Aceeași valoare cu alt corp → 409 conflict.

• Ce publicați cu o cheie de test nu apare niciodată în bursa publică, în alerte sau în barometru.
• Anunțurile de test se șterg singure după 24 de ore.
• Cheile de test nu pot crea comenzi. Când totul merge, creați o cheie Live și schimbați doar variabila de mediu.

Adăugați un URL HTTPS în Setări → API și integrări → Webhooks (sau prin POST /webhooks) și alegeți evenimentele. Secretul whsec_… se afișează o singură dată.

POST /gocargo/webhook HTTP/1.1
Content-Type: application/json
GoCargo-Signature: t=1760180000,v1=8f3c...e91a

{
  "id": "evt_2b7f0c9e1a4d",
  "type": "order.status_changed",
  "created_at": "2026-10-11T09:30:00Z",
  "data": { ... }
}

• Răspundeți cu un cod 2xx în cel mult 10 secunde; procesarea grea faceți-o după.
• Altfel reîncercăm după 1 min, 5 min, 30 min, 2 h, 6 h și 24 h. După 50 de eșecuri la rând, endpoint-ul se dezactivează și vă anunțăm.
• Același eveniment poate sosi de două ori: folosiți câmpul id ca să ignorați dublurile.

Verificarea semnăturii

Antetul GoCargo-Signature: t=<unix>,v1=<hex>, unde v1 = HMAC-SHA256 cu secretul webhook-ului (întreg, cu whsec_) peste {t}.{corpul brut}. Respingeți semnăturile mai vechi de 5 minute.

# pip install flask
import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["GOCARGO_WEBHOOK_SECRET"]  # whsec_..., întreg
app = Flask(__name__)


def verify(header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(SECRET.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)


@app.post("/gocargo/webhook")
def webhook():
    # Semnătura se calculează pe corpul BRUT, exact cum a sosit.
    if not verify(request.headers.get("GoCargo-Signature", ""), request.get_data()):
        abort(400)
    event = request.get_json()
    print(event["type"], event["data"])
    return "", 204

Dacă la creare bifați „Semnătură HMAC obligatorie”, primiți și un secret de semnare. Fiecare cerere trebuie să aibă în plus antetele X-GoCargo-Timestamp (secunde unix) și X-GoCargo-Signature = HMAC-SHA256 în hex peste {timestamp}.{METODĂ}.{cale}.{corp}.

• cale este calea completă de pe server plus query-ul exact cum îl trimiteți (dacă există), ex. /api/v1/loads sau /api/v1/loads?status=active. Pentru GET, corpul e gol (mesajul se termină cu „.”).
• Ceasul trebuie să fie corect: acceptăm ±300 de secunde. O semnătură folosită o dată nu mai e acceptată (anti-replay).
• Semnați exact șirul de octeți pe care îl trimiteți ca body.

import hashlib
import hmac
import json
import os
import time

import requests

ORIGIN = "https://gocargo.ro"
PATH = "/api/v1/loads"
KEY = os.environ["GOCARGO_API_KEY"]
SIGNING_SECRET = os.environ["GOCARGO_SIGNING_SECRET"]

body = json.dumps({"origin_city": "Cluj-Napoca", "dest_country": "DE", "dest_city": "Stuttgart",
                   "cargo": "Piese auto", "loading_date": "2026-10-18"}).encode()
ts = str(int(time.time()))
message = ts.encode() + b".POST." + PATH.encode() + b"." + body
signature = hmac.new(SIGNING_SECRET.encode(), message, hashlib.sha256).hexdigest()

r = requests.post(ORIGIN + PATH, data=body, timeout=30, headers={
    "Authorization": "Bearer " + KEY,
    "Content-Type": "application/json",
    "X-GoCargo-Timestamp": ts,
    "X-GoCargo-Signature": signature,
})
print(r.status_code, r.text)

GET /export/{set}?format=csv|xlsx|json&from=AAAA-LL-ZZ&to=AAAA-LL-ZZ, cu set ∈ loads, trucks, orders, quotes, reviews. Cheia are nevoie de export:read. Maximum 50.000 de rânduri și 366 de zile pe cerere. CSV-ul are BOM UTF-8 și separator „;”, ca să se deschidă corect în Excel.

curl -o comenzi.xlsx \
  "https://gocargo.ro/api/v1/export/orders?format=xlsx&from=2026-01-01&to=2026-06-30" \
  -H "Authorization: Bearer $GOCARGO_API_KEY"

Fără cod: Setări → Export date.

Nu puneți niciodată cheia API în HTML sau în JavaScript din browser. Oricine deschide pagina o vede (View Source, DevTools) și poate publica în numele firmei voastre. Cheia stă doar pe server: formularul trimite la un script al vostru, iar scriptul cheamă GoCargo.

<!-- formularul din site: trimite la scriptul PHP de pe serverul vostru, NU la GoCargo -->
<form method="post" action="/publica.php">
  <input name="origin_city" placeholder="De la" required>
  <input name="dest_city" placeholder="Până la" required>
  <input name="dest_country" value="RO" maxlength="2">
  <input name="cargo" placeholder="Marfă" required>
  <input name="loading_date" type="date" required>
  <button>Publică pe GoCargo</button>
</form>

<?php // publica.php — cheia stă doar aici, pe server
$key = getenv('GOCARGO_API_KEY');
$load = [
    'origin_country' => 'RO', 'origin_city' => $_POST['origin_city'] ?? '',
    'dest_country' => strtoupper($_POST['dest_country'] ?? 'RO'), 'dest_city' => $_POST['dest_city'] ?? '',
    'cargo' => $_POST['cargo'] ?? '', 'loading_date' => $_POST['loading_date'] ?? '',
];
$ch = curl_init('https://gocargo.ro/api/v1/loads');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($load, JSON_UNESCAPED_UNICODE)]);
$res = curl_exec($ch);
http_response_code(curl_getinfo($ch, CURLINFO_HTTP_CODE) ?: 502);
header('Content-Type: application/json');
echo $res;

Protejați scriptul (doar utilizatori autentificați în site-ul vostru, token CSRF) și setați GOCARGO_API_KEY în configurarea serverului, nu în fișier. Ideal, o cheie doar cu loads:write și restricție pe IP-ul serverului.