{"openapi":"3.1.0","info":{"title":"Direcciones AR API","version":"0.1.0","description":"Normalización y geocodificación de direcciones argentinas con el callejero oficial (georef, INDEC/IGN) para agentes de IA. Cobro por créditos prepagos. También disponible como servidor MCP remoto en /mcp."},"servers":[{"url":"https://direcciones-ar-api-103907796853.us-east1.run.app"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key con prefijo ak_"}}},"security":[{"apiKey":[]}],"paths":{"/v1/keys":{"post":{"operationId":"crearKeyDePrueba","summary":"Crear una API key de prueba con 50 créditos (sin registro)","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Key creada. El campo `key` se muestra una sola vez.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"key_id":{"type":"string"},"credits":{"type":"integer"}}}}}},"429":{"description":"Demasiadas keys creadas desde esta IP","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/balance":{"get":{"operationId":"consultarSaldo","summary":"Saldo de créditos y últimos movimientos de la key","responses":{"200":{"description":"Saldo","content":{"application/json":{"schema":{"type":"object","properties":{"key_id":{"type":"string"},"credits":{"type":"integer"},"recent":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/packs":{"get":{"operationId":"listarPacks","summary":"Packs de créditos a la venta (producto, créditos, precio)","security":[],"responses":{"200":{"description":"Packs","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/checkout":{"post":{"operationId":"crearCheckout","summary":"Crea un checkout de Polar para recargar la key autenticada y devuelve checkout_url para mostrar al usuario","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer","description":"Cantidad deseada; se elige el pack más chico que la cubre"},"product_id":{"type":"string","description":"Pack puntual, de /v1/packs"},"email":{"type":"string","description":"Email del comprador, para precargar el checkout"}}}}}},"responses":{"201":{"description":"Checkout creado","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string"},"expires_at":{"type":"string"},"pack":{"type":"object"}}}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"503":{"description":"Compra no habilitada","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/tools":{"get":{"operationId":"listarTools","summary":"Lista las tools disponibles con su costo en créditos","security":[],"responses":{"200":{"description":"Tools","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/tools/normalizar_direccion":{"post":{"operationId":"normalizar_direccion","summary":"Normalizar y geocodificar una dirección argentina","description":"Interpreta una dirección escrita a mano ('Av. Corrientes 1234, CABA', 'corrientes y callao', 'San Martín 450 piso 3 Rosario'), la normaliza según el callejero oficial (INDEC/IGN vía georef) y devuelve candidatos con calle, altura, localidad, departamento, provincia y coordenadas lat/lon. Pasá provincia o localidad si las conocés: reduce ambigüedad. Si `cantidad` es 0 la dirección no existe en el callejero oficial; si hay varios candidatos, elegí por localidad o pedí precisión al usuario.\n\nCosto: 2 crédito(s) por llamada exitosa.","x-credits-cost":2,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"direccion":{"type":"string","minLength":3,"maxLength":200,"description":"Dirección en texto libre: 'calle altura' o 'calle y calle', opcionalmente con piso/depto"},"provincia":{"description":"Nombre o id de provincia ('Buenos Aires', 'CABA', 'Córdoba', '02')","type":"string","maxLength":60},"departamento":{"description":"Partido, departamento o comuna ('Tigre', 'Comuna 1')","type":"string","maxLength":60},"localidad":{"description":"Localidad censal ('Rosario', 'Mar del Plata')","type":"string","maxLength":80},"max":{"default":3,"description":"Cantidad máxima de candidatos","type":"integer","minimum":1,"maximum":10}},"required":["direccion"]},"example":{"direccion":"Av. Corrientes 1234","provincia":"CABA"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object"},"credits":{"type":"object","properties":{"cost":{"type":"integer"},"balance":{"type":"integer"}}}}}}}},"400":{"description":"Input inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"402":{"description":"Créditos insuficientes. Incluye `checkout_url` para recargar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"502":{"description":"Falló un proveedor externo. No se cobra.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/tools/ubicacion":{"post":{"operationId":"ubicacion","summary":"Geocodificación inversa: lat/lon → provincia, departamento y municipio","description":"Dado un punto (latitud, longitud) devuelve en qué provincia, departamento/partido y municipio de Argentina cae, con ids oficiales INDEC. Si el punto está fuera del país, `en_argentina` es false y los campos vienen null. No devuelve calle ni altura.\n\nCosto: 1 crédito(s) por llamada exitosa.","x-credits-cost":1,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitud en grados decimales (Argentina: aprox. -22 a -55)"},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitud en grados decimales (Argentina: aprox. -53 a -74)"}},"required":["lat","lon"]},"example":{"lat":-34.6037,"lon":-58.3816}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object"},"credits":{"type":"object","properties":{"cost":{"type":"integer"},"balance":{"type":"integer"}}}}}}}},"400":{"description":"Input inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"402":{"description":"Créditos insuficientes. Incluye `checkout_url` para recargar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"502":{"description":"Falló un proveedor externo. No se cobra.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/tools/buscar_localidad":{"post":{"operationId":"buscar_localidad","summary":"Buscar localidades argentinas","description":"Busca localidades (ciudades, pueblos, barrios censales) por nombre aproximado y devuelve provincia, departamento/partido, municipio, categoría y coordenadas del centroide, con ids oficiales INDEC. Útil para desambiguar ('¿qué Rosario?'), completar formularios o resolver la ubicación de un cliente. Filtrá por provincia cuando la conozcas.\n\nCosto: 1 crédito(s) por llamada exitosa.","x-credits-cost":1,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":2,"maxLength":80,"description":"Nombre (tolera tildes y errores leves)"},"provincia":{"description":"Nombre o id de provincia","type":"string","maxLength":60},"departamento":{"description":"Departamento o partido","type":"string","maxLength":60},"max":{"default":5,"type":"integer","minimum":1,"maximum":20}},"required":["nombre"]},"example":{"nombre":"Rosario","provincia":"Santa Fe"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object"},"credits":{"type":"object","properties":{"cost":{"type":"integer"},"balance":{"type":"integer"}}}}}}}},"400":{"description":"Input inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"402":{"description":"Créditos insuficientes. Incluye `checkout_url` para recargar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"502":{"description":"Falló un proveedor externo. No se cobra.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/tools/buscar_calle":{"post":{"operationId":"buscar_calle","summary":"Buscar calles en el callejero oficial","description":"Busca calles por nombre aproximado y devuelve nombre oficial, categoría (CALLE, AV, PJE, RUTA...), rango de alturas y a qué localidad/departamento/provincia pertenece cada tramo. Sirve para validar que una calle existe y que una altura está dentro del rango antes de normalizar, o para autocompletar.\n\nCosto: 1 crédito(s) por llamada exitosa.","x-credits-cost":1,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nombre":{"type":"string","minLength":2,"maxLength":80},"provincia":{"type":"string","maxLength":60},"departamento":{"type":"string","maxLength":60},"localidad":{"description":"Localidad censal","type":"string","maxLength":80},"categoria":{"description":"Filtrar por tipo: CALLE, AV, PJE, RUTA, DIAG, etc.","type":"string","maxLength":20},"max":{"default":5,"type":"integer","minimum":1,"maximum":20}},"required":["nombre"]},"example":{"nombre":"Santa Fe","provincia":"CABA","categoria":"AV"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object"},"credits":{"type":"object","properties":{"cost":{"type":"integer"},"balance":{"type":"integer"}}}}}}}},"400":{"description":"Input inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"402":{"description":"Créditos insuficientes. Incluye `checkout_url` para recargar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"502":{"description":"Falló un proveedor externo. No se cobra.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/tools/buscar_division":{"post":{"operationId":"buscar_division","summary":"Buscar provincias, departamentos o municipios","description":"Busca divisiones administrativas oficiales por nombre aproximado: provincias (24), departamentos/partidos/comunas o municipios. Devuelve id INDEC, nombre oficial, provincia a la que pertenece y centroide. Usala para resolver 'Bs As' → 'Buenos Aires' (id 06) vs 'CABA' (id 02), listar los partidos de una provincia, o conseguir el id que piden otros sistemas.\n\nCosto: 1 crédito(s) por llamada exitosa.","x-credits-cost":1,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tipo":{"type":"string","enum":["provincia","departamento","municipio"]},"nombre":{"description":"Nombre aproximado; omitilo para listar (ej. todas las provincias)","type":"string","maxLength":80},"provincia":{"description":"Restringir a una provincia (para departamentos y municipios)","type":"string","maxLength":60},"max":{"default":10,"type":"integer","minimum":1,"maximum":100}},"required":["tipo"]},"example":{"tipo":"provincia","nombre":"cordoba"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object"},"credits":{"type":"object","properties":{"cost":{"type":"integer"},"balance":{"type":"integer"}}}}}}}},"400":{"description":"Input inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"402":{"description":"Créditos insuficientes. Incluye `checkout_url` para recargar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"502":{"description":"Falló un proveedor externo. No se cobra.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}},"/v1/tools/ejecutar":{"post":{"operationId":"ejecutar","summary":"Ejecutar código contra la API (Code Mode)","description":"Corre JavaScript en un sandbox con un objeto `api` ya autenticado: una función async por tool, mismos parámetros y mismo resultado que llamarla directo. Ideal para lotes (validar 50 CBUs, armar 20 cronogramas) o para encadenar llamadas sin volver al modelo. El código puede usar await, console.log y return; el valor retornado vuelve en `resultado`. Costo: 1 crédito por ejecución + la suma de las llamadas internas. Máximo 100 llamadas y 15 s. Sin acceso a red, archivos ni módulos.\n\nFunciones disponibles:\napi.normalizarDireccion({\"direccion\":\"Av. Corrientes 1234\",\"provincia\":\"CABA\"}) → 2 crédito(s): Normalizar y geocodificar una dirección argentina\napi.ubicacion({\"lat\":-34.6037,\"lon\":-58.3816}) → 1 crédito(s): Geocodificación inversa: lat/lon → provincia, departamento y municipio\napi.buscarLocalidad({\"nombre\":\"Rosario\",\"provincia\":\"Santa Fe\"}) → 1 crédito(s): Buscar localidades argentinas\napi.buscarCalle({\"nombre\":\"Santa Fe\",\"provincia\":\"CABA\",\"categoria\":\"AV\"}) → 1 crédito(s): Buscar calles en el callejero oficial\napi.buscarDivision({\"tipo\":\"provincia\",\"nombre\":\"cordoba\"}) → 1 crédito(s): Buscar provincias, departamentos o municipios\n\nCosto: 1 crédito(s) por llamada exitosa.","x-credits-cost":1,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codigo":{"type":"string","minLength":1,"maxLength":20000,"description":"JavaScript. Ej: const r = await api.validarCuit({cuit:'20-12345678-6'}); return r.valido;"},"timeout_ms":{"default":5000,"description":"Tiempo máximo total en milisegundos","type":"integer","minimum":100,"maximum":15000}},"required":["codigo"]},"example":{"codigo":"const cuits = ['20-12345678-6','30-50001091-2'];\nconst r = [];\nfor (const c of cuits) r.push(await api.validarCuit({ cuit: c }));\nreturn r.filter(x => x.valido).map(x => x.formateado);"}}}},"responses":{"200":{"description":"Resultado","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object"},"credits":{"type":"object","properties":{"cost":{"type":"integer"},"balance":{"type":"integer"}}}}}}}},"400":{"description":"Input inválido","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"401":{"description":"Key faltante o inválida","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"402":{"description":"Créditos insuficientes. Incluye `checkout_url` para recargar.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}},"502":{"description":"Falló un proveedor externo. No se cobra.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":true}}}}}}}}}