Handlers (Intervenientes)

Nesta seção, iremos demonstrar como é feito o gerenciamento de Handlers dentro da plataforma Flowls. Um Handler é o vínculo entre um Interveniente (Actor) e uma função específica dentro de um pedido ou processo logístico — como CUSTOMER, FREIGHT_FORWARDER, IMPORTER, entre outros.

O que são Intervenientes (Actors) e Handlers?

• Interveniente (Actor) é a entidade que participa da cadeia logística: uma empresa, pessoa ou organização envolvida na operação.
• Handler é a associação entre esse Interveniente (Actor) e um papel específico em uma determinada operação.

Ou seja: Actors são os participantes, e Handlers são as responsabilidades que eles assumem dentro de pedidos ou processos.

Na plataforma, os Handlers são utilizados em dois contextos principais:

• Order Handlers: vinculados diretamente às orders (compra, venda, transporte), definindo quem são os participantes daquela transação específica — como o CUSTOMER ou SUPPLIER.

• Process Handlers: vinculados aos processos logísticos, representam os intervenientes responsáveis por etapas operacionais — como FREIGHT_FORWARDER, CUSTOMS_BROKER, NATIONAL_ROAD_CARRIER, entre outros.

Handler “owner” (apenas orders)

Em orders, é obrigatório incluir o handler owner, ou seja, o interveniente responsável pelo pedido:

• 'IMPORTER' para pedidos de importação
• 'EXPORTER' para pedidos de exportação

Esses valores são configurados por padrão, mas podem ser ajustados pela equipe Flowls conforme necessidade do cliente.

Como os Handlers são enviados

Handlers são enviados no corpo da requisição de criação ou atualização de orders e processos, dentro da chave handlers, que é sempre uma lista de vínculos.

Cada item representa a associação entre:

• um actor (Interveniente), identificado pelos seus dados ou pelo seu actor_id;
• um operation_handler_id, que define qual papel esse interveniente exercerá na operação.

ℹ️ O campo operation_handler_id é fixo e representa uma função específica configurada para a operação (ex: EXPORTER = 41, IMPORTER = 42). Esses valores são fornecidos pela equipe de integração da Flowls.

Enviando os handlers

Para enviar os intervenientes em pedidos ou processos, utilize a chave handlers, que deve conter uma lista de participantes vinculados à operação.

Cada item da lista representa a associação entre:

• um interveniente (Actor), e
• um papel (Handler), definido por operation_handler_id.

Você pode informar o interveniente de duas formas:

Enviar os dados diretamente em orders e process

A Flowls criará ou atualizará automaticamente o interveniente com base nos dados enviados (internal_code ou document_type + official_document).

"handlers": [
  {
    "actor": {
      "name": "Agente de Carga",
      "document_type": "CNPJ",
      "official_document": "00111222000199",
      "roles": [
        { "role": "FREIGHT_FORWARDER" }
      ]
    },
    "operation_handler_id": 2
  }
]

ℹ️ O campo roles é obrigatório. Você pode incluir access_group_id se quiser dar acesso à plataforma.

2. Referenciar um actor já cadastrado (actor_id)

Se o interveniente já estiver cadastrado, você pode informá-lo por actor_id:

"handlers": [
  {
    "actor_id": 4321,
    "operation_handler_id": 3
  }
]

Para criar um interveniente e consultar seu actor_id via endpoint actors:

Consultar intervenientes existentes:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  https://api.flowls.app/api/actors

Cadastrar um novo interveniente:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  --data '{
    "params": {
      "official_name": "Novo Interveniente",
      "document_type": "CNPJ",
      "official_document": "00111222000100",
      "roles": [
        { "role": "CUSTOMER" }
      ]
    }
  }' \
  https://api.flowls.app/api/partnerships

ℹ️ Após criado, o id retornado pode ser usado como actor_id dentro da lista de handlers.

Caso o interveniente deva ter acesso à plataforma Flowls (por exemplo, para visualizar pedidos, responder documentos ou interagir com o processo), é possível conceder esse acesso informando o campo access_group_id dentro do objeto roles.

Esse campo representa o grupo de permissões atribuído ao interveniente, conforme previamente acordado com a equipe da Flowls.

"roles": [
  {
    "role": "CUSTOMER",
    "access_group_id": null
  }
]

ℹ️ A ausência de access_group_id não impede o envio do handler — ele será considerado apenas um interveniente de sistema, sem acesso à plataforma.

Exemplos de estrutura da lista handlers[]

🧩 Handler identificado por internal_code

"handlers": [
  {
    "actor": {
      "name": "Cliente",
      "internal_code": "CLI-001",
      "roles": [
        {
          "access_group_id": null,
          "role": "CUSTOMER"
        }
      ]
    },
    "operation_handler_id": 1
  }
]

🧩 Handler identificado por document_type + official_document

"handlers": [
  {
    "actor": {
      "name": "Agente de Carga",
      "document_type": "CNPJ",
      "official_document": "00111222000199",
      "roles": [
        {
          "role": "FREIGHT_FORWARDER"
        }
      ]
    },
    "operation_handler_id": 2
  }
]

🧩 Exemplo com múltiplos intervenientes

"handlers": [
  {
    "actor": {
      "name": "Exportador Ltda",
      "document_type": "CNPJ",
      "official_document": "12345678000100",
      "roles": [{ "role": "EXPORTER" }]
    },
    "operation_handler_id": 3
  },
  {
    "actor": {
      "name": "Agente de Carga XYZ",
      "internal_code": "AGT-123",
      "roles": [{ "role": "FREIGHT_FORWARDER" }]
    },
    "operation_handler_id": 2
  }
]