# Métodos de cobro GET /v1/collection-methods Métodos de cobro de la empresa, con país, moneda, mínimos y máximos. | Dato | Valor | |---|---| | Método y ruta | `GET /v1/collection-methods` | | Servidor | `https://widget.fital.xyz` | | `operationId` | `listCollectionMethods` | | Acceso | Llave con el scope `collections:read` | | Firma de petición | No aplica | | Idempotencia | No aplica | - Sólo lista los métodos que puede usar tu empresa. `available: false` significa que el método existe pero hoy no se puede usar. - `payer_fields` lista lo que el método pide en `payer` al crear el cobro, y `POST /v1/collections` lo aplica: `required`, `options` con los valores admitidos y `phone_prefix`. Vacío significa que no pide nada. ## 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í | Métodos de cobro disponibles para la empresa. | | `data[].available` | booleano | Sí | true si se puede usar ahora. | | `data[].country` | texto o `null` | Sí | País del método. | | `data[].currency` | texto o `null` | Sí | Moneda del método. | | `data[].max_amount` | texto o `null` | Sí | Monto máximo. | | `data[].method` | texto o `null` | Sí | Nombre a usar en `method`. | | `data[].min_amount` | texto o `null` | Sí | Monto mínimo. | | `data[].payer_fields` | lista de objeto | Sí | Lo que el método pide en `payer` al crear el cobro. | | `data[].payer_fields[].name` | texto | Sí | Clave dentro de `payer`. `firstName`: Nombre, o razón social. `lastName`: Apellido. `email`: Correo. `phone`: Teléfono con su prefijo internacional. `documentType`: Tipo de documento. `documentNumber`: Número de documento. | | `data[].payer_fields[].options` | lista de texto o `null` | Sí | Valores admitidos. null si es texto libre. | | `data[].payer_fields[].phone_prefix` | texto o `null` | Sí | Prefijo del país, como `+57`. null si no aplica. | | `data[].payer_fields[].required` | booleano | Sí | true si el cobro se rechaza sin este dato. | #### Valores de `data[].payer_fields[].name` | Valor | Significado | |---|---| | `firstName` | Nombre, o razón social. | | `lastName` | Apellido. | | `email` | Correo. | | `phone` | Teléfono con su prefijo internacional. | | `documentType` | Tipo de documento. | | `documentNumber` | Número de documento. | El contrato lo declara como texto: trata la lista como extensible. ```json { "data": [ { "available": true, "country": "MX", "currency": "MXN", "max_amount": "50000.00", "method": "spei", "min_amount": "10.00", "payer_fields": [ { "name": "firstName", "options": null, "phone_prefix": null, "required": true }, { "name": "email", "options": null, "phone_prefix": null, "required": true }, { "name": "documentType", "options": [ "RFC", "CURP" ], "phone_prefix": null, "required": false }, { "name": "phone", "options": null, "phone_prefix": "+52", "required": false } ] } ] } ``` ## 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 | [`forbidden_scope`](/docs/errores/#forbidden_scope) | La llave no tiene el scope de esta operación. `details.required_scope` lo nombra. | `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 forbidden_scope`: ```json { "error": { "code": "forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0123456789abcdef0123456789abcdef", "details": { "required_scope": "collections:read" }, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope" } } ``` `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/collection-methods" \ -H "Authorization: Bearer $FITAL_KEY" ``` ```js const r = await fetch(`${process.env.FITAL_API}/collection-methods`, { 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"] + "/collection-methods", 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 - [Cobros](/docs/recetas/cobros/) - [Cobertura](/docs/cobertura/) - [Autenticación](/docs/autenticacion/) - [Lista de migración](/docs/migracion/) - [Paginación](/docs/paginacion/)