# Países del riel `latam`

GET /v1/latam/countries

Países a los que tu empresa puede pagar por el riel `latam`, con su moneda y lo que cada uno pide para dar de alta una cuenta. Sale de la configuración vigente: consúltalo en vez de copiarlo.

| Dato | Valor |
|---|---|
| Método y ruta | `GET /v1/latam/countries` |
| Servidor | `https://widget.fital.xyz` |
| `operationId` | `listLatamCountries` |
| Acceso | Llave con el scope `beneficiaries:read` |
| Firma de petición | No aplica |
| Idempotencia | No aplica |

- Sale de la configuración vigente y sólo trae los países que tu empresa puede pagar: consúltalo antes de un alta, en vez de copiar la tabla de [Cobertura](/docs/cobertura/#países-del-riel-latam).
- `available: false` significa que el país está restringido por ahora: el alta y los pagos pueden fallar.
- `account` dice qué pide el alta: `entity_required`, `account_type_required` con sus valores en `account_types`, y el largo del número. Un largo que no aplica llega en `null`.
- En la cuenta de prueba los países son ficticios y todos llegan con `available: false`: ese ambiente sólo simula SPEI, así que el alta `latam` no procede.

## 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í | Países del riel `latam` para tu empresa. |
| `data[].account` | objeto | Sí | Qué se pide de la cuenta. |
| `data[].account.account_type_required` | booleano | Sí | true si el alta exige `account_type`. |
| `data[].account.account_types` | lista de texto | Sí | Valores admitidos en `account_type`. |
| `data[].account.digits_only` | booleano | Sí | true si sólo admite dígitos. |
| `data[].account.entity_required` | booleano | Sí | true si el alta exige `entity`. |
| `data[].account.exact_length` | entero o `null` | Sí | Largo exacto. null si no aplica. |
| `data[].account.label` | texto o `null` | Sí | Cómo se llama el número de cuenta en ese país. |
| `data[].account.max_length` | entero o `null` | Sí | Largo máximo. null si no aplica. |
| `data[].account.min_length` | entero o `null` | Sí | Largo mínimo. null si no aplica. |
| `data[].available` | booleano | Sí | false mientras el país esté restringido: el alta y los pagos pueden fallar. |
| `data[].country` | texto | Sí | País, en código de 2 letras. Es el `country` del alta. |
| `data[].currency` | texto | Sí | Moneda de la cuenta. Es el `currency` del alta. |
| `data[].document_types` | lista de texto | Sí | Valores admitidos en `document_type`. |

#### Valores de `data[].account.account_types`

| Valor | Significado |
|---|---|
| `checking` | Cuenta de cheques o corriente. |
| `savings` | Cuenta de ahorro. |

Lista vacía si el país no usa tipo de cuenta.

```json
{
  "data": [
    {
      "account": {
        "account_type_required": false,
        "account_types": [
          "checking",
          "savings"
        ],
        "digits_only": true,
        "entity_required": true,
        "exact_length": null,
        "label": "Número de cuenta",
        "max_length": 20,
        "min_length": 5
      },
      "available": true,
      "country": "CL",
      "currency": "CLP",
      "document_types": [
        "RUT",
        "PP"
      ]
    }
  ]
}
```

## 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 | [`rail_not_enabled`](/docs/errores/#rail_not_enabled) | El riel `latam` no está habilitado para tu empresa. | `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 rail_not_enabled`:

```json
{
  "error": {
    "code": "rail_not_enabled",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_not_enabled"
  }
}
```

`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/latam/countries" \
  -H "Authorization: Bearer $FITAL_KEY"
```

```js
const r = await fetch(`${process.env.FITAL_API}/latam/countries`, {
  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"] + "/latam/countries", 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
<?php
$c = curl_init(getenv('FITAL_API') . '/latam/countries');
curl_setopt_array($c, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('FITAL_KEY'),
  ],
]);
echo curl_exec($c), "\n";
```

## Guías

- [Pago LatAm](/docs/recetas/pago-latam/)
- [Cobertura](/docs/cobertura/)
- [Autenticación](/docs/autenticacion/)
- [Lista de migración](/docs/migracion/)
- [Cuenta de prueba](/docs/sandbox/cuenta-de-prueba/)