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.
Cómo se envía
Section titled “Cómo se envía”En cada petición, en el encabezado x-api-key:
curl -H "x-api-key: TU_LLAVE" https://colonix.silgaru.mx/v1/postal-codes/06700La 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).
Tipos de llave
Section titled “Tipos de llave”| 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).
La llave de prueba
Section titled “La llave de prueba”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.
Cómo cuidarla
Section titled “Cómo cuidarla”- 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-keyen los logs de tu aplicación ni de tu proxy.
Si tu llave se filtró
Section titled “Si tu llave se filtró”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.
Errores de autenticación
Section titled “Errores de autenticación”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:
{ "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.
© 2026 Silgaru