Skip to main content

Getting Started

Para demonstrar de forma prática como utilizar a API, iremos fazer o gerenciamento de Produtos na plataforma. Este é apenas um exemplo, mas a grande maioria dos recursos disponíveis na REST API seguirão os mesmos padrões. Para entender as especificidades de cada endpoint, use a documentação oficial da API como referência.

Iremos utilizar cURL para realizar os requests de exemplo, mas fique à vontade para adaptar os requests para sua linguagem de preferência.

Criando um produto

Para começar, vamos criar um novo produto. Assim como apresentado na documentação da API, a criação do produto se dá por meio de um request POST no endpoint /products:

curl -X POST -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' --data '{"params": {"description":"Produto Teste", "code":"TEST01"}}' https://api.flowls.app/api/products

Espera-se uma resposta com código HTTP 201, representando a criação bem sucedida. Além disso, a resposta conterá os dados do novo produto, como representado no exemplo abaixo:

{
"data": {
"id": 275,
"code": "REF1234",
"description": "Shock Absorbers",
"family": "Suspension and Handling",
"category": "Suspension",
"country": "DE",
"internalCodes": [
{
"code": "REF5678",
"label": "Supplier"
}
],
"manufacturer": "Schneider-Rutherford",
"mercosulCode": "8708.80.00",
"multiplePackageCapacity": "30",
"multiplePackageMeasurementUnit": "BOXES",
"packageCapacity": "4",
"packageCode": "PR017",
"packageMeasurementUnit": "PAIRS",
"packageType": "PAIRS",
"productForeignOperators": [],
"c9_ratio": null,
"extra": null
}
}

Listando produtos

Caso tenha dado tudo certo, você pode acessar a plataforma e ver o novo produto já disponível, em https://www.flowls.app/products. Além disso, podemos também usar a própria API para listar todos os produtos disponíveis:

curl -X GET -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' https://api.flowls.app/api/products

Por padrão, todas as listagens da API possuem uma paginação default, seguindo os seguintes parâmetros:

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

Isso significa que por padrão, os dados serão retornados ordenados pela sua data de inserção em ordem decrescente, de forma que os mais recentes serão retornados primeiro. Além disso, o retorno é limitado a 20 itens, de forma a evitar respostas muito grandes inesperadas.

Todos esses parâmetros podem ser ajustados conforme necessidade, como mostra o exemplo a seguir que usa um limite maior, e ordena o resultado baseado no campo de código do produto. Como este endpoint é do tipo GET, os parâmetros devem ser enviados via query params:

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

Obtendo um produto específico

Além disso, também conseguimos obter os dados de um produto específico através de seu ID. Os IDs são gerados automaticamente pela Flowls e devem ser usados para referenciar os dados dentro da REST API. Para esse exemplo, pegue o ID retornado na resposta da criação ou na listagem do passo anterior e substitua em YOUR_ID:

curl -X GET -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' https://api.flowls.app/api/products/YOUR_ID

Editando um produto

Além de obter um produto específico, também é possível editar produtos individualmente através do método PUT:

curl -X PUT -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' --data '{"params": {"description":"Nova descrição"}}' https://api.flowls.app/api/products/YOUR_ID

Deletando um produto

Por fim, vamos deletar esse produto de testes usando o método DELETE:

curl -X DELETE -H 'Content-type: application/json' -H 'api-key: YOUR_API_KEY' https://api.flowls.app/api/products/YOUR_ID

Próximos passos

Se você chegou até aqui, significa que já dominou o básico da API da Flowls, e está pronto para criar a sua integração conforme suas necessidades!