Guia de Referência de API
Atualizado em 07/01/2023
API
Visão geral
A API Gestão de Ativos JSON REST permite que você execute a maioria das mesmas ações por meio de suas próprias ferramentas assim como você faz através da interface web.
Esta documentação (e a própria API) estão sempre em desenvolvimento, portanto, algumas coisas podem não funcionar exatamente como esperado, ou podemos não ter exemplos de código e respostas de exemplo para tudo. Por favor, seja paciente. À medida que continuamos a desenvolver a API, estamos atualizando a documentação.
Filosofia
Nossa filosofia em códigos de status HTTP é que, desde que o pipe (a própria solicitação http) seja sólido, a API deve retornar um código de status. Percebemos que algumas pessoas muito inteligentes têm uma filosofia muito diferente, mas, em geral, queremos que o código de status HTTP descreva o estado do ponto de extremidade do recurso, com o status real da transação retornado na carga JSON. 200 OK
Por exemplo, se você fez uma solicitação HTTP válida para recuperar um ativo que não existe, retornaremos um OK 200, com a seguinte carga útil:
200 OK Resposta JSON
{
"status": "error",
"messages": "Asset does not exist."
}
Da mesma forma, se você tentar atualizar um recurso, mas não fornecer todas as informações necessárias, responderemos com erros de validação na seção da resposta:messages
JSON
{
"status": "error",
"messages": {
"model_id": [
"The selected model id is invalid."
],
"status_id": [
"The selected status id is invalid."
]
}
}
Gerando tokens de API
Para usar a API, você precisará gerar uma chave de API que será associada ao seu usuário. Você pode fazer isso através da interface web do Gestão de Ativos, acessando a lista suspensa da sua conta no canto superior direito e clicando em "Gerenciar chaves de API".
Permissões de API
Como usamos Tokens de Acesso Pessoal, as permissões do token de API refletem as permissões do usuário ao qual ele está associado.
Por exemplo, se você tiver um usuário que só tem permissão para exibir ativos, mas não de atualizá-los, todas as solicitações de API feitas usando o Token de Acesso Pessoal desse usuário retornarão um erro Não autorizado se ele tentar executar uma ação que seu usuário conectado regular não tem permissão para fazer, como atualizar um ativo.
Autenticando com a API
Testes no Postman
Usando o API Explorer
Limitação de API
Power BI
ATIVO
/hardware [GET]
[GET] https://demo.gestaodeativos.app.br/api/v1/hardware
Retornar uma listagem de ativos
COLUNAS CLASSIFICÁVEIS
| Nome do campo | Descrição |
|---|---|
| id | IDs de ativos |
| name | Nomes de ativos |
| asset_tag | Tag de ativo exclusivo do ativo |
| serial | Números de série dos ativos |
| model | Nome do modelo de ativo associado |
| model_number | Número do modelo do modelo de ativo associado |
| last_checkout | Data em que o ativo foi submetido ao check-out pela última vez |
| category | Nome da categoria associada ao modelo de ativos |
| manufacturer | Nome do fabricante do ativo |
| notes | Notas de ativos |
| expected_checkin | Data prevista de check-in |
| order_number | Número do pedido associado ao ativo |
| companyName | Nome da empresa associado ao ativo, se aplicável |
| location | Nome do local do ativo, o local padrão Pronto para Implantar ou o local do usuário atribuído |
| image | Nome do arquivo de imagem opcional associado ao ativo |
| status_label | Nome do rótulo de status associado ao ativo |
| assigned_to | Nome da pessoa a quem o ativo é atribuído |
| created_at | Data em que o ativo foi criado |
| purchase_date | Data em que o ativo foi comprado |
| purchase_cost | Custo de compra do ativo |
PARÂMETROS DA CONSULTA
| Parâmetro | Tipo | Descrição |
|---|---|---|
| limit | int32 | Especifique o número de resultados que você deseja retornar. O padrão é 50, mas o definimos como 2 por padrão para que o explorador de API não role para sempre. |
| offset | int32 | Deslocamento a ser usado |
| search | string | Uma cadeia de caracteres de texto para pesquisar os dados de ativos |
| order_number | string | Retornar somente ativos associados a um número de pedido específico |
| sort | string | Especifique o nome da coluna pela qual você deseja classificar |
| order | string | Especifique a ordem (asc ou desc) pela qual você deseja ordenar em sua coluna de classificação |
| model_id | int32 | Opcionalmente, restrinja os resultados dos ativos a essa ID de modelo de ativo |
| category_id | int32 | Opcionalmente, restrinja os resultados dos ativos a essa ID de rótulo de status |
| manufacturer_id | int32 | Opcionalmente, restrinja os resultados dos ativos a essa ID de modelo de ativo |
| company_id | int32 | Opcionalmente, restrinja os resultados dos ativos a esse ID da empresa |
| location_id | int32 | Opcionalmente, restrinja os resultados dos ativos a essa ID de local |
| status | string | Opcionalmente, restrinja os resultados dos ativos a um destes tipos de status: RTD, Implantado, Não implantável, Excluído, Arquivado, Solicitante |
| status_id | int32 | Opcionalmente, restrinja os resultados dos ativos a essa ID de rótulo de status |
RESPOSTAS
RESPOSTA 200
Response body
object
total integer
rows array of object
id integer
name string
asset_tag string
serial string
model object
id integer
name string
model_number string
eol object
date string
formatted string
status_label
object
STATUS_LABEL OBJECT
id integer
name string
status_type string
status_meta string
category object
id integer
name string
manufacturer object
id integer
name string
supplier object
id integer
name string
notes string
order_number string
company string
location object
id integer
name String
rtd_location object
id integer
name string
image string
qr string
alt_barcode string
assigned_to string
warranty_months string
warranty_expires string
created_at object
datetime string
formatted string
updated_at object
datetime string
formatted string
last_audit_date string
next_audit_date string
deleted_at string
purchase_date object
date string
formatted string
age string
last_checkout string
expected_checkin string
purchase_cost string
checkin_counter integer
checkout_counter integer
requests_counter integer
user_can_checkout boolean
custom_fields object
available_actions object
checkout boolean
checkin boolean
clone boolean
restore boolean
update boolean
delete boolean
RESPOSTA 401
Response body
object
status string
messages string
payload string
RESPOSTA 405
Response body
object
status string
messages string
payload string