Ogni richiesta porta l'intestazione Authorization: Bearer gc_live_… (sau gc_test_…). L'indirizzo base è https://gocargo.ro/api/v1. Solo HTTPS.

• Le chiavi vengono create e revocate solo dall'amministratore dell'azienda. La chiave viene mostrata una sola volta; conserviamo solo la sua impronta (SHA-256).
• Facoltativo: restrizione per IP (IP o CIDR), data di scadenza e firma HMAC obbligatoria.
• Alla creazione e alla revoca, gli amministratori ricevono un'email. L'uso da un nuovo IP compare nelle vostre notifiche.
• Ogni risposta ha X-Request-Id; inviatelo quando ci chiedete assistenza.

Una richiesta senza l'autorizzazione necessaria riceve 403 scope_missing.

• Intestazioni in ogni risposta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Oltre il limite: 429 con Retry-After (secunde).
• La quota mensile dell'azienda è visibile in X-Quota-Limit e X-Quota-Remaining; consuma tutte le chiavi, comprese quelle di test. Pacchetti aggiuntivi e licenze commerciali: prezzi API.
• Uso proprio: i webhook arrivano solo sui domini dell’azienda (il primo si registra automaticamente). Per i software che collegano altre aziende o per altre borse serve una licenza commerciale.
• Corpo di una richiesta: massimo 1 MB. Al massimo 20 chiavi attive per azienda.
• Elenchi paginati con cursore: ?limit=100&cursor=…, risposta {data, next_cursor}. Per la sincronizzazione utilizzate updated_since.
• Fino a 100 carichi in una richiesta, con esito per ogni elemento:

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": "..."}}
]}

Su qualsiasi POST inviate l'intestazione Idempotency-Key con un valore univoco (es. un UUID). Se la rete cade e riprovate con lo stesso valore, ricevete esattamente la stessa risposta, senza un secondo carico. La risposta viene conservata per 24 ore. Stesso valore con corpo diverso → 409 conflict.

• Ciò che pubblicate con una chiave di prova non compare mai nella borsa pubblica, negli avvisi o nel barometro.
• Gli annunci di prova si cancellano da soli dopo 24 ore.
• Le chiavi di prova non possono creare ordini. Quando tutto funziona, create una chiave Live e cambiate solo la variabile d'ambiente.

Aggiungete un URL HTTPS in Impostazioni → API e integrazioni → Webhook (oppure tramite POST /webhooks) e scegliete gli eventi. Il segreto whsec_… viene mostrato una sola volta.

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": { ... }
}

• Rispondete con un codice 2xx entro 10 secondi; l'elaborazione pesante fatela dopo.
• Altrimenti riproviamo dopo 1 min, 5 min, 30 min, 2 h, 6 h e 24 h. Dopo 50 errori consecutivi l'endpoint viene disattivato e vi informiamo.
• Lo stesso evento può arrivare due volte: utilizzate il campo id per ignorare i duplicati.

Verifica della firma

L'intestazione GoCargo-Signature: t=<unix>,v1=<hex>, dove v1 = HMAC-SHA256 con il segreto del webhook (intero, con whsec_) su {t}.{corpul brut}. Rifiutate le firme più vecchie di 5 minuti.

# 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

Se alla creazione spuntate «Firma HMAC obbligatoria», ricevete anche un segreto di firma. Ogni richiesta deve avere inoltre le intestazioni X-GoCargo-Timestamp (secondi unix) e X-GoCargo-Signature = HMAC-SHA256 in esadecimale su {timestamp}.{METODĂ}.{cale}.{corp}.

• cale è il percorso completo sul server più la query esatta come la inviate (se presente), ad es. /api/v1/loads sau /api/v1/loads?status=active. Per GET il corpo è vuoto (il messaggio termina con «.»).
• L'orologio deve essere corretto: accettiamo ±300 secondi. Una firma già usata una volta non viene più accettata (anti-replay).
• Firmate esattamente la stringa di byte che inviate come 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-19"}).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, con insieme ∈ loads, trucks, orders, quotes, reviews. La chiave richiede export:read. Massimo 50.000 righe e 366 giorni per richiesta. Il CSV ha BOM UTF-8 e separatore «;», per aprirsi correttamente in 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"

Senza codice: Impostazioni → Esportazione dati.

Non inserite mai la chiave API in HTML o JavaScript del browser. Chiunque apra la pagina la vede (View Source, DevTools) e può pubblicare a nome della vostra azienda. La chiave resta solo sul server: il modulo invia a un vostro script, e lo script chiama 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;

Proteggete lo script (solo utenti autenticati sul vostro sito, token CSRF) e impostate GOCARGO_API_KEY nella configurazione del server, non nel file. Idealmente, una chiave solo con loads:write e restrizione sull'IP del server.