SAT Codes API

GET https://ship.flashamericas.com/api/v1/sat-code/lookup/en/plastic
Authorization: Bearer YOUR_API_KEY
Accept: application/json

# Search in English
curl -X GET "https://ship.flashamericas.com/api/v1/sat-code/lookup/en/plastic" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

# Search in Spanish
curl -X GET "https://ship.flashamericas.com/api/v1/sat-code/lookup/es/plastico" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

# Search auto parts
curl -X GET "https://ship.flashamericas.com/api/v1/sat-code/lookup/en/auto%20parts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"

{
"success": true,
"data": [
  {
    "sat_code": "24121807",
    "description_es": "Plásticos en formas primarias",
    "description_en": "Plastics in primary forms",
    "category": "Productos químicos",
    "subcategory": "Resinas y compuestos plásticos"
  },
  {
    "sat_code": "24121808",
    "description_es": "Productos de plástico para construcción",
    "description_en": "Plastic construction products", 
    "category": "Materiales de construcción",
    "subcategory": "Productos plásticos"
  },
  {
    "sat_code": "24121809", 
    "description_es": "Envases y embalajes de plástico",
    "description_en": "Plastic containers and packaging",
    "category": "Envases y embalajes",
    "subcategory": "Productos plásticos"
  }
],
"total": 3,
"search_term": "plastic",
"language": "en"
}

async function searchSatCodes(searchTerm, language = 'en') {
if (searchTerm.length < 3) return [];

const response = await fetch(
  `https://ship.flashamericas.com/api/v1/sat-code/lookup/${language}/${encodeURIComponent(searchTerm)}`,
  {
    headers: {
      'Authorization': 'Bearer your-api-key',
      'Accept': 'application/json'
    }
  }
);

if (!response.ok) {
  throw new Error(`SAT code search failed: ${response.status}`);
}

const data = await response.json();

return data.data.map(item => ({
  code: item.sat_code,
  label: `${item.sat_code} - ${item.description_en}`,
  description: {
    en: item.description_en,
    es: item.description_es
  },
  category: item.category,
  subcategory: item.subcategory
}));
}

// Usage in form
document.getElementById('productSearch').addEventListener('input', async (e) => {
const query = e.target.value;
if (query.length >= 3) {
  try {
    const codes = await searchSatCodes(query);
    displaySatCodeSuggestions(codes);
  } catch (error) {
    console.error('SAT code search error:', error);
  }
}
});

function displaySatCodeSuggestions(codes) {
const dropdown = document.getElementById('satCodeDropdown');
dropdown.innerHTML = codes.map(code => 
  `<div class="sat-code-option" data-code="${code.code}">
    <strong>${code.code}</strong> - ${code.description.en}
    <br><small>${code.category} → ${code.subcategory}</small>
  </div>`
).join('');
}

async function getQuoteWithSatCode(quoteRequest, productDescription) {
// First, find appropriate SAT code
const satCodes = await searchSatCodes(productDescription);

if (satCodes.length === 0) {
  throw new Error('No SAT code found for product description');
}

// Use the first matching SAT code
const selectedSatCode = satCodes[0].code;

// Add SAT code to cargo items for Mexico shipments
const enhancedRequest = {
  ...quoteRequest,
  cargo: quoteRequest.cargo.map(item => ({
    ...item,
    satCode: selectedSatCode,
    satDescription: satCodes[0].description.es
  }))
};

// Get quote with SAT code included
const response = await fetch('https://ship.flashamericas.com/api/v1/quote', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    ...enhancedRequest,
    returnJson: true
  })
});

return response.json();
}

// Usage for cross-border shipment
const quote = await getQuoteWithSatCode({
originAddress: {
  city: "Dallas",
  state: "TX",
  postalCode: "75201",
  country: "US"
},
destinationAddress: {
  city: "Mexico City",
  state: "CDMX", 
  postalCode: "09300",
  country: "MX"
},
cargo: [{
  weight: 10,
  length: 12,
  width: 8,
  height: 6,
  quantity: 1,
  description: "Electronic components",
  value: 500
}]
}, "electronic components");

class SatCodeSelector {
constructor(containerId, options = {}) {
  this.container = document.getElementById(containerId);
  this.language = options.language || 'en';
  this.onSelect = options.onSelect || (() => {});
  this.apiKey = options.apiKey;
  
  this.init();
}

init() {
  this.container.innerHTML = `
    <div class="sat-code-selector">
      <div class="language-toggle">
        <button class="lang-btn ${this.language === 'en' ? 'active' : ''}" data-lang="en">English</button>
        <button class="lang-btn ${this.language === 'es' ? 'active' : ''}" data-lang="es">Español</button>
      </div>
      <input type="text" class="sat-search-input" 
             placeholder="${this.language === 'en' ? 'Search for product...' : 'Buscar producto...'}" />
      <div class="sat-results"></div>
      <div class="selected-sat-code" style="display: none;">
        <strong>Selected:</strong> <span class="selected-code"></span> - <span class="selected-desc"></span>
      </div>
    </div>
  `;
  
  this.bindEvents();
}

bindEvents() {
  // Language toggle
  this.container.querySelectorAll('.lang-btn').forEach(btn => {
    btn.addEventListener('click', (e) => {
      this.language = e.target.dataset.lang;
      this.container.querySelectorAll('.lang-btn').forEach(b => b.classList.remove('active'));
      e.target.classList.add('active');
      this.updatePlaceholder();
    });
  });
  
  // Search input
  const input = this.container.querySelector('.sat-search-input');
  let searchTimeout;
  
  input.addEventListener('input', (e) => {
    clearTimeout(searchTimeout);
    searchTimeout = setTimeout(() => {
      this.performSearch(e.target.value);
    }, 300);
  });
}

updatePlaceholder() {
  const input = this.container.querySelector('.sat-search-input');
  input.placeholder = this.language === 'en' ? 'Search for product...' : 'Buscar producto...';
}

async performSearch(query) {
  if (query.length < 3) {
    this.clearResults();
    return;
  }
  
  try {
    const response = await fetch(
      `https://ship.flashamericas.com/api/v1/sat-code/lookup/${this.language}/${encodeURIComponent(query)}`,
      {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Accept': 'application/json'
        }
      }
    );
    
    if (response.ok) {
      const data = await response.json();
      this.displayResults(data.data);
    }
  } catch (error) {
    console.error('SAT code search failed:', error);
  }
}

displayResults(codes) {
  const resultsContainer = this.container.querySelector('.sat-results');
  
  if (codes.length === 0) {
    resultsContainer.innerHTML = `<div class="no-results">${this.language === 'en' ? 'No codes found' : 'No se encontraron códigos'}</div>`;
    return;
  }
  
  resultsContainer.innerHTML = codes.map(code => `
    <div class="sat-result-item" data-code="${code.sat_code}">
      <div class="sat-code">${code.sat_code}</div>
      <div class="sat-description">${this.language === 'en' ? code.description_en : code.description_es}</div>
      <div class="sat-category">${code.category} → ${code.subcategory}</div>
    </div>
  `).join('');
  
  // Bind click events
  resultsContainer.querySelectorAll('.sat-result-item').forEach(item => {
    item.addEventListener('click', () => {
      const code = codes.find(c => c.sat_code === item.dataset.code);
      this.selectCode(code);
    });
  });
}

selectCode(code) {
  // Update UI
  const selectedContainer = this.container.querySelector('.selected-sat-code');
  const codeSpan = this.container.querySelector('.selected-code');
  const descSpan = this.container.querySelector('.selected-desc');
  
  codeSpan.textContent = code.sat_code;
  descSpan.textContent = this.language === 'en' ? code.description_en : code.description_es;
  selectedContainer.style.display = 'block';
  
  // Clear search
  this.container.querySelector('.sat-search-input').value = '';
  this.clearResults();
  
  // Callback
  this.onSelect(code);
}

clearResults() {
  this.container.querySelector('.sat-results').innerHTML = '';
}
}

// Usage
const satSelector = new SatCodeSelector('sat-code-container', {
language: 'en',
apiKey: 'your-api-key',
onSelect: (code) => {
  console.log('Selected SAT code:', code);
  // Update your form or shipping data
}
});

// Use specific product terms
const goodSearches = [
"electronic components",
"plastic containers", 
"automotive parts",
"textile materials"
];

// Avoid generic terms
const poorSearches = [
"stuff",
"things",
"products",
"items"
];

// Search strategy
async function intelligentSatSearch(productDescription) {
// Try exact description first
let results = await searchSatCodes(productDescription);

// If no results, try key words
if (results.length === 0) {
  const keywords = productDescription.split(' ').filter(word => word.length > 3);
  for (const keyword of keywords) {
    results = await searchSatCodes(keyword);
    if (results.length > 0) break;
  }
}

// If still no results, try broader categories
if (results.length === 0) {
  const categories = extractProductCategory(productDescription);
  results = await searchSatCodes(categories);
}

return results;
}

class SatCodeCache {
constructor(maxAge = 24 * 60 * 60 * 1000) { // 24 hours
  this.cache = new Map();
  this.maxAge = maxAge;
}

getCacheKey(language, searchTerm) {
  return `${language}:${searchTerm.toLowerCase()}`;
}

get(language, searchTerm) {
  const key = this.getCacheKey(language, searchTerm);
  const cached = this.cache.get(key);
  
  if (cached && Date.now() - cached.timestamp < this.maxAge) {
    return cached.data;
  }
  
  return null;
}

set(language, searchTerm, data) {
  const key = this.getCacheKey(language, searchTerm);
  this.cache.set(key, {
    data,
    timestamp: Date.now()
  });
}

async searchWithCache(language, searchTerm) {
  // Check cache first
  const cached = this.get(language, searchTerm);
  if (cached) return cached;
  
  // Fetch from API
  const results = await searchSatCodes(searchTerm, language);
  
  // Cache results
  this.set(language, searchTerm, results);
  
  return results;
}
}

const satCache = new SatCodeCache();

async function safeSatCodeLookup(searchTerm, language = 'en') {
try {
  // Validate input
  if (!searchTerm || searchTerm.length < 3) {
    throw new Error('Search term must be at least 3 characters');
  }
  
  if (!['en', 'es'].includes(language)) {
    throw new Error('Language must be "en" or "es"');
  }
  
  const response = await fetch(
    `https://ship.flashamericas.com/api/v1/sat-code/lookup/${language}/${encodeURIComponent(searchTerm)}`,
    {
      headers: {
        'Authorization': 'Bearer your-api-key',
        'Accept': 'application/json'
      },
      timeout: 10000 // 10 second timeout
    }
  );
  
  if (!response.ok) {
    if (response.status === 401) {
      throw new Error('Invalid API key');
    } else if (response.status === 429) {
      throw new Error('Rate limit exceeded. Please try again later.');
    } else {
      throw new Error(`API error: ${response.status}`);
    }
  }
  
  const data = await response.json();
  return data.data || [];
  
} catch (error) {
  console.error('SAT code lookup failed:', error);
  
  // Return fallback or cached results if available
  const fallback = getFallbackSatCodes(searchTerm);
  if (fallback.length > 0) {
    console.warn('Using fallback SAT codes');
    return fallback;
  }
  
  throw error;
}
}

{
"success": true,
"data": [],
"message": "Search term must be at least 3 characters",
"total": 0
}

{
"success": false,
"error": "Invalid language code. Use 'en' or 'es'"
}