Agente (Shipments)

Import logistics and customs platform for Mexican importers. 12-stage shipment pipeline, AI document classification, COFEPRIS permit tracking, and landed-cost calculation — all exposed via events and a broker-portal surface.

URL: agente.redbroomsoftware.comStatus: LIVE Tier: T2 (vertical SaaS primitive) SDK: @r-bsoftware/ecosystem-sdk — createWebhookHandler, createWebhookSender, signPayload, verifySignature, createSubscriptionClient

What you can integrate

• Subscribe to shipment lifecycle events — know when a container is booked, arrived, cleared, received, or closed
• Receive AI-classified document events when Agente parses a bill of lading, invoice, or COFEPRIS permit
• Get landed-cost events when customs clears and Agente finalizes COGS + FIFO lot data
• Watch for compliance alerts — COFEPRIS expiring, demurrage accumulating, cost overruns
• Ingest broker-portal updates — external customs brokers can advance a shipment through customs stages without touching your app

Authentication

• Primary: Firebase Auth session cookie for user flows
• API: Firebase ID token as Authorization: Bearer <token>
• SSO: Camino OAuth2 PKCE via /auth/rbs/callback — see Auth
• Webhook auth: HMAC-SHA256 per source app — see Webhooks

Broker portal uses a scoped auth that only exposes customs-stage transitions on shipments it is assigned to.

Endpoints

Method	Path
GET, POST	/api/alerts
GET	/api/broker-portal/shipments
PATCH	/api/broker-portal/shipments/:id/status
GET, POST	/api/brokers
POST	/api/caracol/products/create-draft
POST	/api/caracol/products/search
GET, POST	/api/cofepris
GET	/api/companies/by-rbs-org/:orgId
GET, POST	/api/costs
GET	/api/dashboard/stats

43 total — 7 admin/cron/internal (hidden) — +26 more primary endpoints not shown. Source: src/routes/api/**/+server.{ts,js} in the agente repo.

Shipment status machine (12 stages)

draft → booked → in_transit → arrived_port → customs_processing →
previo → customs_cleared → inland_transit → received → inventory_allocated → closed
                                                                 └─→ cancelled

Transitions are enforced by a graph in shipment.service.ts. Every status change auto-stamps a timestamp and emits a shipment.status_changed event.

Events emitted

Event	Receivers	Description
app.tenant_id_assigned	(none declared)	An app has bound its local tenant identifier to a canonical RBS org for the first time (or backfilled an existing binding). NOT routed via the standard webhook bus — producer calls CPR POST /api/v1/internal/tenant-mapping/upsert directly with X-RBS-Auth: App HMAC. Receiver list is empty because no app-side handler exists; the consumer is the Control Plane (ecosystem.redbroomsoftware.com). Topic 25 Phase 3 substrate — populates app_tenant_mappings junction. Senders list will grow as each app's producer wires (caracol first per S381 Phase 1 Session 3).
cofepris.expiring	camino	An Agente COFEPRIS permit is expiring within 30 days — triggers WhatsApp alert and CRM activity log in Camino
company.ecosystem_linked	baul	Emitted by Agente when a company is linked to an RBS ecosystem org (ecosystemOrgId set). Consumed by Baúl to auto-set operators.ecosystem_company_id.
cost.calculated	constanza	[auto-derived] cost.calculated event
demurrage.accumulating	camino	[auto-derived] demurrage.accumulating event
shipment.closed	colectiva	[auto-derived] shipment.closed event
shipment.created	colectiva	[auto-derived] shipment.created event
shipment.received	baul, caracol	[auto-derived] shipment.received event
shipment.status_changed	(none declared)	Agente updated shipment status (assigned, in_transit, delivered, exception). PD-160 (S406): receivers list is currently empty — agente code hardcodes targets:['camino'] in camino-emit.ts, so the event is delivered to camino via its existing handler chain (caracol.shipment.created etc.), not via this registry entry. Kept as a forward-design slot; remove or repopulate based on S404 routing decision.

Events consumed

Event	Senders	Description
cfdi.cancelled	constanza	A CFDI invoice has been cancelled
cfdi.stamped	constanza	A CFDI invoice has been stamped by the SAT via Constanza — receiver apps attach the UUID to their local invoice record and update status.
customer.merged	camino	Two duplicate customer records were merged in Camino — receiver apps update their local foreign keys to the canonical customer ID.
customer.updated	camino, constanza, caracol	A customer/contact record was updated in Camino — receiver apps sync the changed fields to their local customer records for display and invoicing accuracy.
handoff.completed	baul	Generic physical handoff completed with proof. Covers document delivery, product returns, sample collection, key handoff, equipment transfer. Baul physical layer event.
insights.available	camino	Camino's AI engine generated new business insights for a tenant — receiver apps surface the insights in their dashboards for operator review.
inventory.received	caracol	An inventory shipment was received at the warehouse — Agente updates the shipment status and the landed cost is finalized for COGS accounting.
payment.received	colectiva, constanza	A payment has been processed via Colectiva
payment.reconciled	constanza	Constanza completed bank reconciliation for a payment — receiver apps update their local payment records to mark the payment as reconciled against the bank statement.
subscription.activated	camino, colectiva	A subscription plan has been activated for a tenant — all apps that gate features behind the subscription tier update their local tier state.
subscription.cancelled	camino, colectiva	A subscription has been cancelled — all apps that gate features behind the subscription tier update their local tier state to free/cancelled.
subscription.limit_approaching	camino	A tenant's subscription usage is approaching the plan limit — Camino notifies subscriber apps to surface a plan-upgrade prompt to the tenant operator.
subscription.suspended	camino	A subscription was suspended due to non-payment or compliance issue — Camino disables access until resolution. Receiver apps lock out the tenant and surface a suspension banner.

Document AI pipeline

Upload a document via POST /api/documents, then trigger classification with POST /api/documents/[id]/classify. Pipeline: keyword pre-classifier (19 doc types) → Colectiva LLM proxy → JSON field extraction → Firestore write → document.discrepancy_found if fields contradict the shipment record.

Broker portal surface

External customs brokers log into /broker-portal with scoped credentials. They can:

• List shipments assigned to them
• Advance customs_processing → previo → customs_cleared
• Upload pedimentos and supporting documents

They cannot see commercial terms, supplier pricing, or other brokers' shipments.

Webhook signature

Standard ecosystem HMAC-SHA256 over raw body — see Webhooks.

Gotchas

• The 12-stage machine is enforced. Attempting to skip a stage returns 400 invalid_transition. Subscribe to shipment.status_changed rather than polling.
• cofepris.expiring fires at T-30 days, cofepris.expired the day after expiry. Build your reminder cascade on both — do not rely on a single warning.
• Landed-cost events fire on customs_cleared, not on closed. Listen for cost.calculated if you need COGS the moment customs releases the shipment.
• Broker-portal updates emit the same shipment.status_changed event as internal updates. Your handler should not differentiate by source.