Voltar para Aprenda

Aptabit Platformv3.7

API

API de fluxos

Endpoint de cada fluxo publicado, token próprio, origens permitidas e erros.

Nesta página

Um fluxo publicado com exposição API recebe um endpoint próprio, protegido por um token exclusivo daquele fluxo. É a API externa documentada da Aptabit Platform para integrar sistemas da organização aos fluxos.

Endpoint

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

Corpo da requisição:

JSON
{
  "input": {
    "message": "Resuma o contrato anexado ao chamado 4821."
  }
}

O objeto input deve seguir o esquema de entrada do contrato do fluxo. Um fluxo novo espera message (obrigatório) e query (opcional) e devolve response.

Exemplo com 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 o contrato anexado ao chamado 4821."}}'

Resposta

A chamada é síncrona: a resposta chega ao fim da execução, com o registro da execução.

JSON
{
  "id": "uuid da execução",
  "flow_id": "uuid do fluxo",
  "source": "api",
  "status": "succeeded",
  "input": { "message": "Resuma o contrato anexado ao chamado 4821." },
  "output": { "response": "..." },
  "error_message": null,
  "created_at": "2026-10-08T12:00:00Z",
  "completed_at": "2026-10-08T12:00:04Z"
}
Campo Descrição
status succeeded ou failed.
output Saída do bloco de saída, conforme o esquema de saída do contrato.
error_message Motivo da falha, quando status é failed.

Uma execução que falha durante os blocos responde com HTTP 200, status igual a failed e error_message preenchido. Uma entrada fora do contrato também falha e gera uma irregularidade no registro de qualidade de dados. O rastro de cada bloco fica guardado na execução e pode ser consultado em Configurações > Logs.

Token por fluxo

Cada fluxo tem o próprio token, com prefixo flw_. O valor aparece uma única vez, na criação do fluxo ou na rotação, e é guardado pela plataforma apenas em hash. O contrato mostra só os metadados:

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

Para rotacionar o token, use a opção de rotação no fluxo ou a chamada abaixo, com uma sessão autenticada na plataforma:

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

{ "rotate_trigger_token": true }

A resposta traz o novo trigger_token uma única vez. Guarde-o no cofre de segredos do sistema que chamará o fluxo.

Origens permitidas

Chamadas de servidor para servidor, sem cabeçalho Origin, não passam por verificação de origem. Para aplicações de navegador hospedadas fora da plataforma, defina as origens no contrato do fluxo:

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

O padrão é ["*"], que aceita qualquer origem. O endpoint responde à requisição de pré-verificação OPTIONS com os métodos POST e OPTIONS e os cabeçalhos Authorization, Content-Type e Accept.

Erros

Os erros seguem o formato Problem Details:

JSON
{
  "type": "…/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid flow bearer token.",
  "code": "unauthorized"
}
Status Código Causa
400 bad_request O fluxo não está publicado, ou o cabeçalho Origin é inválido.
401 unauthorized Token ausente ou inválido.
403 forbidden Origem do navegador fora da lista permitida.
404 not_found Não existe fluxo com esse trigger_slug, ou ele foi arquivado.

Toda resposta traz o cabeçalho x-request-id, com o valor enviado pelo cliente ou um gerado pela API. Informe-o ao suporte para localizar a chamada nos logs.

Postman

A Aptabit fornece uma coleção Postman para o endpoint externo, com a pré-verificação de origem e a chamada do fluxo. Antes de executar, configure baseUrl, flowEndpoint, flowApiToken, requestOrigin e message.

Escopo da API

O endpoint de fluxos é a API externa documentada. Criar, publicar, editar contratos e rotacionar tokens são operações feitas na plataforma. A especificação OpenAPI publicada pela API cobre apenas os endpoints de saúde e de versão.

Documentaçãov3.7