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

⚠️ IMPORTANTE: O campo handlers[] (array) está DEPRECATED. Utilize sempre a nova estrutura com handler{} (objeto).

Handlers são enviados no corpo da requisição de criação ou atualização de orders e processos, dentro da chave handler, que é um objeto com as listas de intervenientes por papel (role).

Estrutura:

"handler": {
  "importer": [ { "actor": { "name": "IMPORTER123", "internal_code": "INT-001", "roles": [{ "role": "IMPORTER" }] } } ],
  "exporter": [ { "actor_id": 123 } ],
  "freight_forwarder": []
}

É um objeto onde cada chave tem uma lista de handlers:

• Cada chave representa um papel (role) - por exemplo, importer, exporter, supplier
• Cada lista contém os intervenientes (actors) associados àquele papel
• Cada item da lista representa um actor (Interveniente), identificado pelos seus dados ou pelo seu actor_id

Enviando os handlers

Para enviar os intervenientes em pedidos ou processos, utilize a chave handler, agrupando por papel (role).

Você pode informar o interveniente de duas formas:

1. 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).

"handler": {
  "freight_forwarder": [
    {
      "actor": {
        "name": "Agente de Carga",
        "document_type": "CNPJ",
        "official_document": "00111222000199",
        "roles": [
          { "role": "FREIGHT_FORWARDER" }
        ]
      },
      "business_unit": "Business Unit",
      "reference": "Handler Reference",
      "secondary_reference": "Handler Secondary Reference"
    }
  ]
}

2. Referenciar um actor já cadastrado (actor_id)

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

"handler": {
  "customs_broker": [
    {
      "actor_id": 4321
    }
  ]
}

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 de handler[role].

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.

Removendo handlers

Exemplo: Removendo um fornecedor específico de um pedido que possui múltiplos fornecedores.

Situação inicial - pedido com 2 fornecedores:

"handler": {
  "supplier": [
    {
      "actor_id": 1234
    },
    {
      "actor_id": 5678
    }
  ]
}

Para remover apenas o actor_id 5678 e manter o outro, envie apenas o fornecedor que deseja manter:

"handler": {
  "supplier": [
    {
      "actor_id": 1234
    }
  ]
}

Se você enviar uma lista vazia para um papel, todos handlers daquele papel serão removidos do pedido/processo.

"handler": {
  "supplier": []
}

Exemplos de estrutura para envio de handler{}

🧩 Handler identificado por internal_code

"handler": {
  "customer": [
    {
      "actor": {
        "name": "Cliente",
        "internal_code": "CLI-001",
        "roles": [
          { "role": "CUSTOMER" }
        ]
      }
    }
  ]
}

🧩 Handler identificado por document_type + official_document

"handler": {
  "freight_forwarder": [
    {
      "actor": {
        "name": "Agente de Carga",
        "document_type": "CNPJ",
        "official_document": "00111222000199",
        "roles": [
          { "role": "FREIGHT_FORWARDER" }
        ]
      }
    }
  ]
}

🧩 Exemplo com múltiplos intervenientes

"handler": {
  "exporter": [
    {
      "actor": {
        "name": "Exportador Ltda",
        "document_type": "CNPJ",
        "official_document": "12345678000100",
        "roles": [
          { "role": "EXPORTER" }
        ]
      }
    },
    {
      "actor_id": 2345
    }
  ],
  "freight_forwarder": [
    {
      "actor_id": 12345
    }
  ]
}