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.