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 eEXPORTER
em pedidos de exportação). Cada handler requeroperation_handler_id
e os dados doactor
ouactor_id
.
Entenda melhor a entidadehandlers
: (veja Handlers)purchase_order
ousales_order
(object): define o tipo de pedido e lista de itens.purchase_order
para pedidos de importação esales_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
ouline_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.