# Estimar un cobro POST /v1/collections/estimate Estima montos y comisiones de un cobro antes de crearlo. Es indicativa y no crea nada, por eso no pide `Idempotency-Key`. Va firmada como las demás escrituras de cobros. | Dato | Valor | |---|---| | Método y ruta | `POST /v1/collections/estimate` | | Servidor | `https://widget.fital.xyz` | | `operationId` | `estimateCollection` | | Acceso | Llave con el scope `collections:write` | | Firma de petición | **Obligatoria** en producción y en la cuenta de prueba. El simulador público no la valida. Ver [Firma de petición](/docs/autenticacion/#firma-de-petición) | | Idempotencia | No aplica | - Es indicativa y no crea nada: por eso no pide `Idempotency-Key`. Firma con la última línea vacía. Ver [Firma de petición](/docs/autenticacion/#firma-de-petición). ## Encabezados de la petición | Encabezado | Obligatorio | Descripción | |---|---|---| | `Authorization` | Sí | `Bearer` y tu llave. | | `Content-Type` | Sí | `application/json`. | | `X-Fital-Timestamp` | Sí | Hora Unix en segundos. Se acepta hasta 300 s de diferencia. | | `X-Fital-Signature` | Sí | Firma `v1=` de la petición con el secreto de firma de la llave. | | `X-Fital-Scenario` | No | Sólo simuladores: elige la respuesta que quieres practicar. | ## Cuerpo | Campo | Tipo | Obligatorio | Descripción | |---|---|---|---| | `amount` | texto | Sí | Monto a estimar. | | `currency` | texto | Sí | Moneda del cobro. | | `method` | texto | Sí | Método de cobro. Hasta 40 caracteres. | ```json { "currency": "MXN", "method": "spei", "amount": "1250.00" } ``` ## Respuestas correctas ### 200 Correcto | Campo | Tipo | Obligatorio | Descripción | |---|---|---|---| | `amount` | texto o `null` | Sí | Monto estimado. | | `currency` | texto o `null` | Sí | Moneda del monto. | | `exchange_rate` | texto o `null` | Sí | Tipo de cambio aplicado, si hay conversión. | | `expires_at` | texto o `null` | Sí | Vigencia de la estimación. ISO 8601 en UTC. | | `fee` | texto o `null` | Sí | Comisión. | | `fee_currency` | texto o `null` | Sí | Moneda de la comisión. | | `indicative` | booleano | Sí | Siempre true: es una estimación. | | `max_amount` | texto o `null` | Sí | Monto máximo del método. | | `min_amount` | texto o `null` | Sí | Monto mínimo del método. | | `plan_fee_pct` | texto o `null` | Sí | Comisión de tu plan, en porcentaje. | | `receive_amount` | texto o `null` | Sí | Lo que recibirías. null en `efectivo`: se fija al conciliar el pago. | | `receive_currency` | texto o `null` | Sí | Moneda de lo que recibirías. | | `total_cost_pct` | texto o `null` | Sí | Costo total, en porcentaje. | ```json { "amount": "1250.00", "currency": "MXN", "exchange_rate": null, "expires_at": "2026-11-04T18:05:00.000Z", "fee": "25.00", "fee_currency": "MXN", "indicative": true, "max_amount": "50000.00", "min_amount": "10.00", "plan_fee_pct": "2.00", "receive_amount": "1225.00", "receive_currency": "MXN", "total_cost_pct": "2.00" } ``` ## 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` | | 401 | [`invalid_signature`](/docs/errores/#invalid_signature) | Falta la firma, no coincide o tiene más de 5 minutos. | `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` | | 413 | [`invalid_request`](/docs/errores/#invalid_request) | El cuerpo supera 64 KB. | `false` | | 422 | [`method_unavailable`](/docs/errores/#method_unavailable) | El método no está disponible. | `false` | | 422 | [`amount_out_of_range`](/docs/errores/#amount_out_of_range) | El monto está fuera del rango del método. | `false` | | 422 | [`collection_rejected`](/docs/errores/#collection_rejected) | La estimación se rechazó. | `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": { "amount": "Valor inválido" } }, "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": "collections:write" }, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope" } } ``` `413 invalid_request`: ```json { "error": { "code": "invalid_request", "message": "Petición inválida", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request" } } ``` `422 method_unavailable`: ```json { "error": { "code": "method_unavailable", "message": "Operación rechazada", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#method_unavailable" } } ``` `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 No lleva clave de idempotencia y no mueve dinero: repetirla es seguro. - `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" export FITAL_SIGNING_SECRET="secreto_de_firma_de_prueba_publico" ``` 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 CUERPO='{"currency":"MXN","method":"spei","amount":"1250.00"}' TS=$(date +%s) HASH=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -r | cut -d' ' -f1) FIRMA=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/collections/estimate "$HASH" "" \ | openssl dgst -sha256 -hmac "$FITAL_SIGNING_SECRET" -r | cut -d' ' -f1) curl -sS -X POST "$FITAL_API/collections/estimate" \ -H "Authorization: Bearer $FITAL_KEY" \ -H "Content-Type: application/json" \ -H "X-Fital-Timestamp: $TS" \ -H "X-Fital-Signature: v1=$FIRMA" \ -d "$CUERPO" ``` ```js import { createHash, createHmac } from 'node:crypto'; const cuerpo = JSON.stringify({"currency":"MXN","method":"spei","amount":"1250.00"}); const ts = String(Math.floor(Date.now() / 1000)); const hash = createHash('sha256').update(cuerpo).digest('hex'); const firma = createHmac('sha256', process.env.FITAL_SIGNING_SECRET) .update([ts, 'POST', '/v1/collections/estimate', hash, ''].join('\n')).digest('hex'); const r = await fetch(`${process.env.FITAL_API}/collections/estimate`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FITAL_KEY}`, 'Content-Type': 'application/json', 'X-Fital-Timestamp': ts, 'X-Fital-Signature': `v1=${firma}`, }, body: cuerpo, }); console.log(r.status, await r.json()); ``` ```python import hashlib, hmac, json, os, time, urllib.error, urllib.request cuerpo = json.dumps({"currency":"MXN","method":"spei","amount":"1250.00"}).encode() ts = str(int(time.time())) canon = "\n".join([ts, "POST", "/v1/collections/estimate", hashlib.sha256(cuerpo).hexdigest(), ""]) firma = hmac.new(os.environ["FITAL_SIGNING_SECRET"].encode(), canon.encode(), hashlib.sha256).hexdigest() pet = urllib.request.Request(os.environ["FITAL_API"] + "/collections/estimate", method="POST", data=cuerpo, headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"], "Content-Type": "application/json", "X-Fital-Timestamp": ts, "X-Fital-Signature": "v1=" + firma}) 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_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FITAL_KEY'), 'Content-Type: application/json', 'X-Fital-Timestamp: ' . $ts, 'X-Fital-Signature: v1=' . $firma, ], CURLOPT_POSTFIELDS => $cuerpo, ]); echo curl_exec($c), "\n"; ``` ## Guías - [Cobros](/docs/recetas/cobros/) - [Autenticación](/docs/autenticacion/)