Add-on necessário
Uso geral — sem add-on específico.

GET https://app.fracttal.com/api/items_spare_parts/
GET https://app.fracttal.com/api/items_spare_parts/{code}

O código do ativo também é aceito como parte do caminho. Se for enviado no caminho e como parâmetro code, prevalece o do caminho.

Parâmetros de entrada — Obrigatórios

Enviados como query params (ou code no caminho).

Parâmetro	Tipo	Obrigatório	Descrição
`code`	texto	Sim	Código do ativo. É um texto: os zeros à esquerda são preservados. A busca é exata e diferencia maiúsculas, minúsculas e espaços.

Parâmetros de entrada — Opcionais

Parâmetro	Tipo	Obrigatório	Descrição
`item_type`	texto	Não (recomendado)	Tipo do ativo, de `1` a `5`: `1` Localizações, `2` Equipamentos, `3` Ferramentas, `4` Peças e suprimentos, `5` Digitais. O código de um ativo não é único e pode se repetir entre tipos; se o código coincidir com mais de um ativo e `item_type` não for enviado, a API responde `400` e não retorna dados. Recomenda-se enviá-lo sempre.
`start`	texto	Não	Registro a partir do qual a consulta começa. Padrão `0`. Um valor negativo ou não numérico responde `400`.
`limit`	texto	Não	Quantidade de registros por página. Padrão e máximo `100`. Um valor menor que `1`, maior que `100` ou não numérico responde `400`.

Um valor vazio em qualquer um desses parâmetros é tratado como se não tivesse sido enviado.

Permissões necessárias
A aplicação se autentica com OAuth2 (client_credentials). Seu grupo de permissões deve ter view sobre o módulo de ativos em Localizações, Equipamentos e Peças e Suprimentos, e em particular sobre o tipo do ativo consultado. Sem essa permissão, a API responde com um erro de autorização (ver a seção de erros).

O que a consulta retorna

Somente peças e suprimentos são retornados. Ferramentas e outros tipos de recursos de um plano de tarefas não aparecem.

Do plano de tarefas do ativo, são incluídas apenas as tarefas ativas e não paradas, de planos ativos.

Uma mesma peça pode aparecer várias vezes: uma pela ficha do ativo e uma por cada tarefa do plano que a utiliza. Use origin e task para diferenciá-las. As quantidades nunca são somadas.

As peças inativas também são retornadas; são identificadas por is_active = false.

As linhas são ordenadas por origin (asset antes de task_plan) e depois por code.

A API não pagina automaticamente: se total for maior que a quantidade de linhas recebidas, repita a consulta incrementando start com o valor de limit.

Parâmetros de saída

Parâmetro	Tipo	Descrição
`success`	booleano	`true` se a consulta foi bem-sucedida.
`message`	texto	`"200"` em caso de sucesso; código ou mensagem de erro caso contrário.
`total`	inteiro	Quantidade total de linhas do ativo, antes da paginação — não o tamanho da página retornada.
`data`	array de objetos	Página de resultados. Ver a estrutura na tabela a seguir.

Estrutura de cada elemento em data:

Parâmetro	Tipo	Descrição
`code`	texto	Código da peça ou suprimento.
`description`	texto	Descrição da peça ou suprimento.
`qty`	número	Quantidade (aceita decimais). Com `origin = asset` é a quantidade registrada na ficha do ativo; com `origin = task_plan` é a quantidade por execução da tarefa.
`unit`	texto	Unidade de medida. `null` se a peça não tiver unidade.
`is_active`	booleano	`true` se a peça está ativa.
`origin`	texto	`asset`: provém da ficha do ativo. `task_plan`: provém de um plano de tarefas do ativo.
`task`	texto	Descrição da tarefa do plano que utiliza o recurso. `null` quando `origin` é `asset`.

Erros

Código	Causa
`400`	Falta `code`; `item_type` fora do intervalo de `1` a `5`; `start` ou `limit` inválidos; ou o código coincide com mais de um ativo (enviar `item_type`). O detalhe vem em `data[0].ERROR`.
`401`	A aplicação não tem permissão `view` sobre o tipo do ativo consultado. Chega com `data.Error = "UNAUTHORIZED_ENDPOINT"`.
`404`	O código não existe na empresa. O detalhe vem em `data[0].ERROR`.
`INVALID_TOKEN`	Token inválido ou sem autorização para a empresa.
`INVALID_ENDPOINT`	O serviço não está habilitado para a aplicação.
`UNAUTHORIZED_ENDPOINT`	O grupo de permissões da aplicação não cumpre a permissão necessária.
`UNAUTHORIZED_USE`	A empresa não tem o uso da API habilitado.
`ERROR_SQL`	Erro interno não controlado.

Nota sobre os erros de autorização
Um erro de permissões pode chegar de duas formas: com message: "401" e data.Error = "UNAUTHORIZED_ENDPOINT", ou com message: "UNAUTHORIZED_ENDPOINT" e data: null. Em ambos os casos significa que o grupo de permissões da aplicação não tem a permissão necessária. Nas respostas de erro 400 e 404, o campo total chega como texto ("0").

Exemplo

Request

GET https://app.fracttal.com/api/items_spare_parts/?code=EQ-0042&item_type=2&start=0&limit=50

Response `200`

{
  "success": true,
  "message": "200",
  "total": 3,
  "data": [
    {
      "code": "REP-001",
      "description": "Rodamiento 6002 { REP-001 }",
      "qty": 2,
      "unit": "Unidad",
      "is_active": true,
      "origin": "asset",
      "task": null
    },
    {
      "code": "REP-002",
      "description": "Filtro de aceite { REP-002 }",
      "qty": 1,
      "unit": "Litros",
      "is_active": true,
      "origin": "task_plan",
      "task": "Mantenimiento cada 250 hr"
    },
    {
      "code": "REP-002",
      "description": "Filtro de aceite { REP-002 }",
      "qty": 4,
      "unit": "Litros",
      "is_active": false,
      "origin": "task_plan",
      "task": "Mantenimiento anual"
    }
  ]
}

Response — Ativo sem peças (`200`)

{
  "success": true,
  "message": "200",
  "total": 0,
  "data": []
}

Response — Código ausente (`400`)

{
  "success": false,
  "message": "400",
  "total": "0",
  "data": [
    { "ERROR": "code is required" }
  ]
}

Response — Código repetido sem `item_type` (`400`)

{
  "success": false,
  "message": "400",
  "total": "0",
  "data": [
    { "ERROR": "code matches more than one item, item_type is required: EQ-0042" }
  ]
}

Response — Código inexistente (`404`)

{
  "success": false,
  "message": "404",
  "total": "0",
  "data": [
    { "ERROR": "code does not exist: EQ-9999" }
  ]
}

Response — Sem permissão sobre o tipo do ativo (`401`)

{
  "success": false,
  "message": "401",
  "data": { "Error": "UNAUTHORIZED_ENDPOINT" }
}

OpenAPI definition

{
  "openapi": "3.1.0",
  "info": {
    "title": "Peças e suprimentos de um ativo",
    "version": "3-pt"
  },
  "servers": [
    { "url": "https://app.fracttal.com/api/items_spare_parts" }
  ],
  "security": [{}],
  "paths": {
    "/": {
      "get": {
        "summary": "Consultar peças e suprimentos de um ativo",
        "description": "",
        "operationId": "consultar-pecas-e-suprimentos-de-um-ativo",
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}

Add-on necessário

Parâmetros de entrada — Obrigatórios

Parâmetros de entrada — Opcionais

Permissões necessárias

O que a consulta retorna

Parâmetros de saída

Erros

Nota sobre os erros de autorização

Exemplo

Request

Response 200

Response — Ativo sem peças (200)

Response — Código ausente (400)

Response — Código repetido sem item_type (400)

Response — Código inexistente (404)

Response — Sem permissão sobre o tipo do ativo (401)

OpenAPI definition

Response `200`

Response — Ativo sem peças (`200`)

Response — Código ausente (`400`)

Response — Código repetido sem `item_type` (`400`)

Response — Código inexistente (`404`)

Response — Sem permissão sobre o tipo do ativo (`401`)