Autenticación

Toda petición lleva tu llave en Authorization: Bearer. Las que mueven dinero llevan además una firma. En producción, la llave sólo funciona desde las IP que registraste.

LlavesCopiar enlace

Se crean en la pantalla Llaves del panel. El formato es sk_live_fital_<id>_<secreto>_<verificador> en producción y sk_test_fital_… en la cuenta de prueba. Al crear una llave ves también su secreto de firma, una sola vez. Guarda ambos en tu gestor de secretos.

VencimientoCopiar enlace

La pantalla Llaves muestra la fecha de cada llave. La pantalla Avisos te avisa 30, 7 y 1 días antes, sin correo. Una llave vencida responde 401 invalid_api_key y ya no se puede rotar: tendrás que crear otra, con su lista de IP.

Varias empresasCopiar enlace

Un usuario del panel puede pertenecer a más de una empresa. En ese caso el panel muestra el selector Empresa: cambiar de empresa abre una sesión nueva, y el login reciente no viaja. Llaves, listas de IP, destinos de webhook y datos son de cada empresa. Por API no hay selector: la llave determina la empresa.

ScopesCopiar enlace

Cada llave tiene sólo los permisos que le des. La referencia indica el scope de cada operación.

GET /v1/status acepta cualquier llave válida. GET /v1/health y GET /v1/meta/egress-ips son públicas.

Firma de peticiónCopiar enlace

Con los scopes payments:write, beneficiaries:write, collections:write, deposit_addresses:write, accounts:write el bearer solo no basta. Una llave robada sin el secreto de firma no saca dinero.

X-Fital-Timestamp: <segundos unix>
X-Fital-Signature: v1=<hex>

La firma es HMAC-SHA256, usando como clave el secreto de firma tal como lo recibiste, sobre estas cinco líneas unidas por salto de línea:

timestamp
MÉTODO
ruta y consulta, siempre desde /v1/
sha256 hexadecimal de los bytes del cuerpo
Idempotency-Key, o vacío si la operación no la lleva

La ruta es siempre la canónica, /v1/..., también en los simuladores: cambiar de ambiente no cambia tu código. Una firma vale 5 minutos. La clave de idempotencia va firmada.

Vector de pruebaCopiar enlace

Comprueba tu implementación con este caso. El resultado debe coincidir exactamente. Todos sus datos son ficticios y están publicados a propósito: el secreto del vector no pertenece a ninguna llave y no sirve en ningún ambiente.

CUERPO='{"beneficiary_id":"ben_demo","amount":"1500.00","currency":"MXN","external_ref":"factura-1042"}'
SECRETO_FICTICIO=c15dc9d93f7e23efa923836a3a9d2f7abc8bc9e6d6f353b5a827f7315f25dc9a
HASH=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -r | cut -d' ' -f1)
FIRMA=$(printf '%s\n%s\n%s\n%s\n%s' 1793800000 POST /v1/payments "$HASH" pago-factura-1042 \
  | openssl dgst -sha256 -hmac "$SECRETO_FICTICIO" -r | cut -d' ' -f1)
echo "v1=$FIRMA"

Las operaciones firmadas sin cuerpo, como POST /v1/payments/{id}/cancel, firman el hash de cero bytes. POST /v1/collections/estimate se firma con la última línea vacía.

IP permitidasCopiar enlace

En producción es obligatorio registrar las IP por llave. Ver IP permitidas.

RotaciónCopiar enlace

Rota cada llave en el panel antes de que venza. Rotar crea una llave nueva, con los mismos scopes y la misma lista de IP, y un secreto de firma nuevo, que se muestran una sola vez.

La llave anterior, con su secreto de firma, sigue operando 24 horas: despliega la nueva en ese plazo. Mientras tanto aparece En gracia y no se puede rotar otra vez.

Si la llave se filtró, no rotes: revócala. La revocación aplica a escrituras de inmediato; una lectura puede tardar hasta 30 segundos. Vale igual para llaves de prueba.

Errores comunesCopiar enlace

Un 401 o 403 de acceso no dice si un pago ocurrió. Ver Reintentos.

Qué sigueCopiar enlace

Idempotencia.

Ver esta página en Markdown