Estimar un cobro

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
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.

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.

{
  "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.

{
  "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: error.code, message, request_id, details, retryable y docs_url. Decide por code.

HTTP	Código	Cuándo sale	`retryable`
400	`invalid_request`	Algún parámetro o campo no cumple el esquema. Mira `details.fields`.	`false`
401	`invalid_api_key`	La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida.	`false`
401	`wrong_environment`	La llave es de otro ambiente.	`false`
401	`invalid_signature`	Falta la firma, no coincide o tiene más de 5 minutos.	`false`
403	`forbidden_scope`	La llave no tiene el scope de esta operación. `details.required_scope` lo nombra.	`false`
403	`ip_not_allowed`	La IP de origen no está activa en la lista de esa llave.	`false`
403	`kyb_required`	La empresa no tiene KYB aprobado o aún no está inscrita.	`false`
403	`account_not_active`	La cuenta no está activa.	`false`
413	`invalid_request`	El cuerpo supera 64 KB.	`false`
422	`method_unavailable`	El método no está disponible.	`false`
422	`amount_out_of_range`	El monto está fuera del rango del método.	`false`
422	`collection_rejected`	La estimación se rechazó.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
500	`internal_error`	Fallo nuestro. El resultado de la petición no se conoce.	`true`
503	`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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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 y Límites.

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:

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.

op-estimar-cobro.sh

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"

Guías

Ver esta página en Markdown

Encabezados de la peticiónCopiar enlace

CuerpoCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página