APIEstado por capacidad
GET /v1/status
Estado de pagos, cobros, webhooks y API para tu empresa. Acepta cualquier llave válida. not_enabled indica que tu empresa no tiene esa capacidad y unknown que no hay medición reciente.
| Dato | Valor |
|---|---|
| Método y ruta | GET /v1/status |
| Servidor | https://widget.fital.xyz |
operationId | getStatus |
| Acceso | Cualquier llave válida |
| 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 |
|---|---|---|---|
capabilities | lista de objeto | Sí | Una fila por capacidad. |
capabilities[].id | texto | Sí | Identificador de la capacidad. payments_mxn: Pagos por SPEI. payments_latam: Pagos por el riel latam. payments_pix: Pagos por PIX. collections: Cobros. webhooks: Entrega de webhooks. api: La API. |
capabilities[].name | texto | Sí | Nombre legible. |
capabilities[].since | texto o null | Sí | Desde cuándo está en ese estado. null si no se sabe. |
capabilities[].status | texto | Sí | Estado de la capacidad. operational: Funciona con normalidad. degraded: Funciona con problemas. outage: No funciona. unknown: Sin medición reciente. not_enabled: No está habilitada para tu empresa. |
updated_at | texto | Sí | Momento en que se armó esta respuesta. |
Valores de capabilities[].id
| Valor | Significado |
|---|---|
payments_mxn | Pagos por SPEI. |
payments_latam | Pagos por el riel latam. |
payments_pix | Pagos por PIX. |
collections | Cobros. |
webhooks | Entrega de webhooks. |
api | La API. |
El contrato lo declara como texto: trata la lista como extensible.
Valores de capabilities[].status
| Valor | Significado |
|---|---|
operational | Funciona con normalidad. |
degraded | Funciona con problemas. |
outage | No funciona. |
unknown | Sin medición reciente. |
not_enabled | No está habilitada para tu empresa. |
{
"capabilities": [
{
"id": "payments_mxn",
"name": "Pagos MXN",
"since": "2026-11-04T10:00:00.000Z",
"status": "operational"
},
{
"id": "payments_pix",
"name": "Pagos PIX",
"since": null,
"status": "not_enabled"
}
],
"updated_at": "2026-11-04T18:00:00.000Z"
}Variante status_degraded:
{
"updated_at": "2026-11-04T18:00:00.000Z",
"capabilities": [
{
"id": "payments_mxn",
"name": "Pagos MXN",
"status": "degraded",
"since": "2026-11-04T10:00:00.000Z"
},
{
"id": "webhooks",
"name": "Webhooks",
"status": "operational",
"since": "2026-11-04T09:00:00.000Z"
},
{
"id": "api",
"name": "API",
"status": "operational",
"since": "2026-11-04T09:00:00.000Z"
}
]
}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 | 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 ip_not_allowed:
{
"error": {
"code": "ip_not_allowed",
"message": "IP no permitida para esta llave",
"request_id": "0123456789abcdef0123456789abcdef",
"details": {},
"retryable": false,
"docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed"
}
}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/status" \
-H "Authorization: Bearer $FITAL_KEY"