Portales e integraciones

API REST y servidor MCP

Todas las llamadas, documentadas — una API REST completa más un servidor MCP nativo para Claude, Cursor y cualquier agente de IA.

Autenticación

Dos credenciales, un solo límite. Una API key de plataforma para integraciones servidor a servidor y agentes, o una sesión iniciada para las llamadas que hace la propia app. El aislamiento entre cuentas lo impone Postgres con row-level security, no el handler: una credencial solo puede leer los datos de su propia cuenta.

curl -H "Authorization: Bearer $FALCONARA_API_KEY" \
  https://falconarahn.com/api/v1/fleet

Creá tu key en Settings → Integrations → API keys. Copiala cuando se muestra — solo se guarda un hash, así que no se puede volver a mostrar; si la perdés, revocala y emití otra. Las keys llevan su propia cuenta, así que una llamada solo puede leer tus datos, y la misma key sirve para la API REST y para MCP.

Las llamadas por sesión tienen un piso de rol: solo owner, admin y dispatcher llegan a estos endpoints. Las sesiones de driver y carrier owner se rechazan — sus portales nunca los llaman, y estos endpoints responden con datos de toda la cuenta.

Especificación legible por máquina

La descripción completa en OpenAPI 3.1 es pública en /api/v1/openapi.json — no hace falta key para leerla. Importala en Postman o Insomnia, o generá un cliente tipado directo desde ahí.

curl https://falconarahn.com/api/v1/openapi.json

Cargas y flota

Llamada	Qué hace
GET /api/v1/loads	Lista de cargas, más recientes primero. Filtros: status, dateFrom, dateTo, carrierId, brokerId, limit (máx. 100), offset.
POST /api/v1/quick-claim	Crea una carga desde un aviso del load board y, si querés, manda la consulta al broker en la misma llamada.
GET /api/v1/fleet	Cada truck activo con la carga que está corriendo, más totales por carrier.
GET /api/v1/next-load-suggestions	Por cada truck libre o que entrega en las próximas 24h: su próxima ubicación libre, los mejores corredores desde ahí y los brokers que mejor pagan en ellos.

Inteligencia de tarifas y brokers

Llamada	Qué hace
GET /api/v1/brokers	Directorio de brokers con contacto, rating y tarifa por milla histórica. Filtrá por mc o name.
GET /api/v1/broker-pulse	Win rate, cantidad de cargas y mejores lanes por broker en los últimos 30 días.
GET /api/v1/corridors?from=TX&to=GA	Tu propio RPM promedio, rango y cantidad de cargas para un par origen-destino. Ambos estados son obligatorios.
GET /api/v1/hot-corridors	Top 10 de lanes por RPM promedio de esta semana contra la anterior, con la tendencia.
GET /api/v1/mc-lookup?mc=123456	Resuelve un número MC a su razón social y domicilio registrados en SAFER.

Analítica

Llamada	Qué hace
GET /api/v1/analytics	Ingresos, cargas por estado, PODs pendientes y cargas en tránsito. from y to opcionales.
GET /api/v1/analytics-insights	Los últimos 30 días contra los 30 anteriores, redactado como hallazgos en lenguaje natural. Consume créditos de IA.

Documentos

Todos los endpoints de documentos reciben multipart/form-data con una parte file.

Llamada	Qué hace
POST /api/v1/ocr-rate-con	Lee una rate confirmation. Con loadId la adjunta a esa carga; sin loadId identifica la carga desde el propio documento (MC# del broker más número de carga) e informa si el match fue claro, ambiguo o inexistente.
POST /api/v1/ocr-receipt	Extrae monto, fecha, categoría y proveedor de un recibo de gasto.
POST /api/v1/documents/ingest	Clasifica un POD, BOL, rate con, recibo de lumper o factura, lo matchea a una carga y lo archiva. Un POD sobre una carga entregada la avanza a POD recibido.
POST /api/v1/documents/migrate	La variante de importación masiva: mismo matcheo, pero el resultado queda registrado en un batch para revisar en Doc Migration.

Leer una rate con nunca pisa tu carga. Aplicar los valores extraídos es un paso aparte, campo por campo — un error del OCR no puede reescribir una tarifa en silencio.

Exportaciones

Llamada	Qué hace
GET /api/documents/export	ZIP de documentos por carga, o por carrier y rango de fechas, o un rango completo. Un carrier owner siempre queda limitado a su propio carrier.
GET /api/loads/export	Cargas en CSV, hasta 5000 filas, con los mismos filtros que el listado.
GET /api/quickbooks/export	Facturas de carrier en formato de importación de QuickBooks Online, Net 15. Solo admin; from y to obligatorios.

Servidor MCP

FalconaraTMS es un servidor Model Context Protocol de primera clase, así que Claude, Cursor o cualquier agente compatible con MCP puede consultar tu TMS directo. JSON-RPC 2.0 sobre POST /api/mcp: initialize, tools/list y tools/call.

{
  "mcpServers": {
    "falconaratms": {
      "url": "https://falconarahn.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Herramienta	Argumentos	Devuelve
fleet_status	ninguno	Todos los trucks, cargados o disponibles
list_loads	status, dateFrom, dateTo, limit (máx. 50)	Las cargas que coinciden
pending_pods	ninguno	Cargas entregadas que siguen sin POD — el bloqueo para facturar
corridor_rates	pickupState, deliveryState	Tarifas históricas de ese corredor
broker_lookup	name (coincidencia parcial)	Un broker y su score de confiabilidad

curl -X POST https://falconarahn.com/api/mcp \
  -H "Authorization: Bearer $FALCONARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"pending_pods","arguments":{}}}'

Respuestas y errores

Las llamadas exitosas devuelven { data: ... }, a veces con un bloque meta. Los errores devuelven { error: "..." } con un status con sentido.

Status	Significado
400	Parámetros faltantes o mal formados — el cuerpo dice cuáles
401	Sin credencial, key inválida, o una sesión cuyo rol no está permitido
403	Autenticado pero fuera de alcance (otro carrier, exportación deshabilitada, solo admin)
404	No hubo coincidencias — también se devuelve cuando el registro es de otra cuenta
402	Créditos de IA agotados, en los endpoints que llaman a un modelo

Las fechas son YYYY-MM-DD y el dinero es un número en USD.
Los períodos de ingresos se agrupan por fecha de entrega, porque ahí se reconoce el ingreso. Los filtros de cargas usan la fecha de pickup — son sobre cuándo está ocupado un truck.
El estado de la carga sigue una máquina de estados validada; los saltos arbitrarios se rechazan del lado del servidor.

Carrier portal Notificaciones por correo