# API v1 Customer Onboarding

## Purpose

This document defines the minimum operational flow for onboarding an external customer onto the FlowMint container tracking API.

The goal is simple:
- issue a consumer token
- register at least one webhook target when push delivery is needed
- hand the customer one concise launch pack

## Base URL

- Target public host: `https://api.cargoflowplus.com`
- Temporary production host until DNS is fully live: `https://flowmint.cargoflowplus.com`

## Minimum onboarding checklist

1. confirm customer scope
   - `tenant_id`
   - `consumer_id`
   - production vs sandbox usage
   - polling only, or polling + webhooks

2. issue a consumer token
   - create one token per customer environment
   - recommended split:
     - production token
     - staging or sandbox token

3. register webhook target if needed
   - endpoint URL
   - signing secret
   - event filters:
     - `container.updated`
     - `container.completed`

4. send the customer launch pack
   - base URL
   - bearer token
   - first curl example
   - webhook signing note
   - one sample container for demo

## Internal admin flow

Issue a consumer token through the internal admin API:

```bash
curl -sS -X POST "https://flowmint.cargoflowplus.com/api/v1/admin/consumer-tokens" \
  -H "X-FlowMint-Internal-Token: <internal-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "token_id": "TOKEN-CUSTOMER-PROD-1",
    "tenant_id": "tenant-customer",
    "consumer_id": "customer-prod"
  }'
```

Register a webhook target through the public subscription API:

```bash
curl -sS -X POST "https://flowmint.cargoflowplus.com/api/v1/subscriptions/webhooks" \
  -H "Authorization: Bearer <consumer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://client.example.com/webhooks/flowmint",
    "signing_secret": "replace-me-with-a-random-secret",
    "event_filters": ["container.updated", "container.completed"]
  }'
```

## Customer launch pack

Send the customer exactly these items:

- Base URL  
  `https://flowmint.cargoflowplus.com`

- Bearer token  
  `Authorization: Bearer <consumer-token>`

- Track endpoint  
  `POST /api/v1/containers/track`

- Current endpoint  
  `GET /api/v1/containers/{container_number}`

- Timeline endpoint  
  `GET /api/v1/containers/{container_number}/timeline`

- Optional webhook endpoint  
  `POST /api/v1/subscriptions/webhooks`

- Docs  
  `https://flowmint.cargoflowplus.com/api/v1/containers/docs/containers`

- Demo  
  `https://flowmint.cargoflowplus.com/api/v1/containers/view/page`

## Recommended first example

Track a container:

```bash
curl -sS -X POST "https://flowmint.cargoflowplus.com/api/v1/containers/track" \
  -H "Authorization: Bearer <consumer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "container_number": "TXGU7408862"
  }'
```

Typical response:

```json
{
  "tracking_id": "WATCH-CONTAINER-20260413-ABC123",
  "container_number": "TXGU7408862",
  "status": "tracking",
  "created": true,
  "poll_interval_minutes": 360,
  "next_run_at": "2026-04-13T10:15:00Z",
  "source_hint": null,
  "carrier_scac": null,
  "status_url": "/api/v1/containers/TXGU7408862",
  "timeline_url": "/api/v1/containers/TXGU7408862/timeline"
}
```

## Webhook guidance

- Use a distinct `signing_secret` per customer endpoint
- Start with `container.updated`
- Add `container.completed` when the customer needs closeout events
- Treat the webhook as a notification to re-read the normalized resource when needed

## Support notes

- `port_code` is optional in normal customer flow
- Customers should only send `port_code` when they intentionally want to override route context
- If a source returns no data, FlowMint may continue through the source route automatically