Integración empresarial

Publica Cifra en tu API Management

Cifra expone un contrato OpenAPI 3.0. Tu empresa lo importa en su gateway, guarda la API key en su propio gestor de secretos y gobierna el consumo con sus políticas. Tus equipos internos consumen sin ver nunca la clave.

El patrón, en una imagen

Tus aplicaciones internasSin credenciales de Cifra. Autenticación corporativa (OAuth / JWT / mTLS).

↓

Tu API ManagementInyecta x-api-key desde el secret manager · aplica cuotas, IP allow-list, auditoría y caché

↓ HTTPS

Cifra APImimicifra.cl/api/v1

Regla de oro: la API key de Cifra se guarda una sola vez, en tu gestor de secretos (Key Vault, Secrets Manager, KVM, Vault). Nunca en el código de las aplicaciones ni en el repositorio.

Ir directo a: Azure · AWS · Apigee · Kong · MuleSoft

Azure API Management

El camino más común en banca y retail chileno. La clave vive en Key Vault y se referencia como named value.

Guarda la API key en Key Vault

Portal de Azure → tu Key Vault → Objects → Secrets → Generate/Import. Nombre: cifra-api-key. Valor: tu clave.

Crea el named value en APIM

Tu instancia de APIM → APIs → Named values → + Add. Tipo: Key vault. Nombre: cifra-api-key. Marca secret y selecciona el secreto del paso 1.

Importa el contrato OpenAPI

APIs → + Add API → OpenAPI. En OpenAPI specification pega la URL del spec. Define el API URL suffix (ej. cifra) y el producto que lo publicará.

URL del spec

https://mimicifra.cl/api/openapi.json

Añade la política inbound

Selecciona la API → Design → All operations → en Inbound processing abre el editor de código (</>) y pega la política.

Política inbound (XML)

<policies>
  <inbound>
    <base />
    <!-- La clave de Cifra nunca sale del gateway -->
    <set-header name="x-api-key" exists-action="override">
      <value>{{cifra-api-key}}</value>
    </set-header>

    <!-- Cuota corporativa por aplicación consumidora -->
    <rate-limit-by-key calls="600" renewal-period="60"
                       counter-key="@(context.Subscription?.Id ?? context.Request.IpAddress)" />

    <!-- Caché de lecturas: los datos oficiales cambian a diario, no por segundo -->
    <cache-lookup downstream-caching-type="none" vary-by-developer="false" />
  </inbound>
  <backend><base /></backend>
  <outbound>
    <base />
    <cache-store duration="3600" />
    <!-- No filtrar la cabecera hacia el consumidor -->
    <set-header name="x-api-key" exists-action="delete" />
  </outbound>
  <on-error><base /></on-error>
</policies>

Verifica esto: el set-header del bloque outbound es el que impide que la clave se devuelva por accidente al consumidor interno. No lo omitas.

AWS API Gateway

Con integración HTTP_PROXY la clave se inyecta desde Secrets Manager mediante una función Lambda ligera, o directamente como parámetro de la integración.

Guarda la clave en Secrets Manager

AWS CLI

aws secretsmanager create-secret \
  --name cifra/api-key \
  --description "API key de Cifra" \
  --secret-string '{"x-api-key":"TU_API_KEY"}'

Importa el contrato OpenAPI

Consola → API Gateway → Create API → REST API → Import. O por CLI:

AWS CLI

curl -s https://mimicifra.cl/api/openapi.json -o cifra-openapi.json

aws apigateway import-rest-api \
  --parameters endpointConfigurationTypes=REGIONAL \
  --body 'fileb://cifra-openapi.json'

Configura la integración HTTP_PROXY

En cada método: Integration Request → tipo HTTP Proxy → endpoint https://mimicifra.cl/api/v1/{proxy}. En HTTP Headers agrega x-api-key mapeado desde el stage variable o desde el secreto.

Extensión OpenAPI (x-amazon-apigateway-integration)

{
  "x-amazon-apigateway-integration": {
    "type": "http_proxy",
    "httpMethod": "GET",
    "uri": "https://mimicifra.cl/api/v1/{proxy}",
    "requestParameters": {
      "integration.request.header.x-api-key": "stageVariables.cifraApiKey",
      "integration.request.path.proxy": "method.request.path.proxy"
    },
    "passthroughBehavior": "when_no_match"
  }
}

Aplica plan de uso y despliega

Usage Plans → asocia el stage y define throttling/quota para tus consumidores internos. Luego Deploy API al stage (ej. prod).

Google Apigee

Guarda la clave en un KVM cifrado

gcloud / API de Apigee

# Crea el Key Value Map cifrado
curl -X POST \
  "https://apigee.googleapis.com/v1/organizations/TU_ORG/environments/prod/keyvaluemaps" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"cifra-secrets","encrypted":true}'

Crea el proxy desde el spec

Develop → API Proxies → Create New → Use OpenAPI Spec → pega https://mimicifra.cl/api/openapi.json.

Lee el secreto y setea la cabecera

Añade dos políticas al flujo PreFlow de la request:

KeyValueMapOperations + AssignMessage

<!-- 1) Lee la clave del KVM -->
<KeyValueMapOperations name="KVM-LeerCifraKey" mapIdentifier="cifra-secrets">
  <Get assignTo="private.cifraApiKey">
    <Key><Parameter>api_key</Parameter></Key>
  </Get>
  <Scope>environment</Scope>
</KeyValueMapOperations>

<!-- 2) La inyecta como cabecera hacia el backend -->
<AssignMessage name="AM-SetCifraKey">
  <Set>
    <Headers>
      <Header name="x-api-key">{private.cifraApiKey}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

El prefijo private. evita que la variable aparezca en las trazas de depuración de Apigee.

Kong Gateway

Configuración declarativa: versionable en tu repositorio y aplicable con deck sync.

kong.yaml (declarative config)

_format_version: "3.0"

services:
  - name: cifra-api
    url: https://mimicifra.cl/api/v1
    retries: 3
    connect_timeout: 5000
    read_timeout: 15000
    routes:
      - name: cifra-route
        paths: ["/cifra"]
        strip_path: true
    plugins:
      # Inyecta la clave hacia el upstream
      - name: request-transformer
        config:
          add:
            headers: ["x-api-key:${CIFRA_API_KEY}"]
      # Cuota para consumidores internos
      - name: rate-limiting
        config:
          minute: 600
          policy: local
      # Cachea lecturas
      - name: proxy-cache
        config:
          strategy: memory
          cache_ttl: 3600
          content_type: ["application/json"]

Aplicar

export CIFRA_API_KEY="tu_clave"
deck gateway sync kong.yaml

En producción usa deck con variables de entorno o el plugin de Vault de Kong ({vault://...}) en vez de escribir la clave en el YAML.

MuleSoft Anypoint

Publica el spec en Exchange

Anypoint Exchange → Add asset → REST API → sube el OpenAPI de Cifra. Queda como activo reutilizable para toda la organización.

Guarda la clave en Secure Properties

Usa secure::cifra.apiKey con el módulo de propiedades seguras de Mule, cifrado con la llave del entorno.

Flow de Mule (XML)

<http:request-config name="Cifra_Config">
  <http:request-connection protocol="HTTPS" host="mimicifra.cl" port="443" />
</http:request-config>

<flow name="consultar-boletin-concursal">
  <http:request method="GET" path="/api/v1/boletin-concursal"
                config-ref="Cifra_Config">
    <http:headers><![CDATA[#[{
      "x-api-key": p('secure::cifra.apiKey')
    }]]]></http:headers>
    <http:query-params><![CDATA[#[{
      "q": attributes.queryParams.razonSocial,
      "limit": "50"
    }]]]></http:query-params>
  </http:request>
</flow>

Checklist antes de pasar a producción

La API key está en el gestor de secretos, no en el repositorio ni en variables planas.
La cabecera x-api-key se elimina en el flujo de salida hacia el consumidor.
Hay caché de al menos 1 hora en los datasets cached (ahorra cuota y latencia).
El cliente reintenta con backoff exponencial ante 429 y 502.
Se registra el estado_datos de cada respuesta para trazabilidad.
Los timeouts del gateway son mayores que los de la fuente oficial (sugerido: 15 s).
Se monitorea la cuota del plan contratado contra el volumen real.

¿Quieres que lo revisemos contigo? Acompañamos la primera integración enterprise sin costo: te ayudamos a dejar el proxy y las políticas funcionando en tu entorno. Escríbenos desde tu panel.