Skip to main content

CRUD Processos

Na Flowls, um processo é a entidade central que consolida todas as informações logísticas de uma operação — como pedidos, intervenientes, dados de transporte, faturas, documentos e eventos.

Ele representa uma movimentação logística real, como uma importação, exportação ou transporte nacional. Por meio de um processo, é possível acompanhar toda a jornada da carga, desde a coleta, passando pelo embarque internacional, desembaraço aduaneiro, transporte terrestre, até a entrega no destino final.

A estrutura do processo é flexível e pode incluir:

  • Pedidos vinculados (compra, venda ou transporte)
  • Informações de frete internacional
  • Dados do modal logístico (marítimo, aéreo ou rodoviário)
  • Containers e volumes transportados
  • Faturas comerciais (invoices)
  • Documentos como DUIMP, declarações, licenças
  • Eventos de tracking e checkpoints
  • Campos adicionais definidos para a operação (extra_fields)

Essa flexibilidade permite que a plataforma se adapte a diferentes fluxos logísticos e modelos operacionais.

Endpoint de criação​

POST /api/operations/{operation_id}/processes
  • O operation_id define o tipo da operação (importação, exportação, nacional etc.)
  • Consulte a Flowls para obter os IDs corretos configurados no seu ambiente

Exemplo de criação de processo​

curl -X POST -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
--data '{
  "params": {
    "reference_code": "REF5678",
    "handlers": [],
    "order_reference_codes": ["REF1234"],
    "extra_fields": {},
    "foreign_trade_shipment": {
      "maritime_transport_shipment": {
        "bl": "TEST123",
        "booking": "TEST456"
      },
      "items": [
        {
          "order_reference_code": "REF1234",
          "quantity": 10,
          "line_reference": "1"
        }
      ]
    }
  }
}' https://api.flowls.app/api/operations/OPERATION_ID/processes

Campos principais​

Os campos mais comuns utilizados na criação de processos são:

  • reference_code (string)
    Código único de identificação do processo.

  • handlers (array)
    Lista de intervenientes logísticos envolvidos na operação.
    → Veja mais em Handlers

  • order_ids / order_reference_codes (array)
    Pedidos associados ao processo.
    → Veja mais em Orders

  • foreign_trade_shipment (object)
    Estrutura de embarque internacional, incluindo dados do modal, invoices, containers etc.
    → Veja mais em Foreign Trade Shipment

  • extra_fields (object)
    Campos personalizados definidos por operação.
    → Veja mais em Extra Fields

Listando processos​

Utilize este endpoint GET para listar todos os processos de forma paginada:

curl -X GET -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
https://api.flowls.app/api/operations/OPERATION_ID/processes

Parâmetros padrão de paginação:

{
  "limit": 20,
  "offset": 0,
  "order_by": [
    { "field": "INSERTED_AT", "order": "DESC" }
  ]
}

Exemplo com paginação e ordenação customizada:

curl -X GET -G -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
https://api.flowls.app/api/operations/OPERATION_ID/processes \
-d 'pagination[limit]=50' \
-d 'pagination[order_by][field]=REFERENCE_CODE' \
-d 'pagination[order_by][order]=ASC'

Obtendo um processo específico​

Para consultar os dados completos de um processo já criado, utilize o reference_code (identificador definido no momento da criação):

curl -X GET \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
https://api.flowls.app/api/operations/OPERATION_ID/processes-by-reference-code/REFERENCE_CODE

Também é possível consultar o processo utilizando o PROCESS_ID pela seguinte URL: https://api.flowls.app/api/operations/OPERATION_ID/processes/PROCESS_ID

Editando um processo​

Para atualizar os dados de um processo já criado, envie uma requisição PUT com os campos que deseja alterar:

curl -X PUT -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
--data '{
  "params": {
    "foreign_trade_shipment": {
      "international_freight": {
        "freight_forwarder": "NewCo Shipping",
        "freight_cost_prepaid": "999.99",
        "currency_code": "USD",
        "type": "PREPAID"
      }
    }
  }
}' https://api.flowls.app/api/operations/OPERATION_ID/processes/PROCESS_ID

Também é possível editar o processo utilizando o PROCESS_ID: https://api.flowls.app/api/operations/OPERATION_ID/processes/PROCESS_ID

Deletando um processo​

Para remover um processo da base, utilize o método DELETE:

curl -X DELETE -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
https://api.flowls.app/api/operations/OPERATION_ID/processes/PROCESS_ID

Próximos passos​

A criação de um processo na Flowls pode envolver estruturas adicionais que complementam e enriquecem os dados da operação. Para manter esta seção mais objetiva, deixamos a explicação detalhada desses campos complementares para as seções específicas abaixo:

  • Foreign Trade Shipment: campo de processos responsável por agrupar os dados logísticos do embarque internacional, como modais de transporte, faturas (invoices), DUIMP, containers, rota, entre outros.
  • Handlers: lista dos intervenientes logísticos envolvidos na operação, como exportadores, importadores, agentes de carga, etc.
  • Extra Fields: campos personalizados definidos por operação, permitindo adaptar o processo às regras e necessidades específicas de cada cliente.

Recomendamos a leitura dessas seções para estruturar corretamente os dados do processo de acordo com o tipo de operação e os requisitos do projeto.