Crear una configuración de provider

Utiliza este endpoint para crear una nueva configuración de provider. La configuración se valida contra el JSON Schema del provider.

POST /v1/provider-configurations

Crear una configuración de provider

cURL

curl --request POST \
  --url https://flowker.sandbox.lerian.net/v1/provider-configurations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "baseUrl": "https://api.clearsale.com.br",
    "apiKey": "cs-key-abc123",
    "environment": "production"
  },
  "name": "ClearSale Production",
  "allowedHosts": [
    "api.acme.com",
    ".kyc-provider.io"
  ],
  "allowedPrivateHosts": [
    "nginx.pix-inline.internal"
  ],
  "kind": "external_openapi",
  "description": "ClearSale anti-fraud for Pix transactions",
  "metadata": {
    "environment": "production",
    "team": "risk"
  },
  "providerId": "clearsale",
  "schemaBindings": [
    {
      "schemaId": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
      "type": "openapi",
      "operations": [
        {
          "method": "POST",
          "path": "/payments"
        }
      ]
    }
  ]
}
'

201

{
  "createdAt": "2026-03-17T14:00:00Z",
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "name": "ClearSale Production",
  "status": "active"
}

Autorizaciones

Authorization · string · header · requerido

Token bearer JWT emitido por el provider de identidad. Envíalo en la cabecera Authorization como Bearer <token>.

Cuerpo

application/json

Cuerpo de la solicitud que contiene los detalles de la configuración de provider.

config · object · requerido

Configuración específica del provider que se valida contra el JSON Schema del provider.

Show child attributes

Ejemplo:

{
  "baseUrl": "https://api.clearsale.com.br",
  "apiKey": "cs-key-abc123",
  "environment": "production"
}

name · string · requerido

Nombre único para esta configuración de provider.

Required string length: 1 - 100

Ejemplo:

"ClearSale Production"

allowedHosts · string[] | null

Lista de hosts de destino permitidos para las llamadas salientes. Se aplica a todos los nodes que llaman a través de esta configuración. Omite el campo, o envía una lista vacía, para aceptar cualquier host público. El conector HTTP genérico, con el id de provider http, es la excepción — rechaza una lista vacía con el error FLK-0323. Un punto inicial coincide con los subdominios, así que ".kyc-provider.io" coincide con "api.kyc-provider.io". Las entradas son solo nombres de host, sin literal de IP, sin comodín y sin puerto. Flowker pasa cada entrada a minúsculas. Flowker comprueba contra esta lista los valores base_url, onboarding_base_url y transaction_base_url de config, y en tiempo de ejecución comprueba la URL de la solicitud y cada salto de redirección.

Maximum array length: 100

Maximum string length: 253

Ejemplo:

["api.acme.com", ".kyc-provider.io"]

allowedPrivateHosts · string[] | null

Conjunto de hosts privados permitidos, gestionado por tu equipo de operaciones. Una entrada permite que esta configuración llame a un host que resuelve a una dirección privada o de loopback, que Flowker bloquea por defecto. Las direcciones de metadatos de nube y link-local siguen bloqueadas, y ninguna entrada las alcanza. Las entradas siguen el mismo formato que allowedHosts.

Maximum array length: 100

Maximum string length: 253

Ejemplo:

["nginx.pix-inline.internal"]

kind · enum<string>

Qué tipo de conexión es esta. Omítelo, o envía "catalog", para una conexión a un provider del catálogo — entonces providerId es obligatorio. Envía "external_openapi" para una conexión a un documento OpenAPI que subiste mediante el registro de esquemas OpenAPI; providerId es opcional para ese kind, y su config contiene openapi_schema_id más un bloque auth y un base_url opcionales. Eliges el kind al crear la configuración.

Opciones disponibles: catalog, external_openapi

Ejemplo:

"external_openapi"

description · string

Descripción legible por humanos de esta configuración de provider.

Maximum string length: 500

Ejemplo:

"ClearSale anti-fraud for Pix transactions"

metadata · object

Pares clave-valor personalizados para etiquetado.

Show child attributes

Ejemplo:

{
  "environment": "production",
  "team": "risk"
}

providerId · string

ID del provider del catálogo a configurar. Es obligatorio para el kind catalog, y Flowker rechaza con el error FLK-0297 una creación que lo omite. Una configuración de kind external_openapi puede omitirlo, y una lectura de esa configuración devuelve el id reservado external.openapi.

Ejemplo:

"clearsale"

schemaBindings · object[] | null

Esquemas almacenados a los que se vincula esta configuración. Cada entrada nombra un esquema XSD u OpenAPI ya registrado en tu tenant. Omite el campo, o envía una lista vacía, para no tener vínculos. Dos entradas idénticas en la misma solicitud se rechazan.

Maximum array length: 100

Show child attributes

Respuesta

201

application/json

Indica que el recurso fue creado exitosamente y la operación se completó según lo esperado.

createdAt · string<date-time>

Marca de tiempo de cuando se creó la configuración.

Ejemplo:

"2026-03-17T14:00:00Z"

id · string<uuid>

Identificador único de la configuración creada.

Ejemplo:

"c3d4e5f6-a7b8-9012-cdef-345678901234"

name · string

Nombre de la configuración.

Ejemplo:

"ClearSale Production"

status · string

Estado inicial (siempre active al crear).

Ejemplo:

"active"