Nombre

Listar países

Catálogo completo de países con código ISO, código telefónico y MCC.

Método HTTP y ruta

GET/api/v6/tools/countries

https://developers.hablame.co/api/v6/tools/countries

Qué pasa al ejecutarlo

Solo consulta: no cambia datos de tu organización.
La llamada no se cobra.

Qué hace

Devuelve el catálogo completo de países que la API conoce, con su código ISO, código telefónico, MCC móvil y nombres en inglés y español. Úsalo para renderizar selectores de país, autodetectar el país a partir de un prefijo o resolver MCCs.

El catálogo cambia raras veces. La respuesta incluye Cache-Control: public, max-age=3600 para que tu cliente y cualquier CDN intermedio amortigüen el tráfico.

Idiomas

Los nombres se ofrecen solo en inglés (en) y español (es). Cualquier otro valor de lang cae a inglés.

Disponibilidad y requisitos previos

Publicado y disponible en la API v6 de producción.
Todas las rutas parten de https://developers.hablame.co.
Necesitas una API key de Hablame para llamarlo.

Crea tu clave de API

Autenticación y permisos

Envía tu API key en la cabecera Authorization con el esquema Bearer.

Quién puede llamarlo: Cualquier API key válida.

Límites y consideraciones operativas

Límite de uso: 60 solicitudes por minuto.

Parámetros de ruta

Este endpoint no tiene parámetros de ruta.

Parámetros de consulta

Nombre Tipo Descripción y reglas

Nombre	Tipo	Descripción y reglas
`lang`Opcional	`string`	Código ISO-639-1. Cuando se especifica, cada país devuelve `name` plano en ese idioma en vez del mapa completo `names`. Valores permitidos:`en` `es`Ejemplo:`es`
`callingCode`Opcional	`string`	Filtra países por código telefónico E.164 (por ejemplo `57` para Colombia). Acepta un `+` inicial opcional. Ejemplo:`57`
`search`Opcional	`string`	Búsqueda por subcadena, sin distinguir mayúsculas, sobre el nombre del país en el idioma solicitado. Mínimo 2 caracteres. Largo mínimo:`2`Ejemplo:`col`

langOpcional

string

Código ISO-639-1. Cuando se especifica, cada país devuelve name plano en ese idioma en vez del mapa completo names.

Valores permitidos:en esEjemplo:es

callingCodeOpcional

string

Filtra países por código telefónico E.164 (por ejemplo 57 para Colombia). Acepta un + inicial opcional.

Ejemplo:57

searchOpcional

string

Búsqueda por subcadena, sin distinguir mayúsculas, sobre el nombre del país en el idioma solicitado. Mínimo 2 caracteres.

Largo mínimo:2Ejemplo:col

Encabezados HTTP

Nombre Tipo Descripción y reglas

Nombre	Tipo	Descripción y reglas
`Authorization`Obligatorio	`string`	Tu API key con el esquema Bearer. Ejemplo:`Bearer hk_TU_API_KEY`

AuthorizationObligatorio

string

Tu API key con el esquema Bearer.

Ejemplo:Bearer hk_TU_API_KEY

Cuerpo de la petición

Este endpoint no recibe cuerpo en la petición.

Respuestas satisfactorias

200

Catálogo de países.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "code": "CO",
      "code3": "COL",
      "callingCode": "57",
      "mcc": "732",
      "flag": "https://flagcdn.com/co.svg",
      "names": { "en": "Colombia", "es": "Colombia" }
    },
    {
      "code": "MX",
      "code3": "MEX",
      "callingCode": "52",
      "mcc": "334",
      "flag": "https://flagcdn.com/mx.svg",
      "names": { "en": "Mexico", "es": "México" }
    }
  ],
  "meta": {
    "requestId": "b9b1704baffab211",
    "clientIp": "203.0.113.45",
    "timestamp": "2026-05-23T02:00:00+00:00",
    "responseTimeMs": 4.12
  }
}

Los valores del ejemplo son ilustrativos.

Campos de la respuesta

Nombre	Tipo	Descripción y reglas
`success`Siempre presente	`boolean`
`data`Siempre presente	`array<object>`
`data[].code`Siempre presente	`string`	ISO 3166-1 alpha-2 (2 letras MAYÚSCULA). Ejemplo:`CO`
`data[].code3`Siempre presente	`string`	ISO 3166-1 alpha-3. Ejemplo:`COL`
`data[].callingCode`Siempre presente	`string`	Indicativo E.164, sin `+`. Es string para no perder los ceros a la izquierda. Ejemplo:`57`
`data[].mcc`Siempre presente	`string`	Mobile Country Code (E.212). Ejemplo:`732`
`data[].flag`Siempre presente	`string`	URL de la bandera (SVG). Formato:`uri`
`data[].names`	`object`	Nombre del país por idioma (`en`, `es`). Presente solo cuando NO se envía `?lang`; un idioma sin nombre cargado no aparece.
`data[].names.{cualquier clave}`	`string`
`data[].name`	`string`	Nombre del país en el `lang` pedido. Presente solo cuando se envía `?lang`.
`meta`Siempre presente	`object`	Metadatos de la respuesta.
`meta.requestId`Siempre presente	`string`	Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera `X-Request-Id`. Cítalo al contactar soporte. Ejemplo:`b9b1704baffab211`
`meta.clientIp`Siempre presente	`string`	IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo:`203.0.113.45`
`meta.timestamp`Siempre presente	`string`	Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato:`date-time`Ejemplo:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Siempre presente	`number`	Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo:`4.24`

Códigos de error

Todas las respuestas de error tienen la misma forma: success en false y un objeto error cuyo code dice qué pasó. Aquí están agrupadas por tipo, con los códigos que este endpoint puede devolver.

Forma de una respuesta de error

Nombre	Tipo	Descripción y reglas
`success`Siempre presente	`boolean`	Valor fijo:`false`
`meta`Siempre presente	`object`	Metadatos de la respuesta.
`meta.requestId`Siempre presente	`string`	Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera `X-Request-Id`. Cítalo al contactar soporte. Ejemplo:`b9b1704baffab211`
`meta.clientIp`Siempre presente	`string`	IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo:`203.0.113.45`
`meta.timestamp`Siempre presente	`string`	Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato:`date-time`Ejemplo:`2026-06-04T19:43:59+00:00`
`meta.responseTimeMs`Siempre presente	`number`	Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo:`4.24`
`error`Siempre presente	`object`
`error.code`Siempre presente	`string`	Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor. Ejemplo:`AUTH_REQUIRED`
`error.legacyCode`	`integer`	Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6. Ejemplo:`40002`
`error.type`Siempre presente	`string`	URL a la documentación del error. Formato:`uri`Ejemplo:`https://developers.hablame.co/docs/v6/errors/auth-required`
`error.message`Siempre presente	`string`	Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees.
`error.details`Siempre presente	`array<object>`	Contexto estructurado (validaciones, recurso afectado). Arreglo vacío cuando no hay contexto extra.

Validación

Este endpoint no declara respuestas de este tipo.

Autenticación

401Credenciales inválidas o faltantes.

401AUTH_REQUIRED
No se envió un token Bearer y cada llamada lo requiere.
Mensaje que devuelve la API: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
401AUTH_INVALID_KEY
La clave de API no se reconoce: formato equivocado, revocada o vencida.
Mensaje que devuelve la API: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.

Permisos

403AUTH_IP_NOT_ALLOWED
La clave solo funciona desde ciertas redes y tu IP no está entre ellas.
Mensaje que devuelve la API: This API key cannot be used from this IP address. The address we saw is in `meta.clientIp`: call from one of the networks allowed for the key, or use a key that allows this one.
403ACCOUNT_NOT_ACTIVE
Tu organización está suspendida o cerrada.
Mensaje que devuelve la API: The organization associated with this API key is not active. Please contact support.

Límites de uso

429Se excedió el límite de solicitudes.

429RATE_TPS_EXCEEDED
Excediste el cupo de tu organización para este endpoint.
Mensaje que devuelve la API: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.
429RATE_DDOS_EXCEEDED
Volumen inusualmente alto desde tu IP de origen.
Mensaje que devuelve la API: Too many requests from this IP within a short window. Please wait before retrying.

Recurso inexistente

Este endpoint no declara respuestas de este tipo.

Errores internos y disponibilidad

503Servicio temporalmente no disponible.

503SERVICE_UNAVAILABLE
503 genérico: un servicio del que dependemos no responde.

Otras respuestas

Este endpoint no declara respuestas de este tipo.

Ver en el catálogo de errores

Consideraciones especiales

Este endpoint no tiene consideraciones especiales.

Documentación relacionada

Guías

Otros endpoints de Herramientas

Obtener un país

Endpoints

Listar países

Método HTTP y ruta

Qué hace

Idiomas

Disponibilidad y requisitos previos

Autenticación y permisos

Límites y consideraciones operativas

Parámetros de ruta

Parámetros de consulta

Encabezados HTTP

Cuerpo de la petición

Respuestas satisfactorias

200

Campos de la respuesta

Códigos de error

Validación

Autenticación

Permisos

Límites de uso

Recurso inexistente

Errores internos y disponibilidad

Otras respuestas

Consideraciones especiales

Documentación relacionada

Guías

Otros endpoints de Herramientas

¿Necesitas ayuda?

Pide ayuda sobre esto: este endpoint