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!