APICuentas para recibir
GET /v1/receiving-accounts
Cuentas de la empresa para recibir fondos. Los campos que no apliquen a un tipo de cuenta llegan en null.
| Dato | Valor |
|---|---|
| Método y ruta | GET /v1/receiving-accounts |
| Servidor | https://widget.fital.xyz |
operationId | listReceivingAccounts |
| Acceso | Llave con el scope accounts: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í | Cuentas de la empresa para recibir fondos. |
data[].account_number | texto o null | Sí | Número de cuenta. null si no aplica a esta cuenta. |
data[].bank | texto o null | Sí | Banco de la cuenta. null si no aplica a esta cuenta. |
data[].bic | texto o null | Sí | Código BIC. null si no aplica a esta cuenta. |
data[].br_code | texto o null | Sí | Código BR para pagar por PIX, en cuentas BRL. null si no aplica a esta cuenta. |
data[].bre_b_key | texto o null | Sí | Llave Bre-B, en cuentas COP. null si no aplica a esta cuenta. |
data[].clabe | texto o null | Sí | CLABE de 18 dígitos. null si no aplica a esta cuenta. |
data[].currency | texto o null | Sí | Moneda que recibe la cuenta. |
data[].holder | texto o null | Sí | Titular de la cuenta. null si no aplica a esta cuenta. |
data[].iban | texto o null | Sí | IBAN. null si no aplica a esta cuenta. |
data[].pix_key | texto o null | Sí | Llave PIX, en cuentas BRL. null si no aplica a esta cuenta. |
data[].routing_number | texto o null | Sí | Número de ruta bancaria. null si no aplica a esta cuenta. |
data[].sort_code | texto o null | Sí | Sort code, en cuentas GBP. null si no aplica a esta cuenta. |
{
"data": [
{
"account_number": null,
"bank": "Banco de ejemplo",
"bic": null,
"br_code": null,
"bre_b_key": null,
"clabe": "999180000000000022",
"currency": "MXN",
"holder": "EMPRESA FICTICIA SA DE CV",
"iban": null,
"pix_key": null,
"routing_number": null,
"sort_code": null
}
]
}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": "accounts: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/receiving-accounts" \
-H "Authorization: Bearer $FITAL_KEY"