# Un depósito GET /v1/deposits/{id} Un depósito de tu empresa. El id va sellado por empresa: el de otra da 404. | Dato | Valor | |---|---| | Método y ruta | `GET /v1/deposits/{id}` | | Servidor | `https://widget.fital.xyz` | | `operationId` | `getDeposit` | | Acceso | Llave con el scope `deposits:read` | | Firma de petición | No aplica | | Idempotencia | No aplica | ## Encabezados de la petición | Encabezado | Obligatorio | Descripción | |---|---|---| | `Authorization` | Sí | `Bearer` y tu llave. | | `X-Fital-Scenario` | No | Sólo simuladores: elige la respuesta que quieres practicar. | ## Parámetros | Parámetro | En | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `id` | ruta | texto | Sí | Identificador del recurso. Hasta 250 caracteres. | ## Respuestas correctas ### 200 Correcto | Campo | Tipo | Obligatorio | Descripción | |---|---|---|---| | `amount` | texto o `null` | Sí | Monto recibido. | | `concept` | texto o `null` | Sí | Concepto que escribió quien pagó. | | `credited_amount` | texto o `null` | Sí | Monto acreditado a tu saldo. | | `credited_currency` | texto o `null` | Sí | Moneda acreditada. | | `currency` | texto o `null` | Sí | Moneda recibida. | | `id` | texto | Sí | Identificador del depósito, con prefijo `dpt_`. | | `payer` | objeto o `null` | Sí | Quién pagó. null si no hay datos legibles: nunca se inventa. | | `payer.address` | texto o `null` | Sí | Dirección de origen. null si no se conoce. | | `payer.bank` | texto o `null` | Sí | Banco de origen. null si no se conoce. | | `payer.clabe` | texto o `null` | Sí | CLABE de origen. null si no se conoce. | | `payer.name` | texto o `null` | Sí | Nombre de quien pagó. null si no se conoce. | | `payer.rfc` | texto o `null` | Sí | RFC de quien pagó. null si no se conoce. | | `receipt_url` | texto o `null` | Sí | Enlace https al comprobante, si existe. | | `received_at` | texto o `null` | Sí | Fecha del depósito. ISO 8601 en UTC. | | `reference` | texto o `null` | Sí | Referencia del depósito. | | `status` | texto | Sí | Estado del depósito. `in_review`: El depósito está en revisión. Aún no es dinero disponible. `received`: El dinero ya está acreditado. `returned`: El depósito se devolvió. | | `tracking_key` | texto o `null` | Sí | Clave de rastreo del banco. | #### Valores de `status` | Valor | Significado | |---|---| | `in_review` | El depósito está en revisión. Aún no es dinero disponible. | | `received` | El dinero ya está acreditado. | | `returned` | El depósito se devolvió. | ```json { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": "1250.00", "credited_currency": "MXN", "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "received", "tracking_key": "CLAVE-DE-RASTREO-DEMO" } ``` En revisión: aún no es dinero disponible: ```json { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": null, "credited_currency": null, "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "in_review", "tracking_key": "CLAVE-DE-RASTREO-DEMO" } ``` Sin datos legibles del pagador: ```json { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": "1250.00", "credited_currency": "MXN", "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": null, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "received", "tracking_key": "CLAVE-DE-RASTREO-DEMO" } ``` ## Encabezados de la respuesta | Encabezado | Contenido | |---|---| | `X-Request-Id` | Identificador de la petición. Cítalo con soporte. | | `Retry-After` | Segundos a esperar, con `429` y a veces con `503`. | ## Errores Todos usan la forma de [Errores](/docs/errores/): `error.code`, `message`, `request_id`, `details`, `retryable` y `docs_url`. Decide por `code`. | HTTP | Código | Cuándo sale | `retryable` | |---|---|---|---| | 400 | [`invalid_request`](/docs/errores/#invalid_request) | Algún parámetro o campo no cumple el esquema. Mira `details.fields`. | `false` | | 401 | [`invalid_api_key`](/docs/errores/#invalid_api_key) | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | `false` | | 401 | [`wrong_environment`](/docs/errores/#wrong_environment) | La llave es de otro ambiente. | `false` | | 403 | [`forbidden_scope`](/docs/errores/#forbidden_scope) | La llave no tiene el scope de esta operación. `details.required_scope` lo nombra. | `false` | | 403 | [`ip_not_allowed`](/docs/errores/#ip_not_allowed) | La IP de origen no está activa en la lista de esa llave. | `false` | | 403 | [`kyb_required`](/docs/errores/#kyb_required) | La empresa no tiene KYB aprobado o aún no está inscrita. | `false` | | 403 | [`account_not_active`](/docs/errores/#account_not_active) | La cuenta no está activa. | `false` | | 404 | [`not_found`](/docs/errores/#not_found) | El depósito no existe o es de otra empresa. | `false` | | 429 | [`rate_limited`](/docs/errores/#rate_limited) | Superaste un límite de peticiones. Llega con `Retry-After`. | `true` | | 500 | [`internal_error`](/docs/errores/#internal_error) | Fallo nuestro. El resultado de la petición no se conoce. | `true` | | 503 | [`service_unavailable`](/docs/errores/#service_unavailable) | El servicio no está disponible por ahora. El resultado de la petición no se conoce. | `true` | ### Ejemplos de error `400 invalid_request`: ```json { "error": { "code": "invalid_request", "message": "Petición inválida", "request_id": "0123456789abcdef0123456789abcdef", "details": { "fields": { "limit": "Entre 1 y 100" } }, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request" } } ``` `401 invalid_api_key`: ```json { "error": { "code": "invalid_api_key", "message": "Credencial inválida", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key" } } ``` `403 forbidden_scope`: ```json { "error": { "code": "forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0123456789abcdef0123456789abcdef", "details": { "required_scope": "deposits:read" }, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope" } } ``` `404 not_found`: ```json { "error": { "code": "not_found", "message": "No encontrado", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found" } } ``` `429 rate_limited`: ```json { "error": { "code": "rate_limited", "message": "Demasiadas peticiones", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": true, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited" } } ``` `500 internal_error`: ```json { "error": { "code": "internal_error", "message": "Error interno", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": true, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error" } } ``` `503 service_unavailable`: ```json { "error": { "code": "service_unavailable", "message": "Servicio no disponible", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": true, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable" } } ``` ## Reintentos Es una lectura: repetirla no tiene efecto. - `429 rate_limited`: Espera lo que indique `Retry-After` y repite. - `500 internal_error`: Repite con espera exponencial. - `503 service_unavailable`: Repite con espera exponencial. Respeta `Retry-After` si viene. Ver [Reintentos](/docs/recetas/reintentos/) y [Límites](/docs/limites/). ## Muestras **Variables de estas muestras: simulador público, sin cuenta** Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público: ```bash export FITAL_API="https://widget.fital.xyz/explorar/v1" export FITAL_KEY="sk_test_sandbox_publica" ``` En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los `id` de ejemplo por los tuyos. Ver [Ambientes](/docs/ambientes/). ```bash curl -sS "$FITAL_API/deposits/dpt_7bTcF2qXe9WmL4sD1nHrY6vK" \ -H "Authorization: Bearer $FITAL_KEY" ``` ```js const r = await fetch(`${process.env.FITAL_API}/deposits/dpt_7bTcF2qXe9WmL4sD1nHrY6vK`, { headers: { Authorization: `Bearer ${process.env.FITAL_KEY}`, }, }); console.log(r.status, await r.json()); ``` ```python import json, os, urllib.error, urllib.request pet = urllib.request.Request(os.environ["FITAL_API"] + "/deposits/dpt_7bTcF2qXe9WmL4sD1nHrY6vK", method="GET", headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"]}) try: with urllib.request.urlopen(pet) as r: print(r.status, json.load(r)) except urllib.error.HTTPError as e: print(e.code, e.read().decode()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FITAL_KEY'), ], ]); echo curl_exec($c), "\n"; ``` ## Guías - [Quién pagó](/docs/recetas/quien-pago/) - [Autenticación](/docs/autenticacion/)