{"openapi":"3.0.1","info":{"title":"Skydropx API","version":"v1","description":"# Primeros pasos\n\n**¡Te damos la bienvenida a nuestra documentación API!**\n\nCrea envíos y órdenes a través de la API y automatiza los procesos repetitivos de tu logística con nuestras funcionalidades.\n\n## Credenciales\n\nSimplifica tu integración, elige el ambiente y empieza a usar nuestra API en minutos…\n\n- [Sandbox](https://sb-pro.skydropx.com/merchant_stores/applications)\n- [Producción](https://pro.skydropx.com/merchant_stores/applications)\n\n**1. Encuentra tus credenciales**\n\n- Ve a Conexiones > API y copia tus credenciales (Client ID y Client Secret).\n\n**2. Genera tu bearer token**\n\n- Utiliza las credenciales y genera el bearer token para autenticar tus solicitudes\n\n**3. Empieza a llamar a la API**\n\n- Con tu token listo podrás hacer solicitudes a la API.\n\n> [!note]\n> El token expira en 2 horas y permite hasta 2 solicitudes por segundo. Asegúrate de usar el host correcto: api-pro.skydropx.com.\n\n¿Necesitas ayuda con tu integración? Escríbenos a [api@skydropx.com](mailto:api@skydropx.com)\n\n## Guía rápida: crea un envío\n\n**1. Crea una cotización**\n\n- Envía una solicitud POST a /api/v1/quotations para obtener opciones de precio, servicio y paquetería (carrier).\n\n**2. Consulta la cotización y elige un rate**\n\n- Usa GET en /api/v1/quotations/:id para consultar las opciones disponibles.\n- Importante: revisa que el campo is_completed cambie a true para asegurarte de que la cotización terminó de cargar todas las tarifas.\n- Selecciona y copia el rate_id de la opción que prefieras.\n\n> [!note]\n> Los rates son válidos por 24 horas.\n\n**3. Crea el envío**\n\n- Envía una solicitud POST a /api/v1/shipments incluyendo el rate_id seleccionado.\n- Asegúrate de ingresar correctamente el nombre o código de la paquetería (carrier_name).\n- Ingresa los códigos de Carta Porte obligatorios (consignment_note y package_type).\n\nAsegúrate de ingresar correctamente el nombre o código de la paquetería (\"carrier_name\"), así como los códigos de Carta Porte (\"consignment_note\"; \"package_type\") cuando sean requeridos. [Consultar lista de códigos](https://help.skydropx.com/subcategorias-cda/api).\n\n## Guía rápida: crea un envío internacional\n\nLos pasos para crear una guía internacional son muy similares, pero hay algunas diferencias que debes tener en cuenta. Si necesitas más información sobre los valores que deben incluirse en cada parámetro, visita la documentación de cada endpoint.\n\n**1. Crea una cotización internacional**\n\n- Envía una solicitud POST a /api/v1/quotations para obtener opciones de precio, servicio y paquetería (carrier).\n- Las cotizaciones internacionales requieren el parámetro adicional products para calcular los aranceles de tu envío.\n- Asegúrate de elegir países válidos para tu cotización. Actualmente, solo soportamos envíos internacionales con origen México y los siguientes países como destino: Canadá, China, Colombia, España, EE. UU., Francia y Reino Unido.\n\n**2. Consulta la cotización y elige una tarifa (rate)**\n\n- Usa GET en /api/v1/quotations/:id para ver las tarifas (rates) disponibles.\n- Notarás que estas incluyen el campo import_duty_amount. Este valor representa los aranceles de dicha tarifa y no está incluido en el total de la misma.\n- Elige y copia el rate_id de la opción que prefieras (combinación de precio, servicio y paquetería).\n\n**3. Crea el envío**\n\n- Envía una solicitud POST a /api/v1/shipments con el rate_id seleccionado para generar el envío.\n- Agrega el parámetro customs_payment_payer para definir quién pagará los aranceles (SENDER para ti o RECIPIENT para el destinatario). Si decides pagarlos tú, se descontarán de tus créditos junto con el total de la tarifa.\n- Especifica el propósito del envío en el campo shipment_purpose.\n- Incluye el parámetro products con la información detallada de cada artículo: price (precio unitario), hs_code (código arancelario), hs_code_description (descripción del código) y country_code (país de fabricación en formato ISO).\n- ¿Necesitas la lista de códigos arancelarios? Puedes solicitar el listado completo enviando un correo a api@skydropx.com.\n\n## Guía rápida: crea un envío con múltiples paquetes\n\nLos pasos para crear un envío con múltiples paquetes son muy similares a un envío estándar, pero hay algunas diferencias que debes tener en cuenta. Si necesitas más información sobre los valores que deben incluirse en cada parámetro, visita la documentación de cada endpoint.\n\n**1. Crea una cotización multipaquete**\n\n- Envía una solicitud POST a /api/v1/quotations para obtener opciones de precio, servicio y paquetería (carrier).\n- Las cotizaciones multipaquete requieren el parámetro adicional parcels con el arreglo de las dimensiones y pesos de cada paquete.\n\n**2. Consulta la cotización y elige un rate**\n\n- Usa GET en /api/v1/quotations/:id para ver las tarifas (rates) disponibles y copia el rate_id seleccionado.\n\n**Importante:** revisa el campo **shipment_creation_type** de la tarifa elegida. **multipackage** genera un solo envío con múltiples paquetes (una sola guía máster). **multishipment** genera varios envíos independientes (una guía por cada paquete). **single** solo aplica cuando la cotización fue de un único paquete.\n\n**3. Crea el envío**\n\n- Envía una solicitud POST a /api/v1/shipments incluyendo el rate_id seleccionado.\n- Coincidencia de paquetes (package_number): cada paquete del arreglo debe llevar su package_number (por ejemplo \"1\", \"2\"). La cantidad total de paquetes declarados debe coincidir con la cantidad incluida en la cotización original.\n\n## Guía rápida: importar API a Postman\n\nAqui encontraras los pasos necesarios para importar todas las llamadas al API directamente a una coleccion de Postman.\n\n\n**1. Copia la URL de la colección**\n\n- Haz clic en el botón que se encuentra abajo para copiar la URL de la colección al portapapeles.\n- Esta URL contiene toda la especificación de nuestra API en formato OpenAPI compatible con Postman.\n\n**2. Abre Postman**\n\n- Inicia la aplicación de Postman en tu computadora.\n- Si no tienes Postman instalado, puedes descargarlo desde https://www.postman.com/downloads/\n\n**3. Importa la colección**\n\n- Haz clic en el botón \"Import\" en la parte superior izquierda de Postman.\n- Pega la URL que copiaste en el paso 1.\n- La importacion comenzará de forma automatica\n\n**4. ¡Listo para usar!**\n\n- Ahora puedes explorar y probar todos los endpoints de nuestra API directamente desde Postman.\n- Cada endpoint incluye ejemplos y documentación para facilitar su uso.\n\n[Copiar URL de la colección](https://pro.skydropx.com/es-MX/api-docs.json)"},"paths":{"/api/v1/address_templates":{"get":{"summary":"Recupera todas las direcciones","tags":["Direcciones"],"description":"```\n  GET /api/v1/address_templates\n```\n  Retorna una lista paginada de direcciones con sus direcciones asociadas y estados de verificación por paquetería.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","required":false,"description":"Número de página a obtener","schema":{"type":"integer","example":1}},{"name":"per_page","in":"query","required":false,"description":"Número de elementos por página (max 20, default 20)","schema":{"type":"integer","example":20}}],"responses":{"200":{"description":"Retorna una colección de direcciones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","example":"from"},"default":{"type":"boolean","nullable":true,"example":false},"address":{"type":"object","properties":{"name":{"type":"string","example":"Juan Perez"},"company":{"type":"string","nullable":true,"example":"Acme INC"},"street1":{"type":"string","example":"Insurgentes Sur 1234"},"street_number":{"type":"string","nullable":true,"example":"1234"},"apartment_number":{"type":"string","nullable":true},"postal_code":{"type":"string","example":"06600"},"area_level1":{"type":"string","example":"Ciudad de Mexico"},"area_level2":{"type":"string","example":"Cuauhtemoc"},"area_level3":{"type":"string","nullable":true,"example":"Juarez"},"country_code":{"type":"string","example":"MX"},"phone":{"type":"string","example":"5215555555555"},"email":{"type":"string","example":"juan@example.com"},"reference":{"type":"string","nullable":true,"example":"Cerca del parque"},"rfc":{"type":"string","nullable":true},"tax_id_number":{"type":"string","nullable":true},"tax_id_type":{"type":"string","nullable":true}}},"verified_carriers":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string","example":"interrapidisimo"},"status":{"type":"string","example":"verified"},"update_state":{"type":"string","nullable":true,"example":"pending_to_send"},"verification_id":{"type":"string","nullable":true,"example":"SUC-001"}}}}}}},"meta":{"type":"object","properties":{"total_count":{"type":"integer","example":8},"per_page":{"type":"integer","example":20},"current_page":{"type":"integer","example":1},"total_pages":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true},"prev_page":{"type":"integer","nullable":true}}}}}}}}}}},"/api/v1/address_templates/{address_template_id}":{"get":{"summary":"Consulta dirección","tags":["Direcciones"],"description":"```\n  GET /api/v1/address_templates/{id}\n```\n  Consulta la información de una dirección guardada.\n","parameters":[{"name":"address_template_id","in":"path","description":"ID de la dirección","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna la dirección","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","example":"from"},"default":{"type":"boolean","nullable":true,"example":false},"address":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string","nullable":true},"street1":{"type":"string"},"street_number":{"type":"string","nullable":true},"apartment_number":{"type":"string","nullable":true},"postal_code":{"type":"string"},"area_level1":{"type":"string"},"area_level2":{"type":"string"},"area_level3":{"type":"string","nullable":true},"country_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"reference":{"type":"string","nullable":true},"rfc":{"type":"string","nullable":true},"tax_id_number":{"type":"string","nullable":true},"tax_id_type":{"type":"string","nullable":true}}},"verified_carriers":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string"},"status":{"type":"string"},"update_state":{"type":"string","nullable":true},"verification_id":{"type":"string","nullable":true}}}}}}}}}}},"404":{"description":"Dirección no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/api/v1/address_templates/":{"post":{"summary":"Crear dirección","tags":["Direcciones"],"description":"```\n  POST /api/v1/address_templates\n```\n  Guarda una nueva ubicación en tu libreta de direcciones.\n\n  **Parámetros de la solicitud:**\n","parameters":[],"responses":{"201":{"description":"Dirección creada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","example":"from"},"default":{"type":"boolean","nullable":true,"example":false},"address":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string","nullable":true},"street1":{"type":"string"},"street_number":{"type":"string","nullable":true},"apartment_number":{"type":"string","nullable":true},"postal_code":{"type":"string"},"area_level1":{"type":"string"},"area_level2":{"type":"string"},"area_level3":{"type":"string","nullable":true},"country_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"reference":{"type":"string","nullable":true},"rfc":{"type":"string","nullable":true},"tax_id_number":{"type":"string","nullable":true},"tax_id_type":{"type":"string","nullable":true}}},"verified_carriers":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string"},"status":{"type":"string"},"update_state":{"type":"string","nullable":true},"verification_id":{"type":"string","nullable":true}}}}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Dirección México (MX)","properties":{"address_template":{"type":"object","required":["alias_name","address_type","address_attributes"],"properties":{"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","enum":["from","to","both"],"example":"from"},"default":{"type":"boolean","example":false},"address_attributes":{"type":"object","required":["name","street1","phone","email","country_code","postal_code","area_level1","area_level2","area_level3","reference"],"properties":{"name":{"type":"string","example":"Juan Perez"},"company":{"type":"string","example":"Acme INC"},"street1":{"type":"string","example":"Insurgentes Sur 1234"},"street_number":{"type":"string","description":"Número de calle en un campo propio. En Brasil (BR) mándalo acá y no lo repitas en street1, que la DC-e declara aparte. En MX y CO el número suele viajar dentro de street1 y este campo queda vacío.","example":"1234"},"apartment_number":{"type":"string","example":"4B"},"postal_code":{"type":"string","example":"06600"},"area_level1":{"type":"string","example":"Ciudad de Mexico"},"area_level2":{"type":"string","example":"Cuauhtemoc"},"area_level3":{"type":"string","example":"Juarez"},"country_code":{"type":"string","example":"MX"},"phone":{"type":"string","example":"5215555555555"},"email":{"type":"string","example":"juan@example.com"},"reference":{"type":"string","example":"Cerca del parque"},"rfc":{"type":"string","example":"XAXX010101000"}}}}}}}]}}}}}},"/api/v1/address_templates/{id}":{"patch":{"summary":"Actualizar dirección","tags":["Direcciones"],"description":"```\n  PATCH /api/v1/address_templates/{id}\n```\n  Modifica la información de una dirección guardada.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"id","in":"path","description":"ID de la dirección","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dirección actualizada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","example":"from"},"default":{"type":"boolean","nullable":true,"example":false},"address":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string","nullable":true},"street1":{"type":"string"},"street_number":{"type":"string","nullable":true},"apartment_number":{"type":"string","nullable":true},"postal_code":{"type":"string"},"area_level1":{"type":"string"},"area_level2":{"type":"string"},"area_level3":{"type":"string","nullable":true},"country_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"reference":{"type":"string","nullable":true},"rfc":{"type":"string","nullable":true},"tax_id_number":{"type":"string","nullable":true},"tax_id_type":{"type":"string","nullable":true}}},"verified_carriers":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string"},"status":{"type":"string"},"update_state":{"type":"string","nullable":true},"verification_id":{"type":"string","nullable":true}}}}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Actualizar Dirección México (MX)","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la dirección"},"address_template":{"type":"object","properties":{"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","enum":["from","to","both"],"example":"from"},"default":{"type":"boolean","example":false},"address_attributes":{"type":"object","properties":{"name":{"type":"string","example":"Juan Perez"},"company":{"type":"string","example":"Acme INC"},"street1":{"type":"string","example":"Insurgentes Sur 1234"},"street_number":{"type":"string","description":"Número de calle en un campo propio. En Brasil (BR) mándalo acá y no lo repitas en street1, que la DC-e declara aparte. En MX y CO el número suele viajar dentro de street1 y este campo queda vacío.","example":"1234"},"apartment_number":{"type":"string","example":"4B"},"postal_code":{"type":"string","example":"06600"},"area_level1":{"type":"string","example":"Ciudad de Mexico"},"area_level2":{"type":"string","example":"Cuauhtemoc"},"area_level3":{"type":"string","example":"Juarez"},"country_code":{"type":"string","example":"MX"},"phone":{"type":"string","example":"5215555555555"},"email":{"type":"string","example":"juan@example.com"},"reference":{"type":"string","example":"Cerca del parque"},"rfc":{"type":"string","example":"XAXX010101000"}}}}}}}]}}}}}},"/api/v1/address_templates/{id}/":{"delete":{"summary":"Eliminar dirección","tags":["Direcciones"],"description":"```\n  DELETE /api/v1/address_templates/{id}\n```\n  Remueve permanentemente una dirección de tu cuenta.\n","parameters":[{"name":"id","in":"path","description":"ID de la dirección","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dirección eliminada"},"404":{"description":"Dirección no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/api/v1/address_templates/{address_template_id}/verify_by_carriers":{"post":{"summary":"Validar dirección","tags":["Direcciones"],"description":"```\n  POST /api/v1/address_templates/{address_template_id}/verify_by_carriers\n```\n  Valida si una dirección es apta para generar guías.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"address_template_id","in":"path","description":"ID de la dirección","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Solicitud de verificación aceptada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"alias_name":{"type":"string","example":"Bodega Principal"},"address_type":{"type":"string","example":"from"},"default":{"type":"boolean","nullable":true,"example":false},"address":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string","nullable":true},"street1":{"type":"string"},"street_number":{"type":"string","nullable":true},"apartment_number":{"type":"string","nullable":true},"postal_code":{"type":"string"},"area_level1":{"type":"string"},"area_level2":{"type":"string"},"area_level3":{"type":"string","nullable":true},"country_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"reference":{"type":"string","nullable":true},"rfc":{"type":"string","nullable":true},"tax_id_number":{"type":"string","nullable":true},"tax_id_type":{"type":"string","nullable":true}}},"verified_carriers":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string"},"status":{"type":"string"},"update_state":{"type":"string","nullable":true},"verification_id":{"type":"string","nullable":true}}}}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["carriers"],"properties":{"address_template_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la dirección"},"carriers":{"type":"array","items":{"type":"string"},"example":["interrapidisimo"],"description":"Arreglo de nombres de paqueterías a verificar"}}}}}}}},"/api/v1/oauth/token":{"post":{"summary":"Obtener un token de acceso","tags":["OAuth"],"description":"```\n   POST /api/v1/oauth/token\n```\n   Genera un token de acceso utilizando tus credenciales de autorización (client credentials) o un token de actualización (refresh token).\n\n   **Parámetros de la solicitud:**\n   - `grant_type`: El tipo de concesión utilizada, como `refresh_token` o `client_credentials`.\n   - `client_id`: El identificador del cliente.\n   - `client_secret`: La clave secreta del cliente.\n   - `refresh_token`: El token de actualización (para el tipo de concesión `refresh_token`).\n   - `redirect_uri`: La URI de redirección, debe ser la misma que la `redirect_uri` almacenada en la aplicación Cliente.\n   - `scope`:Los scopes limitan el acceso de los tokens de acceso a partes específicas de la API. Al solicitar un token de acceso, puedes especificar uno o más scopes.\n\n   **Ejemplo de solicitud:**\n```http\n   POST /api/v1/oauth/token\n   Content-Type: application/x-www-form-urlencoded\ngrant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET\n````\n","security":[],"parameters":[],"responses":{"200":{"description":"Obtener un token de acceso","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string"},"expires_in":{"type":"integer"},"scope":{"type":"string"},"created_at":{"type":"integer"}}}}}},"400":{"description":"Credenciales faltantes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"401":{"description":"Credenciales inválidas","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"grant_type":{"type":"string","default":"client_credentials"},"redirect_uri":{"type":"string","nullable":true,"default":"urn:ietf:wg:oauth:2.0:oob"},"refresh_token":{"type":"string","nullable":true},"scope":{"type":"string","nullable":true,"default":"default"}},"required":["client_id","client_secret","grant_type"]}}}}}},"/api/v1/oauth/revoke":{"post":{"summary":"Revocar un token","tags":["OAuth"],"description":"```\n   POST /api/v1/oauth/revoke\n```\n\n   El endpoint de revocación permite a los clientes notificar al servidor de autorización que un token de actualización o acceso previamente obtenido ya no es necesario.\n\n   **Parámetros de la solicitud:**\n   - `client_id`: El identificador del cliente.\n   - `client_secret`: La clave secreta del cliente.\n   - `token`: El token que el cliente desea revocar.\n   - `token_type_hint`: Una pista sobre el tipo de token enviado para revocación, por ejemplo, `access_token` o `refresh_token`.\n\n   **Ejemplo de solicitud:**\n```http\n   POST /api/v1/oauth/revoke\n   Content-Type: application/x-www-form-urlencoded\n\nclient_id=CLIENT_ID&client_secret=CLIENT_SECRET&token=TOKEN&token_type_hint=access_token\n```\n","security":[],"parameters":[],"responses":{"200":{"description":"Revocar un token","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"403":{"description":"Cliente no autorizado","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"token":{"type":"string"},"token_type_hint":{"type":"string","nullable":true}},"required":["client_id","client_secret","token"]}}}}}},"/api/v1/oauth/introspect":{"post":{"summary":"Obtener detalles del token","tags":["OAuth"],"description":"```\n   POST /api/v1/oauth/introspect\n```\n\n   El endpoint de introspección se utiliza para verificar el estado activo de un token de acceso o de actualización.\n\n   **Parámetros de la solicitud:**\n   - `client_id`: El identificador del cliente.\n   - `client_secret`: La clave secreta del cliente.\n   - `token`: El token del cual el cliente desea obtener detalles.\n   - `token_type_hint`: Una pista sobre el tipo de token enviado para introspección, por ejemplo, `access_token` o `refresh_token`.\n\n   **Ejemplo de solicitud:**\n```http\n   POST /api/v1/oauth/introspect\n   Content-Type: application/x-www-form-urlencoded\n\nclient_id=CLIENT_ID&client_secret=CLIENT_SECRET&token=TOKEN&token_type_hint=access_token\n```\n","security":[],"parameters":[],"responses":{"200":{"description":"Obtener detalles del token","content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"scope":{"type":"string"},"client_id":{"type":"string"},"token_type":{"type":"string"},"exp":{"type":"integer"},"iat":{"type":"integer"}}}}}},"400":{"description":"Credenciales faltantes","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}},"401":{"description":"Credenciales inválidas","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"token":{"type":"string"},"token_type_hint":{"type":"string","nullable":true}},"required":["client_id","client_secret","token"]}}}}}},"/api/v1/external_shipments/imports":{"post":{"summary":"Importación masiva de envíos externos","tags":["Envíos Externos"],"description":"Sube un archivo CSV o XLSX con hasta 500 filas describiendo envíos externos\n(tracking_number, carrier_name, valor declarado, producto) y encola la\nimportación batch asíncrona. Utiliza el `import_id` devuelto para consultar\nel estado mediante el endpoint de status. Archivos que excedan el tamaño\nconfigurado o las 500 filas son rechazados.\n","parameters":[],"responses":{"202":{"description":"Importación aceptada y encolada para procesamiento","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"import_id":{"type":"integer","example":42},"status":{"type":"string","enum":["uploaded","checked","processing","processed","completed","errored"],"example":"uploaded"}}}}}}}},"400":{"description":"Archivo inválido (faltante, formato incorrecto o demasiado grande)"}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"required":true,"description":"CSV or XLSX file containing the external shipments to import."}}},"/api/v1/external_shipments/imports/{id}":{"get":{"summary":"Consultar estado de importación","tags":["Envíos Externos"],"description":"Devuelve el estado actual y los contadores por fila de una importación masiva\ncreada previamente vía `POST /api/v1/external_shipments/imports`.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Estado de la importación","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"import_id":{"type":"integer","example":42},"status":{"type":"string","enum":["uploaded","checked","processing","processed","completed","errored"],"example":"uploaded"},"success_rows":{"type":"integer","nullable":true,"example":240},"unsuccess_rows":{"type":"integer","nullable":true,"example":10},"protected_shipments":{"type":"integer","nullable":true,"example":5},"error_file_url":{"type":"string","nullable":true,"example":"https://example.com/rails/active_storage/blobs/.../external_shipments_import_error.csv","description":"Signed URL to download the CSV with per-row error details. Present only when there are failed rows."}}}}}}}},"404":{"description":"Importación no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/api/v1/external_shipments":{"post":{"summary":"Registrar un envío externo","tags":["Envíos Externos"],"description":"Encola la importación de un envío externo (creado fuera de la app). Soporta dos flujos:\n(1) carrier global identificado por `carrier_name` — replica el flujo de \"Agregar envío\nexterno\" desde Mis envíos; (2) carrier de flota propia (Logística Propia) identificado\npor `carrier_custom_code`. Procesamiento asíncrono.\n","parameters":[],"responses":{"202":{"description":"Job de importación encolado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","example":"queued"},"shipment_id":{"type":"string","nullable":true,"example":"9eae25ba-11b4-4b9f-9b01-3d09da8bc12d"},"tracking_number":{"type":"string","nullable":true,"example":"1Z999AA10123456784"}}}}}}}},"400":{"description":"Faltan parámetros requeridos"},"422":{"description":"La paquetería no está disponible en tu cuenta"}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Envío externo","description":"Importa un envío gestionado por un carrier global ya integrado (DHL, FedEx, Estafeta, etc.). Identifica el carrier por su `carrier_name`. Disponible para todos los tenants.","required":["external_shipment"],"properties":{"external_shipment":{"type":"object","required":["tracking_number","carrier_name"],"properties":{"tracking_number":{"type":"string","example":"1Z999AA10123456784","description":"Número de rastreo del envío que se importará a tu cuenta."},"carrier_name":{"type":"string","example":"dhl","description":"Nombre del carrier global con el que se importará el envío (por ejemplo, `dhl`, `fedex`)."}}}}},{"type":"object","title":"Envío externo con Mi flota","description":"Registra un envío gestionado por tu flota propia (Logística Propia). Identifica el carrier por su `carrier_custom_code` y asocia el envío a una orden existente mediante `order_id` para heredar los datos del destinatario. Requiere flota propia activa en la cuenta.","required":["external_shipment"],"properties":{"external_shipment":{"type":"object","required":["tracking_number","carrier_custom_code"],"properties":{"tracking_number":{"type":"string","example":"TRK-MX-1234567890","description":"Número de rastreo del envío que se importará a tu cuenta."},"carrier_custom_code":{"type":"string","example":"mi_flota","description":"Código del carrier de tu flota propia (`name` definido al registrarlo)."},"order_id":{"type":"string","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una orden existente a la que se asociará el envío externo. Opcional pero recomendado para que el envío herede los datos del destinatario (`address_to`) de la orden y disparen las notificaciones de tracking. Sin `order_id` el envío queda solo como histórico, sin destinatario asociado."}}}}}]}}}}}},"/api/v1/finance/credits":{"get":{"summary":"Obtener créditos","tags":["Finanzas"],"description":"```\n   GET /api/v1/finance/credits\n```\n  Obtiene el saldo y la moneda de la cuenta actual.\n","responses":{"200":{"description":"Éxito","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balance":{"type":"number","description":"Saldo actual de la cuenta.","example":1500.5},"currency":{"type":"string","description":"Código de moneda (ej. MXN, USD).","example":"MXN"}}}}}}}}}}},"/api/v1/finance/extra-charges":{"get":{"summary":"Obtener cargos extra","tags":["Finanzas"],"description":"```\n   GET /api/v1/finance/extra-charges\n```\n  Devuelve una lista paginada de cargos extra asociados a la cuenta autenticada. Opcionalmente filtra por rango de fecha de detección.\n","parameters":[{"name":"page","in":"query","required":false,"description":"Page number (default: 1)","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"Items per page (max: 20, default: 20)","schema":{"type":"integer"}},{"name":"start_date","in":"query","required":false,"description":"Filter by detection_date from (e.g. 2026-01-01)","schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"description":"Filter by detection_date to (e.g. 2026-03-31)","schema":{"type":"string"}}],"responses":{"200":{"description":"Éxito","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"package_id":{"type":"string","description":"UUID del paquete del envío.","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"shipment_id":{"type":"string","description":"UUID del envío.","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"status":{"type":"string","description":"Estado de pago del cargo extra.","example":"pending_payment"},"carrier":{"type":"string","description":"Nombre del carrier.","example":"fedex"},"service":{"type":"string","nullable":true,"description":"Nombre del servicio del carrier.","example":"FedEx Ground"},"tracking_number":{"type":"string","description":"Número de rastreo del paquete.","example":"TRACK12345"},"label_date":{"type":"string","nullable":true,"description":"Fecha de creación de la guía del envío (ISO 8601).","example":"2026-02-26T00:00:00-06:00"},"detection_date":{"type":"string","nullable":true,"description":"Fecha en que se detectó el cargo extra (ISO 8601).","example":"2026-02-26T16:30:35-06:00"},"amount":{"type":"string","description":"Monto del cargo extra.","example":"15.50"},"charge_type":{"type":"string","description":"Tipo de cargo extra.","example":"ExtraCharge::Overweight"},"metadata":{"type":"object","description":"Metadatos adicionales relacionados al cargo. Puede estar vacío."}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":5},"total_count":{"type":"integer","example":95}}}}}}}}}}},"/api/v1/office_points":{"get":{"summary":"Obtener puntos de oficina para una tarifa","tags":["Puntos de oficina"],"description":"```\n   GET /api/v1/office_points\n```\n  Devuelve los puntos de oficina que un cliente puede usar para una tarifa cotizada, en la dirección solicitada. Los puntos de oficina están filtrados por cobertura y restricciones de la tarifa y ordenados del más cercano al destino. Usa el id de un punto de oficina como office_delivery_point_id u office_pickup_point_id al crear el envío.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"rate_id","in":"query","required":true,"description":"El ID único de la tarifa obtenido de la cotización (GET /api/v1/quotations/{id}).","schema":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}},{"name":"direction","in":"query","required":false,"description":"Dirección del punto de oficina — `delivery` (el destinatario recoge en la sucursal) o `pickup` (el remitente entrega en la sucursal). Por defecto `delivery`.","schema":{"type":"string","enum":["delivery","pickup"],"example":"delivery"}},{"name":"limit","in":"query","required":false,"description":"Número máximo de puntos de oficina a devolver (del más cercano primero). Por defecto 15.","schema":{"type":"integer","example":15}}],"responses":{"200":{"description":"Devuelve la lista de puntos de oficina aplicables","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID del punto de oficina. Úsalo como office_delivery_point_id u office_pickup_point_id al crear el envío.","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"type":{"type":"string","example":"office_point"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"Sucursal Centro","description":"Nombre del punto de oficina (sucursal)."},"carrier_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del paquetero dueño del punto de oficina."},"country_code":{"type":"string","example":"MX","description":"Código de país del punto de oficina (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal del punto de oficina."},"postal_code_label":{"type":"string","example":"C.P. 64000","description":"Etiqueta localizada del código postal."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento del punto de oficina."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio del punto de oficina."},"area_level3":{"type":"string","nullable":true,"example":"Centro","description":"Colonia o barrio del punto de oficina."},"street1":{"type":"string","example":"Av. Principal 123","description":"Calle y número del punto de oficina."},"street2":{"type":"string","nullable":true,"example":"Local 5","description":"Información adicional de la calle del punto de oficina."},"latitude":{"type":"number","example":25.6866,"description":"Latitud del punto de oficina."},"longitude":{"type":"number","example":-100.3161,"description":"Longitud del punto de oficina."},"short_address":{"type":"string","example":"Av. Principal 123, 64000 Monterrey, Nuevo León","description":"Dirección del punto de oficina en una sola línea."}}}}}},"meta":{"type":"object","properties":{"total":{"type":"integer","example":3}}}}}}}}}}},"/api/v1/orders":{"get":{"summary":"Recupera todas las órdenes","tags":["Ordenes"],"description":"```\n   GET /api/v1/orders\n```\n   El endpoint de órdenes sirve para recuperar todas las órdenes realizadas. Funciona como un historial.\n\n   **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","example":1},"description":"Número de página a recuperar"},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","example":20},"description":"Número de elementos por página (máximo 20, por defecto 20)"}],"responses":{"200":{"description":"Retorna una colección de pedidos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"The order uuid, example: 0ac5adcc-a13d-427d-81dd-9ddd70b2f660"},"type":{"type":"string","example":"order"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"The order uuid, example: 0ac5adcc-a13d-427d-81dd-9ddd70b2f660"},"reference":{"type":"string","nullable":true,"example":"188"},"platform":{"type":"string","example":"Wix","nullable":true},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"nullable":true},"ecommerce_id":{"type":"string","example":"12342","nullable":true},"price":{"type":"string","example":"44532","nullable":true},"shipping_preferences":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true,"properties":{"service":{"type":["string",null],"example":"me2"},"price":{"type":["string",null],"example":"100.00"}}}},"payment_type":{"type":"string","nullable":true,"example":"COD"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}}}}}}}}}}},"/api/v1/orders/{id}":{"get":{"summary":"Recupera una orden","tags":["Ordenes"],"description":"```\n   GET /api/v1/orders/:id\n```\n   El endpoint para recuperar una orden sirve para obtener toda la información de una orden.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna una orden","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"type":{"type":"string","example":"order"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"reference":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"nullable":true},"platform":{"type":["string",null],"example":"Shopify"},"ecommerce_id":{"type":["string",null],"example":"SDFG"},"payment_status":{"type":"string","nullable":true,"example":"paid"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"example":10.0},"shipping_preferences":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true,"properties":{"service":{"type":["string",null],"example":"me2"},"price":{"type":["string",null],"example":"100.00"}}}},"payment_type":{"type":"string","nullable":true,"example":"COD"},"shipment_purpose":{"type":"string","nullable":true,"example":"goods"},"customs_payment_payer":{"type":"string","nullable":true,"example":"recipient"},"external_shipment":{"type":"boolean","example":false},"created_at":{"type":"string","format":"date-time","example":"2025-01-07T14:46:38.203-06:00"},"address_from":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string",null],"example":"Nuevo León"},"area_level2":{"type":["string",null],"example":"Monterrey"},"area_level3":{"type":["string",null],"example":"La Finca"},"name":{"type":["string",null],"example":"Name"},"postal_code":{"type":["string",null],"example":"64000"},"country_code":{"type":["string",null],"example":"MX"},"street1":{"type":["string",null],"example":"Olivo 4618"},"company":{"type":["string",null],"example":""},"phone":{"type":["string",null],"example":"1242452456"},"email":{"type":["string",null],"example":"email@example.com"},"reference":{"type":["string",null],"example":"Green house"},"address_type":{"type":"string","example":"from"},"apartment_number":{"type":["string",null],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"address_to":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string",null],"example":"Monterrey Centro"},"area_level2":{"type":["string",null],"example":"Monterrey"},"area_level3":{"type":["string",null],"example":"La finca"},"name":{"type":["string",null],"example":"Mayra Doe"},"postal_code":{"type":["string",null],"example":"64000"},"country_code":{"type":["string",null],"example":"MX"},"street1":{"type":["string",null],"example":"22 Main St"},"company":{"type":["string",null],"example":"ACS Inc."},"phone":{"type":["string",null],"example":"1234567890"},"email":{"type":["string",null],"example":"jhon@doe.com"},"reference":{"type":["string",null],"example":"Near the park"},"address_type":{"type":"string","example":"to"},"apartment_number":{"type":["string",null],"example":"123"},"further_information":{"type":["string",null],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"parcel":{"type":"object","properties":{"weight":{"type":"float","example":2.0},"length":{"type":"integer","example":10},"width":{"type":"integer","example":10},"height":{"type":"integer","example":10},"declared_value":{"type":"number","nullable":true,"example":120.5},"package_protected":{"type":"boolean","nullable":true,"example":false},"package_number":{"type":"integer","nullable":true,"example":1},"package_type":{"type":"string","nullable":true,"example":"4G"},"consignment_note":{"type":"string","nullable":true,"example":"24121500"},"dimension_unit":{"type":"string","example":"cm"},"mass_unit":{"type":"string","example":"kg"}}}}},"relationships":{"type":"object","properties":{"items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"type":{"type":"string","example":"item"}}}}}},"shipments":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"9eae25ba-11b4-4b9f-9b01-3d09da8bc12d"},"type":{"type":"string","example":"shipment"}}}}}}}}}},"included":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"type":{"type":"string","example":"item"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"prueba"},"sku":{"type":"string","example":"prueba","nullable":true},"hs_code":{"type":"string","nullable":true,"example":"9560.63"},"hs_code_description":{"type":"string","nullable":true,"example":"Bicycles"},"description_en":{"type":"string","nullable":true,"example":"Mountain bike"},"product_type_code":{"type":"string","nullable":true,"example":"60141200"},"product_type_name":{"type":"string","nullable":true,"example":"Bicycles"},"country_code":{"type":"string","nullable":true,"example":"MX"},"quantity":{"type":"integer","example":2},"price":{"type":"number","example":15.0},"weight":{"type":"number","example":20.0},"height":{"type":"number","example":30.0},"width":{"type":"number","example":30.0},"length":{"type":"number","example":30.0}}}}},"nullable":true}}}}}}}}},"/api/v1/orders/{order_id}/labels":{"get":{"summary":"Obtener URLs de guías de envíos de una orden","tags":["Ordenes"],"description":"Devuelve las URLs de las guías para todos los envíos descargables asociados a la orden.","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna la URL de la guía de la orden","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660"},"label_urls":{"type":"array","items":{"type":"string","example":"https://example.com/labels/label.pdf"}}}}}}}}}}}},"/api/v1/orders/":{"post":{"summary":"Crea una orden","tags":["Ordenes"],"description":"```\n   POST /api/v1/orders\n```\n   Permite crear una orden que guarda la información del pedido y los productos sin llegar a crear el envío.\n\nPermite edición, automatizaciones y preparación en lote para gestionar tus envíos de manera centralizada. Es ideal si sincronizas ventas de tiendas en línea o gestionas cargas masivas. Puedes declarar el desglose de productos por orden y aprovechar las reglas de automatización de la plataforma.\n\nSe necesita enviar al menos uno de todos los atributos para crear una orden.\n\n","parameters":[],"responses":{"201":{"description":"Pedido creado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"e7c50876-2715-4f76-a83d-da5307d58b07"},"type":{"type":"string","example":"order"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"e7c50876-2715-4f76-a83d-da5307d58b07"},"reference":{"type":"string","nullable":true,"example":"188"},"platform":{"type":"string","example":"Shopify"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"nullable":true},"ecommerce_id":{"type":["string",null],"example":null},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"example":100.0},"created_at":{"type":"string","format":"date-time","example":"2024-09-05T23:13:40.417-06:00"},"updated_at":{"type":"string","format":"date-time","example":"2024-09-05T23:13:40.417-06:00"},"shipping_preferences":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true,"properties":{"service":{"type":["string",null],"example":"me2"},"price":{"type":["string",null],"example":"100.00"}}}},"payment_type":{"type":"string","nullable":true,"example":"COD"}}}}}},"required":["data"]}}}},"422":{"description":"Solicitud inválida","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}]}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Orden México (MX)","properties":{"order":{"type":"object","properties":{"reference":{"type":"string","example":188,"description":"A través de este campo se podrá identificar la orden en la plataforma."},"reference_number":{"type":"string","example":"188-5455445-33334433","description":"Identificador externo de la orden en la plataforma. Puede ser nulo. Si esta presente, debe ser único."},"payment_status":{"type":"string","example":"paid","description":"Estado de pago."},"total_price":{"type":"string","example":"57.00","description":"Precio total de la orden."},"merchant_store_id":{"type":"string","example":"139539AS","description":"Id de la tienda"},"headquarter_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id del headquarter"},"platform":{"type":"string","example":"Shopify","description":"Plataforma desde donde se realizará la orden"},"shipping":{"type":"object","nullable":true,"description":"Opción de envío preferida para la orden.","properties":{"service":{"type":"string","example":"me2","description":"Metodo de envio seleccionado por tu cliente."},"price":{"type":"string","nullable":true,"example":"100.00","description":"Precio de envio informado a tu cliente."}}},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"float","example":10,"description":"Peso del paquete."},"length":{"type":"integer","example":10,"description":"Longitud del paquete."},"width":{"type":"integer","example":10,"description":"Ancho del paquete."},"height":{"type":"integer","example":10,"description":"Altura del paquete."},"quantity":{"type":"integer","example":1,"description":"Cantidad de paquetes con las mismas medidas."},"dimension_unit":{"type":"string","example":"CM","description":"Unidad de medida de las dimensiones."},"mass_unit":{"type":"string","example":"KG","description":"Unidad de medida del peso."},"package_type":{"type":"string","example":"7H1","description":"Tipo de paquete, requerido para automatizaciones que crean guía automática."},"consignment_note":{"type":"string","example":24121500,"description":"Descripción del contenido del paquete. Requerido para México (MX), donde corresponde al código del catálogo Carta Porte (SAT)."},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Bicicleta","description":"Nombre del producto."},"hs_code":{"type":"string","example":"9560.63","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"sku":{"type":"string","example":"BIC-001","description":"Código del producto."},"price":{"type":"string","example":"57.00","description":"Precio del producto."},"quantity":{"type":"integer","example":1,"description":"Cantidad de productos."},"weight":{"type":"float","example":10,"description":"Peso del producto en kilogramos."},"height":{"type":"integer","example":10,"description":"Altura del producto en centímetros."},"length":{"type":"integer","example":10,"description":"Longitud del producto en centímetros."},"width":{"type":"integer","example":10,"description":"Ancho del producto en centímetros."}}}}}}},"shipper_address":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Cuando es un UUID válido de una plantilla de origen, los valores del template (country_code, postal_code, area_level1, area_level2, street1, company, phone, email, etc.) SUSTITUYEN los campos explícitos enviados en shipper_address y se vincula la plantilla a la orden. Si está vacío, es un UUID desconocido o pertenece a una plantilla de destino, se ignora y se usan los campos explícitos de shipper_address."},"address":{"type":"string","example":"Vía Industrial","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"100","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Planta nuclear","description":"Referencia de la dirección."},"sector":{"type":"string","example":"Asarco","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Monterrey","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Nuevo León","description":"Nombre del estado."},"postal_code":{"type":"string","example":"64550","description":"Código postal."},"country":{"type":"string","example":"MX","description":"Código de país según el formato alpha-2 de la ISO 3166-1."},"person_name":{"type":"string","example":"Homero Simpson","description":"Nombre de la persona que recibirá los paquetes."},"company":{"type":"string","example":"Inversiones Montgomery Burns S.A.S de C.V.","description":"Nombre de la empresa que recibirá los paquetes."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono de la persona que recibirá los paquetes."},"email":{"type":"string","example":"homero@burns.com","description":"Correo electrónico de la persona que recibirá los paquetes."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}}},"recipient_address":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Cuando es un UUID válido de una plantilla de destino, los valores del template (country_code, postal_code, area_level1, area_level2, street1, company, phone, email, etc.) SUSTITUYEN los campos explícitos enviados en recipient_address y se vincula la plantilla a la orden. Si está vacío, es un UUID desconocido o pertenece a una plantilla de origen, se ignora y se usan los campos explícitos de recipient_address."},"address":{"type":"string","example":"Avenida Siempre Viva","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"742","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Casa color durazno.","description":"Referencia de la dirección."},"sector":{"type":"string","example":"La Finca","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Monterrey","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Nuevo León","description":"Nombre del estado."},"postal_code":{"type":"string","example":"64000","description":"Código postal."},"country":{"type":"string","example":"MX","description":"País."},"person_name":{"type":"string","example":"Bart Simpson","description":"Nombre de la persona que enviará los paquetes."},"company":{"type":"string","example":"Casa de Bart S.A.S de C.V.","description":"Nombre de la empresa que enviará los paquetes."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono de la persona que enviará los paquetes."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico de la persona que enviará los paquetes."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}}}}}},"required":["order"]},{"type":"object","title":"Orden Internacional (MX → US)","properties":{"order":{"type":"object","properties":{"reference":{"type":"string","example":188,"description":"A través de este campo se podrá identificar la orden en la plataforma."},"reference_number":{"type":"string","example":"188-5455445-33334433","description":"Identificador externo de la orden en la plataforma. Puede ser nulo. Si esta presente, debe ser único."},"payment_status":{"type":"string","example":"paid","description":"Estado de pago."},"total_price":{"type":"string","example":"112.00","description":"Precio total de la orden."},"merchant_store_id":{"type":"string","example":"139539AS","description":"Id de la tienda"},"headquarter_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id del headquarter"},"platform":{"type":"string","example":"Shopify","description":"Plataforma desde donde se realizará la orden"},"shipment_purpose":{"type":"string","enum":["goods","documents","sample","return_of_goods","gift","humanitarian_donation"],"example":"goods","description":"Propósito del envío internacional. Valores permitidos `goods` (mercancía), `documents` (documentos), `sample` (muestra), `return_of_goods` (devolución de mercancía), `gift` (regalo) o `humanitarian_donation` (donación humanitaria). Si se envía un valor fuera de esta lista se guarda como nulo. Requerido para envíos internacionales."},"shipping":{"type":"object","nullable":true,"description":"Opción de envío preferida para la orden.","properties":{"service":{"type":"string","example":"me2","description":"Metodo de envio seleccionado por tu cliente."},"price":{"type":"string","nullable":true,"example":"100.00","description":"Precio de envio informado a tu cliente."}}},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"float","example":12,"description":"Peso del paquete."},"length":{"type":"integer","example":30,"description":"Longitud del paquete."},"width":{"type":"integer","example":25,"description":"Ancho del paquete."},"height":{"type":"integer","example":20,"description":"Altura del paquete."},"quantity":{"type":"integer","example":1,"description":"Cantidad de paquetes con las mismas medidas."},"dimension_unit":{"type":"string","example":"CM","description":"Unidad de medida de las dimensiones."},"mass_unit":{"type":"string","example":"KG","description":"Unidad de medida del peso."},"package_type":{"type":"string","example":"7H1","description":"Tipo de paquete, requerido para automatizaciones que crean guía automática."},"consignment_note":{"type":"string","example":24121500,"description":"Descripción del contenido del paquete. Requerido para México (MX), donde corresponde al código del catálogo Carta Porte (SAT)."},"declared_value":{"type":"string","example":"112.00","description":"Valor declarado del paquete para aduanas internacionales. Requerido para envíos internacionales."},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Bicicleta","description":"Nombre del producto."},"sku":{"type":"string","example":"BIC-001","description":"Código del producto."},"price":{"type":"string","example":"57.00","description":"Precio del producto."},"quantity":{"type":"integer","example":1,"description":"Cantidad de productos."},"weight":{"type":"float","example":10,"description":"Peso del producto en kilogramos."},"height":{"type":"integer","example":10,"description":"Altura del producto en centímetros."},"length":{"type":"integer","example":10,"description":"Longitud del producto en centímetros."},"width":{"type":"integer","example":10,"description":"Ancho del producto en centímetros."},"hs_code":{"type":"string","example":"8712.001510","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"hs_code_description":{"type":"string","example":"Bicycles and other cycles, not motorized","description":"Descripción del código arancelario (HS code). Requerido para envíos internacionales."},"country_code":{"type":"string","example":"MX","description":"País de fabricación del producto (ISO 3166-1 alpha-2). Requerido para envíos internacionales."},"description_en":{"type":"string","example":"Mountain bicycle adult size","description":"Descripción del producto en inglés. Requerido para envíos internacionales."},"product_type_code":{"type":"string","example":"25161500","description":"Código del tipo de producto según el catálogo UNSPSC. Requerido para envíos internacionales."},"product_type_name":{"type":"string","example":"Vehículos a pedal","description":"Nombre del tipo de producto. Requerido para envíos internacionales."}}}}}}},"shipper_address":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Cuando es un UUID válido de una plantilla de origen, los valores del template (country_code, postal_code, area_level1, area_level2, street1, company, phone, email, etc.) SUSTITUYEN los campos explícitos enviados en shipper_address y se vincula la plantilla a la orden. Si está vacío, es un UUID desconocido o pertenece a una plantilla de destino, se ignora y se usan los campos explícitos de shipper_address."},"address":{"type":"string","example":"Vía Industrial","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"100","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Planta nuclear","description":"Referencia de la dirección."},"sector":{"type":"string","example":"Asarco","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Monterrey","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Nuevo León","description":"Nombre del estado."},"postal_code":{"type":"string","example":"64550","description":"Código postal."},"country":{"type":"string","example":"MX","description":"Código de país según el formato alpha-2 de la ISO 3166-1."},"person_name":{"type":"string","example":"Homero Simpson","description":"Nombre de la persona que recibirá los paquetes."},"company":{"type":"string","example":"Inversiones Montgomery Burns S.A.S de C.V.","description":"Nombre de la empresa que recibirá los paquetes."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono de la persona que recibirá los paquetes."},"email":{"type":"string","example":"homero@burns.com","description":"Correo electrónico de la persona que recibirá los paquetes."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}}},"recipient_address":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Cuando es un UUID válido de una plantilla de destino, los valores del template (country_code, postal_code, area_level1, area_level2, street1, company, phone, email, etc.) SUSTITUYEN los campos explícitos enviados en recipient_address y se vincula la plantilla a la orden. Si está vacío, es un UUID desconocido o pertenece a una plantilla de origen, se ignora y se usan los campos explícitos de recipient_address."},"address":{"type":"string","example":"742 Evergreen Terrace","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"742","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Yellow house, two stories","description":"Referencia de la dirección."},"sector":{"type":"string","example":"Downtown","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Springfield","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Oregon","description":"Nombre del estado."},"postal_code":{"type":"string","example":"97477","description":"Código postal."},"country":{"type":"string","example":"US","description":"País."},"person_name":{"type":"string","example":"Bart Simpson","description":"Nombre de la persona que enviará los paquetes."},"company":{"type":"string","example":"Simpson Family LLC","description":"Nombre de la empresa que enviará los paquetes."},"phone":{"type":"string","example":"5415551234","description":"Número de teléfono de la persona que enviará los paquetes."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico de la persona que enviará los paquetes."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Leave with neighbor if absent","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}}}}}},"required":["order"]}]}}}}}},"/api/v1/orders/{order_id}":{"patch":{"summary":"Actualiza una orden","tags":["Ordenes"],"description":"```\n   PATCH /api/v1/orders/:id\n```\n   El endpoint permite actualizar la información de una orden.\n","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Orden actualizada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"type":{"type":"string","example":"order"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"reference":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"nullable":true},"platform":{"type":["string",null],"example":"Shopify"},"ecommerce_id":{"type":["string",null],"example":"SDFG"},"payment_status":{"type":"string","nullable":true,"example":"paid"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"example":10.0},"shipping_preferences":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true,"properties":{"service":{"type":["string",null],"example":"me2"},"price":{"type":["string",null],"example":"100.00"}}}},"payment_type":{"type":"string","nullable":true,"example":"COD"},"shipment_purpose":{"type":"string","nullable":true,"example":"goods"},"customs_payment_payer":{"type":"string","nullable":true,"example":"recipient"},"external_shipment":{"type":"boolean","example":false},"created_at":{"type":"string","format":"date-time","example":"2025-01-07T14:46:38.203-06:00"},"address_from":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string",null],"example":"Nuevo León"},"area_level2":{"type":["string",null],"example":"Monterrey"},"area_level3":{"type":["string",null],"example":"La Finca"},"name":{"type":["string",null],"example":"Name"},"postal_code":{"type":["string",null],"example":"64000"},"country_code":{"type":["string",null],"example":"MX"},"street1":{"type":["string",null],"example":"Olivo 4618"},"company":{"type":["string",null],"example":""},"phone":{"type":["string",null],"example":"1242452456"},"email":{"type":["string",null],"example":"email@example.com"},"reference":{"type":["string",null],"example":"Green house"},"address_type":{"type":"string","example":"from"},"apartment_number":{"type":["string",null],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"address_to":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string",null],"example":"Monterrey Centro"},"area_level2":{"type":["string",null],"example":"Monterrey"},"area_level3":{"type":["string",null],"example":"La finca"},"name":{"type":["string",null],"example":"Mayra Doe"},"postal_code":{"type":["string",null],"example":"64000"},"country_code":{"type":["string",null],"example":"MX"},"street1":{"type":["string",null],"example":"22 Main St"},"company":{"type":["string",null],"example":"ACS Inc."},"phone":{"type":["string",null],"example":"1234567890"},"email":{"type":["string",null],"example":"jhon@doe.com"},"reference":{"type":["string",null],"example":"Near the park"},"address_type":{"type":"string","example":"to"},"apartment_number":{"type":["string",null],"example":"123"},"further_information":{"type":["string",null],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"parcel":{"type":"object","properties":{"weight":{"type":"float","example":2.0},"length":{"type":"integer","example":10},"width":{"type":"integer","example":10},"height":{"type":"integer","example":10},"declared_value":{"type":"number","nullable":true,"example":120.5},"package_protected":{"type":"boolean","nullable":true,"example":false},"package_number":{"type":"integer","nullable":true,"example":1},"package_type":{"type":"string","nullable":true,"example":"4G"},"consignment_note":{"type":"string","nullable":true,"example":"24121500"},"dimension_unit":{"type":"string","example":"cm"},"mass_unit":{"type":"string","example":"kg"}}}}},"relationships":{"type":"object","properties":{"items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"type":{"type":"string","example":"item"}}}}}},"shipments":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"9eae25ba-11b4-4b9f-9b01-3d09da8bc12d"},"type":{"type":"string","example":"shipment"}}}}}}}}}},"included":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"type":{"type":"string","example":"item"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"prueba"},"sku":{"type":"string","example":"prueba","nullable":true},"hs_code":{"type":"string","nullable":true,"example":"9560.63"},"hs_code_description":{"type":"string","nullable":true,"example":"Bicycles"},"description_en":{"type":"string","nullable":true,"example":"Mountain bike"},"product_type_code":{"type":"string","nullable":true,"example":"60141200"},"product_type_name":{"type":"string","nullable":true,"example":"Bicycles"},"country_code":{"type":"string","nullable":true,"example":"MX"},"quantity":{"type":"integer","example":2},"price":{"type":"number","example":15.0},"weight":{"type":"number","example":20.0},"height":{"type":"number","example":30.0},"width":{"type":"number","example":30.0},"length":{"type":"number","example":30.0}}}}},"nullable":true}}}}}},"422":{"description":"La orden no puede ser actualizada","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"string"}}}}}},"404":{"description":"Orden no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"202":{"description":"Solicitud aceptada y encolada para asociar el envío con tu flota propia.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"type":{"type":"string","example":"order"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"reference":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"nullable":true},"platform":{"type":["string",null],"example":"Shopify"},"ecommerce_id":{"type":["string",null],"example":"SDFG"},"payment_status":{"type":"string","nullable":true,"example":"paid"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"example":10.0},"shipping_preferences":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true,"properties":{"service":{"type":["string",null],"example":"me2"},"price":{"type":["string",null],"example":"100.00"}}}},"payment_type":{"type":"string","nullable":true,"example":"COD"},"shipment_purpose":{"type":"string","nullable":true,"example":"goods"},"customs_payment_payer":{"type":"string","nullable":true,"example":"recipient"},"external_shipment":{"type":"boolean","example":false},"created_at":{"type":"string","format":"date-time","example":"2025-01-07T14:46:38.203-06:00"},"address_from":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string",null],"example":"Nuevo León"},"area_level2":{"type":["string",null],"example":"Monterrey"},"area_level3":{"type":["string",null],"example":"La Finca"},"name":{"type":["string",null],"example":"Name"},"postal_code":{"type":["string",null],"example":"64000"},"country_code":{"type":["string",null],"example":"MX"},"street1":{"type":["string",null],"example":"Olivo 4618"},"company":{"type":["string",null],"example":""},"phone":{"type":["string",null],"example":"1242452456"},"email":{"type":["string",null],"example":"email@example.com"},"reference":{"type":["string",null],"example":"Green house"},"address_type":{"type":"string","example":"from"},"apartment_number":{"type":["string",null],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"address_to":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string",null],"example":"Monterrey Centro"},"area_level2":{"type":["string",null],"example":"Monterrey"},"area_level3":{"type":["string",null],"example":"La finca"},"name":{"type":["string",null],"example":"Mayra Doe"},"postal_code":{"type":["string",null],"example":"64000"},"country_code":{"type":["string",null],"example":"MX"},"street1":{"type":["string",null],"example":"22 Main St"},"company":{"type":["string",null],"example":"ACS Inc."},"phone":{"type":["string",null],"example":"1234567890"},"email":{"type":["string",null],"example":"jhon@doe.com"},"reference":{"type":["string",null],"example":"Near the park"},"address_type":{"type":"string","example":"to"},"apartment_number":{"type":["string",null],"example":"123"},"further_information":{"type":["string",null],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"parcel":{"type":"object","properties":{"weight":{"type":"float","example":2.0},"length":{"type":"integer","example":10},"width":{"type":"integer","example":10},"height":{"type":"integer","example":10},"declared_value":{"type":"number","nullable":true,"example":120.5},"package_protected":{"type":"boolean","nullable":true,"example":false},"package_number":{"type":"integer","nullable":true,"example":1},"package_type":{"type":"string","nullable":true,"example":"4G"},"consignment_note":{"type":"string","nullable":true,"example":"24121500"},"dimension_unit":{"type":"string","example":"cm"},"mass_unit":{"type":"string","example":"kg"}}}}},"relationships":{"type":"object","properties":{"items":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"type":{"type":"string","example":"item"}}}}}},"shipments":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"9eae25ba-11b4-4b9f-9b01-3d09da8bc12d"},"type":{"type":"string","example":"shipment"}}}}}}}}}},"included":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"type":{"type":"string","example":"item"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"prueba"},"sku":{"type":"string","example":"prueba","nullable":true},"hs_code":{"type":"string","nullable":true,"example":"9560.63"},"hs_code_description":{"type":"string","nullable":true,"example":"Bicycles"},"description_en":{"type":"string","nullable":true,"example":"Mountain bike"},"product_type_code":{"type":"string","nullable":true,"example":"60141200"},"product_type_name":{"type":"string","nullable":true,"example":"Bicycles"},"country_code":{"type":"string","nullable":true,"example":"MX"},"quantity":{"type":"integer","example":2},"price":{"type":"number","example":15.0},"weight":{"type":"number","example":20.0},"height":{"type":"number","example":30.0},"width":{"type":"number","example":30.0},"length":{"type":"number","example":30.0}}}}},"nullable":true}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Orden México (MX)","properties":{"order_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id de la orden"},"order":{"type":"object","properties":{"total_price":{"type":"string","example":"57.00","description":"Precio total de la orden."},"payment_status":{"type":"string","example":"paid","description":"Estado de pago."},"shipping":{"type":"object","nullable":true,"description":"Opción de envío preferida para la orden.","properties":{"service":{"type":"string","example":"me2","description":"Metodo de envio seleccionado por tu cliente."},"price":{"type":"string","nullable":true,"example":"100.00","description":"Precio de envio informado a tu cliente."}}},"parcels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"UUID del paquete. Si se envía, actualiza el paquete existente. Si se omite, se crea uno nuevo."},"_destroy":{"type":"boolean","example":false,"description":"Establecer en true junto con el id del paquete para eliminarlo de la orden."},"weight":{"type":"float","example":10.0,"description":"Peso del paquete."},"mass_unit":{"type":"string","example":"KG","description":"Unidad de medida del peso."},"length":{"type":"integer","example":10,"description":"Longitud del paquete."},"width":{"type":"integer","example":10,"description":"Ancho del paquete."},"height":{"type":"integer","example":10,"description":"Altura del paquete."},"quantity":{"type":"integer","example":1,"description":"Cantidad de paquetes con las mismas medidas."},"dimension_unit":{"type":"string","example":"CM","description":"Unidad de medida de las dimensiones."},"package_type":{"type":"string","example":"7H1","description":"Tipo de paquete, requerido para automatizaciones que crean guía automática."},"consignment_note":{"type":"string","example":24121500,"description":"Descripción del contenido del paquete. Requerido para México (MX), donde corresponde al código del catálogo Carta Porte (SAT)."},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Bicicleta","description":"Nombre del producto."},"hs_code":{"type":"string","example":"9560.63","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"sku":{"type":"string","example":"BIC-001","description":"Código del producto."},"price":{"type":"string","example":"57.00","description":"Precio del producto."},"quantity":{"type":"integer","example":1,"description":"Cantidad de productos."},"weight":{"type":"integer","example":10,"description":"Peso del producto en kilogramos."},"height":{"type":"integer","example":10,"description":"Altura del producto en centímetros."},"length":{"type":"integer","example":10,"description":"Longitud del producto en centímetros."},"width":{"type":"integer","example":10,"description":"Ancho del producto en centímetros."}}}}}}},"shipper_address":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Cuando es un UUID válido de una plantilla de origen, los valores del template (country_code, postal_code, area_level1, area_level2, street1, company, phone, email, etc.) SUSTITUYEN los campos explícitos enviados en shipper_address y se vincula la plantilla a la orden. Si está vacío, es un UUID desconocido o pertenece a una plantilla de destino, se ignora y se usan los campos explícitos de shipper_address."},"address":{"type":"string","example":"Vía Industrial","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"100","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Planta nuclear","description":"Referencia de la dirección."},"sector":{"type":"string","example":"Asarco","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Monterrey","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Nuevo León","description":"Nombre del estado."},"postal_code":{"type":"string","example":"64550","description":"Código postal."},"country":{"type":"string","example":"MX","description":"Código de país según el formato alpha-2 de la ISO 3166-1."},"person_name":{"type":"string","example":"Homero Simpson","description":"Nombre de la persona que recibirá los paquetes."},"company":{"type":"string","example":"Inversiones Montgomery Burns S.A.S de C.V.","description":"Nombre de la empresa que recibirá los paquetes."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono de la persona que recibirá los paquetes."},"email":{"type":"string","example":"homero@burns.com","description":"Correo electrónico de la persona que recibirá los paquetes."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}}},"recipient_address":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Cuando es un UUID válido de una plantilla de destino, los valores del template (country_code, postal_code, area_level1, area_level2, street1, company, phone, email, etc.) SUSTITUYEN los campos explícitos enviados en recipient_address y se vincula la plantilla a la orden. Si está vacío, es un UUID desconocido o pertenece a una plantilla de origen, se ignora y se usan los campos explícitos de recipient_address."},"address":{"type":"string","example":"Avenida Siempre Viva","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"742","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Casa color durazno.","description":"Referencia de la dirección."},"sector":{"type":"string","example":"La Finca","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Monterrey","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Nuevo León","description":"Nombre del estado."},"postal_code":{"type":"string","example":"64000","description":"Código postal."},"country":{"type":"string","example":"MX","description":"País."},"person_name":{"type":"string","example":"Bart Simpson","description":"Nombre de la persona que enviará los paquetes."},"company":{"type":"string","example":"Casa de Bart S.A.S de C.V.","description":"Nombre de la empresa que enviará los paquetes."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono de la persona que enviará los paquetes."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico de la persona que enviará los paquetes."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}}}}}},"required":["order","order_id"]},{"type":"object","title":"Orden Internacional (MX → US)","properties":{"order_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id de la orden"},"order":{"type":"object","properties":{"total_price":{"type":"string","example":"112.00","description":"Precio total de la orden."},"payment_status":{"type":"string","example":"paid","description":"Estado de pago."},"shipment_purpose":{"type":"string","enum":["goods","documents","sample","return_of_goods","gift","humanitarian_donation"],"example":"goods","description":"Propósito del envío internacional. Valores permitidos `goods` (mercancía), `documents` (documentos), `sample` (muestra), `return_of_goods` (devolución de mercancía), `gift` (regalo) o `humanitarian_donation` (donación humanitaria). Si se envía un valor fuera de esta lista se guarda como nulo. Requerido para envíos internacionales."},"shipping":{"type":"object","nullable":true,"description":"Opción de envío preferida para la orden.","properties":{"service":{"type":"string","example":"me2","description":"Metodo de envio seleccionado por tu cliente."},"price":{"type":"string","nullable":true,"example":"100.00","description":"Precio de envio informado a tu cliente."}}},"parcels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"UUID del paquete. Si se envía, actualiza el paquete existente. Si se omite, se crea uno nuevo."},"_destroy":{"type":"boolean","example":false,"description":"Establecer en true junto con el id del paquete para eliminarlo de la orden."},"weight":{"type":"float","example":12.0,"description":"Peso del paquete."},"mass_unit":{"type":"string","example":"KG","description":"Unidad de medida del peso."},"length":{"type":"integer","example":30,"description":"Longitud del paquete."},"width":{"type":"integer","example":25,"description":"Ancho del paquete."},"height":{"type":"integer","example":20,"description":"Altura del paquete."},"quantity":{"type":"integer","example":1,"description":"Cantidad de paquetes con las mismas medidas."},"dimension_unit":{"type":"string","example":"CM","description":"Unidad de medida de las dimensiones."},"package_type":{"type":"string","example":"7H1","description":"Tipo de paquete, requerido para automatizaciones que crean guía automática."},"consignment_note":{"type":"string","example":24121500,"description":"Descripción del contenido del paquete. Requerido para México (MX), donde corresponde al código del catálogo Carta Porte (SAT)."},"declared_value":{"type":"string","example":"112.00","description":"Valor declarado del paquete para aduanas internacionales. Requerido para envíos internacionales."},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Bicicleta","description":"Nombre del producto."},"sku":{"type":"string","example":"BIC-001","description":"Código del producto."},"price":{"type":"string","example":"57.00","description":"Precio del producto."},"quantity":{"type":"integer","example":1,"description":"Cantidad de productos."},"weight":{"type":"integer","example":10,"description":"Peso del producto en kilogramos."},"height":{"type":"integer","example":10,"description":"Altura del producto en centímetros."},"length":{"type":"integer","example":10,"description":"Longitud del producto en centímetros."},"width":{"type":"integer","example":10,"description":"Ancho del producto en centímetros."},"hs_code":{"type":"string","example":"8712.001510","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"hs_code_description":{"type":"string","example":"Bicycles and other cycles, not motorized","description":"Descripción del código arancelario (HS code). Requerido para envíos internacionales."},"country_code":{"type":"string","example":"MX","description":"País de fabricación del producto (ISO 3166-1 alpha-2). Requerido para envíos internacionales."},"description_en":{"type":"string","example":"Mountain bicycle adult size","description":"Descripción del producto en inglés. Requerido para envíos internacionales."},"product_type_code":{"type":"string","example":"25161500","description":"Código del tipo de producto según el catálogo UNSPSC. Requerido para envíos internacionales."},"product_type_name":{"type":"string","example":"Vehículos a pedal","description":"Nombre del tipo de producto. Requerido para envíos internacionales."}}}}}}},"shipper_address":{"type":"object","properties":{"address":{"type":"string","example":"Vía Industrial","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"100","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Planta nuclear","description":"Referencia de la dirección."},"sector":{"type":"string","example":"Asarco","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Monterrey","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Nuevo León","description":"Nombre del estado."},"postal_code":{"type":"string","example":"64550","description":"Código postal."},"country":{"type":"string","example":"MX","description":"Código de país según el formato alpha-2 de la ISO 3166-1."},"person_name":{"type":"string","example":"Homero Simpson","description":"Nombre de la persona que recibirá los paquetes."},"company":{"type":"string","example":"Inversiones Montgomery Burns S.A.S de C.V.","description":"Nombre de la empresa que recibirá los paquetes."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono de la persona que recibirá los paquetes."},"email":{"type":"string","example":"homero@burns.com","description":"Correo electrónico de la persona que recibirá los paquetes."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}}},"recipient_address":{"type":"object","properties":{"address":{"type":"string","example":"742 Evergreen Terrace","description":"Nombre de la calle o avenida. En Brasil (BR) manda el número de calle en esta misma línea, por ejemplo `Rua das Flores, 123`. Se extrae de la línea y se guarda en un campo propio, que la DC-e declara aparte. Si no se puede identificar el número, el campo queda vacío y hay que completarlo antes de crear el envío."},"internal_number":{"type":"string","maxLength":10,"example":"742","description":"Número de la casa o departamento (máximo 10 caracteres)."},"reference":{"type":"string","example":"Yellow house, two stories","description":"Referencia de la dirección."},"sector":{"type":"string","example":"Downtown","description":"Nombre de la Colonia."},"city":{"type":"string","example":"Springfield","description":"Nombre de la ciudad."},"state":{"type":"string","example":"Oregon","description":"Nombre del estado."},"postal_code":{"type":"string","example":"97477","description":"Código postal."},"country":{"type":"string","example":"US","description":"País."},"person_name":{"type":"string","example":"Bart Simpson","description":"Nombre de la persona que enviará los paquetes."},"company":{"type":"string","example":"Simpson Family LLC","description":"Nombre de la empresa que enviará los paquetes."},"phone":{"type":"string","example":"5415551234","description":"Número de teléfono de la persona que enviará los paquetes."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico de la persona que enviará los paquetes."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Leave with neighbor if absent","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}}}}}},"required":["order","order_id"]},{"type":"object","title":"Asociar orden a Mi flota (MX)","description":"Asocia esta orden a una flota propia (Logística Propia). Cuando se envía el bloque `external_shipment`, el resto de los campos de la orden se ignoran. No se ejecuta el flujo convencional de actualización ni se evalúan otras reglas. La orden queda enlazada al carrier de tu flota y se prepara para recibir eventos de tracking. Requiere flota propia activa en la cuenta.","properties":{"order_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id de la orden"},"order":{"type":"object","properties":{"external_shipment":{"type":"object","description":"Datos para asociar la orden a un carrier de flota propia. Los datos del destinatario (nombre, email, teléfono) se heredan automáticamente del `address_to` de la orden (poblado por la sincronización de tu ecommerce), por lo que para asociar la orden solo necesitas enviar el número de rastreo y el código del carrier.","properties":{"tracking_number":{"type":"string","example":"TRK-MX-1234567890","description":"Número de rastreo del envío que será gestionado con tu flota propia."},"carrier_custom_code":{"type":"string","example":"mi_flota","description":"Código del carrier de flota propia (`name` definido al registrarlo)."}},"required":["tracking_number","carrier_custom_code"]}}}},"required":["order","order_id"]}]}}}}}},"/api/v1/pickups/coverage":{"get":{"summary":"Obtiene cobertura de Fechas","tags":["Recolecciones"],"description":"```\n   GET /api/v1/pickups/coverage?shipment_id={shipment_id}\n```\n   Este endpoint obtiene la cobertura de fechas para realizar una recolección.\n\n   **Parámetros de la solicitud:**\n   - `shipment_id`: ID Envío de referencia que obtuviste del endpoint de envíos (GET /api/v1/shipments)\n","parameters":[{"name":"shipment_id","in":"query","required":true,"description":"ID Envío","schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna fechas disponibles para recolección","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Indica si la solicitud se procesó exitosamente."},"carrier":{"type":"string","example":"FEDEX","description":"Paquetería responsable de la recolección."},"service":{"type":"string","example":"FEDEX_EXPRESS_SAVER","description":"Tipo de servicio ofrecido por la paquetería"},"version":{"type":"string","example":"2.0.0"},"pickupDates":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2024-09-20","description":"Fecha disponible para la recolección."},"startHour":{"type":"string","format":"time","example":"08:30:00","description":"Hora de inicio de la ventana de recolección."},"endHour":{"type":"string","format":"time","example":"14:00:00","description":"Hora de finalización de la ventana de recolección."}}}}}}}}},"422":{"description":"Solicitud inválida","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false,"description":"Indica si la solicitud se procesó exitosamente."},"message":{"type":"string","example":"Carrier services error","description":"Proporciona detalles sobre el error ocurrido."}}}}}},"404":{"description":"Recurso no encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"El recurso buscado no se pudo encontrar."}}}}}}}}},"/api/v1/pickups/reschedule":{"post":{"summary":"Reprograma una recolección","tags":["Recolecciones"],"description":"```\n   POST /api/v1/pickups/reschedule\n```\n   Este endpoint permite reprogramar una recolección\n\n   **Parámetros de la solicitud:**\n   - `reference_shipment_id`: Id del envio a recolectar\n   - `packages`: Número de paquetes a recolectar\n   - `total_weight`: Peso total de los paquetes a recolectar\n   - `scheduled_from`: Fecha y hora de inicio de franja horaria de recolección\n   - `scheduled_to`: Fecha y hora final de franja horaria de recolección\n","parameters":[],"responses":{"201":{"description":"Retorna la recolección reprogramada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":1,"description":"Número de paquetes a recolectar"},"total_weight":{"type":["number","string"],"format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2024-09-20T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2024-09-20T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2024-09-19T07:43:46.614-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2024-09-19T07:43:46.614-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":"Error al programar la recolección","description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":9,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."}}},"relationships":{"type":"object","properties":{"reference_shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}},"address":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"address"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":"from","description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":"Apartamento 404","description":"Número de departamento"}}}}}]}}}}}}},"404":{"description":"Recolección no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"El recurso buscado no se pudo encontrar."}}}}}},"422":{"description":"Retorna una respuesta de error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"object","properties":{"reference_shipment_id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"Id del envio a recolectar"},"packages":{"type":"integer","example":5,"description":"Número de paquetes a recolectar"},"total_weight":{"type":["number","string"],"format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","description":"Fecha y hora de inicio de franja horaria de recolección","example":"2024-09-24 09:00:00"},"scheduled_to":{"type":"string","format":"date-time","description":"Fecha y hora final de franja horaria de recolección","example":"2024-09-24 14:00:00"}}}},"required":["pickup"]}}}}}},"/api/v1/pickups":{"get":{"summary":"Recupera todas las recolecciones","tags":["Recolecciones"],"description":"```\n   GET /api/v1/pickups?page={page}\n```\n   Este endpoint recupera todas las recolecciones, paginadas de diez en diez.\n","parameters":[{"name":"page","in":"query","description":"Nro de página","schema":{"type":"integer"}}],"responses":{"200":{"description":"Retorna una colección paginada de recolecciones","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object,","properties":{"id":{"type":"string","format":"uuid","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la recolección"},"status":{"type":"string","example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":5,"description":"Número de paquetes a recolectar"},"total_weight":{"type":["number","string"],"format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":"Error al programar la recolección","description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":9,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."}}},"relationships":{"type":"object","properties":{"reference_shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","example":"shipment"}}}}},"address":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","example":"address"}}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":"from","description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":"Apartamento 404","description":"Número de departamento"}}}}}]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":2},"next_page":{"type":"integer","nullable":true,"example":3},"prev_page":{"type":"integer","nullable":true,"example":1},"total_pages":{"type":"integer","example":3},"total_count":{"type":"integer","example":30}}}}}}}}}}},"/api/v1/pickups/{id}":{"get":{"summary":"Detalle de Recolección","tags":["Recolecciones"],"description":"```\n   GET /api/v1/pickups/{id}\n```\n   Este endpoint recupera una recolección\n","parameters":[{"name":"id","in":"path","description":"ID de la recolección","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recolección encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":1,"description":"Número de paquetes a recolectar"},"total_weight":{"type":["number","string"],"format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2024-09-20T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2024-09-20T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2024-09-19T07:43:46.614-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2024-09-19T07:43:46.614-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":"Error al programar la recolección","description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":9,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."}}},"relationships":{"type":"object","properties":{"reference_shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}},"address":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"address"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":"from","description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":"Apartamento 404","description":"Número de departamento"}}}}}]}}}}}}},"404":{"description":"Recolección no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"El recurso buscado no se pudo encontrar."}}}}}}}}},"/api/v1/pickups/":{"post":{"summary":"Programa una recolección","tags":["Recolecciones"],"description":"```\n   POST /api/v1/pickups/\n```\n   Este endpoint permite programar una recolección\n\n   **Parámetros de la solicitud:**\n   - `reference_shipment_id`: Id del envio a recolectar\n   - `packages`: Número de paquetes a recolectar\n   - `total_weight`: Peso total de los paquetes a recolectar\n   - `scheduled_from`: Fecha y hora de inicio de franja horaria de recolección\n   - `scheduled_to`: Fecha y hora final de franja horaria de recolección\n\n\n> [!note]\n> Evita cancelaciones por duplicidad agrupando los paquetes con el mismo origen y fecha en una sola recolección.","parameters":[],"responses":{"201":{"description":"Retorna la recolección programada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":1,"description":"Número de paquetes a recolectar"},"total_weight":{"type":["number","string"],"format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2024-09-20T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2024-09-20T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2024-09-19T07:43:46.614-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2024-09-19T07:43:46.614-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":"Error al programar la recolección","description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":9,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."}}},"relationships":{"type":"object","properties":{"reference_shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}},"address":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"address"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":"from","description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":"Apartamento 404","description":"Número de departamento"}}}}}]}}}}}}},"400":{"description":"Retorna una respuesta de error (solicitud incorrecta)"},"422":{"description":"Retorna una respuesta de error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"object","properties":{"reference_shipment_id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"Id del envio a recolectar"},"packages":{"type":"integer","example":5,"description":"Número de paquetes a recolectar"},"total_weight":{"type":["number","string"],"format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","description":"Fecha y hora de inicio de franja horaria de recolección","example":"2024-09-24 09:00:00"},"scheduled_to":{"type":"string","format":"date-time","description":"Fecha y hora final de franja horaria de recolección","example":"2024-09-24 14:00:00"}}}},"required":["pickup"]}}}}}},"/api/v1/products":{"get":{"summary":"Obtener lista de productos","tags":["Productos"],"description":"```\n   GET /api/v1/products\n```\n  El endpoint de productos sirve para obtener una lista de productos.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","required":false,"description":"Número de página a recuperar","schema":{"type":"integer","example":1}},{"name":"filters[destination_country_code]","in":"query","required":false,"description":"Filtrar productos por código de país de destino","schema":{"type":"string","example":"MX"}}],"responses":{"200":{"description":"Devuelve una lista de productos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"El id del producto","example":73},"type":{"type":"string","example":"product"},"attributes":{"type":"object","properties":{"id":{"type":"string","description":"El id del producto","example":73},"name":{"type":"string","example":"Pantalón","description":"El nombre del producto"},"sku":{"type":"string","example":1234567890,"description":"El código del producto"},"hscode":{"type":"string","example":6402.2,"description":"El código HS del producto"},"description":{"type":"string","example":"Descripción del producto","description":"La descripción del producto"},"weight":{"type":"number","example":4,"description":"El peso del producto"},"width":{"type":"number","example":4,"description":"El ancho del producto"},"height":{"type":"number","example":4,"description":"La altura del producto"},"length":{"type":"number","example":4,"description":"La longitud del producto"},"price":{"type":"number","example":4.5,"description":"El precio del producto"},"created_at":{"type":"string","example":"2025-02-06 21:26:41 -0500","description":"La fecha de creación del producto"},"updated_at":{"type":"string","example":"2025-02-06 21:26:41 -0500","description":"La fecha de actualización del producto"},"country_id":{"type":"string","example":"f12f8764-1ee7-48c7-94b3-3f5a4e610e5b","description":"El id del país del producto"},"product_type_code":{"type":"string","example":31261500,"description":"El código del tipo de producto"},"product_type_name":{"type":"string","example":"Producto 1","description":"El nombre del tipo de producto"},"description_en":{"type":"string","example":"Product 1","description":"La descripción del producto en inglés"},"created_from":{"type":"string","example":"interface","description":"La fuente de creación del producto"},"international_shipment_enabled":{"type":"boolean","example":true,"description":"Indica si el producto está habilitado para envío internacional"},"price_mxn":{"type":"number","example":4.5,"description":"El precio del producto en pesos mexicanos"},"destination_country_id":{"type":"string","example":"f12f8764-1ee7-48c7-94b3-3f5a4e610e5b","description":"El id del país de destino del producto"}}}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":2},"next_page":{"type":"integer","nullable":true,"example":3},"prev_page":{"type":"integer","nullable":true,"example":1},"total_pages":{"type":"integer","example":3},"total_count":{"type":"integer","example":8}}}}}}}}}}},"/api/v1/quotations":{"post":{"summary":"Crea una cotización","tags":["Cotizaciones"],"description":"```\n   POST /api/v1/quotations\n```\n   El endpoint crea una solicitud de cotización y la pone en cola para su procesamiento. La respuesta inicial contiene el identificador único de la cotización (`quotation_id`), pero no incluye los resultados de las tarifas.\n\nPara obtenerlos, consulta el siguiente endpoint `GET /api/v1/quotations/{id}` hasta que el estado (`status`) sea `is_completed`.\n\n**Campo opcional**: `order_id` (string) — ID de una orden existente para asociar la cotización. Si se omite, la cotización se crea sin orden vinculada.\n\n","parameters":[],"responses":{"201":{"description":"Retorna una respuesta completa de cotización","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"ID de la cotización."},"is_completed":{"type":"boolean","example":true,"description":"Estado de finalización del procesamiento de la cotización. Si es `false`, aún está en proceso y las tarifas todavía no están disponibles. Si es `true`, el procesamiento terminó y las tarifas ya están disponibles."},"quotation_scope":{"type":"object","oneOf":[{"properties":{"carriers_scoped_to":{"type":"string","enum":["ALL_AVAILABLE","PARTIALLY_SELECTED_CARRIERS"],"example":"ALL_AVAILABLE","description":"Paqueterías cotizadas (todas las paqueterías `ALL_AVAILABLE`)(paqueterías seleccionadas `PARTIALLY_SELECTED_CARRIERS`)"}}},{"properties":{"carriers_scoped_to":{"type":"string","enum":["ALL_AVAILABLE","PARTIALLY_SELECTED_CARRIERS"],"example":"ALL_AVAILABLE","description":"Paqueterías cotizadas (todas las paqueterías `ALL_AVAILABLE`)(paqueterías seleccionadas `PARTIALLY_SELECTED_CARRIERS`)"},"found_carriers":{"type":"array","items":{"type":"string","description":"Paqueterías encontradas."}},"not_found_carriers":{"type":"array","items":{"type":"string","description":"Paqueterías no encontradas."}}}}],"required":["carriers_scoped_to"]},"rates":{"type":"array","description":"Tarifas de las paqueterías.","items":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"ID de la tarifa."},"success":{"type":"boolean","example":true,"description":"Indica si la cotización con la paquetería tuvo éxito. Con `true` se obtuvo una tarifa válida; con `false` no se pudo generar una tarifa para los parámetros proporcionados."},"rate_type":{"type":"string","nullable":true,"description":"Tipo de tarifa."},"country_code":{"type":"string","nullable":true,"example":"mx","description":"Código de país de la dirección."},"provider_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería."},"provider_display_name":{"type":"string","example":"FedEx","description":"Nombre para mostrar de la paquetería."},"provider_service_name":{"type":"string","example":"Standard Overnight","description":"Nombre del servicio de la paquetería."},"provider_service_code":{"type":"string","example":"standard_overnight","description":"Código del servicio de la paquetería."},"status":{"type":"string","example":"pending","description":"Estado de la tarifa (Tarifa pendiente `pending`)(Tafira no aplica `not_applicable`)(Tarifa encontrada `approved`)(Tarifa sin cobertura `no_coverage`)(Tarifa con cobertura comprobada `coverage_checked`)(Tarifa encontrada `price_found_internal`)(Tarifa encontrada `price_found_external`)(Tarifa sin precio `tariff_price_not_found`)"},"currency_code":{"type":"string","example":"MXN","description":"Código de moneda."},"amount":{"type":"string","example":150.0,"description":"Monto de la tarifa."},"total":{"type":"string","example":150.0,"description":"Total de la tarifa."},"service_fee":{"type":"float","example":15.0,"nullable":true,"description":"Tarifa de gestión."},"weight":{"type":"float","example":5,"description":"Peso del paquete."},"days":{"type":"integer","example":2,"description":"Días de entrega."},"insurable":{"type":"boolean","example":true,"description":"Indicador de seguro."},"has_own_agreement":{"type":"boolean","example":false,"description":"Indicador de acuerdo propio."},"own_agreement_amount":{"type":"number","nullable":true,"description":"Monto del acuerdo propio."},"extra_fees":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"value":{"type":"string"}}},"nullable":true},"error_messages":{"type":"array","nullable":true},"zone":{"type":"string","nullable":true,"description":"Zona de la tarifa."},"plan_type":{"type":"string","nullable":true,"description":"Tipo de plan o acuerdo comercial aplicado a la cotización."},"packaging_type":{"type":"string","description":"Indica el tipo de embalaje requerido para el envío, ya sea caja (Package) o tarima (Pallet)."},"protection_value_total":{"type":"float","example":100,"description":"Valor de la protección total."},"total_value_with_protection":{"type":"float","example":100,"description":"Costo total del envío que incluye el total de la tarifa (costo del envío, IVA y cargo por servicio cuando aplica) más el valor de la protección."},"pickup":{"type":"boolean","example":true,"description":"Indica si la recolección está disponible para esta tarifa."},"pickup_automatic":{"type":"boolean","example":false,"description":"Indica si la recolección es automática para esta tarifa."},"pickup_package_min":{"type":"integer","example":1,"description":"Número mínimo de paquetes requeridos para la recolección."},"pickup_ocurre":{"type":"boolean","example":true,"description":"Indica si la recolección ocurre en origen (true) o en sucursal (false)."},"pickup_via_support":{"type":"boolean","example":true,"description":"Indica si la recolección via soporte esta disponible (true) o no (false)."},"shipment_creation_type":{"type":"string","example":"single","description":"El tipo de envío si es creado utilizando esta tarifa (single/multipackage/multishipment)."},"office_delivery":{"type":"boolean","example":false,"description":"Indica si esta tarifa admite entrega en oficina Ocurre (el destinatario recoge en una sucursal del paquetero)."},"office_pickup":{"type":"boolean","example":false,"description":"Indica si esta tarifa admite recolección en oficina Ocurre (el remitente entrega en una sucursal del paquetero)."},"requires_origin_verification":{"type":"boolean","example":false,"description":"Indica si el carrier requiere verificar la dirección de origen y la plantilla de origen aún no está verificada para ese carrier. Si es true, el shipment fallará al crearse hasta completar la verificación."},"customs_payment_payer":{"type":"array","nullable":true,"items":{"type":"string","enum":["sender","recipient"]},"example":["sender","recipient"],"description":"Lista de valores aceptados para `customs_payment_payer` al crear el envío con esta tarifa. Solo aplica a cotizaciones internacionales y contiene `sender`, `recipient` o ambos, según las restricciones del país de destino y del servicio del carrier."},"service_zone":{"type":"string","nullable":true,"description":"Área geográfica real para la que se está cotizando la tarifa."},"vat_fee":{"type":"string","nullable":true,"description":"Tasa de IVA."}}}},"address_template_from_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la plantilla de dirección de origen usada en la cotización (si aplica)."},"address_template_to_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la plantilla de dirección de destino usada en la cotización (si aplica)."},"requires_origin_verification":{"type":"boolean","example":false,"description":"Indica si alguna de las tarifas de la cotización requiere verificación de la dirección de origen."},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"integer","example":1,"description":"Número de índice del paquete cotizado."},"weight":{"type":"string","example":"2.0","description":"Peso del paquete."},"length":{"type":"string","example":"10.0","description":"Longitud del paquete."},"width":{"type":"string","example":"10.0","description":"Ancho del paquete."},"height":{"type":"string","example":"10.0","description":"Altura del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"description":"Declared value of the package."},"protection_value":{"type":"float","example":100,"description":"Valor de la protección del paquete"}}}},"overweight":{"type":"boolean","description":"Indicador de sobrepeso del paquete."}},"required":["id","is_completed","quotation_scope"]}}}},"422":{"description":"Retorna una respuesta de error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"address_from":{"type":"object","properties":{"postal_code":{"type":"array","items":{"type":"string"}},"area_level1":{"type":"array","items":{"type":"string"}},"area_level2":{"type":"array","items":{"type":"string"}},"area_level3":{"type":"array","items":{"type":"string"}}}},"address_to":{"type":"object","properties":{"postal_code":{"type":"array","items":{"type":"string"}},"area_level1":{"type":"array","items":{"type":"string"}},"area_level2":{"type":"array","items":{"type":"string"}},"area_level3":{"type":"array","items":{"type":"string"}}}},"parcel":{"type":"object","properties":{"weight":{"type":"array","items":{"type":"string"}},"length":{"type":"array","items":{"type":"string"}},"width":{"type":"array","items":{"type":"string"}},"height":{"type":"array","items":{"type":"string"}}}}}},"error":{"type":"string"}},"required":["error"]}}}},"400":{"description":"Retorna una respuesta de error (solicitud incorrecta)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Cotización Nacional (MX)","properties":{"quotation":{"type":"object","properties":{"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_from."},"country_code":{"type":"string","example":"MX","minLength":2,"maxLength":2,"description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_to."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del destinatario."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3"]},"parcels":{"type":"array","items":{"type":"object","properties":{"length":{"type":"integer","example":10,"minimum":1,"description":"Longitud del paquete."},"width":{"type":"integer","example":10,"minimum":1,"description":"Ancho del paquete."},"height":{"type":"integer","example":10,"minimum":1,"description":"Altura del paquete."},"weight":{"type":"float","example":2,"minimum":1,"description":"Peso del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"description":"Declared value of the package."}},"required":["length","width","height","weight"]}},"requested_carriers":{"type":"array","items":{"type":"string","example":["fedex","dhl"],"description":"Paqueterías a cotizar. Consulta los Códigos de paqueterías en el menú lateral izquierdo de esta documentación."}}},"required":["address_from","address_to","parcels"]}}},{"type":"object","title":"Cotización Internacional","properties":{"quotation":{"type":"object","properties":{"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_from."},"country_code":{"type":"string","example":"MX","minLength":2,"maxLength":2,"description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_to."},"country_code":{"type":"string","example":"US","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"11201","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"New York","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Brooklyn","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Kings County","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["country_code","postal_code","area_level1","area_level2"]},"parcels":{"type":"array","items":{"type":"object","properties":{"length":{"type":"integer","example":10,"minimum":1,"description":"Longitud del paquete."},"width":{"type":"integer","example":10,"minimum":1,"description":"Ancho del paquete."},"height":{"type":"integer","example":10,"minimum":1,"description":"Altura del paquete."},"weight":{"type":"float","example":2,"minimum":1,"description":"Peso del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"minimum":1,"description":"Declared value of the package."},"products":{"type":"array","items":{"type":"object","properties":{"hs_code":{"type":"string","example":"3407.002000","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"description_en":{"type":"string","example":"Medicine for children","description":"Descripción del producto en inglés."},"country_code":{"type":"string","example":"US","description":"Código de país del producto (ISO 3166-1 alpha-2)."},"quantity":{"type":"integer","example":1,"description":"Cantidad del producto."},"price":{"type":"float","example":100.0,"description":"Precio del producto."}},"required":["hs_code","description_en","country_code","quantity","price"]}}},"required":["length","width","height","weight","products"]}},"requested_carriers":{"type":"array","items":{"type":"string","example":["fedex","dhl"],"description":"Paqueterías a cotizar. Consulta los Códigos de paqueterías en el menú lateral izquierdo de esta documentación."}}},"required":["address_from","address_to","parcels"]}}}]}}}}}},"/api/v1/quotations/{id}":{"get":{"summary":"Obtiene una cotización","tags":["Cotizaciones"],"description":"```\n   GET /api/v1/quotations/{id}\n```\n   Cuando el estado de la cotización (`status`) es `is_completed`, el proceso de cotización ha terminado y se obtienen los resultados de las tarifas creadas con los datos del paso anterior.\n\n   **Parámetros de la solicitud:**\n   - `id`: El parámetro que obtuviste del endpoint de cotizaciones (POST /api/v1/quotations) se agrega en esta sección\n","parameters":[{"name":"id","in":"path","description":"ID de la Cotización","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cotización encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"ID de la cotización."},"is_completed":{"type":"boolean","example":true,"description":"Estado de finalización del procesamiento de la cotización. Si es `false`, aún está en proceso y las tarifas todavía no están disponibles. Si es `true`, el procesamiento terminó y las tarifas ya están disponibles."},"quotation_scope":{"type":"object","oneOf":[{"properties":{"carriers_scoped_to":{"type":"string","enum":["ALL_AVAILABLE","PARTIALLY_SELECTED_CARRIERS"],"example":"ALL_AVAILABLE","description":"Paqueterías cotizadas (todas las paqueterías `ALL_AVAILABLE`)(paqueterías seleccionadas `PARTIALLY_SELECTED_CARRIERS`)"}}},{"properties":{"carriers_scoped_to":{"type":"string","enum":["ALL_AVAILABLE","PARTIALLY_SELECTED_CARRIERS"],"example":"ALL_AVAILABLE","description":"Paqueterías cotizadas (todas las paqueterías `ALL_AVAILABLE`)(paqueterías seleccionadas `PARTIALLY_SELECTED_CARRIERS`)"},"found_carriers":{"type":"array","items":{"type":"string","description":"Paqueterías encontradas."}},"not_found_carriers":{"type":"array","items":{"type":"string","description":"Paqueterías no encontradas."}}}}],"required":["carriers_scoped_to"]},"rates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"ID de la tarifa."},"success":{"type":"boolean","example":true,"description":"Indica si la cotización con la paquetería tuvo éxito. Con `true` se obtuvo una tarifa válida; con `false` no se pudo generar una tarifa para los parámetros proporcionados."},"rate_type":{"type":"string","nullable":true,"description":"Tipo de tarifa."},"country_code":{"type":"string","nullable":true,"example":"mx","description":"Código de país de la dirección."},"provider_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería."},"provider_display_name":{"type":"string","example":"FedEx","description":"Nombre para mostrar de la paquetería."},"provider_service_name":{"type":"string","example":"Standard Overnight","description":"Nombre del servicio de la paquetería."},"provider_service_code":{"type":"string","example":"standard_overnight","description":"Código del servicio de la paquetería."},"status":{"type":"string","example":"pending","description":"Estado de la tarifa (Tarifa pendiente `pending`)(Tafira no aplica `not_applicable`)(Tarifa encontrada `approved`)(Tarifa sin cobertura `no_coverage`)(Tarifa con cobertura comprobada `coverage_checked`)(Tarifa encontrada `price_found_internal`)(Tarifa encontrada `price_found_external`)(Tarifa sin precio `tariff_price_not_found`)"},"currency_code":{"type":"string","example":"MXN","description":"Código de moneda."},"amount":{"type":"string","example":150.0,"description":"Monto de la tarifa."},"total":{"type":"string","example":150.0,"description":"Total de la tarifa."},"service_fee":{"type":"float","example":15.0,"nullable":true,"description":"Tarifa de gestión."},"weight":{"type":"float","example":5,"description":"Peso del paquete."},"days":{"type":"integer","example":2,"description":"Días de entrega."},"insurable":{"type":"boolean","example":true,"description":"Indicador de seguro."},"has_own_agreement":{"type":"boolean","example":false,"description":"Indicador de acuerdo propio."},"own_agreement_amount":{"type":"number","nullable":true,"description":"Monto del acuerdo propio."},"extra_fees":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"value":{"type":"string"}}},"nullable":true},"error_messages":{"type":"array","nullable":true},"zone":{"type":"string","nullable":true,"description":"Zona de la tarifa."},"service_zone":{"type":"string","nullable":true,"description":"Área geográfica real para la que se está cotizando la tarifa."},"vat_fee":{"type":"string","nullable":true,"description":"Tasa de IVA."},"plan_type":{"type":"string","nullable":true,"description":"Tipo de plan o acuerdo comercial aplicado a la cotización."},"packaging_type":{"type":"string","description":"Indica el tipo de embalaje requerido para el envío, ya sea caja (Package) o tarima (Pallet)."},"protection_value_total":{"type":"float","example":100,"description":"Valor de la protección total."},"total_value_with_protection":{"type":"float","example":100,"description":"Costo total del envío que incluye el total de la tarifa (costo del envío, IVA y cargo por servicio cuando aplica) más el valor de la protección."},"pickup":{"type":"boolean","example":true,"description":"Indica si la recolección está disponible para esta tarifa."},"pickup_automatic":{"type":"boolean","example":false,"description":"Indica si la recolección es automática para esta tarifa."},"pickup_package_min":{"type":"integer","example":1,"description":"Número mínimo de paquetes requeridos para la recolección."},"pickup_ocurre":{"type":"boolean","example":true,"description":"Indica si la recolección ocurre en origen (true) o en sucursal (false)."},"pickup_via_support":{"type":"boolean","example":true,"description":"Indica si la recolección via soporte esta disponible (true) o no (false)."},"shipment_creation_type":{"type":"string","example":"single","description":"El tipo de envío si es creado utilizando esta tarifa (single/multipackage/multishipment)."},"office_delivery":{"type":"boolean","example":false,"description":"Indica si esta tarifa admite entrega en oficina Ocurre (el destinatario recoge en una sucursal del paquetero)."},"office_pickup":{"type":"boolean","example":false,"description":"Indica si esta tarifa admite recolección en oficina Ocurre (el remitente entrega en una sucursal del paquetero)."},"requires_origin_verification":{"type":"boolean","example":false,"description":"Indica si el carrier requiere verificar la dirección de origen y la plantilla de origen aún no está verificada para ese carrier. Si es true, el shipment fallará al crearse hasta completar la verificación."}}}},"address_template_from_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la plantilla de dirección de origen usada en la cotización (si aplica)."},"address_template_to_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la plantilla de dirección de destino usada en la cotización (si aplica)."},"requires_origin_verification":{"type":"boolean","example":false,"description":"Indica si alguna de las tarifas de la cotización requiere verificación de la dirección de origen."},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"integer","example":1,"description":"Número de índice del paquete cotizado."},"weight":{"type":"string","example":"2.0","description":"Peso del paquete."},"length":{"type":"string","example":"10.0","description":"Longitud del paquete."},"width":{"type":"string","example":"10.0","description":"Ancho del paquete."},"height":{"type":"string","example":"10.0","description":"Altura del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"description":"Declared value of the package."},"protection_value":{"type":"float","example":100,"description":"Valor de la protección del paquete"}}}}},"required":["id","is_completed","quotation_scope"]}}}},"404":{"description":"Cotización no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"/api/v1/rate/shipments/":{"post":{"summary":"Crear un envío sin cotizar","tags":["Envíos"],"description":"Crea un envío directamente sin una cotización previa. El cálculo del precio se realiza internamente con los parámetros de tu solicitud.\n\n**Consideraciones**\n\n- **Cobertura**: te recomendamos cotizar siempre tus envíos para confirmar la cobertura de la paquetería y evitar errores en la creación o en la entrega.\n- **Tiempos de espera**: si la petición excede el tiempo límite mientras el envío se está creando, no reintentes el POST. Usa el endpoint GET para consultar el estado del envío y obtener la guía generada.\n","parameters":[],"responses":{"201":{"description":"Retorna el envío creado","content":{"application/json":{"schema":{"type":"object","required":["id","status","rate","packages"],"properties":{"id":{"type":"string","format":"uuid","example":"73783895-147e-40f6-83d8-5f901d71a1a3"},"status":{"type":"string","example":"success"},"master_tracking_number":{"type":"string","nullable":true,"example":"1234567890"},"label_url":{"type":"string","nullable":true,"example":"https://label.com"},"order_detail_url":{"type":"string","nullable":true,"example":"https://api.example.com/rails/active_storage/blobs/.../order_details.pdf","description":"URL al PDF del detalle de la orden (packing slip). Se completa cuando `include_order_detail: true` fue enviado en el request y el documento se generó correctamente. `null` en caso contrario.\n"},"rate":{"type":"object","required":["success","id","provider_name","provider_display_name","provider_service_name","provider_service_code","status","currency_code","amount","total","days","insurable","has_own_agreement","extra_fees","packaging_type","weight","protection_value_total","total_value_with_protection","pickup","pickup_automatic","pickup_package_min","pickup_ocurre","pickup_via_support","shipment_creation_type"],"properties":{"success":{"type":"boolean","example":false},"id":{"type":"string","format":"uuid","example":"38ed719c-6a21-4b15-9ef3-d2bdce374018"},"rate_type":{"type":"string","nullable":true,"example":"standard"},"provider_name":{"type":"string","example":"medrano santillán s.r.l chad"},"provider_display_name":{"type":"string","example":"Ups"},"provider_service_name":{"type":"string","example":"Medrano Santillán S.R.L Chad Bronze"},"provider_service_code":{"type":"string","example":"MEDRANO_SANTILLAN_S_R_L_CHAD_BRONZE"},"status":{"type":"string","example":"pending"},"currency_code":{"type":"string","example":"MXN"},"amount":{"type":"string","example":"9.99"},"total":{"type":"string","example":"100"},"days":{"type":"integer","example":1},"insurable":{"type":"boolean","example":false},"has_own_agreement":{"type":"boolean","example":false},"own_agreement_amount":{"type":"string","nullable":true,"example":"50.00"},"extra_fees":{"type":"array","items":{"type":"object"},"example":[]},"zone":{"type":"string","nullable":true},"service_zone":{"type":"string","nullable":true},"vat_fee":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"example":"MX"},"plan_type":{"type":"string","nullable":true},"packaging_type":{"type":"string","example":"package"},"error_messages":{"type":"array","nullable":true,"items":{"type":"string"}},"weight":{"type":"string","example":"0.0"},"protection_value_total":{"type":"string","example":"0.0"},"total_value_with_protection":{"type":"number","format":"float","example":0.0},"pickup":{"type":"boolean","example":false},"pickup_automatic":{"type":"boolean","example":false},"pickup_package_min":{"type":"integer","example":1},"pickup_ocurre":{"type":"boolean","example":false},"pickup_via_support":{"type":"boolean","example":false},"shipment_creation_type":{"type":"string","nullable":true,"example":"single"},"office_delivery":{"type":"boolean","example":false},"office_pickup":{"type":"boolean","example":false},"requires_origin_verification":{"type":"boolean","example":false},"import_duty_amount":{"type":"string","nullable":true},"customs_payment_payer":{"type":"array","nullable":true,"items":{"type":"string","enum":["sender","recipient"]},"example":["sender","recipient"]}}},"error_message_detail":{"type":"string","nullable":true,"example":"Invalid token"},"packages":{"type":"array","items":{"type":"object"},"example":[]}}}}}},"400":{"description":"Retorna una respuesta de error"},"422":{"description":"Retorna una respuesta de error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Envío nacional (MX)","properties":{"timeout":{"type":"integer","example":8,"description":"Tiempo de espera en segundos."},"sync_label_creation":{"required":false,"type":"boolean","example":true,"description":"Opcional. Cuando es `true`, la guía se solicita a la paquetería durante la misma petición y la respuesta ya trae el estado final, en lugar de resolverse de forma asíncrona. Reduce el tiempo de respuesta; si se omite, el envío se procesa como hasta ahora."},"quotation":{"type":"object","properties":{"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"thermal"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"carrier":{"type":"object","properties":{"name":{"type":"string","example":"Nombre de la paquetería en minúscula","description":"Nombre de la paquetería"},"service_name":{"type":"string","example":"Código del servicio","description":"Nombre del servicio"}}},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"68000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Oaxaca","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"68000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Oaxaca","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["name","company","phone","email"]},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","example":5,"description":"Peso del paquete"},"height":{"type":"integer","example":5,"description":"Altura del paquete"},"width":{"type":"integer","example":5,"description":"Ancho del paquete"},"length":{"type":"integer","example":5,"description":"Longitud del paquete"},"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"}},"required":["weight","height","width","length"]}}},"required":["address_from","address_to","parcels"]}}},{"type":"object","title":"Envío internacional","properties":{"timeout":{"type":"integer","example":8,"description":"Tiempo de espera en segundos."},"sync_label_creation":{"required":false,"type":"boolean","example":true,"description":"Opcional. Cuando es `true`, la guía se solicita a la paquetería durante la misma petición y la respuesta ya trae el estado final, en lugar de resolverse de forma asíncrona. Reduce el tiempo de respuesta; si se omite, el envío se procesa como hasta ahora."},"quotation":{"type":"object","properties":{"customs_payment_payer":{"type":"string","description":"Entidad que pagará los aranceles del envío. Puede ser `sender` o `recipient`.","enum":["sender","recipient"],"example":"sender"},"shipment_purpose":{"type":"string","description":"Propósito del envío (`goods`, `documents`, `sample`, `return_of_goods`, `gift` o `humanitarian_donation`).","enum":["goods","documents","sample","return_of_goods","gift","humanitarian_donation"],"example":"goods"},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"standard"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"carrier":{"type":"object","properties":{"name":{"type":"string","example":"Nombre de la paquetería en minúscula","description":"Nombre de la paquetería"},"service_name":{"type":"string","example":"Código del servicio","description":"Nombre del servicio"}}},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"68000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Oaxaca","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3","name","company","phone","email"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"US","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"33326","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Florida","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"Weston","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"Weston","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3","name","company","phone","email"]},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","example":5,"description":"Peso del paquete"},"height":{"type":"integer","example":5,"description":"Altura del paquete"},"width":{"type":"integer","example":5,"description":"Ancho del paquete"},"length":{"type":"integer","example":5,"description":"Longitud del paquete"},"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Producto 1","description":"Nombre del producto"},"description_en":{"type":"string","example":"Product description","description":"Descripción en inglés"},"quantity":{"type":"integer","example":1,"description":"Cantidad"},"price":{"type":"number","example":100.0,"description":"Precio en pesos mexicanos"},"sku":{"type":"string","example":"SKU-123","description":"SKU"},"hs_code":{"type":"string","example":"9706.900060","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"hs_code_description":{"type":"string","example":"Descripción del HS Code","description":"Descripción del código Harmonizado"},"product_type_code":{"type":"string","example":"P","description":"Código de tipo de producto"},"product_type_name":{"type":"string","example":"Producto","description":"Nombre del tipo de producto"},"country_code":{"type":"string","example":"MX","description":"Código de país en ISO 3166-1 alpha-2"}},"required":["name","hs_code","description_en"]}}},"required":["weight","height","width","length","products"]}}},"required":["customs_payment_payer","shipment_purpose","address_from","address_to","parcels"]}}}]}}}}}},"/api/v1/settings/printing_formats":{"patch":{"summary":"Actualiza el formato de impresión","tags":["Opciones de impresión"],"description":"Establece el formato de impresión según el tipo de impresora que se utilice.","parameters":[],"responses":{"202":{"description":"Solicitud aceptada."},"422":{"description":"Solicitud inválida.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","example":"Formato de impresión inválido"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"printing_format":{"required":true,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"standard"}}}}}}}},"/api/v1/shipments/{shipment_id}/cancellations":{"post":{"summary":"Cancelar un envío","tags":["Envíos"],"description":"Este endpoint permite cancelar un envío.","parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Retorna la cancelcación del envío","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la cancelación"},"reason":{"type":"string","example":"Ya no es necesario","description":"Razón de la cancelación"},"status":{"type":"string","example":"approved","description":"Estado de la cancelación"},"success":{"type":"boolean","example":true,"description":"Indicador de éxito"}}}}}},"422":{"description":"El envío no se puede cancelar","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Envío no encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","example":"Ya no es necesario","description":"Razón de la cancelación."},"shipment_id":{"type":"string","example":12345,"description":"Id o número de rastreo del envío."}}}}}}}},"/api/v1/shipments/carrier_services":{"get":{"summary":"Obtiene todos los servicios","tags":["Envíos"],"description":"```\n   GET /api/v1/shipments/carrier_services\n```\n   Este endpoint obtiene todos los servicios de paquetería disponibles.\n\n   **Parámetros de la solicitud:**","parameters":[{"name":"page","in":"query","type":"integer","required":false,"description":"Número de página a obtener","schema":{"type":"integer","example":1}},{"name":"per_page","in":"query","type":"integer","required":false,"description":"Número de elementos por página (máx 20, por defecto 20)","schema":{"type":"integer","example":5}}],"responses":{"200":{"description":"Retorna una colección de servicios","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería"},"service_name":{"type":"string","example":"standard_overnight","description":"Nombre del servicio de la paquetería"},"service_code":{"type":"string","example":"standard_overnight","description":"Código único del servicio de la paquetería"},"min_delivery_packages":{"type":"integer","nullable":true,"example":1,"description":"Número mínimo de paquetes para entrega"},"is_national":{"type":"boolean","example":true,"description":"Si el servicio es nacional"},"volumetric_weight_formula":{"type":"string","example":"(height * width * length) / 5000.00","description":"Fórmula utilizada para calcular el peso volumétrico"},"has_pickup":{"type":"boolean","example":false,"description":"Si el servicio soporta recolección"},"multi_packages_enabled":{"type":"boolean","example":false,"description":"Si el servicio soporta múltiples paquetes"},"is_ltl":{"type":"boolean","example":false,"description":"Si el servicio es de carga parcial"},"package_type":{"type":"string","example":"package","description":"Tipo de paquete soportado"},"has_reschedule_pick":{"type":"boolean","example":true,"description":"Si el servicio soporta reprogramación de recolección"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":1},"total_count":{"type":"integer","example":5}}}}}}}}}}},"/api/v1/shipments/consignment_notes":{"get":{"summary":"Obtiene todas las carta porte","tags":["Envíos"],"description":"```\n   GET /api/v1/shipments/consignment_notes\n```\n  El endpoint se utiliza para obtener todas las carta porte.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","required":false,"description":"Número de página a obtener","schema":{"type":"integer","example":1}},{"name":"per_page","in":"query","required":false,"description":"Número de elementos por página (máx 20, por defecto 20)","schema":{"type":"integer","example":5}},{"name":"consignment_note","in":"query","required":false,"description":"Filtra por código exacto de carta porte (opcional). Ej. `?consignment_note=20142200`.","schema":{"type":"string","example":20142200}},{"name":"description","in":"query","required":false,"description":"Filtra por descripción; coincidencia parcial sin distinguir mayúsculas ni acentos (opcional). Ej. `?description=calentadores`.","schema":{"type":"string","example":"camisas"}}],"responses":{"200":{"description":"Retorna una colección de carta porte","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"consignment_note":{"type":"integer","example":20142200},"description":{"type":"string","example":"Calentadores de linea"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":2},"next_page":{"type":"integer","nullable":true,"example":3},"prev_page":{"type":"integer","nullable":true,"example":1},"total_pages":{"type":"integer","example":3},"total_count":{"type":"integer","example":8}}}}}}}}}}},"/api/v1/shipments/package_templates":{"get":{"summary":"Obtiene los paquetes guardados de la cuenta","tags":["Envíos"],"description":"```\n   GET /api/v1/shipments/package_templates\n```\n   Este endpoint obtiene los paquetes guardados de la cuenta (\"Mis paquetes\"), con su empaque, medidas y peso, ordenados del más usado al menos usado.\n\n   **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","type":"integer","required":false,"description":"Número de página a obtener","schema":{"type":"integer","example":1}},{"name":"per_page","in":"query","type":"integer","required":false,"description":"Número de elementos por página (máx 20, por defecto 20)","schema":{"type":"integer","example":20}},{"name":"name","in":"query","required":false,"description":"Busca por nombre, tipo de empaque o contenido (opcional). Ej. `?name=caja`.","schema":{"type":"string","example":"caja"}}],"responses":{"200":{"description":"Retorna una colección de paquetes guardados","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"7d7c5b3e-2f1a-4c9e-9a41-5b2f6c8e1d20","description":"Identificador del paquete guardado"},"name":{"type":"string","example":"Caja chica","description":"Nombre del paquete guardado"},"package_type":{"type":"string","example":"4G","description":"Código del tipo de empaque"},"length":{"type":"number","example":30,"description":"Largo en centímetros"},"width":{"type":"number","example":20,"description":"Ancho en centímetros"},"height":{"type":"number","example":15,"description":"Alto en centímetros"},"weight":{"type":"number","example":2,"description":"Peso en kilogramos"},"consignment_note":{"type":"string","nullable":true,"example":"53111600","description":"Clave de producto de la Carta Porte"},"package_content":{"type":"string","nullable":true,"example":null,"description":"Descripción del contenido del paquete"},"declared_value":{"type":"number","nullable":true,"example":1500.0,"description":"Valor declarado del paquete"},"default":{"type":"boolean","example":false,"description":"Si es el paquete predeterminado de la cuenta"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":1},"total_count":{"type":"integer","example":5}}}}}}}}}}},"/api/v1/shipments/packagings":{"get":{"summary":"Obtiene todos los tipos de empaque","tags":["Envíos"],"description":"```\n   GET /api/v1/shipments/packagings\n```\n   Este endpoint obtiene todos los tipos de empaque disponibles.\n\n   **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","type":"integer","required":false,"description":"Número de página a obtener","schema":{"type":"integer","example":1}},{"name":"per_page","in":"query","type":"integer","required":false,"description":"Número de elementos por página (máx 20, por defecto 20)","schema":{"type":"integer","example":20}},{"name":"code","in":"query","required":false,"description":"Filtra por código exacto del tipo de empaque (opcional). Ej. `?code=4G`.","schema":{"type":"string","example":"4G"}},{"name":"name","in":"query","required":false,"description":"Filtra por nombre; coincidencia parcial sin distinguir mayúsculas ni acentos, considerando traducciones (opcional). Ej. `?name=caja`.","schema":{"type":"string","example":"caja"}}],"responses":{"200":{"description":"Retorna una colección de tipos de empaque","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"4G","description":"Código del tipo de empaque"},"name":{"type":"string","example":"Box","description":"Nombre del tipo de empaque"}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":1},"total_count":{"type":"integer","example":5}}}}}}}}}}},"/api/v1/shipments/{shipment_id}/protect":{"post":{"summary":"Protege un envío","tags":["Envíos"],"description":"Este endpoint permite proteger un envío.","parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Retorna la información de la protección del envío","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"681ddd3e-4fc5-4c15-bfed-f9f4224e8095"},"type":{"type":"string","example":"protect"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"681ddd3e-4fc5-4c15-bfed-f9f4224e8095"},"declared_value":{"type":"string","example":1000,"description":"Valor declarado del envío"},"total":{"type":"string","example":110,"description":"Costo total de la protección del envío"},"fixed_cost":{"type":"string","example":10,"description":"Costo fijo del envío"},"percentage":{"type":"number","example":10,"description":"Costo porcentaje del envío"},"created_at":{"type":"string","example":"2024-10-09 13:38:33","description":"Fecha de creación de la protección"},"updated_at":{"type":"string","example":"2024-10-09 13:38:33","description":"Fecha de actualización de la protección"},"shipment_id":{"type":"string","example":"7f433cf4-e54a-4294-b421-1522cd377c12","description":"UUID del envío"}}}}}},"required":["data"]}}}},"422":{"description":"El envío no se puede proteger","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"string","example":"Valor declarado debe estar entre 100.0 y 500.0"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"protect":{"type":"object","properties":{"declared_value":{"type":"string","required":true,"example":1000,"description":"Valor declarado del envío"}}},"shipment_id":{"type":"string","required":true,"example":"7f433cf4-e54a-4294-b421-1522cd377c12","description":"UUID del envío"}},"required":["protect"]}}}}}},"/api/v1/shipments/tracking?tracking_number={tracking_number}&carrier_name={carrier_name}":{"get":{"summary":"Rastrea un envío","tags":["Envíos"],"description":"Permite consultar el estado y el rastreo de un envío en tiempo real. Los eventos y estados mostrados dependen de la información que reporta la paquetería.","parameters":[{"name":"tracking_number","in":"path","required":true,"schema":{"type":"string"}},{"name":"carrier_name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna la lista de los eventos ocurridos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del evento de rastreo"},"type":{"type":"string","description":"Tipo de registro"},"attributes":{"type":"object","properties":{"description":{"type":"string","example":"EN RUTA DE ENTREGA","description":"Descripción del estado"},"location":{"type":"string","example":"CORDOBA","description":"Ubicación donde ocurrio el evento"},"date":{"type":"string","format":"date-time","example":"2024-09-05T23:13:00","description":"Fecha del evento"},"status":{"type":"string","example":"last_mile","description":"Código del estado"},"event_description":{"type":"string","example":"En ruta de entrega - Cordoba","description":"Descripción del evento informada por el carrier; coincide con la enviada por el webhook del envío."}}}}}}}}}},"404":{"description":"Este número de guía no cuenta con eventos de rastreo","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/shipments/tracking":{"post":{"summary":"Reportar evento de tracking","tags":["Envíos Externos"],"description":"Reporta un evento de tracking para un envío gestionado por tu flota propia\n(Logística Propia). Cada llamada registra un evento nuevo, ejecuta la transición\ndel estado del paquete y dispara las notificaciones configuradas (WhatsApp,\ncorreo, plataforma de ecommerce). Requiere flota propia activa en la cuenta.\n","parameters":[],"responses":{"202":{"description":"Evento de tracking aceptado y encolado para procesamiento","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","example":"queued","description":"Estado del procesamiento del job (`queued` cuando se acepta)."},"tracking_number":{"type":"string","example":"TRK-MX-1234567890","description":"Número de rastreo del envío gestionado por tu flota propia."},"carrier_custom_code":{"type":"string","example":"mi_flota","description":"Código del carrier de tu flota propia (`name` definido al registrarlo)."},"tracking_status":{"type":"string","example":"in_transit","description":"Estado de tracking reportado en la solicitud, devuelto como confirmación."}}}}}}}},"422":{"description":"No se encontró un envío con ese número de rastreo para el carrier indicado"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking"],"properties":{"tracking":{"type":"object","description":"Datos del evento de tracking a reportar.","required":["tracking_number","carrier_custom_code","status"],"properties":{"tracking_number":{"type":"string","example":"TRK-MX-1234567890","description":"Número de rastreo del envío gestionado por tu flota propia."},"carrier_custom_code":{"type":"string","example":"mi_flota","description":"Código del carrier de tu flota propia (`name` definido al registrarlo)."},"status":{"type":"string","enum":["created","picked_up","in_transit","last_mile","delivery_attempt","delivered_to_branch","delivered","exception","in_return","canceled","destroyed","retained"],"example":"in_transit","description":"Estado a reportar — `created`, `picked_up`, `in_transit`, `last_mile`, `delivery_attempt`, `delivered_to_branch`, `delivered`, `exception`, `in_return`, `canceled`, `destroyed`, `retained`."}}}}}}}}}},"/api/v1/shipments":{"get":{"summary":"Recupera todos los envíos","tags":["Envíos"],"description":"Este endpoint recupera todos los envíos, paginados de diez en diez.","parameters":[{"name":"page","in":"query","required":false,"description":"Número de página a obtener","schema":{"type":"integer","example":1}},{"name":"ids","in":"query","required":false,"description":"Lista de IDs de envíos a recuperar, separados por comas. Si no se proporcionan, se recuperarán todos los envíos.","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Retorna una colección de envíos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío"},"carrier_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería"},"workflow_status":{"type":"string","example":"pending","description":"Estado del envío"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago"},"total":{"type":"string","example":"38.20","description":"Costo total del envío"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)"},"carrier_id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la paquetería"},"service_id":{"type":"string","example":"standart_overnight","nullable":true,"description":"UUID del servicio"},"master_tracking_number":{"type":"string","example":"234234234233","nullable":true,"description":"Número de rastreo"},"original_shipment_id":{"type":"string","example":"0199977a-e032-78bf-a335-00a9ae3cfdff","nullable":true,"description":"ID del envío original."},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"Dirección de destino no válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://example.com/order_detail.pdf","description":"Translation missing: es.swagger.shipments.show.response_params.attributes.order_detail_url"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del paquete"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"weight":{"type":"string","example":1,"description":"Peso del paquete"},"length":{"type":"string","example":1,"description":"Longitud del paquete"},"width":{"type":"string","example":1,"description":"Ancho del paquete"},"height":{"type":"string","example":1,"description":"Altura del paquete"},"consignment_note":{"type":"string","example":53102400,"description":"Carta porte ID"},"package_content":{"type":"string","nullable":true},"tracking_url_provider":{"type":"string","example":"https://www.fedex.com/fedextrack/?trknbr=234234234233","description":"URL de seguimiento"},"tracking_status":{"type":"string","nullable":true,"tracking_status":"created","description":"Estado de seguimiento"},"tracking_number":{"type":"string","example":123123123123,"description":"Número de seguimiento"},"label_url":{"type":"string","nullable":true,"example":"https://label.com","description":"URL de la guía"},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","example":"to","description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección"},"apartment_number":{"type":"string","nullable":true,"description":"Número de departamento"},"further_information":{"type":"string","nullable":true,"description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}}]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":2},"next_page":{"type":"integer","nullable":true,"example":3},"prev_page":{"type":"integer","nullable":true,"example":1},"total_pages":{"type":"integer","example":3},"total_count":{"type":"integer","example":8}}}}}}}}}}},"/api/v1/shipments/{id}":{"get":{"summary":"Recupera un envío","tags":["Envíos"],"description":"Recupera un envío","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna un envío","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío"},"carrier_name":{"type":"string","example":"FEDEX","description":"Nombre de la paquetería"},"workflow_status":{"type":"string","example":"success","description":"Estado del envío"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago"},"total":{"type":"string","example":"500.0","description":"Costo total del envío"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)"},"carrier_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID de la paquetería"},"service_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID del servicio"},"master_tracking_number":{"type":"string","nullable":true,"example":"234234234233","description":"Número de rastreo"},"original_shipment_id":{"type":"string","nullable":true,"example":"0199977a-e032-78bf-a335-00a9ae3cfdff","description":"ID del envío original."},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://example.com/order_detail.pdf","description":"Translation missing: es.swagger.shipments.show.response_params.attributes.order_detail_url"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID del paquete"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"weight":{"type":"string","example":"1","description":"Peso del paquete"},"length":{"type":"string","example":"1","description":"Longitud del paquete"},"width":{"type":"string","example":"1","description":"Ancho del paquete"},"height":{"type":"string","example":"1","description":"Altura del paquete"},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_content":{"type":"string","nullable":true},"tracking_url_provider":{"type":"string","example":"https://www.fedex.com/fedextrack/?trknbr=234234234233","description":"URL de seguimiento"},"tracking_status":{"type":"string","nullable":true,"example":"created","description":"Estado de seguimiento"},"tracking_number":{"type":"string","example":234234234233,"description":"Número de seguimiento"},"label_url":{"type":"string","nullable":true,"example":"https://label.com","description":"URL de la guía"},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","description":"UUID de la dirección","example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","example":"to","description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección"},"apartment_number":{"type":"string","nullable":true,"description":"Número de departamento"},"further_information":{"type":"string","nullable":true,"description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}}]}}}}}}},"404":{"description":"Retorna un mensaje de no encontrado","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"El recurso buscado no se pudo encontrar."}}}}}}}}},"/api/v1/shipments/":{"post":{"summary":"Crea un envío","tags":["Envíos"],"description":"Este endpoint permite crear un envío, usando la cotización creada (POST /api/v1/quotations) y obtenida previamente (GET /api/v1/quotations/{id}).","parameters":[],"responses":{"202":{"description":"Retorna el envío creado","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío\n"},"type":{"type":"string","description":"Tipo de envío\n"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío\n"},"carrier_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería\n"},"workflow_status":{"type":"string","example":"pending","description":"Estado del envío\n"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago\n"},"total":{"type":"string","example":"38.20","description":"Costo total del envío\n"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)\n"},"carrier_id":{"type":"string","nullable":true,"example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la paquetería\n"},"service_id":{"type":"string","nullable":true,"example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del servicio\n"},"master_tracking_number":{"type":"string","example":"1234567890","nullable":true,"description":"Número de rastreo\n"},"original_shipment_id":{"type":"string","example":"0199977a-e032-78bf-a335-00a9ae3cfdff","nullable":true,"description":"ID del envío original.\n"},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación\n"},"updated_at":{"type":"string","description":"Fecha de actualización\n"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla\n","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://api.example.com/rails/active_storage/blobs/.../order_details.pdf","description":"URL al PDF del detalle de la orden (packing slip). Se completa cuando `include_order_detail: true` fue enviado en el request y el documento se generó correctamente. `null` en caso contrario.\n"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del paquete\n"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete\n"},"weight":{"type":"string","example":1,"description":"Peso del paquete\n"},"length":{"type":"string","example":1,"description":"Longitud del paquete\n"},"width":{"type":"string","example":1,"description":"Ancho del paquete\n"},"height":{"type":"string","example":1,"description":"Altura del paquete\n"},"consignment_note":{"type":"string","example":53102400,"description":"Carta porte ID\n"},"package_content":{"type":"string","nullable":true},"tracking_url_provider":{"type":"string","nullable":true,"example":"https://www.fedex.com/fedextrack/?trknbr=234234234233","description":"URL de seguimiento\n"},"tracking_status":{"type":"string","nullable":true,"example":"created","description":"Estado de seguimiento\n"},"tracking_number":{"type":"string","nullable":true,"example":123123123123,"description":"Número de seguimiento\n"},"label_url":{"type":"string","nullable":true,"example":"https://label.com","description":"URL de la guía\n"},"created_at":{"type":"string","description":"Fecha de creación\n"},"updated_at":{"type":"string","description":"Fecha de actualización\n"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección\n"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección\n"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección\n"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente\n"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección\n"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección\n"},"address_type":{"type":"string","example":"to","description":"Tipo de dirección\n"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección\n"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa\n"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono\n"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico\n"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección\n"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección\n"},"apartment_number":{"type":"string","nullable":true,"description":"Número de departamento\n"},"further_information":{"type":"string","nullable":true,"description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería.\n"},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}}]}}}}}}},"422":{"description":"Retorna una respuesta de error","content":{"Insufficient Funds":{"examples":{"example_0":{"value":{"errors":"No tienes los créditos suficientes para este envío. Agrega créditos y continúa."}}}},"Unsupported Format":{"examples":{"example_1":{"value":{"errors":{"printing_format":["Formato de impresión no soportado"]}}}}},"Invalid Structure":{"examples":{"example_2":{"value":{"errors":{"consignment_note":["No puede estar en blanco"],"package_type":["No puede estar en blanco"],"address_from":["No puede estar en blanco"],"address_to":["No puede estar en blanco"]}}}}},"Rate not found":{"examples":{"example_3":{"value":{"errors":{"rate_id":["no existe un rate con ese id"]}}}}},"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"errors":{"type":"string","example":"Fondos insuficientes"}}},{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","properties":{"printing_format":{"type":"array","items":{"type":"string","example":"Formato de impresión inválido"}}}}}},{"type":"object","properties":{"errors":{"type":"object","properties":{"consignment_note":{"type":"array","items":{"type":"string","example":"no puede estar en blanco"}},"package_type":{"type":"array","items":{"type":"string","example":"no puede estar en blanco"}},"address_from":{"type":"array","items":{"type":"string","example":"no puede estar en blanco"}},"address_to":{"type":"array","items":{"type":"string","example":"no puede estar en blanco"}}}}}},{"type":"object","properties":{"errors":{"type":"object","properties":{"rate_id":{"type":"array","items":{"type":"string","example":"no existe un rate con ese id"}}}}}},{"type":"object","properties":{"shipment":{"type":"object","properties":{"quotation_id":{"type":"string","example":"5f4b3b4b-4b3b-4b3b-4b3b-4b3b4b3b4b3b","description":"Id de la cotización, resultado del endpoint POST /api/v1/quotations."},"rate_id":{"type":"string","example":"5f4b3b4b-4b3b-4b3b-4b3b-4b3b4b3b4b3b","description":"Id único del precio obtenido al consultar la cotización (GET  /api/v1/quotations/{id})."},"protected":{"type":"boolean","required":false,"example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","required":false,"example":1400.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"thermal"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"address_from":{"type":"object","properties":{"country_code":{"type":"string","example":"mx","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"street1":{"type":"string","example":"Calle Example","description":"Calle y número de la dirección."},"name":{"type":"string","example":"Homero Simpson","description":"Nombre completo del remitente (máximo 30 caracteres)."},"company":{"type":"string","example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3","street1","name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"country_code":{"type":"string","example":"mx","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"58258","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Michoacán","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Morelia","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Ampliación Nicolás Romero","description":"Barrio o colonia de la dirección."},"street1":{"type":"string","example":"Avenida Example","description":"Calle y número de la dirección."},"name":{"type":"string","example":"Bart Simpson","description":"Nombre completo del destinatario (máximo 30 caracteres)."},"company":{"type":"string","example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3","street1","name","company","phone","email"]},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","example":"product_not_found","description":"ID del productome') %>"},"country_code":{"type":"string","example":"MX","description":"Código de país en ISO 3166-1 alpha-2"}}}}},"required":["rate_id","address_from","address_to","consignment_note","package_type"]}}}],"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Envío nacional (MX)","properties":{"shipment":{"type":"object","properties":{"rate_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id único del precio obtenido al consultar la cotización (GET  /api/v1/quotations/{id})."},"unique_shipment":{"type":"boolean","required":false,"default":false,"example":false,"description":"Opcional. Cuando es true, el sistema cachea la respuesta para el rate_id y la replica en reintentos con el mismo rate_id, evitando envíos duplicados. Devuelve 200 OK con el payload original en replay, 409 Conflict si una solicitud previa aún está en proceso. El cache vive 96 horas, alineado al ciclo de vida del rate_id."},"original_shipment_id":{"required":false,"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del envío original."},"auto_advance":{"required":false,"type":"boolean","example":false,"description":"Opcional. **Solo en sandbox**. Cuando es `true`, simula la progresión automática del tracking del envío (created → picked_up → in_transit → last_mile → delivered) cada minuto, sin esperar al carrier real. En producción se ignora."},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"thermal"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"office_delivery":{"required":false,"type":"boolean","default":false,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"required":false,"type":"boolean","default":false,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"required":false,"type":"string","format":"uuid","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"required":false,"type":"string","format":"uuid","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"street_number":{"type":"string","nullable":true,"example":"123","description":"Número de calle en un campo propio. Obligatorio en Brasil (BR) —la DC-e lo declara aparte y un envío sin él responde 422— y ahí street1 no debe repetirlo. En MX y CO el número viaja dentro de street1 y este campo es opcional."},"name":{"type":"string","maxLength":30,"example":"Homero Simpson","description":"Nombre completo del remitente (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["street1","name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Avenida Example","description":"Calle y número de la dirección."},"street_number":{"type":"string","nullable":true,"example":"456","description":"Número de calle en un campo propio. Obligatorio en Brasil (BR) —la DC-e lo declara aparte y un envío sin él responde 422— y ahí street1 no debe repetirlo. En MX y CO el número viaja dentro de street1 y este campo es opcional."},"name":{"type":"string","maxLength":30,"example":"Bart Simpson","description":"Nombre completo del destinatario (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["street1","name","company","phone","email"]},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del producto"},"name":{"type":"string","example":"Producto 1","description":"Nombre del producto"},"description_en":{"type":"string","example":"Product description","description":"Descripción en inglés"},"quantity":{"type":"integer","example":1,"description":"Cantidad"},"price":{"type":"number","example":100.0,"description":"Precio en pesos mexicanos"},"sku":{"type":"string","example":"SKU-123","description":"SKU"},"hs_code":{"type":"string","example":"9706.900060","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"hs_code_description":{"type":"string","example":"Descripción del HS Code","description":"Descripción del código Harmonizado"},"product_type_code":{"type":"string","example":"P","description":"Código de tipo de producto"},"product_type_name":{"type":"string","example":"Producto","description":"Nombre del tipo de producto"},"country_code":{"type":"string","example":"MX","description":"Código de país en ISO 3166-1 alpha-2"}}}}}}}},"required":["rate_id","address_from","address_to","packages"]}}},{"type":"object","title":"Envío internacional","properties":{"shipment":{"type":"object","properties":{"rate_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id único del precio obtenido al consultar la cotización (GET  /api/v1/quotations/{id})."},"unique_shipment":{"type":"boolean","required":false,"default":false,"example":false,"description":"Opcional. Cuando es true, el sistema cachea la respuesta para el rate_id y la replica en reintentos con el mismo rate_id, evitando envíos duplicados. Devuelve 200 OK con el payload original en replay, 409 Conflict si una solicitud previa aún está en proceso. El cache vive 96 horas, alineado al ciclo de vida del rate_id."},"customs_payment_payer":{"type":"string","description":"Entidad que pagará los aranceles del envío. Puede ser `sender` o `recipient`.","enum":["sender","recipient"],"example":"sender"},"shipment_purpose":{"type":"string","description":"Propósito del envío (`goods`, `documents`, `sample`, `return_of_goods`, `gift` o `humanitarian_donation`).","enum":["goods","documents","sample","return_of_goods","gift","humanitarian_donation"],"example":"goods"},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"standard"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"street_number":{"type":"string","nullable":true,"example":"123","description":"Número de calle en un campo propio. Obligatorio en Brasil (BR) —la DC-e lo declara aparte y un envío sin él responde 422— y ahí street1 no debe repetirlo. En MX y CO el número viaja dentro de street1 y este campo es opcional."},"name":{"type":"string","maxLength":30,"example":"Homero Simpson","description":"Nombre completo del remitente (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["street1","name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Avenida Example","description":"Calle y número de la dirección."},"street_number":{"type":"string","nullable":true,"example":"456","description":"Número de calle en un campo propio. Obligatorio en Brasil (BR) —la DC-e lo declara aparte y un envío sin él responde 422— y ahí street1 no debe repetirlo. En MX y CO el número viaja dentro de street1 y este campo es opcional."},"name":{"type":"string","maxLength":30,"example":"Bart Simpson","description":"Nombre completo del destinatario (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["street1","name","company","phone","email"]},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Moldes dentales - USA","description":"Nombre del producto"},"sku":{"type":"string","example":"SKU-1","description":"SKU"},"product_type_code":{"type":"string","example":"42152400","description":"Código de tipo de producto"},"product_type_name":{"type":"string","example":"Materiales dentales","description":"Nombre del tipo de producto"}}}}}}}},"required":["rate_id","customs_payment_payer","shipment_purpose","address_from","address_to","packages"]}}}]}}}}}},"/api/v1/transaction_stats":{"get":{"summary":"Obtener lista de movimientos","tags":["Movimientos"],"description":"```\n   GET /api/v1/transaction_stats\n```\n  El endpoint de movimientos sirve para consultar el historial de transacciones de la cuenta.\n\n  **Parámetros de la solicitud:**\n","parameters":[{"name":"page","in":"query","required":false,"description":"Número de página a recuperar","schema":{"type":"integer","example":1}},{"name":"sort","in":"query","required":false,"description":"Orden de resultados por fecha de transacción (asc o desc)","schema":{"type":"string","enum":["asc","desc"],"example":"desc"}},{"name":"kind","in":"query","required":false,"description":"Tipo de movimiento (deposit, withdrawal, refund, all)","schema":{"type":"string","enum":["deposit","withdrawal","refund","all"],"example":"deposit"}},{"name":"date_from","in":"query","required":false,"description":"Fecha de inicio del rango (formato ISO 8601)","schema":{"type":"string","example":"2024-01-01"}},{"name":"date_to","in":"query","required":false,"description":"Fecha de fin del rango (formato ISO 8601)","schema":{"type":"string","example":"2024-12-31"}},{"name":"search","in":"query","required":false,"description":"Búsqueda por referencia, número de rastreo, tipo o monto","schema":{"type":"string","example":"REF-001"}}],"responses":{"200":{"description":"Devuelve una lista de movimientos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID interno del movimiento","example":"765"},"type":{"type":"string","example":"transaction_stat"},"attributes":{"type":"object","properties":{"id":{"type":"integer","description":"ID interno del movimiento","example":765},"transaction_reference":{"type":"string","nullable":true,"description":"Referencia única de la transacción","example":"0f43b81bdbcfe536"},"transaction_kind":{"type":"string","description":"Tipo de movimiento (deposit, withdrawal, refund)","example":"deposit"},"transaction_amount":{"type":"string","nullable":true,"description":"Monto de la transacción","example":"300.0"},"transaction_status":{"type":"string","nullable":true,"description":"Estado de la transacción (completed, disputed, error)","example":"completed"},"transaction_source":{"type":"string","nullable":true,"description":"Origen de la transacción","example":"api"},"transaction_comments":{"type":"string","nullable":true,"description":"Comentarios de la transacción","example":"Recarga de saldo"},"transaction_created_at":{"type":"string","nullable":true,"description":"Fecha de creación de la transacción","example":"2024-01-15T10:30:00.000-06:00"},"transaction_updated_at":{"type":"string","nullable":true,"description":"Fecha de última actualización de la transacción","example":"2024-01-15T10:30:00.000-06:00"},"transaction_exported":{"type":"boolean","nullable":true,"description":"Indica si la transacción fue exportada","example":true},"transaction_invoiceable":{"type":"boolean","nullable":true,"description":"Indica si la transacción es facturable","example":false},"transaction_tag_name":{"type":"string","nullable":true,"description":"Etiqueta asociada a la transacción","example":"COMP1"},"transaction_shipkraken_reference":{"type":"string","nullable":true,"description":"Referencia externa en Shipkraken"},"transactionable_type":{"type":"string","nullable":true,"description":"Tipo de entidad relacionada al movimiento","example":"Shipment"},"shipment_carrier_name":{"type":"string","nullable":true,"description":"Nombre de la paquetería del envío relacionado","example":"Fedex"},"shipment_carrier_service":{"type":"string","nullable":true,"description":"Servicio de la paquetería","example":"Fedex Express"},"shipment_tracking_number":{"type":"string","nullable":true,"description":"Número de rastreo del envío","example":"123456789"},"shipment_user_email":{"type":"string","nullable":true,"description":"Email del usuario que generó el envío","example":"usuario@ejemplo.com"},"shipment_user_name":{"type":"string","nullable":true,"description":"Nombre del usuario que generó el envío","example":"Juan Pérez"},"shipment_multi_package":{"type":"boolean","nullable":true,"description":"Indica si el envío tiene múltiples paquetes","example":false},"merchant_store_name":{"type":"string","nullable":true,"description":"Nombre de la tienda asociada al movimiento","example":"mi_tienda"}}}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":11},"total_count":{"type":"integer","example":207}}}}}}}}}}},"/api/v2/orders/{id}":{"get":{"summary":"Recupera una orden (V2)","tags":["Ordenes"],"description":"```\n   GET /api/v2/orders/:id\n```\n   Versión V2 del detalle de la orden. Devuelve `parcels` como arreglo (soporte multi-paquete) y agrega `payment_status`, `package_type`, `consignment_note`, `dimension_unit`, `mass_unit` y `hs_code` dentro de cada producto. Incluye además los campos para envíos internacionales `shipment_purpose` y `customs_payment_payer` a nivel de orden; `declared_value`, `package_protected` y `package_number` en cada paquete; y `hs_code_description`, `description_en`, `product_type_code`, `product_type_name` y `country_code` en cada producto. Estos campos siempre están presentes y son `null` cuando no aplican (órdenes nacionales).\n\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retorna una orden","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"type":{"type":"string","example":"order"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"9e270243-762f-40c8-833e-ef1c4ee8282d"},"reference":{"type":"string","nullable":true,"example":"188-5455445-33334433"},"tags":{"type":"array","items":{"type":"string"},"example":["tag1","tag2"],"nullable":true},"platform":{"type":["string","null"],"example":"Shopify"},"ecommerce_id":{"type":["string","null"],"example":"SDFG"},"payment_status":{"type":"string","nullable":true,"example":"paid"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"example":10.0},"shipping_preferences":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":true,"properties":{"service":{"type":["string","null"],"example":"me2"},"price":{"type":["string","null"],"example":"100.00"}}}},"payment_type":{"type":"string","nullable":true,"example":"COD"},"shipment_purpose":{"type":"string","nullable":true,"example":"goods"},"customs_payment_payer":{"type":"string","nullable":true,"example":"recipient"},"created_at":{"type":"string","format":"date-time","example":"2025-01-07T14:46:38.203-06:00"},"address_from":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string","null"],"example":"Nuevo León"},"area_level2":{"type":["string","null"],"example":"Monterrey"},"area_level3":{"type":["string","null"],"example":"La Finca"},"name":{"type":["string","null"],"example":"Name"},"postal_code":{"type":["string","null"],"example":"64000"},"country_code":{"type":["string","null"],"example":"MX"},"street1":{"type":["string","null"],"example":"Olivo 4618"},"company":{"type":["string","null"],"example":""},"phone":{"type":["string","null"],"example":"1242452456"},"email":{"type":["string","null"],"example":"email@example.com"},"reference":{"type":["string","null"],"example":"Green house"},"address_type":{"type":"string","example":"from"},"apartment_number":{"type":["string","null"],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"address_to":{"type":"object","nullable":true,"properties":{"area_level1":{"type":["string","null"],"example":"Monterrey Centro"},"area_level2":{"type":["string","null"],"example":"Monterrey"},"area_level3":{"type":["string","null"],"example":"La finca"},"name":{"type":["string","null"],"example":"Mayra Doe"},"postal_code":{"type":["string","null"],"example":"64000"},"country_code":{"type":["string","null"],"example":"MX"},"street1":{"type":["string","null"],"example":"22 Main St"},"company":{"type":["string","null"],"example":"ACS Inc."},"phone":{"type":["string","null"],"example":"1234567890"},"email":{"type":["string","null"],"example":"jhon@doe.com"},"reference":{"type":["string","null"],"example":"Near the park"},"address_type":{"type":"string","example":"to"},"apartment_number":{"type":["string","null"],"example":"123"},"further_information":{"type":["string","null"],"example":""},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","example":2},"length":{"type":"integer","example":10},"width":{"type":"integer","example":10},"height":{"type":"integer","example":10},"declared_value":{"type":"number","nullable":true,"example":120.5},"package_protected":{"type":"boolean","nullable":true,"example":false},"package_number":{"type":"integer","nullable":true,"example":1},"package_type":{"type":"string","nullable":true,"example":"4G"},"consignment_note":{"type":"string","nullable":true,"example":"24121500"},"dimension_unit":{"type":"string","example":"cm"},"mass_unit":{"type":"string","example":"kg"},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"c2092234-1b85-41a2-a200-858d052c0ad1"},"name":{"type":"string","example":"Bicicleta"},"sku":{"type":"string","nullable":true,"example":"BIC-001"},"hs_code":{"type":"string","nullable":true,"example":"9560.63"},"hs_code_description":{"type":"string","nullable":true,"example":"Bicycles"},"description_en":{"type":"string","nullable":true,"example":"Mountain bike"},"product_type_code":{"type":"string","nullable":true,"example":"60141200"},"product_type_name":{"type":"string","nullable":true,"example":"Bicycles"},"country_code":{"type":"string","nullable":true,"example":"MX"},"quantity":{"type":"integer","example":1},"price":{"type":"number","example":57.0},"weight":{"type":"number","example":10},"height":{"type":"number","example":10},"width":{"type":"number","example":10},"length":{"type":"number","example":10}}}}}}}}},"relationships":{"type":"object","properties":{"shipments":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"9eae25ba-11b4-4b9f-9b01-3d09da8bc12d"},"type":{"type":"string","example":"shipment"}}}}}}}}}},"included":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"9eae25ba-11b4-4b9f-9b01-3d09da8bc12d"},"type":{"type":"string","example":"shipment"},"attributes":{"type":"object","properties":{"carrier_name":{"type":"string","nullable":true,"example":"fedex"},"workflow_status":{"type":"string","nullable":true,"example":"completed"}}}}},"nullable":true}}}}}}}}},"/api/v2/pickups/eligible_shipments":{"get":{"summary":"Recupera los envíos por recolectar","tags":["Recolecciones"],"description":"```\n   GET /api/v2/pickups/eligible_shipments?page={page}&per_page={per_page}\n```\n   Devuelve los envíos que todavía se pueden recolectar, agrupados igual que en la plataforma: por origen, paquetería y tipo de operación. Cada grupo se puede mandar tal cual a `POST /api/v2/pickups` en `shipment_ids`. La respuesta se pagina por grupos.\n","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","example":1},"description":"Número de página a recuperar"},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","example":20},"description":"Número de elementos por página (máximo 20, por defecto 20)"}],"responses":{"200":{"description":"Retorna una colección paginada de grupos de envíos","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","description":"Grupos de envíos que se pueden recolectar juntos","items":{"type":"object","properties":{"origin_address_id":{"type":"string","example":"397f7fb2a1f50c44b86056a2a92e8fa3","description":"Identificador del origen. Se calcula a partir de la ubicación, así que la misma dirección guardada dos veces cuenta como un solo origen. No es el ID de una dirección."},"carrier":{"type":"string","example":"fedex","description":"Paquetería de los envíos del grupo"},"type":{"type":"string","enum":["national_no_ltl","national_ltl","international"],"example":"national_no_ltl","description":"Tipo de operación: national_no_ltl (nacional), national_ltl (nacional LTL) o international (internacional)"},"shipment_ids":{"type":"array","description":"IDs de los envíos del grupo","items":{"type":"string","format":"uuid"},"example":["6c001743-9bed-4818-9820-1265576ef422","a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"]}}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":3},"total_count":{"type":"integer","example":45}}}}}}}}}}},"/api/v2/pickups/{id}/reschedule":{"post":{"summary":"Reprograma una recolección múltiple","tags":["Recolecciones"],"description":"```\n   POST /api/v2/pickups/{id}/reschedule\n```\n   Reprograma una recolección para todos sus envíos en una sola solicitud. No modifica la recolección original: crea una nueva con su propio folio, ligada a la original, y cancela y archiva la original solo cuando la nueva queda programada. Solo se pueden reprogramar recolecciones que la paquetería ya no va a recoger (por ejemplo, con incidencia). Acepta los mismos parámetros que la creación.\n\n   **Parámetros de la solicitud:**\n   - `shipment_ids`: IDs de los envíos a recolectar. Deben formar un solo grupo de los que devuelve eligible_shipments.\n   - `packages`: Número de paquetes a recolectar. Opcional: si no se envía, se calcula a partir de los envíos. Un número mayor le pide a la paquetería capacidad extra.\n   - `total_weight`: Peso total a recolectar. Opcional: si no se envía, se calcula a partir de los envíos.\n   - `scheduled_from`: Fecha y hora de inicio de la franja horaria de recolección\n   - `scheduled_to`: Fecha y hora de fin de la franja horaria de recolección. Debe ser el mismo día que scheduled_from.\n   - `include_manifest`: Si es `true`, se genera el manifiesto en PDF de los envíos de la recolección. Se genera en segundo plano y se consulta después en `manifest_url`.\n","parameters":[{"name":"id","in":"path","description":"ID de la recolección a reprogramar","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Retorna la nueva recolección programada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","enum":["in_progress","scheduled","collected","delayed","incident","scheduling_error","cancelled"],"example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":3,"description":"Número de paquetes a recolectar"},"total_weight":{"type":"string","format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2026-10-01T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2026-10-01T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":null,"description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":null,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."},"manifest_url":{"type":"string","nullable":true,"example":"https://example.com/rails/active_storage/blobs/manifest.pdf","description":"URL del manifiesto en PDF con todos los envíos de la recolección. Es `null` si no se pidió con `include_manifest` al crearla, o mientras el documento se sigue generando."}}},"relationships":{"type":"object","properties":{"shipments":{"type":"object","description":"Envíos que cubre la recolección. Vienen completos en `included`.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}}},"address":{"type":"object","description":"Dirección donde la paquetería recoge los envíos. Viene completa en `included`.","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío"},"carrier_name":{"type":"string","example":"FEDEX","description":"Nombre de la paquetería"},"service_name":{"type":"string","nullable":true,"example":"Express Saver","description":"Nombre del servicio"},"service_code":{"type":"string","nullable":true,"example":"fedex_express_saver","description":"Código del servicio, identificador estable del servicio"},"shipment_scope":{"type":"string","nullable":true,"enum":["national","international",null],"example":"national","description":"Si el envío es nacional o internacional, según los países de origen y destino; null cuando falta el país de alguna dirección"},"estimated_delivery_days":{"type":"integer","nullable":true,"example":3,"description":"Días estimados de entrega según la tarifa elegida; null cuando el envío no tiene tarifa"},"workflow_status":{"type":"string","example":"success","description":"Estado del envío"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago"},"total":{"type":"string","example":"500.0","description":"Costo total del envío"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)"},"carrier_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID de la paquetería"},"service_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID del servicio"},"master_tracking_number":{"type":"string","nullable":true,"example":"234234234233","description":"Número de rastreo"},"original_shipment_id":{"type":"string","nullable":true,"example":"0199977a-e032-78bf-a335-00a9ae3cfdff","description":"ID del envío original."},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://example.com/order_detail.pdf","description":"Translation missing: es.swagger.shipments.show.response_params.attributes.order_detail_url"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero Rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":null,"description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","nullable":true,"example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","nullable":true,"example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":null,"description":"Número de departamento"}}}}}]}}}}}}},"404":{"description":"Recolección no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"El recurso buscado no se pudo encontrar."}}}}}},"422":{"description":"La recolección no se puede reprogramar, ya fue archivada, los envíos no forman un solo grupo elegible o la franja horaria no es válida","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"detail":{"type":"string","example":"La recolección no puede reprogramarse: la paquetería aún puede recolectarla o el envío ya no es elegible"}}}},{"type":"object","description":"Errores de validación de la recolección, agrupados por atributo. Se devuelven cuando la paquetería o la recolección rechazan los datos recibidos."}]}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"object","properties":{"shipment_ids":{"type":"array","items":{"type":"string","format":"uuid"},"example":["6c001743-9bed-4818-9820-1265576ef422","a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"],"description":"IDs de los envíos a recolectar. Deben formar un solo grupo de los que devuelve eligible_shipments."},"packages":{"type":"integer","example":2,"description":"Número de paquetes a recolectar. Opcional: si no se envía, se calcula a partir de los envíos. Un número mayor le pide a la paquetería capacidad extra."},"total_weight":{"type":"string","format":"decimal","example":"30.0","description":"Peso total a recolectar. Opcional: si no se envía, se calcula a partir de los envíos."},"scheduled_from":{"type":"string","format":"date-time","example":"2026-10-01 09:00:00","description":"Fecha y hora de inicio de la franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2026-10-01 14:00:00","description":"Fecha y hora de fin de la franja horaria de recolección. Debe ser el mismo día que scheduled_from."},"include_manifest":{"type":"boolean","example":true,"description":"Si es `true`, se genera el manifiesto en PDF de los envíos de la recolección. Se genera en segundo plano y se consulta después en `manifest_url`."}},"required":["shipment_ids","scheduled_from","scheduled_to"]}},"required":["pickup"]}}}}}},"/api/v2/pickups":{"get":{"summary":"Recupera recolecciones con sus envíos","tags":["Recolecciones"],"description":"```\n   GET /api/v2/pickups?page={page}&per_page={per_page}\n```\n   Devuelve las recolecciones de la cuenta, paginadas. A diferencia de `GET /api/v1/pickups`, cada recolección trae todos los envíos que cubre en la relación `shipments`, en vez de un solo `reference_shipment`, y el campo `manifest_url`.\n","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","example":1},"description":"Número de página a recuperar"},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","example":20},"description":"Número de elementos por página (máximo 20, por defecto 20)"}],"responses":{"200":{"description":"Retorna una colección paginada de recolecciones con sus envíos","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","enum":["in_progress","scheduled","collected","delayed","incident","scheduling_error","cancelled"],"example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":3,"description":"Número de paquetes a recolectar"},"total_weight":{"type":"string","format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2026-10-01T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2026-10-01T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":null,"description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":null,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."},"manifest_url":{"type":"string","nullable":true,"example":"https://example.com/rails/active_storage/blobs/manifest.pdf","description":"URL del manifiesto en PDF con todos los envíos de la recolección. Es `null` si no se pidió con `include_manifest` al crearla, o mientras el documento se sigue generando."}}},"relationships":{"type":"object","properties":{"shipments":{"type":"object","description":"Envíos que cubre la recolección. Vienen completos en `included`.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}}},"address":{"type":"object","description":"Dirección donde la paquetería recoge los envíos. Viene completa en `included`.","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"}}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío"},"carrier_name":{"type":"string","example":"FEDEX","description":"Nombre de la paquetería"},"service_name":{"type":"string","nullable":true,"example":"Express Saver","description":"Nombre del servicio"},"service_code":{"type":"string","nullable":true,"example":"fedex_express_saver","description":"Código del servicio, identificador estable del servicio"},"shipment_scope":{"type":"string","nullable":true,"enum":["national","international",null],"example":"national","description":"Si el envío es nacional o internacional, según los países de origen y destino; null cuando falta el país de alguna dirección"},"estimated_delivery_days":{"type":"integer","nullable":true,"example":3,"description":"Días estimados de entrega según la tarifa elegida; null cuando el envío no tiene tarifa"},"workflow_status":{"type":"string","example":"success","description":"Estado del envío"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago"},"total":{"type":"string","example":"500.0","description":"Costo total del envío"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)"},"carrier_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID de la paquetería"},"service_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID del servicio"},"master_tracking_number":{"type":"string","nullable":true,"example":"234234234233","description":"Número de rastreo"},"original_shipment_id":{"type":"string","nullable":true,"example":"0199977a-e032-78bf-a335-00a9ae3cfdff","description":"ID del envío original."},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://example.com/order_detail.pdf","description":"Translation missing: es.swagger.shipments.show.response_params.attributes.order_detail_url"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero Rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":null,"description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","nullable":true,"example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","nullable":true,"example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":null,"description":"Número de departamento"}}}}}]}},"meta":{"type":"object","properties":{"current_page":{"type":"integer","example":1},"next_page":{"type":"integer","nullable":true,"example":2},"prev_page":{"type":"integer","nullable":true,"example":null},"total_pages":{"type":"integer","example":3},"total_count":{"type":"integer","example":45}}}}}}}}}},"post":{"summary":"Programa una recolección múltiple","tags":["Recolecciones"],"description":"```\n   POST /api/v2/pickups\n```\n   Programa una sola recolección para múltiples envíos. Todos los `shipment_ids` deben pertenecer al mismo grupo de `GET /api/v2/pickups/eligible_shipments`: mismo origen, misma paquetería y mismo tipo de operación, y estar disponibles para recolección. La franja horaria debe empezar y terminar el mismo día.\n\n   **Parámetros de la solicitud:**\n   - `shipment_ids`: IDs de los envíos a recolectar. Deben formar un solo grupo de los que devuelve eligible_shipments.\n   - `packages`: Número de paquetes a recolectar. Opcional: si no se envía, se calcula a partir de los envíos. Un número mayor le pide a la paquetería capacidad extra.\n   - `total_weight`: Peso total a recolectar. Opcional: si no se envía, se calcula a partir de los envíos.\n   - `scheduled_from`: Fecha y hora de inicio de la franja horaria de recolección\n   - `scheduled_to`: Fecha y hora de fin de la franja horaria de recolección. Debe ser el mismo día que scheduled_from.\n   - `include_manifest`: Si es `true`, se genera el manifiesto en PDF de los envíos de la recolección. Se genera en segundo plano y se consulta después en `manifest_url`.\n","parameters":[],"responses":{"201":{"description":"Retorna la recolección programada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","enum":["in_progress","scheduled","collected","delayed","incident","scheduling_error","cancelled"],"example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":3,"description":"Número de paquetes a recolectar"},"total_weight":{"type":"string","format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2026-10-01T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2026-10-01T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":null,"description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":null,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."},"manifest_url":{"type":"string","nullable":true,"example":"https://example.com/rails/active_storage/blobs/manifest.pdf","description":"URL del manifiesto en PDF con todos los envíos de la recolección. Es `null` si no se pidió con `include_manifest` al crearla, o mientras el documento se sigue generando."}}},"relationships":{"type":"object","properties":{"shipments":{"type":"object","description":"Envíos que cubre la recolección. Vienen completos en `included`.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}}},"address":{"type":"object","description":"Dirección donde la paquetería recoge los envíos. Viene completa en `included`.","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío"},"carrier_name":{"type":"string","example":"FEDEX","description":"Nombre de la paquetería"},"service_name":{"type":"string","nullable":true,"example":"Express Saver","description":"Nombre del servicio"},"service_code":{"type":"string","nullable":true,"example":"fedex_express_saver","description":"Código del servicio, identificador estable del servicio"},"shipment_scope":{"type":"string","nullable":true,"enum":["national","international",null],"example":"national","description":"Si el envío es nacional o internacional, según los países de origen y destino; null cuando falta el país de alguna dirección"},"estimated_delivery_days":{"type":"integer","nullable":true,"example":3,"description":"Días estimados de entrega según la tarifa elegida; null cuando el envío no tiene tarifa"},"workflow_status":{"type":"string","example":"success","description":"Estado del envío"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago"},"total":{"type":"string","example":"500.0","description":"Costo total del envío"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)"},"carrier_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID de la paquetería"},"service_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID del servicio"},"master_tracking_number":{"type":"string","nullable":true,"example":"234234234233","description":"Número de rastreo"},"original_shipment_id":{"type":"string","nullable":true,"example":"0199977a-e032-78bf-a335-00a9ae3cfdff","description":"ID del envío original."},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://example.com/order_detail.pdf","description":"Translation missing: es.swagger.shipments.show.response_params.attributes.order_detail_url"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero Rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":null,"description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","nullable":true,"example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","nullable":true,"example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":null,"description":"Número de departamento"}}}}}]}}}}}}},"400":{"description":"Falta el objeto pickup en la solicitud","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Los parámetros de la solicitud son inválidos."}}}}}},"422":{"description":"Los envíos no forman un solo grupo elegible, la franja horaria no es válida o la paquetería rechazó la recolección","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"detail":{"type":"string","example":"Los envíos deben compartir el mismo origen, paquetería y tipo de operación, y estar disponibles para recolección"}}}},{"type":"object","description":"Errores de validación de la recolección, agrupados por atributo. Se devuelven cuando la paquetería o la recolección rechazan los datos recibidos."}]}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"object","properties":{"shipment_ids":{"type":"array","items":{"type":"string","format":"uuid"},"example":["6c001743-9bed-4818-9820-1265576ef422","a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"],"description":"IDs de los envíos a recolectar. Deben formar un solo grupo de los que devuelve eligible_shipments."},"packages":{"type":"integer","example":2,"description":"Número de paquetes a recolectar. Opcional: si no se envía, se calcula a partir de los envíos. Un número mayor le pide a la paquetería capacidad extra."},"total_weight":{"type":"string","format":"decimal","example":"30.0","description":"Peso total a recolectar. Opcional: si no se envía, se calcula a partir de los envíos."},"scheduled_from":{"type":"string","format":"date-time","example":"2026-10-01 09:00:00","description":"Fecha y hora de inicio de la franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2026-10-01 14:00:00","description":"Fecha y hora de fin de la franja horaria de recolección. Debe ser el mismo día que scheduled_from."},"include_manifest":{"type":"boolean","example":true,"description":"Si es `true`, se genera el manifiesto en PDF de los envíos de la recolección. Se genera en segundo plano y se consulta después en `manifest_url`."}},"required":["shipment_ids","scheduled_from","scheduled_to"]}},"required":["pickup"]}}}}}},"/api/v2/pickups/{id}":{"get":{"summary":"Detalle de recolección con sus envíos","tags":["Recolecciones"],"description":"```\n   GET /api/v2/pickups/{id}\n```\n   Devuelve una recolección con todos los envíos que cubre (`shipments`), la dirección de recolección (`address`) y el manifiesto (`manifest_url`), si se pidió.\n","parameters":[{"name":"id","in":"path","description":"ID de la recolección","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recolección encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0"},"type":{"type":"string","example":"pickup"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"ed06f78a-8757-488c-bb82-31964449aea0","description":"UUID de la recolección"},"status":{"type":"string","enum":["in_progress","scheduled","collected","delayed","incident","scheduling_error","cancelled"],"example":"scheduled","description":"Estado de la recolección"},"request_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de solicitud de la recolección"},"packages":{"type":"integer","example":3,"description":"Número de paquetes a recolectar"},"total_weight":{"type":"string","format":"decimal","example":"30.0","description":"Peso total de los paquetes a recolectar"},"scheduled_from":{"type":"string","format":"date-time","example":"2026-10-01T09:00:00.000-06:00","description":"Fecha y hora de inicio de franja horaria de recolección"},"scheduled_to":{"type":"string","format":"date-time","example":"2026-10-01T14:00:00.000-06:00","description":"Fecha y hora final de franja horaria de recolección"},"created_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","example":"2026-09-30T08:55:50.992-06:00","description":"Fecha de actualización"},"error_reason":{"type":"string","nullable":true,"example":null,"description":"Motivo del error si la recolección no se pudo programar"},"reschedule_remaining_days":{"type":"integer","nullable":true,"example":null,"description":"Días restantes hasta que el envío alcance el máximo de días permitidos para reagendar la recolección (14 días). Solo se muestra cuando la recolección puede ser reagendada (available_for_reschedule? retorna true)."},"manifest_url":{"type":"string","nullable":true,"example":"https://example.com/rails/active_storage/blobs/manifest.pdf","description":"URL del manifiesto en PDF con todos los envíos de la recolección. Es `null` si no se pidió con `include_manifest` al crearla, o mientras el documento se sigue generando."}}},"relationships":{"type":"object","properties":{"shipments":{"type":"object","description":"Envíos que cubre la recolección. Vienen completos en `included`.","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"d4ad5784-4f71-4474-9f34-e2a6f8366d5e"},"type":{"type":"string","example":"shipment"}}}}}},"address":{"type":"object","description":"Dirección donde la paquetería recoge los envíos. Viene completa en `included`.","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío"},"carrier_name":{"type":"string","example":"FEDEX","description":"Nombre de la paquetería"},"service_name":{"type":"string","nullable":true,"example":"Express Saver","description":"Nombre del servicio"},"service_code":{"type":"string","nullable":true,"example":"fedex_express_saver","description":"Código del servicio, identificador estable del servicio"},"shipment_scope":{"type":"string","nullable":true,"enum":["national","international",null],"example":"national","description":"Si el envío es nacional o internacional, según los países de origen y destino; null cuando falta el país de alguna dirección"},"estimated_delivery_days":{"type":"integer","nullable":true,"example":3,"description":"Días estimados de entrega según la tarifa elegida; null cuando el envío no tiene tarifa"},"workflow_status":{"type":"string","example":"success","description":"Estado del envío"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago"},"total":{"type":"string","example":"500.0","description":"Costo total del envío"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)"},"carrier_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID de la paquetería"},"service_id":{"type":"string","nullable":true,"example":"91dd6bde-fd08-4bf2-b12d-d79c98b0f7ab","description":"UUID del servicio"},"master_tracking_number":{"type":"string","nullable":true,"example":"234234234233","description":"Número de rastreo"},"original_shipment_id":{"type":"string","nullable":true,"example":"0199977a-e032-78bf-a335-00a9ae3cfdff","description":"ID del envío original."},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación"},"updated_at":{"type":"string","description":"Fecha de actualización"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://example.com/order_detail.pdf","description":"Translation missing: es.swagger.shipments.show.response_params.attributes.order_detail_url"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c"},"type":{"type":"string","example":"simple_address"},"attributes":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"901e4d68-a147-4fdf-9078-c252a672611c","description":"UUID de la dirección"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección"},"area_level3":{"type":"string","example":"Romero Rubio","description":"Barrio o colonia de la dirección"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección"},"address_type":{"type":"string","nullable":true,"example":null,"description":"Tipo de dirección"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección"},"company":{"type":"string","nullable":true,"example":"Company name","description":"Nombre de la empresa"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico"},"reference":{"type":"string","nullable":true,"example":"porton","description":"Referencia de la dirección"},"apartment_number":{"type":"string","nullable":true,"example":null,"description":"Número de departamento"}}}}}]}}}}}}},"404":{"description":"Recolección no encontrada","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"El recurso buscado no se pudo encontrar."}}}}}}}}},"/api/v2/quotations":{"post":{"summary":"Crea una cotización V2","tags":["Cotizaciones"],"description":"```\n   POST /api/v2/quotations\n```\n   El endpoint de cotizaciones se utiliza para consultar los precios con las diferentes paqueterías. A diferencia de V1, este endpoint devuelve todos los tipos de tarifa, incluyendo tarifas con shipment_creation_type \"multishipment\" (para paqueterías que no soportan multipackage nativo), brindando visibilidad completa sobre qué tipo de envío producirá cada tarifa.\n\n","parameters":[],"responses":{"201":{"description":"Retorna una respuesta completa de cotización","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"ID de la cotización."},"is_completed":{"type":"boolean","example":true,"description":"Estado de finalización del procesamiento de la cotización. Si es `false`, aún está en proceso y las tarifas todavía no están disponibles. Si es `true`, el procesamiento terminó y las tarifas ya están disponibles."},"quotation_scope":{"type":"object","oneOf":[{"properties":{"carriers_scoped_to":{"type":"string","enum":["ALL_AVAILABLE","PARTIALLY_SELECTED_CARRIERS"],"example":"ALL_AVAILABLE","description":"Paqueterías cotizadas (todas las paqueterías `ALL_AVAILABLE`)(paqueterías seleccionadas `PARTIALLY_SELECTED_CARRIERS`)"}}},{"properties":{"carriers_scoped_to":{"type":"string","enum":["ALL_AVAILABLE","PARTIALLY_SELECTED_CARRIERS"],"example":"ALL_AVAILABLE","description":"Paqueterías cotizadas (todas las paqueterías `ALL_AVAILABLE`)(paqueterías seleccionadas `PARTIALLY_SELECTED_CARRIERS`)"},"found_carriers":{"type":"array","items":{"type":"string","description":"Paqueterías encontradas."}},"not_found_carriers":{"type":"array","items":{"type":"string","description":"Paqueterías no encontradas."}}}}],"required":["carriers_scoped_to"]},"rates":{"type":"array","description":"Tarifas de las paqueterías.","items":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"ID de la tarifa."},"success":{"type":"boolean","example":true,"description":"Indica si la cotización con la paquetería tuvo éxito. Con `true` se obtuvo una tarifa válida; con `false` no se pudo generar una tarifa para los parámetros proporcionados."},"rate_type":{"type":"string","nullable":true,"description":"Tipo de tarifa."},"country_code":{"type":"string","nullable":true,"example":"mx","description":"Código de país de la dirección."},"provider_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería."},"provider_display_name":{"type":"string","example":"FedEx","description":"Nombre para mostrar de la paquetería."},"provider_service_name":{"type":"string","example":"Standard Overnight","description":"Nombre del servicio de la paquetería."},"provider_service_code":{"type":"string","example":"standard_overnight","description":"Código del servicio de la paquetería."},"status":{"type":"string","example":"pending","description":"Estado de la tarifa (Tarifa pendiente `pending`)(Tafira no aplica `not_applicable`)(Tarifa encontrada `approved`)(Tarifa sin cobertura `no_coverage`)(Tarifa con cobertura comprobada `coverage_checked`)(Tarifa encontrada `price_found_internal`)(Tarifa encontrada `price_found_external`)(Tarifa sin precio `tariff_price_not_found`)"},"currency_code":{"type":"string","example":"MXN","description":"Código de moneda."},"amount":{"type":"string","example":150.0,"description":"Monto de la tarifa."},"total":{"type":"string","example":150.0,"description":"Total de la tarifa."},"service_fee":{"type":"float","example":15.0,"nullable":true,"description":"Tarifa de gestión."},"weight":{"type":"float","example":5,"description":"Peso del paquete."},"days":{"type":"integer","example":2,"description":"Días de entrega."},"insurable":{"type":"boolean","example":true,"description":"Indicador de seguro."},"has_own_agreement":{"type":"boolean","example":false,"description":"Indicador de acuerdo propio."},"own_agreement_amount":{"type":"number","nullable":true,"description":"Monto del acuerdo propio."},"extra_fees":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"value":{"type":"string"}}},"nullable":true},"error_messages":{"type":"array","nullable":true},"zone":{"type":"string","nullable":true,"description":"Zona de la tarifa."},"plan_type":{"type":"string","nullable":true,"description":"Tipo de plan o acuerdo comercial aplicado a la cotización."},"packaging_type":{"type":"string","description":"Indica el tipo de embalaje requerido para el envío, ya sea caja (Package) o tarima (Pallet)."},"protection_value_total":{"type":"float","example":100,"description":"Valor de la protección total."},"total_value_with_protection":{"type":"float","example":100,"description":"Costo total del envío que incluye el total de la tarifa (costo del envío, IVA y cargo por servicio cuando aplica) más el valor de la protección."},"pickup":{"type":"boolean","example":true,"description":"Indica si la recolección está disponible para esta tarifa."},"pickup_automatic":{"type":"boolean","example":false,"description":"Indica si la recolección es automática para esta tarifa."},"pickup_package_min":{"type":"integer","example":1,"description":"Número mínimo de paquetes requeridos para la recolección."},"pickup_ocurre":{"type":"boolean","example":true,"description":"Indica si la recolección ocurre en origen (true) o en sucursal (false)."},"pickup_via_support":{"type":"boolean","example":true,"description":"Indica si la recolección via soporte esta disponible (true) o no (false)."},"shipment_creation_type":{"type":"string","example":"single","description":"El tipo de envío si es creado utilizando esta tarifa (single/multipackage/multishipment)."},"office_delivery":{"type":"boolean","example":false,"description":"Indica si esta tarifa admite entrega en oficina Ocurre (el destinatario recoge en una sucursal del paquetero)."},"office_pickup":{"type":"boolean","example":false,"description":"Indica si esta tarifa admite recolección en oficina Ocurre (el remitente entrega en una sucursal del paquetero)."},"requires_origin_verification":{"type":"boolean","example":false,"description":"Indica si el carrier requiere verificar la dirección de origen y la plantilla de origen aún no está verificada para ese carrier. Si es true, el shipment fallará al crearse hasta completar la verificación."},"customs_payment_payer":{"type":"array","nullable":true,"items":{"type":"string","enum":["sender","recipient"]},"example":["sender","recipient"],"description":"Lista de valores aceptados para `customs_payment_payer` al crear el envío con esta tarifa. Solo aplica a cotizaciones internacionales y contiene `sender`, `recipient` o ambos, según las restricciones del país de destino y del servicio del carrier."},"service_zone":{"type":"string","nullable":true,"description":"Área geográfica real para la que se está cotizando la tarifa."},"vat_fee":{"type":"string","nullable":true,"description":"Tasa de IVA."}}}},"address_template_from_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la plantilla de dirección de origen usada en la cotización (si aplica)."},"address_template_to_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de la plantilla de dirección de destino usada en la cotización (si aplica)."},"requires_origin_verification":{"type":"boolean","example":false,"description":"Indica si alguna de las tarifas de la cotización requiere verificación de la dirección de origen."},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"integer","example":1,"description":"Número de índice del paquete cotizado."},"weight":{"type":"string","example":"2.0","description":"Peso del paquete."},"length":{"type":"string","example":"10.0","description":"Longitud del paquete."},"width":{"type":"string","example":"10.0","description":"Ancho del paquete."},"height":{"type":"string","example":"10.0","description":"Altura del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"description":"Declared value of the package."},"protection_value":{"type":"float","example":100,"description":"Valor de la protección del paquete"}}}},"overweight":{"type":"boolean","description":"Indicador de sobrepeso del paquete."}},"required":["id","is_completed","quotation_scope"]}}}},"422":{"description":"Retorna una respuesta de error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"address_from":{"type":"object","properties":{"postal_code":{"type":"array","items":{"type":"string"}},"area_level1":{"type":"array","items":{"type":"string"}},"area_level2":{"type":"array","items":{"type":"string"}},"area_level3":{"type":"array","items":{"type":"string"}}}},"address_to":{"type":"object","properties":{"postal_code":{"type":"array","items":{"type":"string"}},"area_level1":{"type":"array","items":{"type":"string"}},"area_level2":{"type":"array","items":{"type":"string"}},"area_level3":{"type":"array","items":{"type":"string"}}}},"parcel":{"type":"object","properties":{"weight":{"type":"array","items":{"type":"string"}},"length":{"type":"array","items":{"type":"string"}},"width":{"type":"array","items":{"type":"string"}},"height":{"type":"array","items":{"type":"string"}}}}}},"error":{"type":"string"}},"required":["error"]}}}},"400":{"description":"Retorna una respuesta de error (solicitud incorrecta)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Cotización Nacional (MX)","properties":{"quotation":{"type":"object","properties":{"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_from."},"country_code":{"type":"string","example":"MX","minLength":2,"maxLength":2,"description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_to."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del destinatario."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3"]},"parcels":{"type":"array","items":{"type":"object","properties":{"length":{"type":"integer","example":10,"minimum":1,"description":"Longitud del paquete."},"width":{"type":"integer","example":10,"minimum":1,"description":"Ancho del paquete."},"height":{"type":"integer","example":10,"minimum":1,"description":"Altura del paquete."},"weight":{"type":"float","example":2,"minimum":1,"description":"Peso del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"description":"Declared value of the package."}},"required":["length","width","height","weight"]}},"requested_carriers":{"type":"array","items":{"type":"string","example":["fedex","dhl"],"description":"Paqueterías a cotizar. Consulta los Códigos de paqueterías en el menú lateral izquierdo de esta documentación."}}},"required":["address_from","address_to","parcels"]}}},{"type":"object","title":"Cotización Internacional","properties":{"quotation":{"type":"object","properties":{"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_from."},"country_code":{"type":"string","example":"MX","minLength":2,"maxLength":2,"description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"64000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Nuevo León","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Monterrey","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Monterrey Centro","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, sus valores rellenan los campos no enviados en address_to."},"country_code":{"type":"string","example":"US","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"11201","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"New York","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Brooklyn","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Kings County","description":"Barrio o colonia de la dirección."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["country_code","postal_code","area_level1","area_level2"]},"parcels":{"type":"array","items":{"type":"object","properties":{"length":{"type":"integer","example":10,"minimum":1,"description":"Longitud del paquete."},"width":{"type":"integer","example":10,"minimum":1,"description":"Ancho del paquete."},"height":{"type":"integer","example":10,"minimum":1,"description":"Altura del paquete."},"weight":{"type":"float","example":2,"minimum":1,"description":"Peso del paquete."},"package_protected":{"type":"boolean","example":true,"nullable":true,"description":"Protección SOS (Package protection indicator)."},"declared_value":{"type":"float","example":100,"minimum":1,"description":"Declared value of the package."},"products":{"type":"array","items":{"type":"object","properties":{"hs_code":{"type":"string","example":"3407.002000","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"description_en":{"type":"string","example":"Medicine for children","description":"Descripción del producto en inglés."},"country_code":{"type":"string","example":"US","description":"Código de país del producto (ISO 3166-1 alpha-2)."},"quantity":{"type":"integer","example":1,"description":"Cantidad del producto."},"price":{"type":"float","example":100.0,"description":"Precio del producto."}},"required":["hs_code","description_en","country_code","quantity","price"]}}},"required":["length","width","height","weight","products"]}},"requested_carriers":{"type":"array","items":{"type":"string","example":["fedex","dhl"],"description":"Paqueterías a cotizar. Consulta los Códigos de paqueterías en el menú lateral izquierdo de esta documentación."}}},"required":["address_from","address_to","parcels"]}}}]}}}}}},"/api/v2/rate/shipments":{"post":{"summary":"Crear un envío sin cotizar V2","tags":["Envíos"],"description":"Crea un envío cotizando y generando la guía en la misma solicitud. A diferencia de V1, este endpoint siempre retorna un arreglo de envíos bajo la llave `data`. Para envíos simples o multi-paquete el arreglo contiene un elemento. Para multi-envío (paqueterías sin soporte nativo de multi-paquete) el arreglo contiene un envío por paquete.","parameters":[],"responses":{"202":{"description":"Retorna un arreglo de envíos creados","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","status","rate","packages"],"properties":{"id":{"type":"string","format":"uuid","example":"73783895-147e-40f6-83d8-5f901d71a1a3"},"status":{"type":"string","example":"success"},"master_tracking_number":{"type":"string","nullable":true,"example":"1234567890"},"label_url":{"type":"string","nullable":true,"example":"https://label.com"},"order_detail_url":{"type":"string","nullable":true,"example":"https://api.example.com/rails/active_storage/blobs/.../order_details.pdf","description":"URL al PDF del detalle de la orden (packing slip). Se completa cuando `include_order_detail: true` fue enviado en el request y el documento se generó correctamente. `null` en caso contrario.\n"},"rate":{"type":"object","required":["success","id","provider_name","provider_display_name","provider_service_name","provider_service_code","status","currency_code","amount","total","days","insurable","has_own_agreement","extra_fees","packaging_type","weight","protection_value_total","total_value_with_protection","pickup","pickup_automatic","pickup_package_min","pickup_ocurre","pickup_via_support","shipment_creation_type"],"properties":{"success":{"type":"boolean","example":false},"id":{"type":"string","format":"uuid","example":"38ed719c-6a21-4b15-9ef3-d2bdce374018"},"rate_type":{"type":"string","nullable":true,"example":"standard"},"provider_name":{"type":"string","example":"medrano santillán s.r.l chad"},"provider_display_name":{"type":"string","example":"Ups"},"provider_service_name":{"type":"string","example":"Medrano Santillán S.R.L Chad Bronze"},"provider_service_code":{"type":"string","example":"MEDRANO_SANTILLAN_S_R_L_CHAD_BRONZE"},"status":{"type":"string","example":"pending"},"currency_code":{"type":"string","example":"MXN"},"amount":{"type":"string","example":"9.99"},"total":{"type":"string","example":"100"},"days":{"type":"integer","example":1},"insurable":{"type":"boolean","example":false},"has_own_agreement":{"type":"boolean","example":false},"own_agreement_amount":{"type":"string","nullable":true,"example":"50.00"},"extra_fees":{"type":"array","items":{"type":"object"},"example":[]},"zone":{"type":"string","nullable":true},"service_zone":{"type":"string","nullable":true},"vat_fee":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"example":"MX"},"plan_type":{"type":"string","nullable":true},"packaging_type":{"type":"string","example":"package"},"error_messages":{"type":"array","nullable":true,"items":{"type":"string"}},"weight":{"type":"string","example":"0.0"},"protection_value_total":{"type":"string","example":"0.0"},"total_value_with_protection":{"type":"number","format":"float","example":0.0},"pickup":{"type":"boolean","example":false},"pickup_automatic":{"type":"boolean","example":false},"pickup_package_min":{"type":"integer","example":1},"pickup_ocurre":{"type":"boolean","example":false},"pickup_via_support":{"type":"boolean","example":false},"shipment_creation_type":{"type":"string","example":"single"},"office_delivery":{"type":"boolean","example":false},"office_pickup":{"type":"boolean","example":false},"requires_origin_verification":{"type":"boolean","example":false},"import_duty_amount":{"type":"number","nullable":true,"example":935},"customs_payment_payer":{"type":"array","nullable":true,"items":{"type":"string","enum":["sender","recipient"]},"example":["sender","recipient"]}}},"error_message_detail":{"type":"string","nullable":true,"example":"Invalid token"},"packages":{"type":"array","items":{"type":"object"},"example":[]}}}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Envío nacional (MX)","properties":{"timeout":{"type":"integer","example":8,"description":"Tiempo de espera en segundos."},"sync_label_creation":{"required":false,"type":"boolean","example":true,"description":"Opcional. Cuando es `true`, la guía se solicita a la paquetería durante la misma petición y la respuesta ya trae el estado final, en lugar de resolverse de forma asíncrona. Reduce el tiempo de respuesta; si se omite, el envío se procesa como hasta ahora."},"quotation":{"type":"object","properties":{"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"thermal"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"carrier":{"type":"object","properties":{"name":{"type":"string","example":"Nombre de la paquetería en minúscula","description":"Nombre de la paquetería"},"service_name":{"type":"string","example":"Código del servicio","description":"Nombre del servicio"}}},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"68000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Oaxaca","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"68000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Oaxaca","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["name","company","phone","email"]},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","example":5,"description":"Peso del paquete"},"height":{"type":"integer","example":5,"description":"Altura del paquete"},"width":{"type":"integer","example":5,"description":"Ancho del paquete"},"length":{"type":"integer","example":5,"description":"Longitud del paquete"},"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"}},"required":["weight","height","width","length"]}}},"required":["address_from","address_to","parcels"]}}},{"type":"object","title":"Envío internacional","properties":{"timeout":{"type":"integer","example":8,"description":"Tiempo de espera en segundos."},"sync_label_creation":{"required":false,"type":"boolean","example":true,"description":"Opcional. Cuando es `true`, la guía se solicita a la paquetería durante la misma petición y la respuesta ya trae el estado final, en lugar de resolverse de forma asíncrona. Reduce el tiempo de respuesta; si se omite, el envío se procesa como hasta ahora."},"quotation":{"type":"object","properties":{"customs_payment_payer":{"type":"string","description":"Entidad que pagará los aranceles del envío. Puede ser `sender` o `recipient`.","enum":["sender","recipient"],"example":"sender"},"shipment_purpose":{"type":"string","description":"Propósito del envío (`goods`, `documents`, `sample`, `return_of_goods`, `gift` o `humanitarian_donation`).","enum":["goods","documents","sample","return_of_goods","gift","humanitarian_donation"],"example":"goods"},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"standard"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"carrier":{"type":"object","properties":{"name":{"type":"string","example":"Nombre de la paquetería en minúscula","description":"Nombre de la paquetería"},"service_name":{"type":"string","example":"Código del servicio","description":"Nombre del servicio"}}},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"68000","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Oaxaca","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"string","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"string","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3","name","company","phone","email"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"country_code":{"type":"string","example":"US","description":"Código de país de la dirección (ISO 3166-1 alpha-2)."},"postal_code":{"type":"string","example":"33326","description":"Código postal de la dirección."},"area_level1":{"type":"string","example":"Florida","description":"Estado, provincia o departamento de la dirección."},"area_level2":{"type":"Weston","example":"Oaxaca de Juárez","description":"Ciudad o municipio de la dirección."},"area_level3":{"type":"Weston","example":"Oaxaca centro","description":"Barrio o colonia de la dirección."},"name":{"type":"string","maxLength":30,"example":"John Doe","description":"Nombre completo del remitente (máximo 30 caracteres)."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"further_information":{"type":"string","nullable":true,"maxLength":70,"example":"Dejar con el vecino","description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["country_code","postal_code","area_level1","area_level2","area_level3","name","company","phone","email"]},"parcels":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","example":5,"description":"Peso del paquete"},"height":{"type":"integer","example":5,"description":"Altura del paquete"},"width":{"type":"integer","example":5,"description":"Ancho del paquete"},"length":{"type":"integer","example":5,"description":"Longitud del paquete"},"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Producto 1","description":"Nombre del producto"},"description_en":{"type":"string","example":"Product description","description":"Descripción en inglés"},"quantity":{"type":"integer","example":1,"description":"Cantidad"},"price":{"type":"number","example":100.0,"description":"Precio en pesos mexicanos"},"sku":{"type":"string","example":"SKU-123","description":"SKU"},"hs_code":{"type":"string","example":"9706.900060","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"hs_code_description":{"type":"string","example":"Descripción del HS Code","description":"Descripción del código Harmonizado"},"product_type_code":{"type":"string","example":"P","description":"Código de tipo de producto"},"product_type_name":{"type":"string","example":"Producto","description":"Nombre del tipo de producto"},"country_code":{"type":"string","example":"MX","description":"Código de país en ISO 3166-1 alpha-2"}},"required":["name","hs_code","description_en"]}}},"required":["weight","height","width","length","products"]}}},"required":["customs_payment_payer","shipment_purpose","address_from","address_to","parcels"]}}}]}}}}}},"/api/v2/shipments":{"post":{"summary":"Crea un envío V2","tags":["Envíos"],"description":"Este endpoint permite crear un envío usando una cotización creada previamente (POST /api/v1/quotations o POST /api/v2/quotations). A diferencia de V1, este endpoint siempre retorna un arreglo de envíos. Para envíos únicos o multipaquete, el arreglo contiene un elemento. Para tarifas multienvío, el arreglo contiene un envío por paquete.\n","parameters":[],"responses":{"202":{"description":"Retorna un arreglo de envíos creados","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío\n"},"type":{"type":"string","description":"Tipo de envío\n"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del envío\n"},"carrier_name":{"type":"string","example":"fedex","description":"Nombre de la paquetería\n"},"workflow_status":{"type":"string","example":"pending","description":"Estado del envío\n"},"payment_status":{"type":"string","example":"paid","description":"Estado del pago\n"},"total":{"type":"string","example":"38.20","description":"Costo total del envío\n"},"source":{"type":"string","example":"api","description":"Origen del envío (Api `api`)\n"},"carrier_id":{"type":"string","nullable":true,"example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la paquetería\n"},"service_id":{"type":"string","nullable":true,"example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del servicio\n"},"master_tracking_number":{"type":"string","example":"1234567890","nullable":true,"description":"Número de rastreo\n"},"original_shipment_id":{"type":"string","example":"0199977a-e032-78bf-a335-00a9ae3cfdff","nullable":true,"description":"ID del envío original.\n"},"office_delivery":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"type":"boolean","nullable":true,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"type":"string","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"created_at":{"type":"string","description":"Fecha de creación\n"},"updated_at":{"type":"string","description":"Fecha de actualización\n"},"error_detail":{"type":"object","nullable":true,"description":"Detalles del error cuando el envío falla\n","properties":{"error_code":{"type":"string","nullable":true,"example":"ERR_INVALID_ADDRESS"},"error_message":{"type":"string","nullable":true,"example":"La dirección de destino no es válida"},"error_message_detail":{"type":"string","nullable":true,"example":"Token no válido"}}},"order_detail_url":{"type":"string","nullable":true,"example":"https://api.example.com/rails/active_storage/blobs/.../order_details.pdf","description":"URL al PDF del detalle de la orden (packing slip). Se completa cuando `include_order_detail: true` fue enviado en el request y el documento se generó correctamente. `null` en caso contrario.\n"}}},"relationships":{"type":"object","properties":{"packages":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"address_from":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"address_to":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}}},"included":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID del paquete\n"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete\n"},"weight":{"type":"string","example":1,"description":"Peso del paquete\n"},"length":{"type":"string","example":1,"description":"Longitud del paquete\n"},"width":{"type":"string","example":1,"description":"Ancho del paquete\n"},"height":{"type":"string","example":1,"description":"Altura del paquete\n"},"consignment_note":{"type":"string","example":53102400,"description":"Carta porte ID\n"},"package_content":{"type":"string","nullable":true},"tracking_url_provider":{"type":"string","nullable":true,"example":"https://www.fedex.com/fedextrack/?trknbr=234234234233","description":"URL de seguimiento\n"},"tracking_status":{"type":"string","nullable":true,"example":"created","description":"Estado de seguimiento\n"},"tracking_number":{"type":"string","nullable":true,"example":123123123123,"description":"Número de seguimiento\n"},"label_url":{"type":"string","nullable":true,"example":"https://label.com","description":"URL de la guía\n"},"created_at":{"type":"string","description":"Fecha de creación\n"},"updated_at":{"type":"string","description":"Fecha de actualización\n"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string","example":"0ac5adcc-a13d-427d-81dd-9ddd70b2f660","description":"UUID de la dirección\n"},"area_level1":{"type":"string","example":"Ciudad de México","description":"Estado, provincia o departamento de la dirección\n"},"area_level2":{"type":"string","example":"Venustiano Carranza","description":"Ciudad o municipio de la dirección\n"},"name":{"type":"string","example":"Juan","description":"Nombre del destinatario o remitente\n"},"postal_code":{"type":"string","example":"15400","description":"Código postal de la dirección\n"},"country_code":{"type":"string","example":"MX","description":"Código de país de la dirección\n"},"address_type":{"type":"string","example":"to","description":"Tipo de dirección\n"},"street1":{"type":"string","example":"Persia 143","description":"Calle y número de la dirección\n"},"company":{"type":"string","example":"Company name","description":"Nombre de la empresa\n"},"phone":{"type":"string","example":"3453453453453","description":"Número de teléfono\n"},"email":{"type":"string","example":"juan@mail.com","description":"Correo electrónico\n"},"reference":{"type":"string","example":"porton","description":"Referencia de la dirección\n"},"area_level3":{"type":"string","example":"Romero rubio","description":"Barrio o colonia de la dirección\n"},"apartment_number":{"type":"string","nullable":true,"description":"Número de departamento\n"},"further_information":{"type":"string","nullable":true,"description":"Información adicional para la entrega (máximo 70 caracteres). Se imprime en la guía cuando está habilitado para la paquetería.\n"},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000"},"tax_id_type":{"type":"string","nullable":true,"example":"rfc"}}},"relationships":{"type":"object","properties":{"shipment":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}}}}}]}}}}}}},"422":{"description":"Fondos insuficientes","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"string","additionalProperties":true,"example":"Fondos insuficientes"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Envío nacional (MX)","properties":{"shipment":{"type":"object","properties":{"rate_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id único del precio obtenido al consultar la cotización (GET  /api/v1/quotations/{id})."},"unique_shipment":{"type":"boolean","required":false,"default":false,"example":false,"description":"Opcional. Cuando es true, el sistema cachea la respuesta para el rate_id y la replica en reintentos con el mismo rate_id, evitando envíos duplicados. Devuelve 200 OK con el payload original en replay, 409 Conflict si una solicitud previa aún está en proceso. El cache vive 96 horas, alineado al ciclo de vida del rate_id."},"original_shipment_id":{"required":false,"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del envío original."},"auto_advance":{"required":false,"type":"boolean","example":false,"description":"Opcional. **Solo en sandbox**. Cuando es `true`, simula la progresión automática del tracking del envío (created → picked_up → in_transit → last_mile → delivered) cada minuto, sin esperar al carrier real. En producción se ignora."},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"thermal"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"office_delivery":{"required":false,"type":"boolean","default":false,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el destinatario recoge el paquete en una sucursal del paquetero. Requiere office_delivery_point_id."},"office_pickup":{"required":false,"type":"boolean","default":false,"example":false,"description":"Boolean opcional (por defecto `false`). Ponlo en `true` para un envío Ocurre donde el remitente entrega el paquete en una sucursal del paquetero. Requiere office_pickup_point_id."},"office_delivery_point_id":{"required":false,"type":"string","format":"uuid","nullable":true,"example":"","description":"ID del punto de oficina de destino, obtenido de GET /api/v1/office_points. Requerido cuando office_delivery es true."},"office_pickup_point_id":{"required":false,"type":"string","format":"uuid","nullable":true,"example":"","description":"ID del punto de oficina de origen, obtenido de GET /api/v1/office_points. Requerido cuando office_pickup es true."},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"name":{"type":"string","maxLength":30,"example":"Homero Simpson","description":"Nombre completo del remitente (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["street1","name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Avenida Example","description":"Calle y número de la dirección."},"name":{"type":"string","maxLength":30,"example":"Bart Simpson","description":"Nombre completo del destinatario (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["street1","name","company","phone","email"]},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID del producto"},"name":{"type":"string","example":"Producto 1","description":"Nombre del producto"},"description_en":{"type":"string","example":"Product description","description":"Descripción en inglés"},"quantity":{"type":"integer","example":1,"description":"Cantidad"},"price":{"type":"number","example":100.0,"description":"Precio en pesos mexicanos"},"sku":{"type":"string","example":"SKU-123","description":"SKU"},"hs_code":{"type":"string","example":"9706.900060","description":"Código HS del producto. Escríbenos a api@skydropx.com para obtener el listado."},"hs_code_description":{"type":"string","example":"Descripción del HS Code","description":"Descripción del código Harmonizado"},"product_type_code":{"type":"string","example":"P","description":"Código de tipo de producto"},"product_type_name":{"type":"string","example":"Producto","description":"Nombre del tipo de producto"},"country_code":{"type":"string","example":"MX","description":"Código de país en ISO 3166-1 alpha-2"}}}}}}}},"required":["rate_id","address_from","address_to","packages"]}}},{"type":"object","title":"Envío internacional","properties":{"shipment":{"type":"object","properties":{"rate_id":{"type":"string","example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"Id único del precio obtenido al consultar la cotización (GET  /api/v1/quotations/{id})."},"unique_shipment":{"type":"boolean","required":false,"default":false,"example":false,"description":"Opcional. Cuando es true, el sistema cachea la respuesta para el rate_id y la replica en reintentos con el mismo rate_id, evitando envíos duplicados. Devuelve 200 OK con el payload original en replay, 409 Conflict si una solicitud previa aún está en proceso. El cache vive 96 horas, alineado al ciclo de vida del rate_id."},"customs_payment_payer":{"type":"string","description":"Entidad que pagará los aranceles del envío. Puede ser `sender` o `recipient`.","enum":["sender","recipient"],"example":"sender"},"shipment_purpose":{"type":"string","description":"Propósito del envío (`goods`, `documents`, `sample`, `return_of_goods`, `gift` o `humanitarian_donation`).","enum":["goods","documents","sample","return_of_goods","gift","humanitarian_donation"],"example":"goods"},"printing_format":{"required":false,"type":"string","description":"Formato de impresión de la guía, puede ser `standard` o `thermal`.","enum":["standard","thermal"],"example":"standard"},"include_order_detail":{"required":false,"type":"boolean","description":"Boolean opcional (por defecto `false`). Si es `true`, el sistema genera también el detalle de la orden (packing slip) y devuelve su URL en `order_detail_url` cuando esté disponible. Si es `false` u omitido, `order_detail_url` viene como `null`. Una falla en la generación de este documento no afecta la creación del envío; la URL simplemente permanece en `null`.\n","example":false},"address_from":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de origen previamente guardada. Si se proporciona, rellena los campos no enviados en address_from y vincula la plantilla al envío para validar su verificación por carrier. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_from; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Calle Example","description":"Calle y número de la dirección."},"name":{"type":"string","maxLength":30,"example":"Homero Simpson","description":"Nombre completo del remitente (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Acme INC","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434445","description":"Número de teléfono."},"email":{"type":"string","example":"homero@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":30,"example":"Casa de Homero","description":"Referencia de la dirección (máximo 30 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"XAXX010101000","description":"Número de identificación fiscal del remitente."}},"required":["street1","name","company","phone","email","reference"]},"address_to":{"type":"object","properties":{"address_template_id":{"type":"string","format":"uuid","nullable":true,"example":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","description":"ID de una plantilla de dirección de destino previamente guardada. Si se proporciona, rellena los campos no enviados en address_to. Importante — aunque la cotización asociada se haya creado con un address_template_id, este NO se hereda automáticamente al envío. Si deseas reutilizar la plantilla al crear el envío debes volver a enviar su address_template_id en address_to; de lo contrario se usarán los campos explícitos del payload y solo se heredarán de la cotización country_code, postal_code y area_level1/2/3."},"street1":{"type":"string","maxLength":45,"example":"Avenida Example","description":"Calle y número de la dirección."},"name":{"type":"string","maxLength":30,"example":"Bart Simpson","description":"Nombre completo del destinatario (máximo 30 caracteres)."},"company":{"type":"string","maxLength":60,"example":"Example Company LTDA.","description":"Nombre de la empresa (máximo 60 caracteres)."},"phone":{"type":"string","example":"4434434444","description":"Número de teléfono."},"email":{"type":"string","example":"bart@simpson.com","description":"Correo electrónico."},"reference":{"type":"string","maxLength":40,"example":"Casa de Bart","description":"Referencia de la dirección (máximo 40 caracteres)."},"tax_id_number":{"type":"string","nullable":true,"example":"123456789","description":"Número de identificación fiscal del destinatario."}},"required":["street1","name","company","phone","email"]},"packages":{"type":"array","items":{"type":"object","properties":{"package_number":{"type":"string","example":"1","description":"Número de índice del paquete cotizado."},"package_protected":{"type":"boolean","example":true,"description":"Si tiene seguro se pone true, si no tiene agrega false."},"declared_value":{"type":"number","example":2500.0,"description":"Si tiene seguro se pone el valor a asegurar, ejemplo 500. El valor está en pesos mexicanos."},"consignment_note":{"type":"string","example":"53102400","description":"Carta porte ID"},"package_type":{"type":"string","example":"4G","description":"Tipo de paquete"},"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Moldes dentales - USA","description":"Nombre del producto"},"sku":{"type":"string","example":"SKU-1","description":"SKU"},"product_type_code":{"type":"string","example":"42152400","description":"Código de tipo de producto"},"product_type_name":{"type":"string","example":"Materiales dentales","description":"Nombre del tipo de producto"}}}}}}}},"required":["rate_id","customs_payment_payer","shipment_purpose","address_from","address_to","packages"]}}}]}}}}}}},"servers":[{"url":"https://api-pro.skydropx.com","description":"Skydropx API"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Para obtener el Token de Acceso, realiza una solicitud al endpoint /api/v1/oauth/token.","scheme":"bearer"}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"OAuth","description":"Gestiona la autenticación y autorización de usuarios utilizando el protocolo OAuth."},{"name":"Cotizaciones","description":"Accede y gestiona cotizaciones dentro del sistema.\n\n- [Códigos de paquetería (ID)](https://help.skydropx.com/subcategorias-cda/api)"},{"name":"Envíos","description":"Accede y gestiona envíos dentro del sistema.\n\n- [Códigos de Carta Porte](https://help.skydropx.com/articulos-cda/codigos-carta-porte)\n- [Códigos de empaque](https://help.skydropx.com/articulos-cda/codigos-de-tipos-de-empaques)"},{"name":"Puntos de oficina","description":"Puntos de oficina del paquetero (sucursales) para envíos Ocurre, donde el destinatario recoge el paquete (delivery) o el remitente lo entrega (pickup)."},{"name":"Ordenes","description":"Accede y gestiona órdenes dentro del sistema."},{"name":"Opciones de impresión","description":"Modifica el formato de impresión"},{"name":"Movimientos","description":"Consulta de movimientos y estadísticas de transacciones."},{"name":"Finanzas","description":"Endpoints de finanzas."},{"name":"Direcciones","description":"Gestiona direcciones y verificaciones de paqueterías."},{"name":"Envíos Externos","description":"Registra y rastrea envíos creados fuera de la app."},{"name":"Recolecciones","description":"Programa las recolecciones de tus paquetes"},{"name":"Productos","description":"Acceso y gestión de productos dentro del sistema."},{"name":"Errores","description":"Información sobre los tipos de errores que puede devolver la API y sus códigos correspondientes.\n\n## Estructura de Ejemplo\n\nTodos los errores de la API siguen esta estructura JSON:\n\n```json\n{\n  \"error\": \"invalid_request\",\n  \"error_description\": \"El contenido de la solicitud no es válido\"\n}\n```\n\n> [!note]\n> Los campos 'error' y 'error_description' proporcionan información detallada sobre el problema encontrado.\n\n## Códigos de Error\n\nLa siguiente tabla muestra todos los códigos de error posibles, sus estados HTTP asociados y descripciones:\n\n| Código | Estado HTTP | Descripción |\n| --- | --- | --- |\n| bad_request | 400 | Archivo inválido (faltante, formato incorrecto o demasiado grande) |\n| bad_request | 400 | Credenciales faltantes |\n| bad_request | 400 | Falta el objeto pickup en la solicitud |\n| bad_request | 400 | Faltan parámetros requeridos |\n| bad_request | 400 | Retorna una respuesta de error |\n| bad_request | 400 | Retorna una respuesta de error (solicitud incorrecta) |\n| unauthorized | 401 | Credenciales inválidas |\n| forbidden | 403 | Cliente no autorizado |\n| not_found | 404 | Cotización no encontrada |\n| not_found | 404 | Dirección no encontrada |\n| not_found | 404 | Envío no encontrado |\n| not_found | 404 | Este número de guía no cuenta con eventos de rastreo |\n| not_found | 404 | Importación no encontrada |\n| not_found | 404 | Orden no encontrada |\n| not_found | 404 | Recolección no encontrada |\n| not_found | 404 | Recurso no encontrado |\n| not_found | 404 | Retorna un mensaje de no encontrado |\n| unprocessable_entity | 422 | El envío no se puede cancelar |\n| unprocessable_entity | 422 | El envío no se puede proteger |\n| unprocessable_entity | 422 | Fondos insuficientes |\n| unprocessable_entity | 422 | La orden no puede ser actualizada |\n| unprocessable_entity | 422 | La paquetería no está disponible en tu cuenta |\n| unprocessable_entity | 422 | La recolección no se puede reprogramar, ya fue archivada, los envíos no forman un solo grupo elegible o la franja horaria no es válida |\n| unprocessable_entity | 422 | Los envíos no forman un solo grupo elegible, la franja horaria no es válida o la paquetería rechazó la recolección |\n| unprocessable_entity | 422 | No se encontró un envío con ese número de rastreo para el carrier indicado |\n| unprocessable_entity | 422 | Retorna una respuesta de error |\n| unprocessable_entity | 422 | Solicitud inválida |\n| unprocessable_entity | 422 | Solicitud inválida. |\n\n## Información Adicional\n\n- Todos los errores incluyen un código único y una descripción detallada.\n- Los códigos de estado HTTP siguen los estándares REST estándar.\n- Use el campo 'error' para identificar programáticamente el tipo de error."},{"name":"Webhooks","description":"## Eventos disponibles\n\n### Cargos Adicionales\n\n- **Pending_payment:** El cargo adicional está pendiente de pago.\n- **Paid:** El cargo adicional ha sido pagado.\n\n### Órdenes\n\n- **Draft:** Hay una orden sin envío.\n- **Partially_sent:** Parte de la orden ha sido enviada.\n- **Sent:** La orden ha sido enviada.\n- **Fulfilled:** El envío de la orden ha sido completado.\n\n### Cotizaciones\n\n- **Pending:** Inició el proceso de cotización.\n- **Completed:** Proceso de cotización finalizado.\n\n### Tarifas\n\n- **Created:** Inició el cálculo de la tarifa.\n- **Errored:** Falló el cálculo de la tarifa.\n- **Completed:** Tarifa calculada exitosamente.\n\n### Envíos\n\n- **Created:** El envío ha sido creado.\n- **Exception:** El envío presenta un problema detectado por la paquetería.\n- **Picked_up:** El paquete ha sido recogido por la paquetería.\n- **In_transit:** El envío está recorriendo su ruta de entrega.\n- **Last_mile:** El paquete se encuentra cerca de la dirección de destino.\n- **Delivery_attempt:** Se intentó entregar el paquete, pero no se pudo completar.\n- **Delivered:** El paquete ha sido entregado exitosamente al destinatario.\n- **Delivered_to_branch:** El paquete está disponible para recoger en sucursal.\n- **In_return:** El paquete está siendo devuelto al remitente.\n- **Canceled:** Tu envío fue cancelado.\n- **Error:** El envío no pudo ser creado.\n\n### Recolecciones\n\n- **Scheduled:** La recolección fue programada exitosamente.\n- **Collected:** El carrier completó la recolección.\n- **Delayed:** La recolección fue marcada como retrasada.\n- **Incident:** Se registró una incidencia operativa en la recolección.\n- **Scheduling_error:** Ocurrió un error al programar la recolección.\n\n## Descripción general:\n\nLos webhooks permiten que servicios externos reciban actualizaciones en tiempo real desde nuestra aplicación. Este cliente es responsable de enviar notificaciones cuando ocurren eventos específicos en nuestro sistema.\n\nPodrás activar los Webhooks ingresando a la plataforma, desde la sección Conexiones>Webhooks.\n\n## Encabezados de la solicitud\n\nEl nombre del encabezado de autenticación puede configurarse dinámicamente. Por defecto, se utiliza *Authorization*, pero puede asignarse cualquier nombre que cumpla con las siguientes condiciones:\n\n- Contener entre 3 y 25 caracteres.\n- No incluir espacios.\n\n**Autenticación con Bearer Token (menos segura):**\n\n```\nAuthorization: Bearer <token> (token proporcionado por nosotros)\nContent-Type: application/json\n```\n\n\n**Autenticación HMAC (recomendada):**\n\n```\nAuthorization: HMAC <firma>\nContent-Type: application/json\n```\n\n\nLa firma se genera utilizando el algoritmo HMAC con la función hash SHA-512, como se define en el [RFC 6234](https://www.rfc-editor.org/rfc/rfc6234.html), usando tu clave secreta. El HMAC se calcula sobre el cuerpo crudo de la solicitud (bytes exactos, sin formato) y se codifica como una cadena hexadecimal en minúsculas.\n\n## Cuerpo de la solicitud\n\nEl cuerpo de la solicitud contiene información relevante sobre el evento notificado.\n\n**• Ejemplo de envíos con orden:**\n\n```\n{\n  \"data\": {\n    \"id\": \"6172eb82-7b0b-4852-9954-b1ac1c20e4f8\",\n    \"type\": \"packages\",\n    \"attributes\": {\n      \"status\": \"delivered\",\n      \"tracking_number\": \"794874381730\",\n      \"tracking_url_provider\": \"https://www.fedex.com/fedextrack/?trknbr=794874381730\",\n      \"label_url\": \"https://api.example.com/cloud/storage/blobs/proxy/30a9d3/label_794874381730.pdf\",\n      \"returned_status\": null,\n      \"returned\": false\n    },\n    \"relationships\": {\n      \"shipment\": {\n        \"data\": {\n          \"id\": \"93774c22-8275-4757-9963-71b79b2e8db7\",\n          \"type\": \"shipments\"\n        },\n        \"links\": {\n          \"related\": \"https://api.example.com/api/v1/shipments/93774c22-8275-4757-9963-71b79b2e8db7\"\n        }\n      },\n      \"order\": {\n        \"data\": {\n          \"id\": \"41ae1bf9-bccf-47dd-ba85-053b42f530c2\",\n          \"type\": \"orders\"\n        },\n        \"links\": {\n          \"related\": \"https://api.example.com/api/v1/orders/41ae1bf9-bccf-47dd-ba85-053b42\n        }\n      }\n    }\n  }\n}\n```\n\n\n**• Ejemplo de envíos sin orden:**\n\n```\n{\n  \"data\": {\n    \"id\": \"6172eb82-7b0b-4852-9954-b1ac1c20e4f8\",\n    \"type\": \"packages\",\n    \"attributes\": {\n      \"status\": \"delivered\",\n      \"tracking_number\": \"794874381730\",\n      \"tracking_url_provider\": \"https://www.fedex.com/fedextrack/?trknbr=794874381730\",\n      \"label_url\": \"https://api.example.com/cloud/storage/blobs/proxy/30a9d3/label_794874381730.pdf\",\n      \"returned_status\": null,\n      \"returned\": false\n    },\n    \"relationships\": {\n      \"shipment\": {\n        \"data\": {\n          \"id\": \"93774c22-8275-4757-9963-71b79b2e8db7\",\n          \"type\": \"shipments\"\n        },\n        \"links\": {\n          \"related\": \"https://api.example.com/api/v1/shipments/93774c22-8275-4757-9963-71b79b2e8db7\"\n        }\n      }\n    }\n  }\n}\n```\n\n\n**• Ejemplo de envíos en retorno:**\n\n```\n{\n  \"data\": {\n    \"id\": \"ad73fd3a-0fe4-4fee-9f7c-8c092e1c22a9\",\n    \"type\": \"packages\",\n    \"attributes\": {\n      \"status\": \"in_return\",\n      \"tracking_number\": \"2594564698\",\n      \"tracking_url_provider\": \"https://www.fedex.com/fedextrack/?trknbr=2594564698\",\n      \"label_url\": \"\",\n      \"event_description\": \"\",\n      \"returned_status\": \"in_transit\",\n      \"returned\": true\n    },\n    \"relationships\": {\n      \"shipment\": {\n        \"data\": {\n          \"id\": \"7121cb9b-1cc3-4c01-9a8d-e86fcadeea6e\",\n          \"type\": \"shipments\"\n        },\n        \"links\": {\n          \"related\": \"https://api.example.com/api/v1/shipments/7121cb9b-1cc3-4c01-9a8d-e86fcadeea6e\"\n        }\n      }\n    }\n  }\n}\n```\n\n\n**• Ejemplo de órdenes:**\n\n```\n{\n  \"data\": {\n    \"id\": \"1f92595c-1ba5-40f8-a52b-4788db608293\",\n    \"type\": \"orders\",\n    \"attributes\": {\n      \"status\": \"sent\",\n      \"platform\": \"shopify\",\n      \"platform_id\": \"69b24c26-00f0-4099-90cc-a5c8b26d9bfa\",\n      \"ecommerce_id: \"2d3afffd-ce69-4aa5-ae80-549487d8d5c5\",\n      \"price\": 10_000,\n      \"payment_status\": 'paid',\n      \"delivery_type\": \"shipping\"\n    },\n    \"links\": {\n      \"self\": \"https://api.example.com/api/v1/orders/1f92595c-1ba5-40f8-a52b-4788db608293\"\n    }\n  }\n}\n```\n\n\n**• Ejemplo de cotización:**\n\n```\n{\n  \"data\": {\n    \"id\": \"dde96439-67a9-41ec-90ed-af7f4ca2cec9\",\n    \"type\": \"quotation\",\n    \"attributes\": {\n      \"status\": \"completed\",\n      \"country_code_from\": \"MX\",\n      \"postal_code_from\": \"25904\",\n      \"area_level3_from\": \"Portales\",\n      \"area_level2_from\": \"Ramos Arizpe\",\n      \"area_level1_from\": \"Coahuila de Zaragoza\",\n      \"name_from\": \"Skydropx\",\n      \"email_from\": \"soporte@skydropx.com\",\n      \"phone_from\": \"8341713030\",\n      \"street1_from\": \"Calle\",\n      \"reference_from\": \"Sin referencias\",\n      \"company_from\": \"Skydropx\",\n      \"apartment_number_from\": null,\n      \"country_code_to\": \"MX\",\n      \"postal_code_to\": \"64000\",\n      \"area_level3_to\": \"Monterrey Centro\",\n      \"area_level2_to\": \"Monterrey\",\n      \"area_level1_to\": \"Nuevo León\",\n      \"name_to\": \"Skydropx\",\n      \"email_to\": \"soporte@skydropx.com\",\n      \"phone_to\": \"8341713030\",\n      \"street1_to\": \"Calle\",\n      \"reference_to\": \"Sin referencias\",\n      \"company_to\": \"Skydropx\",\n      \"apartment_number_to\": null\n    },\n    \"relationships\": {\n      \"rates\": {\n        \"data\": [\n          {\n            \"id\": \"4c02c346-0b66-46f3-9c2a-ec98eec56aa4\",\n            \"type\": \"rate\"\n          },\n          {\n            \"id\": \"938f6079-e608-4baa-b9b5-8be7f4de0535\",\n            \"type\": \"rate\"\n          },\n          {\n            \"id\": \"767612b3-9124-4388-889d-451cbba9dd68\",\n            \"type\": \"rate\"\n          }\n        ]\n      },\n      \"packages\": {\n        \"data\": [\n          {\n            \"id\": \"5beefc46-352d-47d9-9856-2d3e2ec0f52a\",\n            \"type\": \"package\"\n          }\n        ]\n      }\n    },\n    \"links\": {\n      \"self\": \"https://api.example.com/api/v1/quotations/dde96439-67a9-41ec-90ed-af7f4ca2cec9\"\n    }\n  },\n  \"included\": [\n    {\n      \"id\": \"4c02c346-0b66-46f3-9c2a-ec98eec56aa4\",\n      \"type\": \"rate\",\n      \"attributes\": {\n        \"success\": false,\n        \"rate_type\": null,\n        \"provider_name\": \"fedex\",\n        \"provider_display_name\": \"FedEx\",\n        \"provider_service_name\": \"Express Saver\",\n        \"provider_service_code\": \"fedex_express_saver\",\n        \"status\": \"not_applicable\",\n        \"currency_code\": null,\n        \"cost\": null,\n        \"amount\": null,\n        \"total\": null,\n        \"days\": null,\n        \"insurable\": null,\n        \"has_own_agreement\": false,\n        \"own_agreement_amount\": null,\n        \"extra_fees\": null,\n        \"zone\": null,\n        \"country_code\": null,\n        \"plan_type\": null,\n        \"packaging_type\": \"package\",\n        \"weight\": 5\n      },\n      \"relationships\": {\n        \"quotation\": {\n          \"data\": {\n            \"id\": \"dde96439-67a9-41ec-90ed-af7f4ca2cec9\",\n            \"type\": \"quotation\"\n          },\n          \"links\": {\n            \"related\": \"https://api.example.com/api/v1/quotations/dde96439-67a9-41ec-90ed-af7f4ca2cec9\"\n          }\n        }\n      }\n    },\n    {\n      \"id\": \"938f6079-e608-4baa-b9b5-8be7f4de0535\",\n      \"type\": \"rate\",\n      \"attributes\": {\n        \"success\": true,\n        \"rate_type\": \"default\",\n        \"provider_name\": \"sendex\",\n        \"provider_display_name\": \"Sendex\",\n        \"provider_service_name\": \"Sin recoleccion\",\n        \"provider_service_code\": \"sin_recoleccion\",\n        \"status\": \"price_found_external\",\n        \"currency_code\": \"MXN\",\n        \"cost\": \"74.3\",\n        \"amount\": \"106.19\",\n        \"total\": \"106.19\",\n        \"days\": 1,\n        \"insurable\": null,\n        \"has_own_agreement\": false,\n        \"own_agreement_amount\": null,\n        \"extra_fees\": [],\n        \"zone\": \"3\",\n        \"country_code\": \"MX\",\n        \"plan_type\": null,\n        \"packaging_type\": \"package\",\n        \"error_messages\": {},\n        \"weight\": 5\n      },\n      \"relationships\": {\n        \"quotation\": {\n          \"data\": {\n            \"id\": \"dde96439-67a9-41ec-90ed-af7f4ca2cec9\",\n            \"type\": \"quotation\"\n          },\n          \"links\": {\n            \"related\": \"https://api.example.com/api/v1/quotations/dde96439-67a9-41ec-90ed-af7f4ca2cec9\"\n          }\n        }\n      }\n    },\n    {\n      \"id\": \"767612b3-9124-4388-889d-451cbba9dd68\",\n      \"type\": \"rate\",\n      \"attributes\": {\n        \"success\": true,\n        \"rate_type\": \"default\",\n        \"provider_name\": \"dhl\",\n        \"provider_display_name\": \"DHL\",\n        \"provider_service_name\": \"Standard\",\n        \"provider_service_code\": \"standard\",\n        \"status\": \"price_found_external\",\n        \"currency_code\": \"MXN\",\n        \"cost\": \"153.54\",\n        \"amount\": \"228.11\",\n        \"total\": \"246.74\",\n        \"days\": 1,\n        \"insurable\": null,\n        \"has_own_agreement\": false,\n        \"own_agreement_amount\": null,\n        \"extra_fees\": [\n          {\n            \"code\": \"FUEL_SURCHARGE_FEE\",\n            \"value\": 18.63,\n            \"currency_code\": \"MXN\"\n          }\n        ],\n        \"zone\": \"flat\",\n        \"country_code\": \"MX\",\n        \"plan_type\": null,\n        \"packaging_type\": \"package\",\n        \"error_messages\": {},\n        \"weight\": 5\n      },\n      \"relationships\": {\n        \"quotation\": {\n          \"data\": {\n            \"id\": \"dde96439-67a9-41ec-90ed-af7f4ca2cec9\",\n            \"type\": \"quotation\"\n          },\n          \"links\": {\n            \"related\": \"https://api.example.com/api/v1/quotations/dde96439-67a9-41ec-90ed-af7f4ca2cec9\"\n          }\n        }\n      }\n    },\n    {\n      \"id\": \"5beefc46-352d-47d9-9856-2d3e2ec0f52a\",\n      \"type\": \"package\",\n      \"attributes\": {\n        \"package_number\": 1,\n        \"weight\": \"5.0\",\n        \"length\": \"7.0\",\n        \"width\": \"7.0\",\n        \"height\": \"7.0\"\n      }\n    }\n  ]\n}\n```\n\n\n**• Ejemplo de tarifas:**\n\n```\n{\n  \"data\": {\n    \"id\": \"ab85cf5a-0129-42ea-9e6a-cc50cb19d99b\",\n    \"type\": \"rate\",\n    \"attributes\": {\n      \"success\": true,\n      \"rate_type\": \"default\",\n      \"provider_name\": \"sendex\",\n      \"provider_display_name\": \"Sendex\",\n      \"provider_service_name\": \"Reg\",\n      \"provider_service_code\": \"reg\",\n      \"status\": \"price_found_external\",\n      \"currency_code\": \"MXN\",\n      \"cost\": \"74.3\",\n      \"amount\": \"106.19\",\n      \"total\": \"106.19\",\n      \"days\": 1,\n      \"insurable\": null,\n      \"has_own_agreement\": false,\n      \"own_agreement_amount\": null,\n      \"extra_fees\": [],\n      \"zone\": \"3\",\n      \"country_code\": \"MX\",\n      \"plan_type\": null,\n      \"packaging_type\": \"package\",\n      \"error_messages\": {},\n      \"weight\": 5\n    },\n    \"relationships\": {\n      \"quotation\": {\n        \"data\": {\n          \"id\": \"76b094f9-0e15-4505-8a45-948931baf847\",\n          \"type\": \"quotation\"\n        },\n        \"links\": {\n          \"related\": \"http://skydropx.localhost.skydropx:3000/api/v1/quotations/76b094f9-0e15-4505-8a45-948931baf847\"\n        }\n      }\n    }\n  }\n}\n```\n\n\n**• Ejemplo de cargos extra (Aplica para todos los tipos, metadatos pueden variar):**\n\n```\n{\n  \"data\": {\n    \"id\": \"ec12345-abcd-4567-8901-23456789abcd\",\n    \"type\": \"extra_charges\",\n    \"attributes\": {\n      \"status\": \"pending_payment\",\n      \"carrier\": \"FedEx\",\n      \"service\": \"Standard Overnight\",\n      \"tracking_number\": \"794874381730\",\n      \"label_date\": \"2024-02-27T00:00:00-06:00\",\n      \"detection_date\": \"2024-02-27T14:30:00-06:00\",\n      \"amount\": \"125.50\",\n      \"charge_type\": \"ExtraCharge::AddressUpdate\",\n      \"metadata\": {\n        \"overweight\": \"2.0\",\n        \"real_width\": \"10.0\",\n        \"real_height\": \"10.0\",\n        \"real_length\": \"10.0\",\n        \"real_weight\": \"4.0\",\n        \"quotation_id\": \"88352d20-3ee6-4ea0-bdb3-bd26d9cfba1e\",\n        \"original_weight\": \"2.0\",\n        \"quotation_status\": \"coverage_found\",\n        \"discrepancy_weight\": \"2.0\",\n        \"last_quotation_try_at\": \"2026-02-17T16:59:09.944-06:00\",\n        \"real_volumetric_weight\": \"1.0\"\n      }\n    },\n    \"relationships\": {\n      \"shipment\": {\n        \"data\": {\n          \"id\": \"93774c22-8275-4757-9963-71b79b2e8db7\",\n          \"type\": \"shipments\"\n        },\n        \"links\": {\n          \"related\": \"https://api.example.com/api/v1/shipments/93774c22-8275-4757-9963-71b79b2e8db7\"\n        }\n      }\n    }\n  }\n}\n```\n\n\n**• Ejemplo de recolecciones:**\n\n```\n{\n  \"data\": {\n    \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n    \"type\": \"pickups\",\n    \"attributes\": {\n      \"status\": \"scheduled\",\n      \"tracking_number\": \"794874381730\",\n      \"folio\": \"987654321\",\n      \"carrier\": \"FedEx\",\n      \"updated_at\": \"2026-04-29T12:00:00-06:00\"\n    },\n    \"links\": {\n      \"self\": \"https://api.example.com/api/v1/pickups/a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n    }\n  }\n}\n```\n\n\n## Métodos de autenticación\n\n**Autenticación con Bearer Token**\n\nUtiliza el token estático proporcionado para una autenticación sencilla (menos segura).\n\n**Autenticación HMAC (Recomendada)**\n\n- Crear la cadena de firma: *raw_request_body*.\n- Calcular HMAC-SHA512 utilizando tu clave secreta.\n- Enviar la firma en el encabezado *Authorization*.\n\n## Información adicional\n\nPor razones de privacidad, no podemos compartir toda la información directamente en el webhook. Sin embargo, los clientes pueden hacer una solicitud adicional a la API usando los enlaces proporcionados en el cuerpo de la respuesta para obtener los detalles completos del evento.\n\nPara la documentación completa de la API:\n\n- Envíos: [Documentación de envíos](/es-MX/api-docs#get-api-v1-shipments-id)\n- Órdenes: [Documentación de órdenes](/es-MX/api-docs#get-api-v1-orders-id)\n\n**Envíos en retorno:**\n\nCuando un envío está en proceso de devolución, el atributo *status* se establece en *\"in_return\"* durante todo el trayecto. El rastreo (tracking) detallado del paquete se reporta en el campo *returned_status*. Los atributos *returned* y *returned_status* siempre se incluyen en el payload, incluso si el envío no está en retorno (en cuyo caso los valores serán *returned: false* y *returned_status: null*).\n\n- Comportamiento de Webhooks / Eventos: Las suscripciones a eventos se siguen disparando con el estado operativo real (*in_transit*, *last_mile*, etc.) y no con *\"in_return\"*. Por lo tanto, no es necesario realizar cambios ni migraciones en tus suscripciones existentes para continuar recibiendo notificaciones durante el proceso de retorno.\n- La estructura del payload es fija: los campos *returned* y *returned_status* nunca se omiten.\n\n## Seguridad\n\nAsegúrate de que tu URL de webhook use HTTPS.\n\n**Para autenticación con Bearer Token:**\n\n- Trata el token como credenciales sensibles.\n- Rota los tokens periódicamente.\n- Valida todas las solicitudes entrantes antes de procesarlas.\n\n**Para autenticación HMAC:**\n\n- Almacena tu clave secreta de forma segura.\n\n## Contacto y soporte\n\nPara preguntas o problemas, por favor contacta a nuestro equipo de soporte en: hola@skydropx.com"}]}