# Estado 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. | ```json { "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`: ```json { "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](/docs/errores/): `error.code`, `message`, `request_id`, `details`, `retryable` y `docs_url`. Decide por `code`. | HTTP | Código | Cuándo sale | `retryable` | |---|---|---|---| | 400 | [`invalid_request`](/docs/errores/#invalid_request) (sólo cuenta de prueba) | El encabezado `X-Fital-Scenario` trae un escenario desconocido. | `false` | | 401 | [`invalid_api_key`](/docs/errores/#invalid_api_key) | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | `false` | | 401 | [`wrong_environment`](/docs/errores/#wrong_environment) | La llave es de otro ambiente. | `false` | | 403 | [`ip_not_allowed`](/docs/errores/#ip_not_allowed) | La IP de origen no está activa en la lista de esa llave. | `false` | | 403 | [`kyb_required`](/docs/errores/#kyb_required) | La empresa no tiene KYB aprobado o aún no está inscrita. | `false` | | 403 | [`account_not_active`](/docs/errores/#account_not_active) | La cuenta no está activa. | `false` | | 429 | [`rate_limited`](/docs/errores/#rate_limited) | Superaste un límite de peticiones. Llega con `Retry-After`. | `true` | | 500 | [`internal_error`](/docs/errores/#internal_error) | Fallo nuestro. El resultado de la petición no se conoce. | `true` | | 503 | [`service_unavailable`](/docs/errores/#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`: ```json { "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`: ```json { "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`: ```json { "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`: ```json { "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`: ```json { "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`: ```json { "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 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](/docs/recetas/reintentos/) y [Límites](/docs/limites/). ## 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: ```bash 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](/docs/ambientes/). ```bash curl -sS "$FITAL_API/status" \ -H "Authorization: Bearer $FITAL_KEY" ``` ```js const r = await fetch(`${process.env.FITAL_API}/status`, { headers: { Authorization: `Bearer ${process.env.FITAL_KEY}`, }, }); console.log(r.status, await r.json()); ``` ```python import json, os, urllib.error, urllib.request pet = urllib.request.Request(os.environ["FITAL_API"] + "/status", method="GET", headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"]}) try: with urllib.request.urlopen(pet) as r: print(r.status, json.load(r)) except urllib.error.HTTPError as e: print(e.code, e.read().decode()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FITAL_KEY'), ], ]); echo curl_exec($c), "\n"; ``` ## Guías - [Salud y estado](/docs/salud-y-estado/) - [Autenticación](/docs/autenticacion/) - [Cobertura](/docs/cobertura/) - [Pago PIX](/docs/recetas/pago-pix/)