API Reference

The Flash Americas API provides comprehensive freight management capabilities through a RESTful interface. This reference covers all available endpoints, request/response formats, and integration patterns.

Base URL

All API requests should be made to:

[object Object]

Authentication

All requests require authentication via API key in the Authorization header:

[object Object]

Request Format

Content Type: application/json
Method: HTTP methods (GET, POST, PUT, DELETE)
Headers: Include authentication and content type

Response Format

All API responses follow a consistent structure:

{
"success": true,
"data": {
  // Response payload
},
"error": null,
"meta": {
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "1.0.0"
}
}

Error Response Format

{
"success": false,
"data": null,
"error": {
  "code": "ERROR_CODE",
  "message": "Human readable error message",
  "details": {
    // Additional error context
  }
},
"meta": {
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00Z"
}
}

Core Resources

Quotes

Get shipping rates and service options for cargo between addresses.

Endpoint	Method	Description
`/quote`	POST	Create a new rate quote

Note: Quote retrieval and booking are handled through the quote response data

Addresses & Locations

Validate addresses and search for locations by ZIP code or city.

Endpoint	Method	Description
`/address/validate`	POST	Validate and correct addresses
`/location/search/{location}`	GET	Search locations by ZIP code or city
`/location/search/{country}/{location}`	GET	Search locations within specific country

SAT Codes

Mexican tax classification codes for cross-border shipping.

Endpoint	Method	Description
`/sat-code/lookup/{language}/{value}`	GET	Search SAT codes for products

Helper Endpoints

Additional utilities for shipping integration.

Endpoint	Method	Description
`/help`	GET	API documentation and status

Note: This API focuses on quote generation and location services. For advanced shipment management, tracking, and document access, contact support about additional API capabilities.

Common Parameters

Address Object

{
"address1": "123 Main Street",
"address2": "Suite 100",
"city": "Dallas",
"state": "TX",
"postalCode": "75201",
"country": "US",
"companyName": "Acme Corp",
"contactName": "John Smith",
"phone": "214-555-0123",
"email": "john@acme.com"
}

Cargo Object

{
"weight": 25.5,
"length": 18,
"width": 12,
"height": 10,
"quantity": 1,
"description": "Electronics",
"value": 1500.00,
"currency": "USD",
"hazmat": false,
"nmfcCode": "50",
"freightClass": "65"
}

Pagination

List endpoints support pagination via query parameters:

GET /shipments?page=1&limit=25&sort=createdAt&order=desc

Response includes pagination metadata:

{
"success": true,
"data": [...],
"meta": {
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 150,
    "pages": 6,
    "hasNext": true,
    "hasPrev": false
  }
}
}

Filtering and Sorting

Common Filters

Most list endpoints support filtering:

# Filter by date range
GET /shipments?createdAfter=2025-01-01&createdBefore=2025-01-31

# Filter by status
GET /shipments?status=IN_TRANSIT

# Filter by provider
GET /shipments?provider=FEDEX

# Search by tracking number
GET /shipments?trackingNumber=1234567890

Sorting Options

# Sort by creation date (newest first)
GET /shipments?sort=createdAt&order=desc

# Sort by total cost (lowest first) 
GET /shipments?sort=totalCost&order=asc

# Sort by delivery date
GET /shipments?sort=deliveryDate&order=asc

Rate Limiting

API requests are rate limited based on your plan:

Plan	Requests per Minute
Sandbox	100
Production Basic	1,000
Production Premium	5,000
Enterprise	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200
X-RateLimit-Window: 60

Status Codes

The API uses standard HTTP status codes:

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
429	Rate Limit Exceeded
500	Internal Server Error
503	Service Unavailable

Error Codes

Common error codes and their meanings:

Code	Description
`AUTHENTICATION_ERROR`	Invalid or missing API key
`INVALID_REQUEST`	Malformed request payload
`INVALID_ADDRESS`	Address validation failed
`RATE_LIMIT_ERROR`	Too many requests
`PROVIDER_ERROR`	Carrier service unavailable
`SHIPMENT_NOT_FOUND`	Shipment does not exist
`INSUFFICIENT_FUNDS`	Account balance too low

Webhooks

Configure webhooks to receive real-time notifications:

Event Types

{
"shipment.created": "Shipment was booked",
"shipment.picked_up": "Shipment was picked up",
"shipment.in_transit": "Shipment is in transit",
"shipment.delivered": "Shipment was delivered", 
"shipment.exception": "Delivery exception occurred",
"shipment.cancelled": "Shipment was cancelled"
}

Webhook Payload

{
"eventId": "550e8400-e29b-41d4-a716-446655440000",
"eventType": "shipment.delivered",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "trackingNumber": "1234567890",
  "status": "DELIVERED",
  "deliveredAt": "2025-01-15T10:00:00Z",
  "location": {
    "city": "Houston",
    "state": "TX",
    "country": "US"
  }
},
"signature": "sha256=abc123..."
}

SDK Examples

Node.js/TypeScript

import { FlashAmericasAPI } from '@flash-americas/api';

const api = new FlashAmericasAPI({
apiKey: process.env.FLASH_AMERICAS_API_KEY,
environment: 'production' // or 'sandbox'
});

// Get quotes
const quotes = await api.quotes.create({
originAddress: { city: 'Dallas', state: 'TX', country: 'US' },
destinationAddress: { city: 'Houston', state: 'TX', country: 'US' },
cargo: [{ weight: 25, length: 18, width: 12, height: 10 }]
});

// Book shipment
const shipment = await api.shipments.create({
quoteId: quotes.data.quoteId,
selectedRate: quotes.data.rates[0],
shipperInfo: { /* ... */ },
consigneeInfo: { /* ... */ }
});

Python

from flash_americas import FlashAmericasAPI

api = FlashAmericasAPI(
  api_key=os.getenv('FLASH_AMERICAS_API_KEY'),
  environment='production'
)

# Get quotes
quotes = api.quotes.create({
  'originAddress': {'city': 'Dallas', 'state': 'TX', 'country': 'US'},
  'destinationAddress': {'city': 'Houston', 'state': 'TX', 'country': 'US'},
  'cargo': [{'weight': 25, 'length': 18, 'width': 12, 'height': 10}]
})

# Book shipment
shipment = api.shipments.create({
  'quoteId': quotes['data']['quoteId'],
  'selectedRate': quotes['data']['rates'][0],
  'shipperInfo': {},
  'consigneeInfo': {}
})

Environment URLs

Environment	URL
Production	`https://ship.flashamericas.com/api/v1`
Sandbox	Contact support for sandbox credentials

API Versioning

Current Version: v1.0
Version Header: X-API-Version: 1.0
Deprecation: 12 months notice for breaking changes
Migration: Detailed upgrade guides provided

Support

For API support and questions:

Documentation: Continue reading detailed endpoint guides
Examples: Check our code examples
Support: Contact support@flashamericas.com
Status: Monitor status.flashamericas.com

Next Steps

Explore specific endpoint documentation:

Quotes API - Get shipping rates
Shipments API - Manage shipments
Tracking API - Track packages
Documents API - Access documents
Webhooks Guide - Real-time notifications