Cada solicitud lleva la cabecera Authorization: Bearer gc_live_… (sau gc_test_…). La dirección base es https://gocargo.ro/api/v1. Solo HTTPS.

• Las claves las crea y revoca solo el administrador de la empresa. La clave se muestra una sola vez; solo conservamos su huella (SHA-256).
• Opcional: restricción por IP (IP o CIDR), fecha de caducidad y firma HMAC obligatoria.
• Al crear y al revocar, los administradores reciben un correo. El uso desde una IP nueva aparece en sus notificaciones.
• Cada respuesta lleva X-Request-Id; envíelo cuando nos pida ayuda.

Una solicitud sin el permiso necesario recibe 403 scope_missing.

• Cabeceras en cada respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Por encima del límite: 429 con Retry-After (secunde).
• La cuota mensual de la empresa se ve en X-Quota-Limit y X-Quota-Remaining; consume todas las claves, incluidas las de prueba. Paquetes adicionales y licencias comerciales: precios de la API.
• Uso propio: los webhooks llegan solo a los dominios de la empresa (el primero se registra automáticamente). Para software que conecta a otras empresas o para otras bolsas se necesita una licencia comercial.
• Cuerpo de una solicitud: máximo 1 MB. Como máximo 20 claves activas por empresa.
• Listas paginadas con cursor: ?limit=100&cursor=…, respuesta {data, next_cursor}. Para la sincronización utilice updated_since.
• Hasta 100 cargas en una solicitud, con resultado para cada 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": "..."}}
]}

Sobre cualquiera POST envíe la cabecera Idempotency-Key con un valor único (p. ej. un UUID). Si la red se cae y reintenta con el mismo valor, recibe exactamente la misma respuesta, sin una segunda carga. La respuesta se conserva 24 horas. El mismo valor con otro cuerpo → 409 conflict.

• Lo que publique con una clave de prueba nunca aparece en la bolsa pública, en las alertas ni en el barómetro.
• Los anuncios de prueba se borran solos tras 24 horas.
• Las claves de prueba no pueden crear pedidos. Cuando todo funcione, cree una clave Live y cambie solo la variable de entorno.

Añada una URL HTTPS en Ajustes → API e integraciones → Webhooks (o mediante POST /webhooks) y elija los eventos. El secreto whsec_… se muestra una sola vez.

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

• Responda con un código 2xx en un máximo de 10 segundos; el procesamiento pesado hágalo después.
• De lo contrario, reintentamos tras 1 min, 5 min, 30 min, 2 h, 6 h y 24 h. Tras 50 fallos seguidos, el endpoint se desactiva y se lo comunicamos.
• El mismo evento puede llegar dos veces: use el campo id para ignorar los duplicados.

Verificación de la firma

La cabecera GoCargo-Signature: t=<unix>,v1=<hex>, donde v1 = HMAC-SHA256 con el secreto del webhook (completo, con whsec_) sobre {t}.{corpul brut}. Rechace las firmas con más de 5 minutos de antigüedad.

# 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

Si al crearla marca «Firma HMAC obligatoria», recibe también un secreto de firma. Cada solicitud debe llevar además las cabeceras X-GoCargo-Timestamp (segundos unix) y X-GoCargo-Signature = HMAC-SHA256 en hexadecimal sobre {timestamp}.{METODĂ}.{cale}.{corp}.

• cale es la ruta completa en el servidor más la consulta exacta tal como la envía (si existe), p. ej. /api/v1/loads sau /api/v1/loads?status=active. Para GET, el cuerpo está vacío (el mensaje termina con «.»).
• El reloj debe estar en hora: aceptamos ±300 segundos. Una firma ya usada una vez no se vuelve a aceptar (anti-replay).
• Firme exactamente la cadena de bytes que envía como 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 conjunto ∈ loads, trucks, orders, quotes, reviews. La clave necesita export:read. Máximo 50.000 filas y 366 días por solicitud. El CSV tiene BOM UTF-8 y separador «;», para que se abra correctamente en 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"

Sin código: Ajustes → Exportar datos.

No ponga nunca la clave API en HTML ni en JavaScript del navegador. Cualquiera que abra la página la ve (View Source, DevTools) y puede publicar en nombre de su empresa. La clave se queda solo en el servidor: el formulario envía a un script suyo y el script llama a 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 el script (solo usuarios autenticados en su sitio web, token CSRF) y configure GOCARGO_API_KEY en la configuración del servidor, no en el archivo. Lo ideal, una clave solo con loads:write y restricción por la IP del servidor.