APISaldos disponibles
GET /v1/balances
Saldo disponible de la empresa dueña de la llave, una fila por moneda.
| Dato | Valor |
|---|---|
| Método y ruta | GET /v1/balances |
| Servidor | https://widget.fital.xyz |
operationId | listBalances |
| Acceso | Llave con el scope balances: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. |
Respuestas correctas
200 Correcto
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
data | lista de objeto | Sí | Un saldo por moneda. |
data[].available | texto | Sí | Saldo disponible en esa moneda, como decimal en texto. |
data[].currency | texto | Sí | Moneda del saldo. |
{
"data": [
{
"available": "125000.00",
"currency": "MXN"
},
{
"available": "4200.00",
"currency": "USD"
}
]
}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 (sólo cuenta de prueba) | El encabezado X-Fital-Scenario trae un escenario desconocido. | 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 |
| 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 |
| 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": {
"limit": "Entre 1 y 100"
}
},
"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": "balances:read"
},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
}
}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
Es una lectura: repetirla no tiene efecto.
429 rate_limited: Espera lo que indiqueRetry-Aftery repite.500 internal_error: Repite con espera exponencial.503 service_unavailable: Repite con espera exponencial. RespetaRetry-Aftersi 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"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.
curl -sS "$FITAL_API/balances" \
-H "Authorization: Bearer $FITAL_KEY"