Skip to main content

Products

Nesta seção, vamos demonstrar como utilizar a API da Flowls para gerenciar produtos na plataforma. Esta é uma das operações mais comuns em integrações de dados e serve como base para o entendimento do padrão de uso da REST API da Flowls.

A criação, listagem, edição e deleção de produtos segue um formato consistente com o restante dos recursos da API. Os exemplos a seguir utilizam cURL para facilitar a reprodução dos requests, mas você pode adaptar para a linguagem ou ferramenta de sua preferência (como Postman, Python, Node, etc.).

Campos obrigatórios​

Para criar um produto, informe ao menos:

  • code (string): código único do produtov (SKU).
  • description (string): descrição legível do produto.

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": {
    "code": "REF_PROD",
    "description": "Produto Teste"
  }
}' 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 id e code do novo produto, como representado no exemplo abaixo:

{
  "data": {
    "id": 275,
    "code": "REF_PROD"
  }
}

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/PRODUCT_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 no endpoint /products:

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/PRODUCT_ID

Upsert de produtos​

Também é possível realizar o Upsert de produtos, enviando neste formato novos produtos serão criados e produtos existentes serão atualizados, é feito através do método PUT, enviando "params" como uma lista:

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

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/PRODUCT_ID

Próximos passos​

Você concluiu seu primeiro teste de integração com a API da Flowls utilizando o recurso de produtos.

Siga com a leitura da documentação para continuar a integração conforme as necessidades do seu projeto.