{ "item": [ { "name": "rates", "description": "Cotización multi-paquetería", "item": [ { "id": "c67ea6d5-91f0-485b-a951-70899dd16f7c", "name": "Cotizar en todas las paqueterías", "request": { "name": "Cotizar en todas las paqueterías", "description": { "content": "Cotiza el paquete con todas las paqueterías activas y devuelve tarifas con `id` (`rate_id`) listas para `POST /shipments`. Requiere scope `rates:read`. Solo rutas domésticas MX y UN paquete por solicitud (`country` ≠ MX o `packages` → 422). Las tarifas de referencia de mostrador (market) NO se incluyen: todo `rate_id` devuelto es enviable. Con seguro (`insurance.declared_value`), la prima de la plataforma (si está activa) queda incluida y firmada dentro de `pricing.total_price`. La respuesta es la MISMA para toda llave (los costos de proveedor nunca se exponen).", "type": "text/plain" }, "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "0492705b-b6ea-4e9d-99f5-d1a7bc1a2a1d", "name": "Cotización exitosa (forma autenticada all-vendors).", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"services\": [\n {\n \"id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"carrier\": \"Estafeta\",\n \"service_name\": \"Terrestre\",\n \"service_type\": \"standard_economy\",\n \"tier\": \"standard_economy\",\n \"delivery_window\": \"ground\",\n \"pickup_included\": false,\n \"address_delivery\": true,\n \"pricing\": {\n \"total_price\": 145.5,\n \"currency\": \"MXN\",\n \"iva_included\": true,\n \"insurance_premium\": 0,\n \"insured_value\": null\n },\n \"delivery\": {\n \"estimated_days\": \"3-5\",\n \"estimated_date\": null,\n \"min_days\": 3,\n \"max_days\": 5\n },\n \"insurance_included\": false,\n \"insurance_not_supported\": false,\n \"zona_extendida\": false\n },\n {\n \"id\": \"e2etest_E2ETestCarrier_E2EExpress_7f0a16b2\",\n \"carrier\": \"FedEx\",\n \"service_name\": \"Express Nacional\",\n \"service_type\": \"express\",\n \"tier\": \"express\",\n \"delivery_window\": \"next_day\",\n \"pickup_included\": true,\n \"address_delivery\": true,\n \"pricing\": {\n \"total_price\": 289,\n \"currency\": \"MXN\",\n \"iva_included\": true,\n \"insurance_premium\": 0,\n \"insured_value\": null\n },\n \"delivery\": {\n \"estimated_days\": \"1-2\",\n \"estimated_date\": null,\n \"min_days\": 1,\n \"max_days\": 2\n },\n \"insurance_included\": false,\n \"insurance_not_supported\": false,\n \"zona_extendida\": false\n }\n ],\n \"fetched_at\": \"2026-07-13T18:42:05Z\",\n \"stale_after\": \"2026-07-13T18:47:05Z\",\n \"meta\": {\n \"billable_weight\": 1,\n \"volumetric_weight\": 0.6,\n \"zone\": 5\n },\n \"rate_id_expires_in_seconds\": 1800\n },\n \"requestId\": \"req_a1b2c3d4e5\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "06eb7ef2-3f41-4506-a8b6-7bf59fa8f5a0", "name": "`INVALID_JSON` (cuerpo vacío/no-JSON) · `MISSING_ROUTE` · `MISSING_PACKAGE` · `WEIGHT_EXCEEDED` (peso facturable > 70 kg).", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d4b62ac0-a72f-4591-af1d-a9fe392297f8", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ea84a01c-acb8-4fea-9fb8-c3a1733d912c", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ee02ed82-6231-4c07-8c34-50e65114e0f8", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c67ae4b4-3ea1-4212-8a14-e766fac1a4e6", "name": "`VALIDATION_ERROR` (details.fields lista los campos — incluye `country` ≠ MX, `packages` presente y campos desconocidos a nivel raíz) · `INSURANCE_VALUE_TOO_HIGH` (valor declarado sobre el máximo asegurable).", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "504f7009-b5c5-4b98-b0fc-58e4ff0d5864", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7a146ac1-2652-4c26-b387-196b311177a6", "name": "`RATES_ERROR` — la cotización falló; reintenta.", "originalRequest": { "url": { "path": [ "rates" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "shipments", "description": "Creación y consulta de envíos", "item": [ { "id": "d29e0e54-a9ec-4ba3-bdf0-ddd5c807d7e0", "name": "Crear un envío (genera la guía y cobra créditos)", "request": { "name": "Crear un envío (genera la guía y cobra créditos)", "description": { "content": "Crea el envío contra un `rate_id` vigente (≤ 30 min) cotizado con la MISMA llave (y mismo PDV, si aplica). Solo domésticos MX y UN paquete (`packages`/`customs`/`ocurre`, `country` ≠ MX o campos desconocidos → 422). Remitente/destinatario van inline (la plataforma crea o reutiliza los registros del directorio con dedupe exacto normalizado) o por referencia (`from_id`/`to_id` del directorio — la fila guardada se usa tal cual). El cargo sigue el ciclo autorizar→capturar/anular — un envío rechazado nunca deja fondos retenidos. **Usa `Idempotency-Key`** en todo intento.", "type": "text/plain" }, "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "80afcb4b-660e-4b89-9feb-1830a7d9b875", "name": "Envío creado (o repetido idempotentemente — header `Idempotent-Replay: true`; o deduplicado contra una guía existente — `duplicate: true`, en cuyo caso `carrier`/`service` pueden ser null).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Idempotent-Replay", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Limit", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Remaining", "value": "" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "X-RateLimit-Reset", "value": "" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"shipment\": {\n \"id\": \"20260713-000123\",\n \"guia\": \"1234567890\",\n \"carrier\": \"Estafeta\",\n \"service\": \"Terrestre\",\n \"status\": \"created\",\n \"total\": 145.5,\n \"currency\": \"MXN\",\n \"label_url\": \"/api/v1/labels/20260713-000123\",\n \"tracking_pending\": false,\n \"created_at\": \"2026-07-13T18:45:12Z\"\n }\n },\n \"requestId\": \"req_b2c3d4e5f6\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "31b72ca3-aef8-4f9a-851a-813fa9c661c5", "name": "`INVALID_JSON` · `VALIDATION_FAILED` (rechazo del núcleo, details.validationErrors) · `INVALID_VENDOR` · `OCURRE_CARRIER_MISMATCH` · `IDEMPOTENCY_KEY_INVALID` (header presente pero vacío, >128 chars o con caracteres no imprimibles; omitirlo es válido, mandarlo mal no).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "96121d12-54e7-44a1-bcc1-9d05aef95c12", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0d9bfb5c-8dd6-4170-b02b-ba3c69cb48af", "name": "`CREDIT_ERROR` — créditos insuficientes. `details`: `{required, available, shortfall}`. Recarga y reintenta con el MISMO `Idempotency-Key`.", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Payment Required", "code": 402, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a253ddbe-acab-4b61-87ce-5104ea93d614", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "699d7594-2c60-4837-8328-5f87e115040a", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f076d908-25fb-4f95-a27a-c77226ddfacc", "name": "`RATE_NOT_FOUND` (cotiza de nuevo) · `RATE_EXPIRED` (>30 min) · `RATE_TAMPERED` · `RATE_PDV_MISMATCH` (se cotizó bajo otro PDV) · `RATE_PACKAGE_MISMATCH` (el `package` enviado difiere del cotizado — reenvía el MISMO paquete que cotizaste, o cotiza de nuevo) · `GUIA_COLLISION` · `IDEMPOTENCY_KEY_REUSED` (misma llave en otro endpoint — desde 2026-08 el carril web cuenta como otro endpoint) · `IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` (misma llave, cuerpo o `X-PDV-ID` distintos: manda una llave nueva) · `IDEMPOTENCY_KEY_EXPIRED` (la llave ya se completó hace más de 15 min: consulta `GET /shipments` o manda una llave nueva) · `RATE_ADDRESS_MISMATCH` (la cotización corresponde a OTRA ruta: los CP de origen/destino con los que se está creando el envío no son los que se cotizaron — cotiza de nuevo con las direcciones definitivas; desde 2026-08 esto rechaza en lugar de solo registrarse) · `REQUOTE_REQUIRED` (el precio del envío no coincide con el de la cotización; no se espera en este carril — el total se toma de la MISMA fila firmada que el ejecutor vuelve a verificar — y se documenta por completitud: cotiza de nuevo).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c4e6cc49-dec7-48d0-90f9-4ba6b0d06837", "name": "`VALIDATION_ERROR` (contrato público, details.fields) · `PRICING_CONFIG_ERROR` (margen mal configurado; contacta soporte) · `MISSING_PHONE` (remitente y/o destinatario sin teléfono válido de 10 dígitos; `details.missing` lista cuál).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "682b4f02-4937-4f83-a068-1b3d3aa7e795", "name": "`RISK_LIMIT` (tope de guías/gasto diario de la cuenta, o tope de gasto de la LLAVE en ventana móvil de 24 h — este último con `details {daily_cap_mxn, spent_24h_mxn, attempted_mxn}`) · `RATE_LIMITED` (límite por llave; ver `Retry-After`).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "afe82dc3-5ab5-4404-a091-d5fa3c79380d", "name": "`SHIPMENT_ERROR` (falla pre-commit; el cargo se revirtió — `details.refunded`) · `ADDRESS_ERROR` (no se pudo registrar remitente/destinatario; reintenta) · `CREDIT_ERROR` (falla interna de créditos) · **`POST_COMMIT_ERROR` — EL ENVÍO ES REAL y el cargo NO se revierte (`details.committed: true`). NO reintentes con llave nueva: consulta `GET /shipments`.**", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5a8fef61-3fbc-47e3-b162-dd2811df61b7", "name": "`VENDOR_ERROR` — la paquetería rechazó/falló ANTES del commit; el cargo se revirtió (`details.refunded`). `details.vendorError: true`; el status HTTP refleja el de la paquetería (4xx/5xx). Reintenta solo si `retryable` aplica (falla de red).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "UUID fresco por operación lógica (1–128 caracteres ASCII imprimibles; presente pero inválida → `400 IDEMPOTENCY_KEY_INVALID`). Un reintento con la misma llave Y el mismo cuerpo repite la respuesta 2xx original (`Idempotent-Replay: true`) sin doble cargo, durante **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID`: cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`; pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED`. **Cambio 2026-08:** ya NO se comparte espacio de nombres con el carril web del mismo usuario (antes una llave se repetía entre `/v1/shipments` y la app web; ahora eso responde `409 IDEMPOTENCY_KEY_REUSED`). Fuertemente recomendado en `POST /shipments`.", "type": "text/plain" }, "key": "Idempotency-Key", "value": "string" }, { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"rate_id\": \"e2etest_E2ETestCarrier_E2EStandard_ab12cd34\",\n \"from\": {\n \"name\": \"Juan Pérez\",\n \"phone\": \"5512345678\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"to\": {\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n },\n \"package\": {\n \"weight_kg\": 1\n },\n \"contenido\": \"Ropa\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "44bfa1cc-75fc-46ec-ae6e-90e80d493228", "name": "Listar envíos (paginado)", "request": { "name": "Listar envíos (paginado)", "description": { "content": "Por defecto: solo envíos creados por el usuario de la llave, para TODOS los roles — una llave admin ve únicamente sus propios envíos de cuenta de servicio.\n\n**Alcance por PDV (opt-in).** Una llave admin que envía `X-PDV-ID` **y** tiene el scope `shipments:read:pdv` lista en cambio los envíos de ese punto de venta, sin importar qué operador los creó — el mismo fondo que ya responden `/senders`, `/recipients` y `/balance` bajo ese header. Sin el scope, el header no amplía nada y sigues viendo solo lo tuyo (los integradores que ya lo envían no cambian de resultados).\n\n**Cambio de contrato (2026-07):** `X-PDV-ID` ahora se **valida** en esta ruta aunque no amplíe nada. Antes se ignoraba por completo, así que un PDV inexistente o fuera de la allowlist de la llave respondía `200` con lista vacía mientras `/senders` respondía `403`; ahora responde `403 PDV_NOT_ALLOWED` como todas las rutas hermanas.\n\nOrden: más recientes primero. Requiere scope `shipments:read` (+ `shipments:read:pdv` para el alcance por PDV).", "type": "text/plain" }, "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "3699c19d-9f1a-4c58-b53b-abf28f5c275f", "name": "Página de envíos.", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"shipments\": [\n {\n \"id\": \"20260713-000123\",\n \"guia\": \"1234567890\",\n \"carrier\": \"Estafeta\",\n \"service\": \"Terrestre\",\n \"status\": \"in_transit\",\n \"status_label\": \"En tránsito\",\n \"total\": 145.5,\n \"currency\": \"MXN\",\n \"created_at\": \"2026-07-13T18:45:12Z\",\n \"tracking_pending\": false,\n \"label_url\": \"/api/v1/labels/20260713-000123\",\n \"packages\": [\n {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n ],\n \"billable_weight_kg\": 1,\n \"declared_value\": null,\n \"content\": \"Ropa\",\n \"sender\": {\n \"name\": \"Juan Pérez\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"recipient\": {\n \"name\": \"María López\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n }\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"limit\": 20,\n \"total\": 1\n }\n },\n \"requestId\": \"req_e5f6a7b8c9\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "aed5fda6-f120-46f7-9c62-ba971af6ce7c", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "73be6e04-a5d2-485d-91b1-b2482d6838b7", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e5a5b7e2-8fde-44ae-92a1-1cd0d43b66b9", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "37eddd20-0eb1-4aa8-b7c7-ab4887e9b466", "name": "`VALIDATION_ERROR` — filtro inválido (details.fields).", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dad302ff-ffd7-4282-b625-b494a78eff3b", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d6c58830-d284-4392-bba4-1268013c19ef", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "shipments" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Búsqueda exacta por número de guía. Es la forma de llegar a un envío cuando solo tienes el número que ve el cliente (el `id` interno no es adivinable). Devuelve una página de 0 o 1 elementos, sujeta a la misma visibilidad que el resto del listado.", "type": "text/plain" }, "key": "guia", "value": "eMOl" }, { "disabled": false, "description": { "content": "Filtra por estatus canónico — exactamente el mismo valor que devuelve el campo `status` de cada envío. Un valor fuera del enum es `422 VALIDATION_ERROR`, nunca una lista vacía silenciosa. (This can only be one of created,collected,in_transit,out_for_delivery,delivered,exception,returned,cancelled,unknown)", "type": "text/plain" }, "key": "status", "value": "returned" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (zona horaria de negocio America/Mexico_City) desde el cual listar, por fecha de creación. Solo `YYYY-MM-DD`.", "type": "text/plain" }, "key": "from", "value": "0289-32-56" }, { "disabled": false, "description": { "content": "Día calendario INCLUSIVO (America/Mexico_City) hasta el cual listar — el día completo, hasta las 23:59:59 locales. `from` posterior a `to` es `422`.", "type": "text/plain" }, "key": "to", "value": "0289-32-56" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "2f23214c-a7ce-4d2b-bdf0-6e022cb65125", "name": "Consultar un envío", "request": { "name": "Consultar un envío", "description": { "content": "Misma visibilidad que el listado: propios por defecto, o los del PDV con `X-PDV-ID` + scope `shipments:read:pdv`. Devuelve exactamente los mismos campos que cada elemento de `GET /shipments` (incluyendo `packages`, pesos y remitente) — el detalle no es más rico que la lista, por diseño. Si solo tienes el número de guía, usa `GET /shipments?guia=…`.", "type": "text/plain" }, "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id", "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "3dcd3bc1-b0d3-4a16-9870-10f2a7f90154", "name": "El envío.", "originalRequest": { "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"shipment\": {\n \"id\": \"20260713-000123\",\n \"guia\": \"1234567890\",\n \"carrier\": \"Estafeta\",\n \"service\": \"Terrestre\",\n \"status\": \"in_transit\",\n \"status_label\": \"En tránsito\",\n \"total\": 145.5,\n \"currency\": \"MXN\",\n \"created_at\": \"2026-07-13T18:45:12Z\",\n \"tracking_pending\": false,\n \"label_url\": \"/api/v1/labels/20260713-000123\",\n \"packages\": [\n {\n \"weight_kg\": 1,\n \"length_cm\": 20,\n \"width_cm\": 15,\n \"height_cm\": 10\n }\n ],\n \"billable_weight_kg\": 1,\n \"declared_value\": null,\n \"content\": \"Ropa\",\n \"sender\": {\n \"name\": \"Juan Pérez\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n },\n \"recipient\": {\n \"name\": \"María López\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\"\n }\n }\n },\n \"requestId\": \"req_f6a7b8c9d0\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0d0989a9-dd7a-4b81-b7b7-7624e88b1605", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7fffbd7a-eb55-4405-9d4c-0ecdd8771f8c", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b94933d8-02f3-40d1-a786-792e58f4cccf", "name": "`NOT_FOUND` — no existe o no es visible para la llave (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c88d4687-1b1e-425b-a863-60f61be7eefa", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9fe03f66-03b8-4913-9006-fab3b3010d2d", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "shipments", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Id del envío (p. ej. `20260712-000123`).", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "tracking", "description": "Rastreo público", "item": [ { "id": "0d7e7fb6-3fa0-4512-91fc-1a1d26e87f10", "name": "Rastrear cualquier guía", "request": { "name": "Rastrear cualquier guía", "description": { "content": "Datos públicos de rastreo (mismo payload PII-mínimo de la página pública: estatus canónico, ciudad/estado de origen y destino, línea de tiempo con nombres de receptor depurados). No requiere que la guía sea propia. Agnóstico al modo de la llave (funciona igual con `ek_test_`). Requiere scope `tracking:read`.", "type": "text/plain" }, "url": { "path": [ "tracking", ":guia" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "string", "key": "guia", "disabled": false, "description": { "content": "(Required) Número de guía (coincidencia EXACTA).", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "581e05ae-35c7-4b53-9584-4ab23e59d8bd", "name": "Estado de rastreo.", "originalRequest": { "url": { "path": [ "tracking", ":guia" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Número de guía (coincidencia EXACTA).", "type": "text/plain" }, "type": "any", "value": "string", "key": "guia" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"guia\": \"1234567890\",\n \"carrier\": \"Estafeta\",\n \"status\": \"in_transit\",\n \"status_label\": \"En tránsito\",\n \"origin\": {\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\"\n },\n \"destination\": {\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\"\n },\n \"created_at\": \"2026-07-13T18:45:12Z\",\n \"events\": [\n {\n \"timestamp\": \"2026-07-13T20:10:00Z\",\n \"description\": \"Recolectado\",\n \"location\": \"Ciudad de México, CDMX\"\n },\n {\n \"timestamp\": \"2026-07-14T09:30:00Z\",\n \"description\": \"En tránsito al destino\",\n \"location\": \"Querétaro, QRO\"\n }\n ]\n },\n \"requestId\": \"req_c3d4e5f6a7\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3be7cb30-c443-497d-987f-7f2d7a4963f1", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "tracking", ":guia" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Número de guía (coincidencia EXACTA).", "type": "text/plain" }, "type": "any", "value": "string", "key": "guia" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a809fef6-6e90-440e-8130-e4e6743dc267", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "tracking", ":guia" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Número de guía (coincidencia EXACTA).", "type": "text/plain" }, "type": "any", "value": "string", "key": "guia" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "650cb318-5926-4344-9927-ef4a225d2be7", "name": "`NOT_FOUND` — genérico y de forma estable para toda guía desconocida/ inválida (sin oráculo de existencia).", "originalRequest": { "url": { "path": [ "tracking", ":guia" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Número de guía (coincidencia EXACTA).", "type": "text/plain" }, "type": "any", "value": "string", "key": "guia" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "54f143d3-9e9c-4a20-bc86-7c0d30a324bb", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "tracking", ":guia" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Número de guía (coincidencia EXACTA).", "type": "text/plain" }, "type": "any", "value": "string", "key": "guia" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "cancellations", "description": "Solicitudes de cancelación", "item": [ { "id": "9327b0d8-753b-4752-ab71-fd279575bba5", "name": "Solicitar la cancelación de un envío propio", "request": { "name": "Solicitar la cancelación de un envío propio", "description": { "content": "Crea una solicitud de cancelación (estado inicial `pending`). El avance del estado es operado por el staff/los procesos de la plataforma — consulta `GET /cancellations/{id}`. El reembolso esperado es lo que se cobró por el envío. Requiere scope `cancellations:write`.", "type": "text/plain" }, "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "8b82405a-04fc-4aef-b728-f581f7079f18", "name": "Solicitud creada.", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"id\": 42,\n \"display_id\": \"CR00000042\",\n \"status\": \"pending\",\n \"refund_status\": \"not_applicable\",\n \"refund_amount_expected\": 145.5,\n \"vendor_cancellation_deadline\": \"2026-07-14T18:45:12Z\"\n },\n \"requestId\": \"req_a7b8c9d0e1\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c438efe3-cfec-4af4-a968-b03e32b7b998", "name": "`INVALID_JSON` · `REQUEST_FAILED` (rechazo del servicio).", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "94e9285f-5b77-4737-be16-3e96445485b2", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "412c769c-0d27-4b0b-8aa1-45f94b256ce0", "name": "`FORBIDDEN` (rechazo de permiso del servicio) · `INSUFFICIENT_SCOPE` · `PDV_NOT_ALLOWED`.", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "07ea2f91-c289-4e50-892f-ad62226b4f69", "name": "`NOT_FOUND` — el envío no existe o no pertenece al usuario de la llave (respuesta idéntica).", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "be7a0698-ff16-4cce-8ab2-92ad7de91ba6", "name": "`CONFLICT` — el envío ya está cancelado o ya existe una solicitud abierta (`details.existing_request_id`).", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e83ac7bd-539e-465e-b1c3-d327028a0e20", "name": "`VALIDATION_ERROR` (details.fields).", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dee7ca84-602f-4226-8e89-a7d988988d91", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3a7b49b3-9cf1-4737-8506-61e421669000", "name": "`REQUEST_ERROR`.", "originalRequest": { "url": { "path": [ "cancellations" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"shipment_id\": \"20260713-000123\",\n \"reason_code\": \"customer_changed_mind\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "1b8a13ed-f63d-4472-b608-01e096e80301", "name": "Consultar una solicitud de cancelación", "request": { "name": "Consultar una solicitud de cancelación", "description": { "content": "Visibilidad idéntica a la del envío que cancela (propios por defecto; los del PDV con `X-PDV-ID` + scope `shipments:read:pdv`) — deliberadamente en paralelo, para que un envío que puedes leer nunca tenga una cancelación que no.\n\nMáquina de estados: `pending → approved → vendor_processing → vendor_cancelled | vendor_rejected`; otros terminales: `not_cancellable`, `vendor_reported`, `rejected`, `failed`, `expired`. Reembolso: `not_applicable, awaiting_vendor_refund, vendor_refunded, vendor_denied_refund, user_refunded, manual_override_refund`. Requiere scope `cancellations:read`.", "type": "text/plain" }, "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "6359", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "fea014cd-de84-46db-bf0d-071614d254d3", "name": "La solicitud.", "originalRequest": { "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "6359", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"cancellation\": {\n \"id\": 42,\n \"display_id\": \"CR00000042\",\n \"shipment_id\": \"20260713-000123\",\n \"status\": \"vendor_cancelled\",\n \"refund_status\": \"vendor_refunded\",\n \"reason_code\": \"customer_changed_mind\",\n \"reason_text\": null,\n \"refund_amount_expected\": 145.5,\n \"refund_amount_actual\": 145.5,\n \"vendor_cancellation_deadline\": \"2026-07-14T18:45:12Z\",\n \"created_at\": \"2026-07-13T19:02:33Z\",\n \"updated_at\": \"2026-07-15T10:12:05Z\",\n \"resolved_at\": \"2026-07-15T10:12:05Z\"\n }\n },\n \"requestId\": \"req_b8c9d0e1f2\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8131e0e6-39c4-4d72-b29e-e40a12d96b92", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "6359", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d6f93bdd-73f6-4196-8541-e40b20e15cb1", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "6359", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8c071340-1baf-405e-8450-7367b2d35981", "name": "`NOT_FOUND` — no existe o el envío subyacente no pertenece al usuario de la llave (respuesta idéntica).", "originalRequest": { "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "6359", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6078559e-760a-4e45-8296-d80b9e50f46e", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "6359", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3011c19a-5a94-4db2-b755-30102bc8d678", "name": "`GET_ERROR`.", "originalRequest": { "url": { "path": [ "cancellations", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "6359", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "balance", "description": "Saldo de créditos", "item": [ { "id": "d03bbc46-699a-4d34-b994-ff19360a9bd2", "name": "Consultar el saldo que cargarían tus envíos", "request": { "name": "Consultar el saldo que cargarían tus envíos", "description": { "content": "Sin `X-PDV-ID`: el saldo del usuario de la llave. Con `X-PDV-ID` (llaves admin, misma allowlist que `POST /shipments`): el fondo del punto de venta — exactamente el principal que un envío bajo ese header cargaría. `available` es lo gastable; `held` son autorizaciones pendientes; `balance` = available + held. Requiere scope `balance:read`.", "type": "text/plain" }, "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "9a56f5ba-95a2-4e90-a1f8-c0269a8daca6", "name": "Saldo del principal.", "originalRequest": { "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"balance\": 4820.5,\n \"held\": 145.5,\n \"available\": 4675,\n \"currency\": \"MXN\",\n \"scope\": {\n \"type\": \"user\",\n \"id\": \"U0000001\"\n }\n },\n \"requestId\": \"req_d4e5f6a7b8\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "49620751-2c5f-482f-96f7-18050e4d9cbb", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "64da583d-330b-48c9-aea9-db61cd1e572f", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "417697d6-89d8-48e1-bcac-16271ba9fad0", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e27fbbe4-fd0a-49cf-aae0-cefaffc22393", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8bafcd30-20f0-43ab-a23b-d885158a7a58", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "balance" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "labels", "description": "Etiquetas (guías)", "item": [ { "id": "0d9aca43-b5cd-46fc-8632-26845703e9d5", "name": "Descargar la etiqueta de un envío propio", "request": { "name": "Descargar la etiqueta de un envío propio", "description": { "content": "Transmite la copia almacenada por la plataforma (PDF/ZPL) cuando existe; si no, redirige (302) a la URL de la paquetería. Solo envíos creados por el usuario de la llave (todos los roles). Requiere scope `labels:read`.", "type": "text/plain" }, "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/pdf" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "72105f50-fd5a-4a31-b7ce-01b93aa01a2b", "name": "Bytes de la etiqueta (copia de la plataforma).", "originalRequest": { "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id" } ] }, "header": [ { "key": "Accept", "value": "application/pdf" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/pdf" } ], "body": "string", "cookie": [], "_postman_previewlanguage": "text" }, { "id": "e5c36cce-feea-4908-b3d1-7435ba05e595", "name": "Redirección a la URL de etiqueta de la paquetería (fallback cuando no hay copia almacenada). `Cache-Control: private, no-store`.", "originalRequest": { "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id" } ] }, "header": [ { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Found", "code": 302, "header": [ { "disabled": false, "description": { "content": "URL de la etiqueta en el proveedor.", "type": "text/plain" }, "key": "Location", "value": "string" } ], "cookie": [], "_postman_previewlanguage": "text" }, { "id": "d4d81e1c-37cf-4ce9-9491-d871f5c81e77", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5b288f82-43ed-4684-af71-d394d236490f", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5b030209-65e4-4d14-8704-0cd7028fc69b", "name": "`NOT_FOUND` — no existe, no es del usuario de la llave, o no hay etiqueta disponible (respuesta idéntica en todos los casos).", "originalRequest": { "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "557b75b4-5807-47c9-927f-7600c39090e8", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "labels", ":envio_id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "envio_id" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] }, { "name": "addresses", "description": "Directorio: remitentes y destinatarios", "item": [ { "id": "614e802d-ee25-4ab1-a02b-9169ca6990a3", "name": "Listar remitentes del directorio", "request": { "name": "Listar remitentes del directorio", "description": { "content": "Remitentes visibles para la llave. Visibilidad: llaves de cliente y llaves admin SIN `X-PDV-ID` ven solo los registros creados por el usuario de la llave; una llave admin con `X-PDV-ID` validado ve exactamente el directorio de ese punto de venta (el mismo que usa el personal de mostrador). Nunca hay lectura global en este carril. Requiere scope `addresses:read`. Este endpoint SÍ devuelve dirección completa y teléfono — el guardián es la visibilidad, no el recorte de campos.", "type": "text/plain" }, "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "baee4060-a10b-4544-b0cc-e7e4d2055c7b", "name": "Página de remitentes.", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"senders\": [\n {\n \"id\": \"C0012345\",\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"apellido_materno\": null,\n \"company\": null,\n \"rfc\": null,\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\",\n \"created_at\": \"2026-07-13T18:40:00Z\"\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"limit\": 20,\n \"total\": 1\n }\n },\n \"requestId\": \"req_c9d0e1f2a3\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d6945dcc-048a-4547-ad74-c0b4fca55c0a", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "92ca9e79-6a03-428a-b026-d7f46efa0cb6", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "031fff56-6518-4104-b2e7-9470bf7c38b4", "name": "`VALIDATION_ERROR` — filtro inválido (details.fields).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "39d8b963-362c-4010-87da-74e4fb4be3dc", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "188834de-6ffc-42bd-ac3e-eac984ceb3e6", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Filtro exacto por CP (5 dígitos; otro formato → 422).", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, razón social, RFC, teléfono, email y dirección (calle/colonia/municipio/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo: `arturo meijueiro` encuentra un registro cuyo nombre es `ARTURO` y cuyo apellido solo aparece en el email. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "228996e4-0e97-4975-aebe-28e180cc50df", "name": "Crear (o reutilizar) un remitente", "request": { "name": "Crear (o reutilizar) un remitente", "description": { "content": "Create-or-reuse con el MISMO dedupe exacto normalizado que usa `POST /shipments` al registrar direcciones inline, evaluado sobre las filas visibles para la llave: si ya existe un remitente idéntico visible, se devuelve ese (`created: false`, 200); si no, se crea (`created: true`, 201). Requiere scope `addresses:write`. Con `X-PDV-ID` (llave admin), la fila creada pertenece al directorio de ese PDV y queda visible para su personal.", "type": "text/plain" }, "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "886913f7-c790-4cb5-a2d8-c0f7e212c824", "name": "Remitente idéntico ya existente reutilizado (`created: false`).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"sender\": {\n \"id\": \"C0012345\",\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"apellido_materno\": null,\n \"company\": null,\n \"rfc\": null,\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\",\n \"created_at\": \"2026-07-13T18:40:00Z\"\n },\n \"created\": false\n },\n \"requestId\": \"req_e1f2a3b4c5\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c645a2d3-aae9-4081-8494-f1a8d37054d3", "name": "Remitente creado (`created: true`).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"sender\": {\n \"id\": \"C0012345\",\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"apellido_materno\": null,\n \"company\": null,\n \"rfc\": null,\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\",\n \"created_at\": \"2026-07-13T18:40:00Z\"\n },\n \"created\": true\n },\n \"requestId\": \"req_d0e1f2a3b4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9fcaa04a-e8ad-4a9f-8bdb-e6d7be2b0be7", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "91cb54df-2dc5-4bb0-9d2b-284225550d14", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "fcfb0655-ee49-418b-82e4-857a7c71302f", "name": "`VALIDATION_ERROR` — campos faltantes/inválidos o desconocidos (details.fields).", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0f243d59-3324-4edc-96dd-fa738270d1a3", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "21061814-b3c1-47c2-a89d-1b8aad030ec5", "name": "`ADDRESS_ERROR` — no se pudo registrar; reintenta.", "originalRequest": { "url": { "path": [ "senders" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d9c697bf-4e10-460a-9752-eba09820f586", "name": "Consultar un remitente", "request": { "name": "Consultar un remitente", "description": { "content": "Requiere scope `addresses:read`. 404 idéntico para inexistente y no-visible (sin oráculo).", "type": "text/plain" }, "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "77583ade-340b-4f99-b88b-adcba49cd1ca", "name": "El remitente.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"sender\": {\n \"id\": \"C0012345\",\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"apellido_materno\": null,\n \"company\": null,\n \"rfc\": null,\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\",\n \"created_at\": \"2026-07-13T18:40:00Z\"\n }\n },\n \"requestId\": \"req_f2a3b4c5d6\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9fe6a059-fd69-4029-9f8c-47d9a58e6e94", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "451ff795-9545-4672-8516-20a8702c15cb", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9dbac0c6-04f3-4b0f-9b87-6c0186aa777e", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "78907c6c-fdc5-419a-8ce3-b713036d9173", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "063f6137-0248-40b6-aa82-bfd2dd387502", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "09bc8c0b-f97f-4726-947c-02dad93fbf3b", "name": "Editar un remitente", "request": { "name": "Editar un remitente", "description": { "content": "Actualización PARCIAL de un remitente visible. Requiere scope `addresses:write`. Solo los campos presentes cambian; se debe enviar al menos uno. Los requeridos pueden cambiarse pero no vaciarse; los opcionales aceptan `null` para limpiarse. Los apellidos NO forman parte del dedupe, así que `PATCH` es la forma de completarlos en una fila creada sin ellos. 404 idéntico para inexistente y no-visible (sin oráculo).", "type": "text/plain" }, "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "a8c8f5c5-8a77-4a47-b7cc-ef32d2a681e9", "name": "El remitente actualizado.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"sender\": {\n \"id\": \"C0012345\",\n \"name\": \"Juan\",\n \"apellido_paterno\": \"Pérez\",\n \"apellido_materno\": \"García\",\n \"company\": null,\n \"rfc\": null,\n \"phone\": \"5512345678\",\n \"email\": \"juan@ejemplo.com\",\n \"street\": \"Av. Insurgentes Sur\",\n \"number\": \"600\",\n \"colonia\": \"Del Valle\",\n \"city\": \"Ciudad de México\",\n \"state\": \"CDMX\",\n \"postal_code\": \"01000\",\n \"created_at\": \"2026-07-13T18:40:00Z\"\n }\n },\n \"requestId\": \"req_a3b4c5d6e7\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b0d4e296-d6bd-4af7-aa93-99d553a99b45", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0ed1285c-17ed-4919-b3c0-aff68daa6d2e", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "15616345-217a-40e7-a4f9-1a6240559bc8", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "05f13d48-83d1-444a-ac03-50b4397be9e6", "name": "`DUPLICATE_ADDRESS` — la edición dejaría este remitente idéntico a OTRO ya visible para la llave. La fila no se modifica.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0883e28a-345c-4645-a799-8130ed3026d2", "name": "`VALIDATION_ERROR` (details.fields) — campo desconocido, requerido vaciado, `country` ≠ MX, apellido > 50, o cuerpo sin campos editables.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a5f54fb0-3b47-4435-bde3-c51312a49452", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "20a7329c-303b-4e3c-9e04-ae577f981431", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "senders", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"apellido_materno\": \"García\",\n \"email\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "090a6aa3-3e25-4ee3-9cf6-3a4a3975beda", "name": "Listar destinatarios del directorio", "request": { "name": "Listar destinatarios del directorio", "description": { "content": "Misma visibilidad que `GET /senders`. Un destinatario siempre pertenece a un remitente (`sender_id`). Requiere scope `addresses:read`.", "type": "text/plain" }, "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "4c0b78d8-2227-4774-acd8-df3c44b527e2", "name": "Página de destinatarios.", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"recipients\": [\n {\n \"id\": \"D0067890\",\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"email\": null,\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\",\n \"created_at\": \"2026-07-13T18:41:00Z\"\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"limit\": 20,\n \"total\": 1\n }\n },\n \"requestId\": \"req_b4c5d6e7f8\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "64f9cb0b-8b8a-4f40-affa-a4ff96933610", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4aba4e22-cb61-4733-abf5-1acba6024fda", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7180bdde-8278-410f-95f5-554fe5c94682", "name": "`VALIDATION_ERROR` — filtro inválido (details.fields).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8fa544bd-3884-4aa9-9afe-3ad7ec57bcab", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5af35fb6-b052-4e62-99b7-a1f44e7e6145", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [ { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "page", "value": "1" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "limit", "value": "20" }, { "disabled": false, "description": { "content": "Solo destinatarios de este remitente.", "type": "text/plain" }, "key": "sender_id", "value": "string" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "postal_code", "value": "76541" }, { "disabled": false, "description": { "content": "Búsqueda de texto sobre nombre, alias, teléfono, email y dirección (calle/colonia/ciudad/estado/CP). Cada palabra debe aparecer en ALGÚN campo, no necesariamente en el mismo. Insensible a acentos y mayúsculas; se consideran las primeras 5 palabras.", "type": "text/plain" }, "key": "q", "value": "string" } ], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "6d571f73-807f-4093-9058-3b7b6f7e9d84", "name": "Crear (o reutilizar) un destinatario", "request": { "name": "Crear (o reutilizar) un destinatario", "description": { "content": "Create-or-reuse bajo el remitente `sender_id` (debe ser visible para la llave; si no → 404 ciego). Mismo dedupe normalizado que el carril de envíos; en una reutilización, `alias`/`referencia`/`delivery_instructions` NO se aplican (no forman parte de la identidad — la fila existente se devuelve intacta). Requiere scope `addresses:write`.", "type": "text/plain" }, "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "be95fdd3-9731-4199-b798-335e1db840b3", "name": "Destinatario idéntico ya existente reutilizado (`created: false`).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"recipient\": {\n \"id\": \"D0067890\",\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"email\": null,\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\",\n \"created_at\": \"2026-07-13T18:41:00Z\"\n },\n \"created\": false\n },\n \"requestId\": \"req_d6e7f8a9b0\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "af10b732-e12c-412d-8d94-601d3693eed2", "name": "Destinatario creado (`created: true`).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"recipient\": {\n \"id\": \"D0067890\",\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"email\": null,\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\",\n \"created_at\": \"2026-07-13T18:41:00Z\"\n },\n \"created\": true\n },\n \"requestId\": \"req_c5d6e7f8a9\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4bff7227-0fbb-4474-8f88-2dc0b0464c66", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "25ded5a7-1192-478b-a211-9d1831b1af6d", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "55432ed4-982b-4df9-a28a-b4a1870c267b", "name": "`NOT_FOUND` — `sender_id` inexistente o no visible (respuesta idéntica).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bf8e526a-3421-40dc-a74c-dad020d22c16", "name": "`VALIDATION_ERROR` — campos faltantes/inválidos o desconocidos (details.fields).", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4a03ca01-e6b9-40e5-a174-6d7df76b73f4", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "19f3f752-3e83-4b79-a5a5-4fb1c3c75dcb", "name": "`ADDRESS_ERROR` — no se pudo registrar; reintenta.", "originalRequest": { "url": { "path": [ "recipients" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f4771845-fc9d-4551-a9e7-06d11a44cf17", "name": "Consultar un destinatario", "request": { "name": "Consultar un destinatario", "description": { "content": "Requiere scope `addresses:read`. 404 idéntico para inexistente y no-visible (sin oráculo).", "type": "text/plain" }, "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "51a9241f-14b9-4110-b65f-e9d90c7c8527", "name": "El destinatario.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"recipient\": {\n \"id\": \"D0067890\",\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654321\",\n \"email\": null,\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\",\n \"created_at\": \"2026-07-13T18:41:00Z\"\n }\n },\n \"requestId\": \"req_e7f8a9b0c1\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0e925763-d31a-4f74-b540-e451ef0b4b40", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dcb77a08-a03f-470f-a71b-aa76fdc73d6f", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "206562bf-78eb-44bf-a4be-14a00f5d95a5", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "62b4c8bb-5c2f-4ff4-acbb-897d69a53eab", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "67eaee5a-1d32-4b6e-9964-6428632bb107", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "39e3a108-41ec-48aa-a23e-e853ad5baabe", "name": "Editar un destinatario", "request": { "name": "Editar un destinatario", "description": { "content": "Actualización PARCIAL de un destinatario visible. Requiere scope `addresses:write`. `sender_id` es inmutable (no se re-asigna de remitente). Solo los campos presentes cambian; al menos uno. Los requeridos pueden cambiarse pero no vaciarse; los opcionales aceptan `null`. 404 idéntico para inexistente y no-visible.", "type": "text/plain" }, "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "591fc109-ec94-4def-acfb-56cc71ad9ff4", "name": "El destinatario actualizado.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"recipient\": {\n \"id\": \"D0067890\",\n \"sender_id\": \"C0012345\",\n \"alias\": \"Oficina\",\n \"name\": \"María López\",\n \"phone\": \"8187654322\",\n \"email\": null,\n \"street\": \"Av. Constitución\",\n \"number\": \"400\",\n \"colonia\": \"Centro\",\n \"city\": \"Monterrey\",\n \"state\": \"Nuevo León\",\n \"postal_code\": \"64000\",\n \"referencia\": \"Edificio azul, junto a la farmacia\",\n \"delivery_instructions\": \"Entregar en recepción\",\n \"created_at\": \"2026-07-13T18:41:00Z\"\n }\n },\n \"requestId\": \"req_f8a9b0c1d2\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7a70855f-425f-4b39-b044-22d358eef8d9", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "79dbe2ed-968c-4165-97b3-079aa27e3650", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "079f57bb-dd7f-4ef8-a71e-aff477cefdd2", "name": "`NOT_FOUND` — ruta desconocida, recurso ajeno/inexistente, o la API pública no está habilitada (respuestas indistinguibles por diseño).", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ac6f54c0-9f0f-40d8-bcc6-28b8f7c78b97", "name": "`DUPLICATE_ADDRESS` — la edición dejaría este destinatario idéntico a OTRO del MISMO remitente. La fila no se modifica.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bc3c2090-78fd-4ac1-a688-750da94a1ca7", "name": "`VALIDATION_ERROR` (details.fields) — campo desconocido, `sender_id` presente (inmutable), requerido vaciado, `country` ≠ MX, o cuerpo sin campos editables.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6a460510-d4e8-4d4e-9bf9-ca3b7c4510a5", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "27e05cd5-6f5f-437a-8821-85221db5bbe7", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "recipients", ":id" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "r9XpgY3QemuF0Pxt2E8bh97V1dxQ", "key": "id" } ] }, "header": [ { "disabled": false, "description": { "content": "Solo llaves de cuentas admin: el punto de venta cuyo fondo se carga/consulta. Requiere que la llave tenga una allowlist de PDVs configurada por un administrador (`pdv_allowlist`); sin allowlist, todo PDV real es denegado por defecto. Validado además contra los PDV activos. Cualquier violación → `403 PDV_NOT_ALLOWED`. El valor `personal_account` equivale a omitir el header.", "type": "text/plain" }, "key": "X-PDV-ID", "value": "string" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"phone\": \"8187654322\",\n \"delivery_instructions\": null\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "344fb6ba-b531-47cd-b60e-c2fb8024c65c", "name": "Validar un código postal y listar sus colonias", "request": { "name": "Validar un código postal y listar sus colonias", "description": { "content": "Resuelve un código postal mexicano (catálogo SEPOMEX) en su estado, municipio y el conjunto de colonias/asentamientos — justo lo que se necesita para llenar una dirección antes de `POST /senders` o `POST /shipments`. Requiere scope `addresses:read`. Datos de referencia públicos y de solo lectura: responde IDÉNTICo con llaves `ek_live_` y `ek_test_` (no hay nada que simular). `422` si el CP no son 5 dígitos; `404` si no existe en el catálogo; `200` con los datos si es válido.", "type": "text/plain" }, "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "type": "any", "value": "76541", "key": "postal_code", "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" } } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {}, "auth": null }, "response": [ { "id": "d86a6a2e-fde3-4c6b-bac3-547b260b6822", "name": "El código postal existe.", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"data\": {\n \"postal_code\": \"64000\",\n \"state\": \"Nuevo León\",\n \"state_code\": \"NL\",\n \"municipality\": \"Monterrey\",\n \"city\": \"Monterrey\",\n \"colonias\": [\n {\n \"name\": \"Centro\",\n \"settlement_type\": \"Colonia\"\n }\n ]\n },\n \"requestId\": \"req_a9b0c1d2e3\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f3d0850a-056d-4caa-ba10-b5dfbafc9a5e", "name": "`UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6be1df72-c4f3-4e87-9794-52f02f28a96f", "name": "`INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "50c248f9-38b2-4d08-9068-19aa79e6e54d", "name": "`NOT_FOUND` — el código postal (bien formado) no está en el catálogo SEPOMEX.", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "80f2787c-06de-40bd-bed0-1f4694e8cdad", "name": "`VALIDATION_ERROR` — el código postal debe ser exactamente 5 dígitos.", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4a2945b3-42dc-441f-9891-ab9fd617d309", "name": "`RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": false, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "27d2de95-c31e-4aae-bd3a-12a5d7589c21", "name": "`SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.", "originalRequest": { "url": { "path": [ "postal-codes", ":postal_code" ], "host": [ "{{baseUrl}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) Código postal de 5 dígitos.", "type": "text/plain" }, "type": "any", "value": "76541", "key": "postal_code" } ] }, "header": [ { "key": "Accept", "value": "application/json" }, { "description": { "content": "Added as a part of security scheme: bearer", "type": "text/plain" }, "key": "Authorization", "value": "Bearer " } ], "method": "GET", "body": {} }, "status": "Internal Server Error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": {\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Validation failed\",\n \"details\": {\n \"fields\": [\n \"from.postal_code: must be a 5-digit Mexican postal code\"\n ]\n }\n },\n \"requestId\": \"req_b0c1d2e3f4\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ], "auth": { "type": "bearer", "bearer": [ { "type": "any", "value": "{{bearerToken}}", "key": "token" } ] }, "event": [], "variable": [ { "key": "baseUrl", "value": "https://api.enviadores.com.mx/api/v1" } ], "info": { "_postman_id": "815d0b57-a684-4836-83fc-88250e805147", "name": "Enviadores Public API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "API server-to-server autenticada por llave secreta (`Authorization: Bearer ek_live_…` / `ek_test_…`). Las llaves se administran desde la cuenta (una llave se muestra UNA sola vez al crearla). Nunca uses una llave secreta en un navegador o app móvil — no hay CORS en esta superficie por diseño.\n\n**Sobre (envelope):** toda respuesta JSON tiene la forma `{\"success\": true, \"data\": {…}, \"requestId\": \"…\"}` o `{\"success\": false, \"error\": {\"code\", \"message\", \"details\"?}, \"requestId\"}`. `requestId` también viaja en el header `X-Request-Id` — inclúyelo al reportar un problema.\n\n**Flujo cotiza→envía:** `POST /rates` devuelve tarifas con `id` (el `rate_id`). Ese `rate_id` es válido por **30 minutos** (`rate_id_expires_in_seconds`) y está ligado al usuario de la llave (y al PDV del header `X-PDV-ID`, si se usó): la creación del envío debe hacerse con la MISMA llave/usuario (y mismo PDV) o recibirás `RATE_NOT_FOUND` / `RATE_PDV_MISMATCH`.\n\n**Idempotencia:** manda un header `Idempotency-Key` (UUID fresco por operación lógica, 1–128 caracteres ASCII imprimibles) en `POST /shipments`. Un reintento con la MISMA llave y el MISMO cuerpo repite la respuesta original (header `Idempotent-Replay: true`) sin doble cargo, dentro de una ventana de **15 minutos**. La llave queda ligada al cuerpo exacto de la primera solicitud y al `X-PDV-ID` con que se envió: misma llave + cuerpo distinto → `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` (manda una llave nueva); misma llave pasados los 15 min → `409 IDEMPOTENCY_KEY_EXPIRED` (la llave sigue registrada 24 h pero ya no se repite — consulta `GET /shipments`); llave presente pero inválida (vacía, >128 chars, caracteres no imprimibles) → `400 IDEMPOTENCY_KEY_INVALID`; misma llave en otro endpoint → `409 IDEMPOTENCY_KEY_REUSED`. **Cambio 2026-08:** las llaves de `POST /shipments` ya NO comparten espacio de nombres con el carril web (`app.enviadores.com.mx`) de la misma cuenta — una llave usada en un carril y reusada en el otro responde `409 IDEMPOTENCY_KEY_REUSED` en lugar de repetir el envío del otro carril.\n\n**`POST_COMMIT_ERROR` (500): NO reintentes con una llave NUEVA.** El envío ES real y el cargo NO se revierte — la falla fue posterior al punto de commit. Consulta `GET /shipments` para recuperar la guía. Reintentar con el MISMO `Idempotency-Key` nunca crea un segundo envío: dentro de la ventana de 15 min repite este mismo `500 POST_COMMIT_ERROR` (con `Idempotent-Replay: true`) y pasada la ventana responde `409 IDEMPOTENCY_KEY_EXPIRED`. Una llave NUEVA sí crearía un segundo envío con un segundo cargo.\n\n**Límites de tasa:** por llave (token bucket). Cada respuesta incluye `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset`; un `429 RATE_LIMITED` incluye `Retry-After` (segundos) y `details.retry_after_ms`. Niveles: live standard 60 rpm sostenido / ráfaga 120; elevated 240/480; llaves de prueba 30/60.\n\n**Alcances (scopes):** cada llave porta un subconjunto de `rates:read`, `shipments:write`, `shipments:read`, `shipments:read:pdv`, `tracking:read`, `cancellations:write`, `cancellations:read`, `balance:read`, `labels:read`, `addresses:read`, `addresses:write`. Falta de scope → `403 INSUFFICIENT_SCOPE`. Los scopes se fijan al CREAR la llave: una llave creada antes de que existiera un scope no lo porta — crea una llave nueva para usar endpoints nuevos.\n\n`shipments:read:pdv` es un scope **ampliado**: es el único que deja ver filas que la llave no creó (los envíos de un PDV completo, bajo `X-PDV-ID`). Por eso NUNCA se otorga de forma implícita — hay que pedirlo por nombre al crear la llave, aunque se pidan \"todos\" los permisos.\n\n**`X-PDV-ID` (solo llaves de cuentas admin):** dirige el cargo (y el binding de cotización) a un punto de venta específico; requiere que la llave tenga una allowlist de PDVs configurada (sin allowlist, TODO `X-PDV-ID` real → `403 PDV_NOT_ALLOWED` — denegado por defecto). El valor `personal_account` equivale a omitir el header. Sin header, el principal cargado es el usuario de la llave.\n\n**Cobertura v1 (aplicada, no solo documentada):** envíos domésticos MX (CP de 5 dígitos) y UN paquete por solicitud. `country` distinto de `MX`, `packages`, `customs`, `ocurre`, `package.type` distinto de `paquete`, o cualquier campo desconocido a nivel raíz → `422 VALIDATION_ERROR` con el campo nombrado en `details.fields` — nunca se ignoran en silencio. Los campos `reference` y `metadata` de `POST /shipments` se aceptan pero están RESERVADOS (no se persisten en v1; `metadata.test_scenario` es un concepto del modo de prueba).\n\n**Límite de gasto por llave (opcional):** una llave puede portar un tope de gasto en ventana móvil de 24 h (`spend_cap_daily_mxn`, configurado por un administrador). Excederlo responde `429 RISK_LIMIT` con `details {daily_cap_mxn, spent_24h_mxn, attempted_mxn}`.\n\nContact Support:\n Name: Enviadores", "type": "text/plain" } } }