Países del riel `latam`

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.
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.

{
  "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: 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	`rail_not_enabled`	El riel `latam` no está habilitado para tu empresa.	`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 rail_not_enabled:

{
  "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:

{
  "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 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 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.

op-listar-paises-latam.sh

curl -sS "$FITAL_API/latam/countries" \
  -H "Authorization: Bearer $FITAL_KEY"

Guías

Ver esta página en Markdown

Países del riel `latam`

Encabezados de la peticiónCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar enlace

Valores de data[].account.account_typesCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página