{"openapi":"3.0.3","info":{"title":"Smart Sends Express API","version":"1.0.0","description":"API pública de Smart Sends Express para integraciones con VTEX, Shopify, WooCommerce y desarrollos propios. Permite cotizar, crear envíos, rastrear paquetes y recibir webhooks.","contact":{"name":"Smart Sends Express","url":"https://smartsendsllc.com/app","email":"dev@smartsendsllc.com"}},"servers":[{"url":"https://smartsendsllc.com/app/api/v1","description":"Producción"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key con prefijo ss_live_. Obtén una desde tu dashboard en /dashboard/developers"}},"headers":{"X-RateLimit-Limit":{"description":"Límite máximo de solicitudes por minuto","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana actual","schema":{"type":"integer","example":55}},"X-RateLimit-Reset":{"description":"Timestamp Unix cuando se renueva la ventana","schema":{"type":"integer","example":1711036800}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Campo 'origin.city' requerido"}}}}},"Address":{"type":"object","required":["city","country"],"properties":{"name":{"type":"string","example":"Juan Pérez"},"phone":{"type":"string","example":"3001234567"},"email":{"type":"string","format":"email"},"address":{"type":"string","example":"Cra 76 #29-32"},"city":{"type":"string","example":"Medellin"},"state":{"type":"string","example":"Antioquia"},"country":{"type":"string","example":"CO"},"postal_code":{"type":"string","example":"050001"}}},"Package":{"type":"object","required":["weight_kg"],"properties":{"weight_kg":{"type":"number","example":2.5},"length_cm":{"type":"number","example":30},"width_cm":{"type":"number","example":20},"height_cm":{"type":"number","example":15},"content":{"type":"string","example":"Ropa"},"declared_value":{"type":"number","example":50000}}},"Quote":{"type":"object","properties":{"id":{"type":"string","example":"quote_a1b2c3d4e5f6"},"carrier":{"type":"string","example":"TCC"},"service":{"type":"string","example":"TCC Mensajeria"},"service_type":{"type":"string","example":"courier_nacional"},"price":{"type":"number","example":29718},"currency":{"type":"string","example":"COP"},"estimated_days":{"type":"string","example":"1-2 días"}}},"Shipment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tracking_number":{"type":"string","example":"SSE-A1B2C3D4"},"status":{"type":"string","enum":["creado","recolectado","en_transito","en_destino","entregado","cancelado"]},"service_type":{"type":"string"},"price":{"type":"number"},"origin_city":{"type":"string"},"dest_city":{"type":"string"},"weight_kg":{"type":"number"},"created_at":{"type":"string","format":"date-time"}}},"TrackingEvent":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"description":{"type":"string"},"location":{"type":"string"},"status":{"type":"string"}}},"WebhookPayload":{"type":"object","properties":{"event":{"type":"string","enum":["shipment.created","shipment.shipped","shipment.in_transit","shipment.delivered","shipment.cancelled","shipment.exception"]},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Shipment"}}}}},"paths":{"/quotes":{"post":{"summary":"Cotizar envío","tags":["Cotizaciones"],"operationId":"getQuotes","description":"Obtén cotizaciones de múltiples carriers (DHL, FedEx, TCC, Coordinadora, ServiEntrega, etc.) para un envío.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["origin","destination","package"],"properties":{"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"package":{"$ref":"#/components/schemas/Package"},"declared_value":{"type":"number","example":50000}}}}}},"responses":{"200":{"description":"Lista de cotizaciones","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}},"meta":{"type":"object"}}}}}},"401":{"description":"API key inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit excedido"}}}},"/shipments":{"get":{"summary":"Listar envíos","tags":["Envíos"],"operationId":"listShipments","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista paginada de envíos"}}},"post":{"summary":"Crear envío","tags":["Envíos"],"operationId":"createShipment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service_type","origin","destination","package"],"properties":{"service_type":{"type":"string","example":"courier_nacional"},"carrier_account":{"type":"string","example":"envia:tcc"},"origin":{"$ref":"#/components/schemas/Address"},"destination":{"$ref":"#/components/schemas/Address"},"package":{"$ref":"#/components/schemas/Package"}}}}}},"responses":{"201":{"description":"Envío creado"},"400":{"description":"Error de validación"}}}},"/shipments/{id}":{"get":{"summary":"Obtener envío","tags":["Envíos"],"operationId":"getShipment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Detalle del envío"},"404":{"description":"No encontrado"}}}},"/shipments/{id}/label":{"get":{"summary":"Descargar guía PDF","tags":["Envíos"],"operationId":"downloadLabel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF de la guía","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Guía no disponible"}}}},"/shipments/{id}/cancel":{"post":{"summary":"Cancelar envío","tags":["Envíos"],"operationId":"cancelShipment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Envío cancelado con reembolso"},"400":{"description":"No se puede cancelar"}}}},"/tracking/{number}":{"get":{"summary":"Rastrear envío","tags":["Rastreo"],"operationId":"trackShipment","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"},"description":"Número de guía"}],"responses":{"200":{"description":"Datos de rastreo","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"tracking":{"type":"object","properties":{"tracking_number":{"type":"string"},"status":{"type":"string"},"carrier":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"}},"estimated_delivery":{"type":"string"}}}}}}}},"404":{"description":"No encontrado"}}}},"/addresses/validate":{"post":{"summary":"Validar dirección","tags":["Direcciones"],"operationId":"validateAddress","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["city","country"],"properties":{"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Resultado de validación"}}}},"/webhooks":{"get":{"summary":"Obtener configuración de webhook","tags":["Webhooks"],"operationId":"getWebhook","responses":{"200":{"description":"Configuración actual del webhook"}}},"put":{"summary":"Configurar webhook","tags":["Webhooks"],"operationId":"updateWebhook","description":"Configura la URL donde recibirás notificaciones cuando cambie el estado de un envío. Se firma cada request con HMAC-SHA256 usando el webhook secret.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://mi-tienda.com/webhooks/smartsends"},"events":{"type":"array","items":{"type":"string","enum":["shipment.created","shipment.shipped","shipment.in_transit","shipment.delivered","shipment.cancelled","shipment.exception"]}}}}}}},"responses":{"200":{"description":"Webhook configurado"}}}}},"x-webhooks":{"shipmentStatusChange":{"post":{"summary":"Webhook: Cambio de estado","description":"Se envía a tu URL configurada cada vez que un envío cambia de estado. Verifica la firma HMAC-SHA256 del header X-SmartSends-Signature.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}}}}}}