Skip to main content

Orders

Nesta seção, vamos demonstrar como utilizar a API da Flowls para gerenciar pedidos (orders) na plataforma. Pedidos representam transações comerciais — como compras ou vendas — e são uma das principais entidades manipuladas em integrações com a API.

Todos os exemplos abaixo seguem o padrão REST e utilizam cURL, podendo ser facilmente adaptados para qualquer linguagem ou ferramenta (Postman, Python, etc.).

Campos obrigatórios​

Para criar um pedido, informe ao menos:

  • reference_code (string): código único do pedido.
    Pode ser opcional caso sua operação esteja configurada para geração automática na Flowls.

  • handlers (array): lista de intervenientes. Deve conter ao menos o handler responsável por aquele pedido (IMPORTER em pedidos de importação e EXPORTER em pedidos de exportação). Cada handler requer operation_handler_id e os dados do actor ou actor_id.
    Entenda melhor a entidade handlers: (veja Handlers)

  • purchase_order ou sales_order (object): define o tipo de pedido e lista de itens. purchase_order para pedidos de importação e sales_order para pedidos de exportação.

Criando um pedido​

Para criar um novo pedido, envie uma requisição POST para o endpoint /operations/OPERATION_ID/orders. O payload deve incluir, em um exemplo de Importação:

curl -X POST -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
--data '{
  "params": {
    "reference_code": "REF_ORDER",
    "handlers": [
      {
        "actor": {
          "name": "Importador",
          "internal_code": "internal_code_aqui",
          "roles": [
            {
              "role": "IMPORTER"
            }
          ]
        },
        "operation_handler_id": 1
      }
    ],
    "purchase_order": {
      "type": "DIRECT",
      "items": [
        {
          "line_reference": "1",
          "line_number": 1,
          "product_code": "REF_PROD", // Deve ser o código de um produto previamente cadastrado
          "quantity": 10
        }
      ]
    }
  }
}' https://api.flowls.app/api/operations/OPERATION_ID/orders

Resposta esperada:

{
  "data": {
    "id": 11223344,
    "reference_code": "REF_ORDER"
  }
}

Um dos campos line_number ou line_reference será obrigatório na criação do pedido, de acordo com a configuração da operação.

Listando pedidos​

Utilize este endpoint GET para listar todos os pedidos 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/orders

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/orders \
-d 'pagination[limit]=50' \
-d 'pagination[order_by][field]=REFERENCE_CODE' \
-d 'pagination[order_by][order]=ASC'

Obtendo um pedido específico​

Para consultar os dados completos de um pedido já criado, a API permite duas abordagens: por reference_code, que é o identificador definido no momento da criação, ou por ORDER_ID, que é o id gerado na criação.

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

Para consultar o pedido utilizando o ORDER_ID pela seguinte URL: https://api.flowls.app/api/operations/OPERATION_ID/orders/ORDER_ID

Editando um pedido​

Para atualizar o status ou outros campos de um pedido existente, você pode usar o reference_code ou ORDER_ID.

curl -X PUT \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
--data '{
    "params": {
      "purchase_order": {
        "type": "DIRECT",
        "items": [
          {
            "line_reference": "1",
            "line_number": 1,
            "product_code": "REF_PROD",
            "quantity": 100
          }
        ]
      }
    }
  }' \
https://api.flowls.app/api/operations/OPERATION_ID/orders-by-reference-code/REFERENCE_CODE

ℹ️ A obrigatoriedade de line_number e line_reference depende da configuração da operação. Esses campos também são utilizados caso o pedido evolua para um processo de embarque.

Também é possível editar o pedido utilizando o ORDER_ID: https://api.flowls.app/api/orders/ORDER_ID

Upsert de pedidos (em lote)​

Este método permite criar ou atualizar múltiplos pedidos em uma única chamada. O payload deve seguir o mesmo modelo da criação, com todos os campos necessários:

curl -X PUT -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' \
--data '{
  "params": [
    {
      "reference_code": "REF_ORDER2",
      "canceled_at": null,
      "handlers": [
        {
          "actor": {
            "name": "Exportador",
            "document_type": "CNPJ",
            "official_document": "00111222000100",
            "roles": [
              {
                "role": "EXPORTER"
              }
            ]
          },
          "operation_handler_id": 1
        }
      ],
      "purchase_order": {
        "type": "DIRECT",
        "items": [
          {
            "line_reference": "1",
            "line_number": 1,
            "product_code": "REF_PROD",
            "quantity": 100
          }
        ]
      }
    },
    {
      "reference_code": "REF_ORDER3",
      "canceled_at": null,
      "handlers": [],
      "purchase_order": {
        "type": "DIRECT",
        "items": [          
          {
            "line_reference": "1",
            "line_number": 1,
            "product_code": "REF_PROD",
            "quantity": 100
          }
        ]
      }
    }
  ]
}' https://api.flowls.app/api/orders

Pedidos com reference_code já existentes serão atualizados. Novos serão criados.

Deletando um pedido​

Para remover um pedido da base:

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

Próximos passos​

Após integrar os pedidos, siga para os próximos recursos disponíveis na API

Esses recursos permitem completar a jornada logística e conectar todos os envolvidos na operação.