Laravel v1.0.0
Servicio disponible · sin autenticación

Catálogos de El Salvador, listos para consumir

API REST de catálogos, unidades de medida, tributos y división territorial de El Salvador. Todos los endpoints responden JSON, no requieren autenticación y están pensados para consumirse desde cualquier sistema (facturación, comercio electrónico, ERP, dashboards).

GET https://catalogs.botblaze.tech/api/v1
Ver endpoints
Endpoints
4

documentados

Catálogos
34

CAT-001 … CAT-032

Valores
1,352

opciones activas

Departamentos
15

nivel 1

Municipios
45

nivel 2

Endpoints

Todos los endpoints aceptan peticiones GET y devuelven application/json.

4 endpoints
GET /api/v1/catalog

Listar catálogos

Devuelve la lista de catálogos disponibles con su código y descripción. Es el punto de partida para descubrir los recursos que se pueden consultar.

Respuesta de ejemplo

200 OK
[
    {
        "id": 1,
        "catalog": "CAT-001",
        "description": "Ambiente de Destino"
    },
    {
        "id": 2,
        "catalog": "CAT-002",
        "description": "Tipo de Documento"
    },
    {
        "id": 3,
        "catalog": "CAT-003",
        "description": "Modelo de Facturación"
    }
]
GET /api/v1/catalog/{catalog}

Consultar catálogo

Devuelve un catálogo con todos sus valores. Acepta el código del catálogo (por ejemplo CAT-014) o los valores especiales documentados en la tabla de alias.

Parámetros

Nombre En Tipo Descripción
catalog req path string Código del catálogo (CAT-XXX), el alias "all" o un catálogo geográfico (CAT-008, CAT-012, CAT-013).

Respuesta de ejemplo

200 OK
{
    "id": 1,
    "catalog": "CAT-001",
    "description": "Ambiente de Destino",
    "created_at": "2024-10-22T15:12:17.000000Z",
    "updated_at": "2024-10-22T15:12:17.000000Z",
    "values": [
        {
            "id": 1,
            "catalog_id": 1,
            "code": "00",
            "value": "Modo Prueba",
            "created_at": "2024-10-22T15:12:17.000000Z",
            "updated_at": "2024-10-22T15:12:17.000000Z"
        },
        {
            "id": 2,
            "catalog_id": 1,
            "code": "01",
            "value": "Modo Producción",
            "created_at": "2024-10-22T15:12:17.000000Z",
            "updated_at": "2024-10-22T15:12:17.000000Z"
        }
    ]
}
GET /api/v1/departamentos

Listar departamentos

Devuelve los 14 departamentos del país con sus municipios y distritos anidados, listos para alimentar selectores de dirección en cascada.

Respuesta de ejemplo

200 OK
[
    {
        "id": 12,
        "codigo": "11",
        "nombre": "Usulután",
        "created_at": "2024-10-22T15:12:17.000000Z",
        "updated_at": "2024-10-22T15:12:17.000000Z",
        "municipios": [
            {
                "id": 36,
                "codigo": "24",
                "nombre": "USULUTAN NORTE",
                "departamento_id": 12,
                "created_at": "2024-10-22T15:12:17.000000Z",
                "updated_at": "2024-10-22T15:12:17.000000Z",
                "distritos": [
                    {
                        "id": 177,
                        "nombre": "Santiago de María",
                        "municipio_id": 36,
                        "created_at": "2024-10-22T15:12:17.000000Z",
                        "updated_at": "2024-10-22T15:12:17.000000Z"
                    }
                ]
            }
        ]
    }
]
GET /api/v1/departamentos/{department}

Consultar departamento

Devuelve un departamento con sus municipios y distritos. Se puede consultar por código (por ejemplo 11) o por nombre.

Parámetros

Nombre En Tipo Descripción
department req path string Código o nombre del departamento a consultar.

Respuesta de ejemplo

200 OK
{
    "id": 12,
    "codigo": "11",
    "nombre": "Usulután",
    "created_at": "2024-10-22T15:12:17.000000Z",
    "updated_at": "2024-10-22T15:12:17.000000Z",
    "municipios": [
        {
            "id": 36,
            "codigo": "24",
            "nombre": "USULUTAN NORTE",
            "departamento_id": 12,
            "created_at": "2024-10-22T15:12:17.000000Z",
            "updated_at": "2024-10-22T15:12:17.000000Z",
            "distritos": [
                {
                    "id": 177,
                    "nombre": "Santiago de María",
                    "municipio_id": 36,
                    "created_at": "2024-10-22T15:12:17.000000Z",
                    "updated_at": "2024-10-22T15:12:17.000000Z"
                }
            ]
        }
    ]
}

Valores especiales

El endpoint /catalog/{catalog} además de los códigos CAT-XXX acepta los siguientes alias.

Valor Endpoint Qué devuelve
all /api/v1/catalog/all Devuelve todos los catálogos con sus valores en una sola respuesta.
CAT-008 /api/v1/catalog/CAT-008 División territorial de tercer nivel: distritos con su municipio y departamento.
CAT-012 /api/v1/catalog/CAT-012 División territorial de primer nivel: departamentos con municipios y distritos.
CAT-013 /api/v1/catalog/CAT-013 División territorial de segundo nivel: municipios con sus distritos.

Catálogos disponibles

34 catálogos con 1,352 valores. Cada tarjeta enlaza directo a su endpoint.

División territorial

Estructura territorial completa del país, disponible tanto por su endpoint dedicado como a través de los catálogos geográficos.

Departamentos

15 registros

/catalog/CAT-012

Municipios

45 registros

/catalog/CAT-013

Distritos

263 registros

/catalog/CAT-008

Ejemplos de uso

Copia y pega el snippet que prefieras para empezar a consumir la API.

curl -X GET "https://catalogs.botblaze.tech/api/v1/catalog/CAT-014" \
  -H "Accept: application/json"
const response = await fetch('https://catalogs.botblaze.tech/api/v1/catalog/CAT-014')

if (!response.ok) {
    throw new Error('Error ' + response.status)
}

const catalog = await response.json()
console.log(catalog.values)
$curl = curl_init('https://catalogs.botblaze.tech/api/v1/catalog/CAT-014');

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Accept: application/json']);

$catalog = json_decode(curl_exec($curl), true);

curl_close($curl);

Códigos de respuesta

La API responde siempre con JSON, incluso en los errores.

Código Descripción
200 La solicitud se procesó correctamente.
404 El catálogo o departamento solicitado no existe.
500 Error interno del servidor. Intenta de nuevo más tarde.

Ejemplo de error

{
    "message": "Catalog not found"
}