Ir al contenido

Llaves

Tu llave es la contraseña de tu aplicación: le dice a Colonix quién hace la consulta, qué plan tiene y a qué cuenta se suma el consumo. Hay dos tipos: la normal, para tu aplicación, y la de prueba, para desarrollar sin gastar consultas.

En cada petición, en el encabezado x-api-key:

curl -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/postal-codes/06700

La llave solo se acepta en ese encabezado. Si la mandas en la URL (?key=…), en Authorization o en cualquier otro encabezado, la API responde como si no la hubieras enviado: 401 con /errors/missing-api-key.

Una llave recién creada tarda unos segundos en empezar a funcionar; mientras tanto responde 401 con /errors/invalid-api-key. En Windows PowerShell escribe curl.exe en lugar de curl (ahí curl es otro comando).

Tipo Empieza con Para qué Qué puede consultar ¿Cuenta para tu cuota?
Normal clx_ Tu aplicación en producción Todo lo que incluye tu plan Sí
De prueba clx_test_ Desarrollo, pruebas automáticas e integración continua Los 5 códigos postales de demostración y los catálogos No

Las dos se crean en tu cuenta de Colonix y se mandan igual. Tu código no necesita distinguirlas: cambia la llave según el ambiente (por ejemplo, una variable de entorno distinta en desarrollo y en producción).

Sirve para escribir y probar tu integración sin gastar consultas: las respuestas son datos reales y completos, solo que limitados a cinco códigos postales.

Código postal Municipio Asentamientos
06700 Cuauhtémoc, Ciudad de México 1: Roma Norte
44100 Guadalajara, Jalisco 1: Guadalajara Centro
64000 Monterrey, Nuevo León 2: La Finca y Monterrey Centro
22000 Tijuana, Baja California 3: Zona Centro, Zona Este y Zona Norte
77500 Benito Juárez (Cancún), Quintana Roo 16, entre ellos Cancún Centro y Zona Hotelera

Entre los cinco tienes un código con una sola colonia y otros con varias, uno de la región fronteriza norte (22000) y tres husos horarios distintos: Centro, Noroeste y Sureste.

Con ella puedes pedir la consulta de esos códigos postales con todos sus datos (include=sat, include=location, include=metro), sus claves del SAT (/v1/sat/postal-codes/{code}), su historial y los catálogos de estados, municipios y tipos de asentamiento. Cualquier otra consulta responde 403 con /errors/plan-not-allowed. Tiene un límite de peticiones por minuto, pero no consume cuota.

  • Solo en tu servidor. Léela de una variable de entorno o del gestor de secretos de tu plataforma. No la pongas en el código fuente ni en el repositorio.
  • Nunca en el navegador ni en una app móvil. Todo lo que viaja al dispositivo del usuario se puede leer. Si tu formulario necesita autocompletar, haz la consulta desde tu servidor.
  • Fuera de tus registros. No guardes el encabezado x-api-key en los logs de tu aplicación ni de tu proxy.

Revócala en tu cuenta y crea una nueva. Para no cortar el servicio, crea primero la nueva, cámbiala en tu aplicación y después revoca la anterior. Una llave revocada deja de funcionar en unos segundos y responde 401 con /errors/invalid-api-key.

Todos llegan como application/problem+json con Cache-Control: no-store. Decide con el campo type.

Estado type Qué pasó Qué hacer
401 /errors/missing-api-key La petición no trae x-api-key Agrega el encabezado
401 /errors/invalid-api-key La llave no existe o fue revocada Revisa que esté completa, sin espacios; si la acabas de crear, espera unos segundos; si la revocaste, usa la nueva
403 /errors/api-key-suspended La llave está suspendida Escríbenos desde tu cuenta
403 /errors/plan-not-allowed Tu plan (o tu llave de prueba) no incluye esa consulta Revisa los planes

Por ejemplo, con una llave que no existe:

401 Unauthorized
{
"type": "/errors/invalid-api-key",
"title": "Invalid API key",
"status": 401,
"detail": "The key does not exist or was revoked."
}

Ninguno de estos errores cuenta para tu cuota.