Volver a Aprenda

Aptabit Platformv3.7

API

API de flujos

Endpoint de cada flujo publicado, token propio, orígenes permitidos y errores.

En esta página

Un flujo publicado con exposición API recibe un endpoint propio, protegido por un token exclusivo de ese flujo. Es la API externa documentada de la Aptabit Platform para integrar los sistemas de su organización con los flujos.

Endpoint

HTTP
POST /api/v1/flow-inputs/{trigger_slug}
Authorization: Bearer {trigger_token}
Content-Type: application/json

Cuerpo de la solicitud:

JSON
{
  "input": {
    "message": "Resuma el contrato adjunto al ticket 4821."
  }
}

El objeto input debe seguir el esquema de entrada del contrato del flujo. Un flujo nuevo espera message (obligatorio) y query (opcional) y devuelve response.

Ejemplo con curl:

Shell
curl -X POST "https://plataforma.example.com/api/v1/flow-inputs/<trigger_slug>" \
  -H "Authorization: Bearer $APTABIT_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Resuma el contrato adjunto al ticket 4821."}}'

Respuesta

La llamada es síncrona: la respuesta llega al final de la ejecución, con el registro de la ejecución.

JSON
{
  "id": "uuid de la ejecución",
  "flow_id": "uuid del flujo",
  "source": "api",
  "status": "succeeded",
  "input": { "message": "Resuma el contrato adjunto al ticket 4821." },
  "output": { "response": "..." },
  "error_message": null,
  "created_at": "2026-10-08T12:00:00Z",
  "completed_at": "2026-10-08T12:00:04Z"
}
Campo Descripción
status succeeded o failed.
output Resultado del bloque de salida, según el esquema de salida del contrato.
error_message Motivo del fallo, cuando status es failed.

Una ejecución que falla durante los bloques responde con HTTP 200, status igual a failed y error_message completado. Una entrada fuera del contrato también falla y genera una irregularidad en el registro de calidad de datos. La traza de cada bloque queda guardada en la ejecución y puede consultarse en Configuración > Logs.

Token por flujo

Cada flujo tiene su propio token, con el prefijo flw_. El valor aparece una sola vez, al crear el flujo o al rotar el token, y la plataforma solo guarda su hash. El contrato muestra únicamente los metadatos:

JSON
{
  "api_auth": {
    "type": "bearer_token",
    "header": "Authorization",
    "scheme": "Bearer",
    "token_prefix": "flw_",
    "token_hint": "flw_...b51365",
    "method": "POST",
    "endpoint": "/api/v1/flow-inputs/mi-flujo"
  }
}

Para rotar el token, utilice la opción de rotación en el flujo o la llamada siguiente, con una sesión autenticada en la plataforma:

HTTP
PATCH /api/v1/flows/{id}
Content-Type: application/json

{ "rotate_trigger_token": true }

La respuesta trae el nuevo trigger_token una sola vez. Guárdelo en el almacén de secretos del sistema que llamará al flujo.

Orígenes permitidos

Las llamadas de servidor a servidor, sin encabezado Origin, no pasan por verificación de origen. Para aplicaciones de navegador alojadas fuera de la plataforma, defina los orígenes en el contrato del flujo:

JSON
{
  "exposure": "api",
  "allowed_origins": ["https://app.example.com", "https://admin.example.com"]
}

El valor predeterminado es ["*"], que acepta cualquier origen. El endpoint responde a la solicitud de verificación previa OPTIONS con los métodos POST y OPTIONS y los encabezados Authorization, Content-Type y Accept.

Errores

Los errores siguen el formato Problem Details:

JSON
{
  "type": "…/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid flow bearer token.",
  "code": "unauthorized"
}
Estado Código Causa
400 bad_request El flujo no está publicado, o el encabezado Origin no es válido.
401 unauthorized Token ausente o no válido.
403 forbidden Origen del navegador fuera de la lista permitida.
404 not_found No existe un flujo con ese trigger_slug, o fue archivado.

Toda respuesta trae el encabezado x-request-id, con el valor enviado por el cliente o uno generado por la API. Infórmelo al soporte para ubicar la llamada en los logs.

Postman

Aptabit proporciona una colección de Postman para el endpoint externo, con la verificación previa de origen y la llamada al flujo. Antes de ejecutarla, configure baseUrl, flowEndpoint, flowApiToken, requestOrigin y message.

Alcance de la API

El endpoint de flujos es la API externa documentada. Crear, publicar, editar contratos y rotar tokens son operaciones que se realizan en la plataforma. La especificación OpenAPI publicada por la API cubre solo los endpoints de salud y de versión.

Documentaciónv3.7