{"openapi":"3.0.3","info":{"title":"Oriana · API de Paqueterías","version":"1.1.0","description":"\nAPI REST para conectar tu tienda en línea (Shopify, WooCommerce, Magento) o tu ERP con las paqueterías configuradas en Oriana: **C807 Xpress**, **Boxful**, **Xpress El Salvador (T&T)** y **Forza Delivery Express**.\n\n> **Xpress El Salvador cambió de sistema** a T&T Lite (Facilito ERP). Usá `xpress_tnt` (o el alias `xpress`, que apunta a T&T en cuanto el negocio lo configura). Sistrack se retiró en la v3.17: `sistrack` se acepta como alias de `xpress_tnt`.\n\n### Flujo recomendado\n1. `GET /ping` para comprobar la llave, sus permisos y el saldo.\n2. `GET /paqueterias` para ver cuáles están activas y qué funciones tiene cada una.\n3. Si hace falta, los **catálogos** de la paquetería (`/paqueterias/{p}/catalogos/{catalogo}`) para obtener IDs de departamentos, municipios o agencias.\n4. Con Boxful, `POST /cotizaciones` para elegir courier y precio.\n5. `POST /guias` para crear la guía. Guardá el número de guía que devuelve.\n6. `GET /guias/{p}/{guia}/etiqueta` para imprimir y `GET /guias/{p}/{guia}/tracking` para seguir el envío.\n\n### Qué ofrece cada paquetería\n| Función | C807 | Boxful | Xpress T&T | Forza |\n|---|:-:|:-:|:-:|:-:|\n| Crear guía | ✅ | ✅ | ✅ | ✅ |\n| Cobro contra entrega | ✅ | ✅ | ✅ | ✅ |\n| Cotizar | — | ✅ | — | — |\n| Tracking | ✅ | ✅ | ✅ | ✅ |\n| Etiqueta PDF | ✅ | ✅ | ✅ | ✅ |\n| Etiqueta ZPL (térmica) | ✅ | — | — | — |\n| Agencia a agencia | ✅ | — | ✅ | — |\n| Anular guía | ✅ | — | — | — |\n| Confirmar recolección | ✅ | — | — | — |\n| Catálogos | departamentos, municipios, agencias, sedes, tipos-documento | estados, direcciones-recoleccion | estados, cuentas | — |\n\n### Créditos\nSolo se cobra cuando la operación sale bien; si la paquetería rechaza o no responde, el costo es 0.\n* Crear guía: **200** créditos\n* Tracking: **30** créditos\n* Etiqueta: **30** créditos\n* Paqueterías, cobertura, catálogos y cotización: **5** créditos\n* Ping, listar guías, detalle, anular y recolección: **gratis**\n\n### Autenticación y permisos\nMandá la llave en `Authorization: Bearer ori_live_...` o en `X-API-Key: ori_live_...` (nunca en la URL). Cada llave tiene permisos:\n* `envios`: crear guías, etiquetas, anular y recolecciones.\n* `cotizar`: cotizaciones.\n* `tracking`: tracking, listado y detalle de guías.\n\n### Formato de errores\nTodas las respuestas llevan `exito`. Los errores traen `error` (código estable para programar) y `mensaje` (texto para personas).\n"},"servers":[{"url":"/api/v1","description":"Este nodo Oriana"}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"tags":[{"name":"Cuenta","description":"Estado de la llave y saldo."},{"name":"Paqueterías","description":"Paqueterías, cobertura y catálogos propios de cada una."},{"name":"Cotizaciones","description":"Precio y courier antes de crear la guía (Boxful)."},{"name":"Guías","description":"Crear, consultar, rastrear, imprimir y anular guías."},{"name":"C807","description":"Funciones exclusivas de C807 Xpress."},{"name":"Catálogo","description":"v3.17 — Productos del negocio con su imagen efectiva (propia o la «Foto única» general). La imagen general se habilita por negocio en Oriana Admin."},{"name":"API externa","description":"v3.17 — Sistema propio o de un tercero: Oriana le envía los pedidos (webhook saliente firmado) y el sistema devuelve estados. Guía completa: docs/integraciones/api-externa.md. Lo habilita Oriana Admin por negocio."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ori_live_...","description":"API Key creada en el panel (Integraciones > API Keys)."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"La misma llave, en cabecera propia."}},"schemas":{"Error":{"type":"object","required":["exito","error","mensaje"],"properties":{"exito":{"type":"boolean","example":false},"error":{"type":"string","description":"Código estable del error.","example":"datos_destinatario_incompletos"},"mensaje":{"type":"string","description":"Explicación para personas.","example":"destinatario.nombre, destinatario.telefono y destinatario.direccion son obligatorios."},"creditos_cobrados":{"type":"number","example":0}}},"Destinatario":{"type":"object","required":["nombre","telefono","direccion"],"properties":{"nombre":{"type":"string","example":"Carlos Menéndez"},"telefono":{"type":"string","description":"Solo dígitos, con o sin código de país.","example":"77889900"},"direccion":{"type":"string","example":"Colonia Escalón, Calle El Mirador #123"},"departamento":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Nombre (cualquier paquetería) o ID del catálogo de C807.","example":"San Salvador"},"municipio":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Nombre o ID del catálogo de C807.","example":"Soyapango"},"colonia":{"type":"string","description":"Colonia o referencia.","example":"Escalón"},"codigo_postal":{"type":"string","description":"Boxful.","example":"01101"},"email":{"type":"string","format":"email","example":"carlos@correo.com"},"documento_identidad":{"type":"string","description":"DUI o pasaporte (C807).","example":"01234567-8"},"punto_referencia":{"type":"string","example":"Frente a farmacia La Buena"},"indicaciones":{"type":"string","example":"Llamar antes de entregar"},"latitud":{"type":"number","description":"Boxful.","example":13.7034},"longitud":{"type":"number","description":"Boxful.","example":-89.2434}}},"Paquete":{"type":"object","properties":{"peso_libras":{"type":"number","description":"Por defecto 2.","example":3.5},"descripcion":{"type":"string","description":"Contenido del paquete.","example":"Zapatos deportivos talla 41"},"tipo_cobro":{"type":"string","enum":["cobro_contra_entrega","pagado","sin_cobro"],"description":"`cobro_contra_entrega`: la paquetería cobra `monto_a_cobrar` al entregar. `pagado`/`sin_cobro`: ya está pagado.","example":"cobro_contra_entrega"},"monto_a_cobrar":{"type":"number","description":"Obligatorio y mayor que 0 con cobro contra entrega.","example":45},"valor_declarado":{"type":"number","description":"Valor de la mercadería (Boxful).","example":45},"piezas":{"type":"integer","example":1},"tipo_entrega":{"type":"string","description":"Atajo de `opciones.c807.tipo_entrega`.","example":"NRML"}}},"OpcionesC807":{"type":"object","description":"Todo lo que la API de C807 permite al crear la guía.","properties":{"tipo_servicio":{"type":"string","enum":["SER","CCE","SEC"],"description":"`SER` servicio regular (ya pagado) · `CCE` cobro contra entrega · `SEC` envío por cobrar (el destinatario paga el flete). Si no se indica, sale de `paquete.tipo_cobro`."},"tipo_entrega":{"type":"string","enum":["NRML","PLUS","ECON","AAP","XL"],"description":"`NRML` C807 entrega a domicilio · `PLUS` dejás el paquete en tu agencia · `ECON` sucursal a sucursal (requiere `agencia_destino`) · `AAP` agencia a puerta · `XL` carga voluminosa. PLUS y AAP usan la agencia origen configurada en el panel.","example":"NRML"},"departamento_id":{"type":"integer","description":"ID del catálogo `departamentos`. Si se da junto a `municipio_id`, no se resuelve por nombre.","example":11},"municipio_id":{"type":"integer","description":"ID del catálogo `municipios`.","example":197},"agencia_destino":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"ID del catálogo `agencias`. Obligatorio con ECON.","example":4},"sede":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"ID del catálogo `sedes`.","example":1},"seguro":{"type":"boolean","description":"Asegurar el envío.","example":true},"seguro_valor_producto":{"type":"number","description":"Valor asegurado.","example":120},"identificacion":{"type":"string","description":"Documento del destinatario (prioridad sobre `destinatario.documento_identidad`).","example":"01234567-8"},"contacto":{"type":"string","description":"Persona de contacto distinta del destinatario.","example":"María (recepción)"},"orden":{"type":"string","description":"Número de orden de tu sistema, visible en C807.","example":"WC-55821"},"unidad_medida":{"type":"string","enum":["LB","KG"],"example":"LB"},"recolecta_fecha":{"type":"string","format":"date","description":"Fecha de recolección (AAAA-MM-DD). Por defecto, el próximo día hábil.","example":"2026-10-12"},"recolecta_comentario":{"type":"string","example":"Recoger después de las 2 p. m."},"direccion_alterna":{"type":"boolean","description":"Recolectar en una dirección distinta a la registrada en C807.","example":true},"recoleccion_direccion":{"type":"string","example":"Bodega 4, Zona Industrial Merliot"},"recoleccion_municipio_id":{"oneOf":[{"type":"integer"},{"type":"string"}],"example":86},"remitente_nombre":{"type":"string","example":"Tienda Ejemplo"},"remitente_telefono":{"type":"string","example":"22223333"},"remitente_correo":{"type":"string","example":"envios@tienda.com"}}},"OpcionesBoxful":{"type":"object","properties":{"courier_id":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Courier elegido en `POST /cotizaciones`. Sin él, Boxful asigna uno.","example":"12"},"direccion_recoleccion_id":{"type":"string","description":"Del catálogo `direcciones-recoleccion`. Sin él, la primera de la cuenta.","example":"addr_9f3a"}}},"OpcionesXpressTnt":{"type":"object","properties":{"cuenta":{"type":"string","description":"ID del catálogo `cuentas` (si el negocio tiene varias llaves de T&T). Sin él, la principal.","example":"tnt_ab12cd34"},"tipo_entrega":{"type":"string","enum":["DOOR_TO_DOOR","AGENCY_TO_AGENCY"],"description":"A domicilio (por defecto) o de agencia a agencia."},"agencia_destino_id":{"type":"string","description":"Obligatoria con AGENCY_TO_AGENCY: ID del catálogo `agencias` (solo las que permiten destino)."},"sub_sender_id":{"type":"string","description":"Solo a domicilio: ID del catálogo `subemisores` (tienda que entrega el paquete). Reemplaza la recolección configurada."},"bultos":{"type":"integer","minimum":1,"example":1},"fragil":{"type":"boolean"}}},"OpcionesForza":{"type":"object","description":"Remitente de esta guía. Sin él, el configurado en el panel.","properties":{"remitente_nombre":{"type":"string","example":"Tienda Ejemplo"},"remitente_telefono":{"type":"string","example":"22223333"},"remitente_direccion":{"type":"string","example":"Av. Olímpica 3500"},"remitente_municipio":{"type":"string","example":"San Salvador"},"remitente_departamento":{"type":"string","example":"San Salvador"}}},"CrearGuia":{"type":"object","required":["destinatario"],"properties":{"paqueteria":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"],"description":"Si no se indica, la primera activa en este orden: c807, boxful, xpress_tnt, forza."},"referencia_externa":{"type":"string","description":"Tu número de pedido. Sirve para buscar la guía después.","example":"PEDIDO-1001"},"forma_pago":{"oneOf":[{"type":"string","enum":["prepago","postpago","credito"]},{"type":"integer","enum":[2,3]}],"description":"Solo C807: cómo pagás el flete (2 prepago, 3 postpago/crédito). Por defecto, el del panel."},"destinatario":{"$ref":"#/components/schemas/Destinatario"},"paquete":{"$ref":"#/components/schemas/Paquete"},"opciones":{"type":"object","description":"Opciones propias de la paquetería elegida. Las de otra paquetería se ignoran.","properties":{"c807":{"$ref":"#/components/schemas/OpcionesC807"},"boxful":{"$ref":"#/components/schemas/OpcionesBoxful"},"xpress_tnt":{"$ref":"#/components/schemas/OpcionesXpressTnt"},"forza":{"$ref":"#/components/schemas/OpcionesForza"}}}}},"GuiaCreada":{"type":"object","properties":{"exito":{"type":"boolean","example":true},"paqueteria":{"type":"string","example":"c807"},"guia":{"type":"string","example":"C807-SV-0012345"},"tracking_url":{"type":"string","nullable":true,"example":"https://app.c807.com/guia.php/seguimiento/C807-SV-0012345"},"etiqueta_url":{"type":"string","example":"/api/v1/guias/c807/C807-SV-0012345/etiqueta"},"estado":{"type":"string","example":"creada"},"referencia_externa":{"type":"string","nullable":true,"example":"PEDIDO-1001"},"fecha":{"type":"string","format":"date-time"},"creditos_cobrados":{"type":"number","example":200},"saldo_restante":{"type":"number","example":9800},"recolecta":{"type":"string","nullable":true,"description":"C807: número de solicitud de recolección."},"departamento_id":{"type":"integer","description":"C807: destino resuelto."},"municipio_id":{"type":"integer","description":"C807: destino resuelto."},"envio_id":{"type":"string","description":"Boxful: número de envío."},"courier":{"type":"string","nullable":true,"description":"Boxful: courier asignado."},"costo_envio":{"type":"number","nullable":true,"description":"Boxful: costo del envío."},"order_id":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Xpress T&T: ID de la orden."},"cuenta":{"type":"string","description":"Xpress T&T: cuenta usada."}}},"Guia":{"type":"object","properties":{"paqueteria":{"type":"string"},"guia":{"type":"string"},"estado":{"type":"string"},"referencia_externa":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"etiqueta_url":{"type":"string"},"destinatario":{"type":"object","properties":{"nombre":{"type":"string"},"telefono":{"type":"string"},"direccion":{"type":"string"},"departamento":{"type":"string"},"municipio":{"type":"string"}}},"monto_cobro":{"type":"number"},"creditos_cobrados":{"type":"number"},"metadata":{"type":"object"},"creada":{"type":"string","format":"date-time"},"actualizada":{"type":"string","format":"date-time"}}}}},"paths":{"/catalogo/productos":{"get":{"tags":["Catálogo"],"summary":"Listar productos con su imagen efectiva (gratis)","description":"Devuelve los productos del catálogo (sin costos internos). `imagen.url` es la foto a mostrar: la propia del producto o, si el negocio activó «Foto única», la imagen general (`imagen.general: true`) según su modo: `sin_foto` (solo productos sin foto) o `siempre`. `imagen` es `null` si no hay ninguna.","parameters":[{"name":"wa_number_id","in":"query","required":false,"schema":{"type":"string"},"description":"Catálogo de una línea concreta (por defecto, el principal)."}],"responses":{"200":{"description":"Productos.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ejemplo":{"summary":"Modo sin_foto","value":{"exito":true,"foto_unica":{"activa":true,"modo":"sin_foto"},"productos":[{"id":"p1","nombre":"Perfume Rosa Imperial 100 ml","precio":"45","activo":true,"stock":8,"variantes":[],"imagen":{"url":"https://panel.ejemplo.com/api/catalogo/imagen/8f3a…","general":false}},{"id":"p2","nombre":"Perfume Bosque Nocturno 50 ml","precio":"39","activo":true,"stock":null,"variantes":[],"imagen":{"url":"https://panel.ejemplo.com/api/catalogo/imagen/0c71…","general":true}}]}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}}}}},"/catalogo/foto-unica":{"get":{"tags":["Catálogo"],"summary":"Configuración de la «Foto única» del negocio","responses":{"200":{"description":"Configuración.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Activa","value":{"exito":true,"activa":true,"modo":"siempre","imagen_url":"https://panel.ejemplo.com/api/catalogo/imagen/0c71…"}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La función no está habilitada para la cuenta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envios/api-externa/estado":{"post":{"tags":["API externa"],"summary":"Informar un cambio de estado de un pedido despachado por API externa","description":"El sistema externo informa el estado de un envío. Alternativa a `POST /api/webhooks/api-externa/estado` (que se autentica con la firma `X-Oriana-Firma` en vez de API Key). `estado` puede ser uno de los estados comunes (`creada`, `recolectada`, `en_transito`, `en_reparto`, `entregada`, `novedad`, `devuelta`, `anulada`) o un texto libre que Oriana clasifica. El estado nunca retrocede. Requiere que el negocio tenga activada la recepción de estados.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"numero_orden":{"type":"string"},"pedido_id":{"type":"integer"},"guia":{"type":"string"},"estado":{"type":"string"},"descripcion":{"type":"string"},"fecha":{"type":"string","format":"date-time"}}},"examples":{"entregada":{"summary":"Entregado","value":{"numero_orden":"ORD-20261020-6840","estado":"entregada","descripcion":"Entregado al cliente","fecha":"2026-10-20T18:05:00Z"}}}}}},"responses":{"200":{"description":"Estado aplicado.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Aplicado","value":{"exito":true,"ok":true,"estado":"entregada","estado_pedido":"entregado"}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"API externa no habilitada para la cuenta, o recepción de estados desactivada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Pedido no encontrado o no despachado por API externa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ping":{"get":{"tags":["Cuenta"],"summary":"Comprobar la llave, sus permisos y el saldo (gratis)","responses":{"200":{"description":"Llave válida.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Respuesta","value":{"exito":true,"mensaje":"API REST de Oriana v1 activa y autorizada.","api_key":{"id":"apk_1a2b3c","nombre":"Tienda Shopify","prefijo":"ori_live_a1b2c3...","permisos":["envios","cotizar","tracking"]},"saldo_creditos":10000,"tarifas":{"crear_guia":200,"tracking":30,"etiqueta":30,"consulta":5},"servidor_tiempo":"2026-10-10T15:00:00.000Z"}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}}}}},"/paqueterias":{"get":{"tags":["Paqueterías"],"summary":"Paqueterías, si están activas y qué funciones tiene cada una (5 créditos)","responses":{"200":{"description":"Lista de paqueterías.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Respuesta","value":{"exito":true,"paqueterias":[{"codigo":"c807","nombre":"C807 Xpress","activa":true,"cobertura":["El Salvador","Honduras","Guatemala"],"funciones":["crear_guia","tracking","etiqueta_pdf","etiqueta_zpl","anular","confirmar_recoleccion","catalogos"],"catalogos":["departamentos","municipios","agencias","sedes","tipos-documento"],"tipos_entrega":["NRML","PLUS","ECON","AAP","XL"],"tipos_servicio":["CCE","SER","SEC"],"forma_pago_defecto":"postpago"},{"codigo":"boxful","nombre":"Boxful","activa":false,"funciones":["cotizar","crear_guia","tracking","etiqueta_pdf","catalogos"]}],"activas":["c807"],"creditos_cobrados":5,"saldo_restante":9995}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}}}}},"/cobertura":{"get":{"tags":["Paqueterías"],"summary":"Departamentos y municipios por país (5 créditos)","parameters":[{"name":"pais","in":"query","schema":{"type":"string"},"example":"SV","description":"Código o nombre. Por defecto, el país del negocio."},{"name":"departamento","in":"query","schema":{"type":"string"},"example":"San Salvador"},{"name":"municipio","in":"query","schema":{"type":"string"},"example":"Soyapango"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Búsqueda libre.","example":"soya"}],"responses":{"200":{"description":"Cobertura.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}}}}},"/paqueterias/{paqueteria}/catalogos/{catalogo}":{"get":{"tags":["Paqueterías"],"summary":"Catálogos propios de cada paquetería (5 créditos)","description":"C807: `departamentos`, `municipios` (con `?departamento_id=`), `agencias`, `sedes`, `tipos-documento`. Boxful: `estados`, `direcciones-recoleccion`. Xpress T&T: `agencias` (con `?cuenta=` y `?solo_destino=1` para las habilitadas como destino), `subemisores`, `cuentas`. Forza no tiene catálogos: usá `/cobertura`.","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"},{"name":"catalogo","in":"path","required":true,"schema":{"type":"string","enum":["departamentos","municipios","agencias","sedes","tipos-documento","estados","direcciones-recoleccion","cuentas","subemisores"]},"example":"municipios"},{"name":"departamento_id","in":"query","schema":{"type":"integer"},"description":"Obligatorio para `municipios` de C807.","example":11}],"responses":{"200":{"description":"Catálogo.","content":{"application/json":{"schema":{"type":"object"},"examples":{"municipios":{"summary":"C807 · municipios de San Salvador","value":{"exito":true,"paqueteria":"c807","catalogo":"municipios","datos":[{"id":197,"nombre":"Soyapango"},{"id":194,"nombre":"San Salvador"}],"creditos_cobrados":5,"saldo_restante":9990}},"agencias":{"summary":"C807 · agencias","value":{"exito":true,"paqueteria":"c807","catalogo":"agencias","datos":[{"id":4,"nombre":"Agencia Santa Ana","direccion":"Av. Independencia"}]}},"direcciones":{"summary":"Boxful · direcciones de recolección","value":{"exito":true,"paqueteria":"boxful","catalogo":"direcciones-recoleccion","datos":[{"id":"addr_9f3a","name":"Bodega central","cityId":10}]}}}}}},"400":{"description":"Datos inválidos o paquetería no configurada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"falta":{"summary":"Falta departamento_id","value":{"exito":false,"error":"falta_departamento_id","mensaje":"Indicá ?departamento_id= (sale del catálogo 'departamentos')."}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}},"404":{"description":"La paquetería no tiene ese catálogo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"no_existe":{"summary":"Catálogo inexistente","value":{"exito":false,"error":"catalogo_no_existe","mensaje":"Forza Delivery Express no tiene el catálogo 'agencias'.","catalogos_disponibles":[]}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}},"/cotizaciones":{"post":{"tags":["Cotizaciones"],"summary":"Cotizar un envío y ver couriers disponibles (Boxful · 5 créditos · permiso cotizar)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrearGuia"},"examples":{"boxful":{"summary":"Cotizar con Boxful","value":{"paqueteria":"boxful","destinatario":{"departamento":"San Salvador","municipio":"Soyapango"},"paquete":{"peso_libras":2,"valor_declarado":25,"tipo_cobro":"cobro_contra_entrega","monto_a_cobrar":25}}}}}}},"responses":{"200":{"description":"Opciones de envío.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Respuesta","value":{"exito":true,"paqueteria":"boxful","opciones":[{"courier_id":"12","courier":"Express Local","servicio":"Mismo día","precio":3.5,"tiempo_entrega":"24 h"}],"nota":"Usá el courier_id elegido en opciones.boxful.courier_id al crear la guía.","creditos_cobrados":5,"saldo_restante":9985}}}}}},"400":{"description":"Datos inválidos o paquetería no configurada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"destino":{"summary":"Falta el destino","value":{"exito":false,"error":"destino_incompleto","mensaje":"Para cotizar hacen falta destinatario.departamento y destinatario.municipio."}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"422":{"description":"La paquetería no ofrece esa función por API (no se cobra).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"no_disponible":{"summary":"Función no disponible","value":{"exito":false,"error":"funcion_no_disponible","mensaje":"Forza Delivery Express no ofrece 'anular' por API.","funciones_disponibles":["crear_guia","tracking","etiqueta_pdf"]}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}},"/guias":{"post":{"tags":["Guías"],"summary":"Crear una guía en cualquier paquetería (200 créditos · permiso envios)","description":"Una sola ruta para las cuatro paqueterías. Los campos comunes van en `destinatario` y `paquete`; lo propio de cada una, en `opciones.<paqueteria>`. Elegí un ejemplo en el desplegable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrearGuia"},"examples":{"c807_cod":{"summary":"C807 · cobro contra entrega a domicilio (NRML)","value":{"paqueteria":"c807","referencia_externa":"PEDIDO-1001","forma_pago":"postpago","destinatario":{"nombre":"Carlos Menéndez","telefono":"77889900","direccion":"Colonia Escalón, Calle El Mirador #123","departamento":"San Salvador","municipio":"San Salvador","email":"carlos@correo.com","punto_referencia":"Frente a farmacia La Buena","indicaciones":"Llamar antes de entregar"},"paquete":{"peso_libras":3.5,"descripcion":"Zapatos deportivos talla 41","tipo_cobro":"cobro_contra_entrega","monto_a_cobrar":45,"piezas":1},"opciones":{"c807":{"tipo_entrega":"NRML"}}}},"c807_econ":{"summary":"C807 · económico sucursal a sucursal (ECON), con IDs del catálogo","value":{"paqueteria":"c807","referencia_externa":"PEDIDO-1002","destinatario":{"nombre":"Ana López","telefono":"70112233","direccion":"Retira en agencia","documento_identidad":"01234567-8"},"paquete":{"peso_libras":1,"descripcion":"Accesorios","tipo_cobro":"pagado"},"opciones":{"c807":{"tipo_entrega":"ECON","departamento_id":11,"municipio_id":197,"agencia_destino":4}}}},"c807_seguro_recoleccion":{"summary":"C807 · con seguro y recolección programada en otra dirección","value":{"paqueteria":"c807","forma_pago":"prepago","destinatario":{"nombre":"Carlos Menéndez","telefono":"77889900","direccion":"Colonia Escalón, Calle El Mirador #123","departamento":"San Salvador","municipio":"San Salvador","email":"carlos@correo.com","punto_referencia":"Frente a farmacia La Buena","indicaciones":"Llamar antes de entregar"},"paquete":{"peso_libras":8,"descripcion":"Licuadora","tipo_cobro":"pagado"},"opciones":{"c807":{"tipo_entrega":"NRML","seguro":true,"seguro_valor_producto":120,"recolecta_fecha":"2026-10-12","recolecta_comentario":"Recoger después de las 2 p. m.","direccion_alterna":true,"recoleccion_direccion":"Bodega 4, Zona Industrial Merliot","recoleccion_municipio_id":86,"remitente_nombre":"Tienda Ejemplo","remitente_telefono":"22223333"}}}},"boxful":{"summary":"Boxful · con el courier elegido en la cotización","value":{"paqueteria":"boxful","referencia_externa":"PEDIDO-2001","destinatario":{"nombre":"Carlos Menéndez","telefono":"77889900","direccion":"Colonia Escalón, Calle El Mirador #123","departamento":"San Salvador","municipio":"San Salvador","email":"carlos@correo.com","punto_referencia":"Frente a farmacia La Buena","indicaciones":"Llamar antes de entregar","latitud":13.7034,"longitud":-89.2434},"paquete":{"peso_libras":2,"descripcion":"Camisa","tipo_cobro":"cobro_contra_entrega","monto_a_cobrar":25,"valor_declarado":25},"opciones":{"boxful":{"courier_id":"12","direccion_recoleccion_id":"addr_9f3a"}}}},"xpress_tnt":{"summary":"Xpress El Salvador (T&T) · cobro contra entrega, a domicilio o de agencia a agencia","value":{"paqueteria":"xpress_tnt","referencia_externa":"PEDIDO-5001","destinatario":{"nombre":"Carlos Menéndez","telefono":"77889900","direccion":"Colonia Escalón, Calle El Mirador #123","departamento":"San Salvador","municipio":"San Salvador","email":"carlos@correo.com","punto_referencia":"Frente a farmacia La Buena","indicaciones":"Llamar antes de entregar"},"paquete":{"descripcion":"Zapatos","tipo_cobro":"cobro_contra_entrega","monto_a_cobrar":42.5},"opciones":{"xpress_tnt":{"cuenta":"tnt_ab12cd34","tipo_entrega":"DOOR_TO_DOOR","bultos":1}}}},"forza":{"summary":"Forza · cobro contra entrega con remitente","value":{"paqueteria":"forza","referencia_externa":"PEDIDO-4001","destinatario":{"nombre":"Carlos Menéndez","telefono":"77889900","direccion":"Colonia Escalón, Calle El Mirador #123","departamento":"San Salvador","municipio":"San Salvador","email":"carlos@correo.com","punto_referencia":"Frente a farmacia La Buena","indicaciones":"Llamar antes de entregar"},"paquete":{"peso_libras":2,"descripcion":"Audífonos","tipo_cobro":"cobro_contra_entrega","monto_a_cobrar":35},"opciones":{"forza":{"remitente_nombre":"Tienda Ejemplo","remitente_telefono":"22223333","remitente_municipio":"San Salvador","remitente_departamento":"San Salvador"}}}},"automatica":{"summary":"Sin elegir paquetería · usa la primera activa (C807, Boxful, Xpress T&T, Forza)","value":{"destinatario":{"nombre":"Carlos Menéndez","telefono":"77889900","direccion":"Colonia Escalón, Calle El Mirador #123","departamento":"San Salvador","municipio":"San Salvador","email":"carlos@correo.com","punto_referencia":"Frente a farmacia La Buena","indicaciones":"Llamar antes de entregar"},"paquete":{"peso_libras":1,"descripcion":"Libro","tipo_cobro":"pagado"}}}}}}},"responses":{"201":{"description":"Guía creada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuiaCreada"},"examples":{"c807":{"summary":"C807","value":{"exito":true,"paqueteria":"c807","guia":"C807-SV-0012345","tracking_url":"https://app.c807.com/guia.php/seguimiento/C807-SV-0012345","etiqueta_url":"/api/v1/guias/c807/C807-SV-0012345/etiqueta","recolecta":"REC-8891","departamento_id":11,"municipio_id":194,"forma_pago_id":3,"estado":"creada","referencia_externa":"PEDIDO-1001","fecha":"2026-10-10T15:00:00.000Z","creditos_cobrados":200,"saldo_restante":9800}},"boxful":{"summary":"Boxful","value":{"exito":true,"paqueteria":"boxful","guia":"BX123456","tracking_url":"https://app.boxful.delivery/tracking/BX123456","etiqueta_url":"/api/v1/guias/boxful/BX123456/etiqueta","envio_id":"SHP-7781","courier":"Express Local","costo_envio":3.5,"estado":"creada","creditos_cobrados":200}},"forza":{"summary":"Forza","value":{"exito":true,"paqueteria":"forza","guia":"FZ-778899","tracking_url":"https://forzadelivery.com/tracking/FZ-778899","etiqueta_url":"/api/v1/guias/forza/FZ-778899/etiqueta","estado":"creada","creditos_cobrados":200}}}}}},"400":{"description":"Datos inválidos o paquetería no configurada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"incompleto":{"summary":"Faltan datos","value":{"exito":false,"error":"datos_destinatario_incompletos","mensaje":"destinatario.nombre, destinatario.telefono y destinatario.direccion son obligatorios."}},"cod":{"summary":"COD sin monto","value":{"exito":false,"error":"monto_a_cobrar_invalido","mensaje":"Con tipo_cobro 'cobro_contra_entrega' hace falta paquete.monto_a_cobrar mayor que 0."}},"destino":{"summary":"C807 no reconoce el destino","value":{"exito":false,"error":"destino_c807_invalido","mensaje":"C807 no reconoce el municipio \"Pueblo X\" en San Salvador. Corregilo en el pedido."}},"inactiva":{"summary":"Paquetería sin configurar","value":{"exito":false,"error":"forza_no_configurado","mensaje":"Forza Delivery Express no está configurada o activa. Activala en el panel: Logística > Forza Delivery Express."}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}},"get":{"tags":["Guías"],"summary":"Listar las guías creadas por la API (gratis · permiso tracking)","parameters":[{"name":"paqueteria","in":"query","schema":{"type":"string"},"example":"c807"},{"name":"referencia_externa","in":"query","schema":{"type":"string"},"example":"PEDIDO-1001"},{"name":"desde","in":"query","schema":{"type":"string","format":"date"},"example":"2026-10-01"},{"name":"hasta","in":"query","schema":{"type":"string","format":"date"},"example":"2026-10-31"},{"name":"limite","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"pagina","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Guías.","content":{"application/json":{"schema":{"type":"object","properties":{"exito":{"type":"boolean"},"guias":{"type":"array","items":{"$ref":"#/components/schemas/Guia"}},"total":{"type":"integer"},"pagina":{"type":"integer"},"limite":{"type":"integer"}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}}}}},"/guias/{paqueteria}/{guia}":{"get":{"tags":["Guías"],"summary":"Detalle de una guía creada por la API (gratis · permiso tracking)","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"},{"name":"guia","in":"path","required":true,"description":"Número de guía devuelto al crearla.","schema":{"type":"string"},"example":"C807-SV-0012345"}],"responses":{"200":{"description":"Guía.","content":{"application/json":{"schema":{"type":"object","properties":{"exito":{"type":"boolean"},"guia":{"$ref":"#/components/schemas/Guia"}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"404":{"description":"No existe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"no":{"summary":"No encontrada","value":{"exito":false,"error":"guia_no_encontrada","mensaje":"Esa guía no fue creada por la API en este negocio."}}}}}}}},"delete":{"tags":["Guías","C807","Xpress T&T"],"summary":"Anular una guía (C807 y Xpress T&T · gratis · permiso envios). En T&T solo mientras esté CREATED o ASSIGNED; `?motivo=` opcional.","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"},{"name":"guia","in":"path","required":true,"description":"Número de guía devuelto al crearla.","schema":{"type":"string"},"example":"C807-SV-0012345"}],"responses":{"200":{"description":"Anulada.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Respuesta","value":{"exito":true,"paqueteria":"c807","guia":"C807-SV-0012345","estado":"anulada","mensaje":"Guía anulada","creditos_cobrados":0}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"409":{"description":"La paquetería no permitió anularla (por ejemplo, ya fue recolectada).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La paquetería no ofrece esa función por API (no se cobra).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"no_disponible":{"summary":"Función no disponible","value":{"exito":false,"error":"funcion_no_disponible","mensaje":"Forza Delivery Express no ofrece 'anular' por API.","funciones_disponibles":["crear_guia","tracking","etiqueta_pdf"]}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}},"patch":{"tags":["Guías","Xpress T&T"],"summary":"Corregir una guía de Xpress T&T: destinatario/dirección, indicaciones o contenido (gratis · permiso envios)","description":"Mandá solo lo que cambia. COD, bultos, frágil y tipo de entrega no se pueden modificar después de crear la guía.","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"},{"name":"guia","in":"path","required":true,"description":"Número de guía devuelto al crearla.","schema":{"type":"string"},"example":"C807-SV-0012345"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destinatario":{"type":"object","properties":{"nombre":{"type":"string"},"telefono":{"type":"string"},"email":{"type":"string"},"direccion":{"type":"string"},"punto_referencia":{"type":"string"},"departamento":{"type":"string"},"municipio":{"type":"string"}}},"indicaciones":{"type":["string","null"],"description":"`null` borra las indicaciones."},"contenido":{"type":"string"}}},"examples":{"direccion":{"summary":"Cambiar dirección","value":{"destinatario":{"direccion":"Col. Escalón, Calle 5, Casa 12"},"indicaciones":"Portón negro"}}}}}},"responses":{"200":{"description":"Orden actualizada (forma de T&T en `datos`).","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Sin cambios o campo no permitido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"409":{"description":"T&T ya no permite modificarla en su estado actual.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La paquetería no ofrece esa función por API (no se cobra).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"no_disponible":{"summary":"Función no disponible","value":{"exito":false,"error":"funcion_no_disponible","mensaje":"Forza Delivery Express no ofrece 'anular' por API.","funciones_disponibles":["crear_guia","tracking","etiqueta_pdf"]}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}},"/paqueterias/{paqueteria}/subemisores":{"post":{"tags":["Xpress T&T"],"summary":"Crear un subemisor (tienda de recolección) en Xpress T&T (gratis · permiso envios)","description":"Para listarlos: `GET /paqueterias/xpress_tnt/catalogos/subemisores`. Usá su `id` en `opciones.xpress_tnt.sub_sender_id` al crear guías a domicilio.","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nombre","telefono","direccion","departamento","municipio"],"properties":{"nombre":{"type":"string"},"telefono":{"type":"string"},"direccion":{"type":"string"},"punto_referencia":{"type":"string"},"departamento":{"type":"string"},"municipio":{"type":"string"},"external_id":{"type":"string"},"cuenta":{"type":"string","description":"ID de la cuenta T&T (si hay varias)."}}}}}},"responses":{"201":{"description":"Creado.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Datos inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"409":{"description":"Ya existe uno con ese nombre o external_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}},"/guias/{paqueteria}/{guia}/tracking":{"get":{"tags":["Guías"],"summary":"Estado e historial en tiempo real (30 créditos · permiso tracking)","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"},{"name":"guia","in":"path","required":true,"description":"Número de guía devuelto al crearla.","schema":{"type":"string"},"example":"C807-SV-0012345"}],"responses":{"200":{"description":"Tracking.","content":{"application/json":{"schema":{"type":"object"},"examples":{"c807":{"summary":"C807","value":{"exito":true,"paqueteria":"c807","guia":"C807-SV-0012345","estado":"En ruta","historial":[{"estatus":"En ruta","codigo":"8","observaciones":null,"fecha":"2026-10-11 09:12"},{"estatus":"Recolectado","codigo":"3","observaciones":null,"fecha":"2026-10-10 16:40"}],"creditos_cobrados":30,"saldo_restante":9770}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}},"/guias/{paqueteria}/{guia}/etiqueta":{"get":{"tags":["Guías"],"summary":"Etiqueta para imprimir (30 créditos · permiso envios)","description":"C807 devuelve el PDF directamente (o ZPL para impresora térmica con `?formato=zpl`). Boxful, Xpress T&T y Forza responden con una redirección (302) al PDF de la paquetería. Solo se cobra si la etiqueta existe.","parameters":[{"name":"paqueteria","in":"path","required":true,"description":"Código de la paquetería. `xpress` (y el viejo `sistrack`) apuntan a `xpress_tnt` (T&T).","schema":{"type":"string","enum":["c807","boxful","xpress_tnt","xpress","forza"]},"example":"c807"},{"name":"guia","in":"path","required":true,"description":"Número de guía devuelto al crearla.","schema":{"type":"string"},"example":"C807-SV-0012345"},{"name":"formato","in":"query","schema":{"type":"string","enum":["pdf","zpl"],"default":"pdf"},"description":"`zpl` solo en C807."}],"responses":{"200":{"description":"Etiqueta (C807).","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string"},"example":"^XA^FO50,50^ADN,36,20^FDC807-SV-0012345^FS^XZ"}}},"302":{"description":"Redirección al PDF de la paquetería (Boxful, Xpress T&T, Forza)."},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"402":{"description":"Saldo de créditos insuficiente. No se llama a la paquetería.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_saldo":{"summary":"Sin saldo","value":{"exito":false,"error":"saldo_insuficiente","mensaje":"Saldo de créditos insuficiente. Se requieren 200 créditos y tu saldo es 120.","creditos_requeridos":200,"saldo_actual":120}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"404":{"description":"La paquetería no informó la etiqueta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"La paquetería no ofrece esa función por API (no se cobra).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"no_disponible":{"summary":"Función no disponible","value":{"exito":false,"error":"funcion_no_disponible","mensaje":"Forza Delivery Express no ofrece 'anular' por API.","funciones_disponibles":["crear_guia","tracking","etiqueta_pdf"]}}}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}},"/paqueterias/c807/recolecciones":{"post":{"tags":["C807"],"summary":"Confirmar la recolección de una o varias guías (gratis · permiso envios)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["guias"],"properties":{"guias":{"type":"array","items":{"type":"string"},"example":["C807-SV-0012345","C807-SV-0012346"]},"recolecta_fecha":{"type":"string","format":"date","description":"Por defecto, el próximo día hábil.","example":"2026-10-12"},"recolecta_comentario":{"type":"string","example":"Tocar el timbre del portón negro"},"tipo_entrega":{"type":"string","enum":["NRML","PLUS","ECON","AAP","XL"],"example":"NRML"},"recolecta":{"type":"string","description":"Número de solicitud de recolección existente, si ya hay una.","example":"REC-8891"}}},"examples":{"ok":{"summary":"Dos guías para mañana","value":{"guias":["C807-SV-0012345","C807-SV-0012346"],"recolecta_fecha":"2026-10-12","recolecta_comentario":"Tocar el timbre del portón negro"}}}}}},"responses":{"200":{"description":"Recolección confirmada.","content":{"application/json":{"schema":{"type":"object"},"examples":{"ok":{"summary":"Respuesta","value":{"exito":true,"paqueteria":"c807","guias":["C807-SV-0012345"],"mensaje":"Solicitud confirmada","creditos_cobrados":0}}}}}},"400":{"description":"Datos inválidos o paquetería no configurada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"faltan":{"summary":"Sin guías","value":{"exito":false,"error":"faltan_guias","mensaje":"Indicá en 'guias' la lista de números de guía a recolectar."}}}}}},"401":{"description":"Falta la API Key o no es válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_llave":{"summary":"Sin API Key","value":{"exito":false,"error":"api_key_requerida","mensaje":"Se requiere una API Key válida en el encabezado Authorization: Bearer <ori_live_...> o X-API-Key."}}}}}},"403":{"description":"La API Key no tiene el permiso de esta operación, o la API REST no está habilitada en el plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"sin_permiso":{"summary":"Permiso faltante","value":{"exito":false,"error":"permiso_insuficiente","mensaje":"Esta API Key no tiene el permiso 'envios'.","permiso_requerido":"envios"}}}}}},"409":{"description":"C807 rechazó la solicitud.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"La paquetería rechazó la operación o no respondió. No se cobran créditos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proveedor":{"summary":"Error del proveedor","value":{"exito":false,"error":"error_proveedor_c807","mensaje":"C807 respondió: municipio inválido","creditos_cobrados":0}}}}}}}}}}}