API REST Bolsa de Carga: Integración para Desarrolladores

Visión General

La API de Cargoffer permite integrar funcionalidades de bolsa de carga en cualquier sistema: TMS, ERP, WMS o aplicación propia.

Características Principales

- REST API con estándar JSON - Autenticación mediante API Keys y JWT - Webhooks para eventos en tiempo real - Sandbox para pruebas sin coste

Autenticación

Obtener API Key# Solic

```bash ita tu API Key en https://cargoffer.com/api ```

Autenticación con API Key

```bash curl -X GET "https://api.cargoffer.com/v1/cargas" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" ```

Autenticación con JWT (para aplicaciones web)

```bash

Obtener token

curl -X POST "https://api.cargoffer.com/v1/auth/token" \ -H "Content-Type: application/json" \ -d '{"client_id": "TU_CLIENT_ID", "client_secret": "TU_CLIENT_SECRET"}'

Usar token

curl -X GET "https://api.cargoffer.com/v1/cargas" \ -H "Authorization: Bearer TOKEN_OBTENIDO" ```

Endpoints Principales

Cargas

```bash

Listar cargas disponibles

GET /v1/cargas?origen=ES&destino=ES&fecha=2026-02-20

Publicar carga

POST /v1/cargas { "origen": { "ciudad": "Madrid", "codigo_postal": "28001", "direccion": "Calle Mayor 1" }, "destino": { "ciudad": "Barcelona", "codigo_postal": "08001", "direccion": "Avenida Diagonal 100" }, "mercancia": { "tipo": "palets", "peso_kg": 1200, "volumen_m3": 2.5, "valor_eur": 5000 }, "fecha_prevista": "2026-02-22", "remitente": { "empresa": "Empresa SL", "cif": "B12345678", "contacto": "Juan García", "telefono": "+34600123456", "email": "juan@empresa.com" } } ```

Transportistas

```bash

Buscar transportistas disponibles

GET /v1/transportistas?zona=ES&disponibles=true&valoracion_minima=4.5

Obtener perfil de transportista

GET /v1/transportistas/{id}

Ver vehículos de transportista

GET /v1/transportistas/{id}/vehiculos ```

Operaciones

```bash

Crear operación de transporte

POST /v1/operaciones { "carga_id": "CARG-2026-001", "transportista_id": "TRANS-001", "precio_acordado": 450, "condiciones": "pagero 7 dias" }

Obtener estado de operación

GET /v1/operaciones/{id}

Actualizar estado

PUT /v1/operaciones/{id}/estado { "estado": "en_transito", "ubicacion_actual": { "lat": 40.4168, "lon": -3.7038, "timestamp": "2026-02-20T10:30:00Z" } } ```

Tracking

```bash

Obtener tracking de envío

GET /v1/tracking/{operacion_id}

Historial de tracking

GET /v1/tracking/{operacion_id}/historial ```

Webhooks

Configurar Webhooks

```bash

Registrar URL de webhook

POST /v1/webhooks { "url": "https://tu-sistema.com/webhook/cargoffer", "eventos": ["operacion.creada", "operacion.entregada", "operacion.incidente"] } ```

Eventos Disponibles

| Evento | Descripción | | ----------------------- | ------------------------ | | `operacion.creada` | Nueva operación aceptada | | `operacion.en_transito` | Transportista en camino | | `operacion.entregada` | Entrega completada | | `operacion.incidente` | Incidencia reportada | | `pago.procesado` | Pago procesado | | `documento.generado` | CMR/eCMR generado |

Formato de Payload

```json { "evento": "operacion.entregada", "timestamp": "2026-02-20T15:30:00Z", "data": { "operacion_id": "OP-2026-001", "carga_id": "CARG-2026-001", "estado": "entregada", "firma_digital": "https://...", "incidentes": [] } } ```

Códigos de Error

| Código | Descripción | | ------ | --------------------------- | | 400 | Solicitud incorrecta | | 401 | Autenticación fallida | | 403 | Permisos insuficientes | | 404 | Recurso no encontrado | | 422 | Validación de datos fallida | | 429 | Rate limit excedido | | 500 | Error interno |

SDKs Disponibles

Python

```python pip install cargoffer

from cargoffer import CargofferAPI

api = CargofferAPI(api_key="TU_API_KEY")

Buscar cargas

cargas = api.cargas.list( origen="ES", destino="ES", fecha="2026-02-20" )

Publicar carga

carga = api.cargas.create({...}) ```

Node.js

```javascript const cargoffer = require("cargoffer");

const api = new cargoffer.Client({ apiKey: "TU_API_KEY" });

// Buscar cargas const cargas = await api.cargas.list({ origen: "ES", destino: "ES", }); ```

sandbox y Pruebas

Acceso a Sandbox

Todas las API keys de desarrollo incluyen acceso gratuito a sandbox:

``` https://api-sandbox.cargoffer.com/v1/... ```

Entorno de Pruebas

- Sin coste para pruebas - Datos de prueba automatizados - Simulación de todos los escenarios - Rate limits relajados

Límites y Cuotas

| Tier | Peticiones/mes | Webhooks | | ------------ | -------------- | --------- | | Free | 1,000 | 1 | | Starter | 10,000 | 5 | | Professional | 100,000 | 20 | | Enterprise | Unlimited | Unlimited |

Contacto y Soporte

- Documentación: https://docs.cargoffer.com - Soporte técnico: api@cargoffer.com - Slack community: join cargoffer developers

_Última actualización: Febrero 2026_