{
  "openapi": "3.1.0",
  "info": {
    "title": "API Gratis de Codigos Postales de Mexico",
    "version": "1.1.0",
    "description": "API publica de solo lectura para consultar codigos postales de Mexico con respuestas estandarizadas en espanol claro. Los nombres de los campos usan snake_case, sin abreviaturas, y separan datos descriptivos de claves operativas de SEPOMEX. Arquitectura: Go + SQLite de solo lectura + indice FTS + rate limit por IP de 5 req/s con burst de 20."
  },
  "servers": [
    {
      "url": "https://cp.terio.dev",
      "description": "Servidor publico actual"
    }
  ],
  "tags": [
    {
      "name": "Estado del servicio",
      "description": "Verificaciones operativas del servicio."
    },
    {
      "name": "Codigos postales",
      "description": "Consulta directa por codigo postal."
    },
    {
      "name": "Busqueda",
      "description": "Busqueda libre por colonia, municipio, ciudad o estado."
    },
    {
      "name": "Catalogos",
      "description": "Catalogos de estados, municipios, ciudades y codigos postales."
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "tags": ["Estado del servicio"],
        "summary": "Validar vida del servicio",
        "responses": {
          "200": {
            "description": "Servicio arriba.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstadoServicio"
                }
              }
            }
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "tags": ["Estado del servicio"],
        "summary": "Validar disponibilidad",
        "responses": {
          "200": {
            "description": "Servicio y base listos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstadoServicio"
                }
              }
            }
          }
        }
      }
    },
    "/v1/codigos-postales/{d_codigo}": {
      "get": {
        "tags": ["Codigos postales"],
        "summary": "Consultar un codigo postal",
        "description": "Devuelve todos los asentamientos asociados a un codigo postal con campos claros y consistentes.",
        "parameters": [
          {
            "name": "d_codigo",
            "in": "path",
            "required": true,
            "description": "Codigo postal de 5 digitos.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{5}$"
            },
            "example": "20000"
          }
        ],
        "responses": {
          "200": {
            "description": "Consulta correcta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRegistrosPostales"
                },
                "example": {
                  "datos": [
                    {
                      "codigo_postal": "20000",
                      "asentamiento": "Aguascalientes Centro",
                      "tipo_asentamiento": "Colonia",
                      "municipio": "Aguascalientes",
                      "estado": "Aguascalientes",
                      "ciudad": "Aguascalientes",
                      "codigo_postal_administracion": "20001",
                      "codigo_estado": "01",
                      "codigo_oficina_postal": "20001",
                      "codigo_postal_origen": "",
                      "codigo_tipo_asentamiento": "09",
                      "codigo_municipio": "001",
                      "clave_asentamiento": "0001",
                      "zona_postal": "Urbano",
                      "codigo_ciudad": "01"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No se encontro el codigo postal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRespuesta"
                }
              }
            }
          },
          "429": {
            "description": "Se excedio el limite de peticiones.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRespuesta"
                }
              }
            }
          }
        }
      }
    },
    "/v1/buscar": {
      "get": {
        "tags": ["Busqueda"],
        "summary": "Buscar por texto",
        "description": "Busca por colonia, municipio, ciudad o estado y devuelve resultados con el mismo formato estandarizado. Este endpoint esta sujeto a rate limit por IP de 5 req/s con burst de 20.",
        "parameters": [
          {
            "name": "texto",
            "in": "query",
            "required": true,
            "description": "Texto libre para buscar.",
            "schema": {
              "type": "string"
            },
            "example": "aguascalientes"
          },
          {
            "name": "limite",
            "in": "query",
            "description": "Maximo de resultados.",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            },
            "example": 3
          }
        ],
        "responses": {
          "200": {
            "description": "Resultados encontrados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRegistrosPostales"
                }
              }
            }
          },
          "400": {
            "description": "Falta el parametro texto.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRespuesta"
                }
              }
            }
          },
          "429": {
            "description": "Se excedio el limite de peticiones.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorRespuesta"
                }
              }
            }
          }
        }
      }
    },
    "/v1/estados": {
      "get": {
        "tags": ["Catalogos"],
        "summary": "Listar estados",
        "responses": {
          "200": {
            "description": "Catalogo de estados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaEstados"
                }
              }
            }
          }
        }
      }
    },
    "/v1/estados/{c_estado}/municipios": {
      "get": {
        "tags": ["Catalogos"],
        "summary": "Listar municipios por estado",
        "parameters": [
          {
            "name": "c_estado",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01"
          }
        ],
        "responses": {
          "200": {
            "description": "Municipios del estado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaMunicipios"
                }
              }
            }
          }
        }
      }
    },
    "/v1/estados/{c_estado}/ciudades": {
      "get": {
        "tags": ["Catalogos"],
        "summary": "Listar ciudades por estado",
        "parameters": [
          {
            "name": "c_estado",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01"
          }
        ],
        "responses": {
          "200": {
            "description": "Ciudades del estado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaCiudades"
                }
              }
            }
          }
        }
      }
    },
    "/v1/estados/{c_estado}/municipios/{c_mnpio}/codigos-postales": {
      "get": {
        "tags": ["Catalogos"],
        "summary": "Listar codigos postales por municipio",
        "parameters": [
          {
            "name": "c_estado",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01"
          },
          {
            "name": "c_mnpio",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "001"
          },
          {
            "name": "limite",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "desplazamiento",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Codigos postales del municipio.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaCodigosPostales"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EstadoServicio": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          }
        },
        "required": ["status"]
      },
      "ErrorRespuesta": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "codigo": {
                "type": "integer",
                "example": 404
              },
              "mensaje": {
                "type": "string",
                "example": "d_codigo no encontrado"
              }
            },
            "required": ["codigo", "mensaje"]
          }
        },
        "required": ["error"]
      },
      "RegistroPostal": {
        "type": "object",
        "properties": {
          "codigo_postal": { "type": "string", "example": "20000" },
          "asentamiento": { "type": "string", "example": "Aguascalientes Centro" },
          "tipo_asentamiento": { "type": "string", "example": "Colonia" },
          "municipio": { "type": "string", "example": "Aguascalientes" },
          "estado": { "type": "string", "example": "Aguascalientes" },
          "ciudad": { "type": "string", "example": "Aguascalientes" },
          "codigo_postal_administracion": { "type": "string", "example": "20001" },
          "codigo_estado": { "type": "string", "example": "01" },
          "codigo_oficina_postal": { "type": "string", "example": "20001" },
          "codigo_postal_origen": { "type": "string", "example": "" },
          "codigo_tipo_asentamiento": { "type": "string", "example": "09" },
          "codigo_municipio": { "type": "string", "example": "001" },
          "clave_asentamiento": { "type": "string", "example": "0001" },
          "zona_postal": { "type": "string", "example": "Urbano" },
          "codigo_ciudad": { "type": "string", "example": "01" }
        },
        "required": [
          "codigo_postal",
          "asentamiento",
          "tipo_asentamiento",
          "municipio",
          "estado",
          "codigo_postal_administracion",
          "codigo_estado",
          "codigo_oficina_postal",
          "codigo_postal_origen",
          "codigo_tipo_asentamiento",
          "codigo_municipio",
          "clave_asentamiento",
          "zona_postal"
        ]
      },
      "Estado": {
        "type": "object",
        "properties": {
          "codigo_estado": { "type": "string", "example": "01" },
          "estado": { "type": "string", "example": "Aguascalientes" }
        },
        "required": ["codigo_estado", "estado"]
      },
      "Municipio": {
        "type": "object",
        "properties": {
          "codigo_estado": { "type": "string", "example": "01" },
          "codigo_municipio": { "type": "string", "example": "001" },
          "municipio": { "type": "string", "example": "Aguascalientes" }
        },
        "required": ["codigo_estado", "codigo_municipio", "municipio"]
      },
      "Ciudad": {
        "type": "object",
        "properties": {
          "codigo_estado": { "type": "string", "example": "01" },
          "codigo_ciudad": { "type": "string", "example": "01" },
          "ciudad": { "type": "string", "example": "Aguascalientes" }
        },
        "required": ["codigo_estado", "codigo_ciudad", "ciudad"]
      },
      "CodigoPostal": {
        "type": "object",
        "properties": {
          "codigo_postal": { "type": "string", "example": "20000" }
        },
        "required": ["codigo_postal"]
      },
      "RespuestaRegistrosPostales": {
        "type": "object",
        "properties": {
          "datos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RegistroPostal"
            }
          }
        },
        "required": ["datos"]
      },
      "RespuestaEstados": {
        "type": "object",
        "properties": {
          "datos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Estado"
            }
          }
        },
        "required": ["datos"]
      },
      "RespuestaMunicipios": {
        "type": "object",
        "properties": {
          "datos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Municipio"
            }
          }
        },
        "required": ["datos"]
      },
      "RespuestaCiudades": {
        "type": "object",
        "properties": {
          "datos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ciudad"
            }
          }
        },
        "required": ["datos"]
      },
      "RespuestaCodigosPostales": {
        "type": "object",
        "properties": {
          "datos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CodigoPostal"
            }
          }
        },
        "required": ["datos"]
      }
    }
  }
}