Documentação PlantScanner

Visão Geral

APIs

Endpoints e integrações disponíveis na plataforma. Saiba mais

API REST

Webhooks

Integrações

Propriedades Reservadas

Propriedades especiais para controle e personalização. Saiba mais

Propriedades de Ordem de Serviço

APIs

Autenticação OAuth2

O PlantScanner utiliza OAuth2 para autenticação. Para integrar com a API, você precisará configurar um cliente OAuth com as seguintes credenciais:

Credenciais do Cliente

{
  "client_id": "portal",
  "client_secret": "gsUkbqCMuv%YcX7z^YhBnJ!#@*uBs26&WpV7agO9H@dZ!unL",
  "scopes": [
    "plantscanner-portal-api",
    "plantscanner-api",
    "offline_access"
  ]
}

Endpoints de Autenticação

URL de Autorização: https://login.plantscanner.io/connect/authorize

URL de Token: https://login.plantscanner.io/connect/token

Fluxo de Autenticação (Authorization Code)

Redirecione o usuário para a URL de autorização com os parâmetros necessários:

GET https://login.plantscanner.io/connect/authorize?
    client_id=portal&
    response_type=code&
    grant_type=authorization_code&
    scope=plantscanner-portal-api plantscanner-api offline_access&
    redirect_uri=<sua-url-de-redirecionamento>

Após a autorização, troque o código por um token:

POST https://login.plantscanner.io/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=portal&
client_secret=<seu-client-secret>&
code=<codigo-recebido>&
redirect_uri=<sua-url-de-redirecionamento>

Use o token recebido nas requisições subsequentes:

Authorization: Bearer <seu-token>

GraphQL API

Além da API REST, o PlantScanner também fornece um endpoint GraphQL para consultas mais flexíveis.

Endpoint: /graphql

Recursos:

Suporte completo para consulta de ordens de serviço e dados relacionados

Capacidades integradas de filtragem e ordenação

Suporte a assinaturas em tempo real

Interface interativa para construção e teste de queries

Exemplo de Queries GraphQL

Webhooks e Notificações

É recomendado utilizar webhooks ao invés de polling as APIs. Para isso, habilite os webhooks e registre uma URL que receberá requisições POST quando os eventos abaixo ocorrerem. Também é possível receber notificações via SMS ou email.

Eventos Disponíveis

ID	Evento	Descrição	Payload
0	ProductionAlert	Disparado quando qualquer alerta de estação de trabalho é invocado por qualquer operador	ProductionAlertHookDto
1	WorkOrderPlanned	Disparado quando uma ordem de serviço é agendada, desagendada ou deslocada	WorkOrderHookDto
2	WorkOrderExecutionBegin	Disparado quando uma ordem de serviço inicia a produção	WorkOrderHookDto
3	WorkOrderExecutionPaused	Disparado quando uma ordem de serviço pausa a produção	WorkOrderHookDto
4	WorkOrderExecutionEnded	Disparado quando o fluxo de uma ordem de serviço é concluído	WorkOrderHookDto
5	WorkOrderReset	Disparado quando uma ordem de serviço é resetada	WorkOrderHookDto
6	WorkOrderConsumedRawMaterialUpdated	Disparado quando um material consumido é atualizado, mesmo com a ordem fechada	WorkOrderHookDto
7	WorkOrderExecutionResumed	Disparado quando uma ordem de serviço pausada é retomada	WorkOrderHookDto
8	MaterialSupplyUpdated	Disparado quando um fornecimento de material é pago	MaterialSupplyPayedHook
9	WorkOrderProducedQuantityUpdated	Disparado quando a quantidade produzida é atualizada via Portal	WorkOrderHookDto
10	CanWorkOrderFinalize	Disparado quando um operador tenta finalizar a ordem, permitindo verificações customizadas	WorkOrderValidationDto
11	CanWorkOrderTrackQuantity	Disparado quando um operador tenta registrar quantidades boas/ruins, permitindo verificações customizadas	WorkOrderValidationDto

Estruturas de Payload

Você consegue através da tela de WebHooks conseguir exemplos de cada um após pelo menos 1 execução.

WorkOrderValidationDto

{
  "Id": 9,
  "Description": "Work Order Produced Quantity",
  "WorkStation": "Fabiano",
  "WorkStationCode": "Fab1",
  "UserTrigger": "superuser@plantscanner.io",
  "EmployeeBadge": null,
  "WorkOrders": [
    {
      "Id": 4309,
      "Type": "Production",
      "WorkOrderGrouper": "1231243",
      "Code": "12301253094",
      "MaterialCode": "SKU001",
      "Customer": "",
      "PromiseDate": "",
      "OperationCode": "Sopra",
      "ProducedQuantityHistory": [
        {
          "Id": 668,
          "Date": "2025-01-23T04:12:55.617811",
          "ProducedGoodQuantity": 4,
          "ProducedBadQuantity": 0
        },
        {
          "Id": 696,
          "Date": "2025-04-15T23:27:07.99094",
          "ProducedGoodQuantity": 59,
          "ProducedBadQuantity": 0
        },
        {
          "Id": 704,
          "Date": "2025-04-29T11:09:43.837144",
          "ProducedGoodQuantity": 60,
          "ProducedBadQuantity": 0
        },
        {
          "Id": 709,
          "Date": "2025-04-29T12:07:26.491461",
          "ProducedGoodQuantity": 65,
          "ProducedBadQuantity": 0
        },
        {
          "Id": 710,
          "Date": "2025-04-29T12:11:17.119494Z",
          "ProducedGoodQuantity": 66,
          "ProducedBadQuantity": 0
        }
      ],
      "Note": "",
      "StatusDescription": null,
      "StatusAdditionalDescription": null,
      "StatusNote": null,
      "RequestedQuantity": 10,
      "ProducedGoodQuantity": 66,
      "ProducedBadQuantity": 0,
      "BeginReal": "2025-01-23T04:12:44.5088",
      "EndReal": null,
      "BeginPlanned": "2024-11-26T07:24:00",
      "EndPlanned": "2024-11-26T07:34:00",
      "RawMaterials": [],
      "Properties": [],
      "LaborPredictedTime": "00:00:00",
      "LaborValueAddedTime": "00:00:00",
      "LaborNonValueAddedTime": "00:00:00",
      "MachinePredictedTime": "00:01:36",
      "MachineValueAddedTime": "00:00:00",
      "MachineNonValueAddedTime": "00:00:00"
    }
  ],
  "ProductionAlert": null,
  "MaterialSupplies": null
}

WorkOrderHookDto

{
  "Id": 4,
  "Description": "Work Order Execution Ended",
  "WorkStation": "NOVO",
  "WorkStationCode": "NOVO",
  "UserTrigger": null,
  "EmployeeBadge": null,
  "WorkOrders": [
    {
      "Id": 4355,
      "Type": "Production",
      "WorkOrderGrouper": "-",
      "Code": "8116",
      "MaterialCode": "PA000021",
      "Customer": null,
      "PromiseDate": "2024-08-12T03:00:00Z",
      "OperationCode": "EMPACOTAMENTO",
      "ProducedQuantityHistory": [
        {
          "Id": 724,
          "Date": "2025-05-22T11:25:11.388699",
          "ProducedGoodQuantity": 12,
          "ProducedBadQuantity": 0
        }
      ],
      "Note": null,
      "StatusDescription": null,
      "StatusAdditionalDescription": null,
      "StatusNote": "",
      "RequestedQuantity": 573,
      "ProducedGoodQuantity": 12,
      "ProducedBadQuantity": 0,
      "BeginReal": "2025-05-22T11:24:47.027551",
      "EndReal": "2025-05-22T11:25:11.399373",
      "BeginPlanned": "2025-05-10T17:08:00",
      "EndPlanned": "2025-05-10T17:18:00",
      "RawMaterials": [
        {
          "Code": "SKU001",
          "Description": "Embalagem Ketchup",
          "Sequence": 0,
          "Quantity": 223,
          "QuantityConsumed": 0,
          "UoM": "UN",
          "ConsumedRawMaterials": [
            {
              "Quantity": 223,
              "SerialNumber": "2.ALI.T-3417"
            }
          ]
        },
        {
          "Code": "RC000010",
          "Description": "",
          "Sequence": 0,
          "Quantity": 1,
          "QuantityConsumed": 0,
          "UoM": "",
          "ConsumedRawMaterials": []
        },
        {
          "Code": "MP000006",
          "Description": "",
          "Sequence": 1,
          "Quantity": 2.44,
          "QuantityConsumed": 0,
          "UoM": "",
          "ConsumedRawMaterials": []
        },
        {
          "Code": "MP000018",
          "Description": "",
          "Sequence": 2,
          "Quantity": 0.24,
          "QuantityConsumed": 0,
          "UoM": "",
          "ConsumedRawMaterials": []
        },
        {
          "Code": "EB000032",
          "Description": "",
          "Sequence": 3,
          "Quantity": 573,
          "QuantityConsumed": 0,
          "UoM": "",
          "ConsumedRawMaterials": []
        }
      ],
      "Properties": [
        {
          "Key": "ProductionOrderNumber",
          "Value": "8116",
          "Name": null,
          "IsLocked": null
        },
        {
          "Key": "ProductionOrderId",
          "Value": "8712",
          "Name": null,
          "IsLocked": null
        },
        {
          "Key": "WarehouseCode",
          "Value": "DP07",
          "Name": null,
          "IsLocked": null
        },
        {
          "Key": "ProductionOrderStatus",
          "Value": "boposReleased",
          "Name": null,
          "IsLocked": null
        },
        {
          "Key": "SAP:Retry",
          "Value": "<a>Clique para enviar</a>",
          "Name": "Enviar ordem SAP",
          "IsLocked": null
        }
      ],
      "LaborPredictedTime": "00:00:00",
      "LaborValueAddedTime": "00:00:00",
      "LaborNonValueAddedTime": "00:00:00",
      "MachinePredictedTime": "00:00:00",
      "MachineValueAddedTime": "00:00:24.3718220",
      "MachineNonValueAddedTime": "00:00:00"
    }
  ],
  "ProductionAlert": null,
  "MaterialSupplies": null
}

ProductionAlertHookDto

{
  "Id": 0,
  "Description": "Production Alert",
  "WorkStation": "PlantScanner 01",
  "WorkStationCode": "PS01",
  "UserTrigger": "superuser@plantscanner.io",
  "EmployeeBadge": null,
  "WorkOrders": null,
  "ProductionAlert": {
    "Id": 84,
    "Type": "Logística",
    "Note": "<b>Observação:</b> ",
    "Status": 3,
    "Opened": "2024-11-21T01:30:49.929674",
    "Acknowledged": "2025-02-01T15:19:40.372835",
    "Closed": "2025-02-01T15:19:44.91526Z"
  },
  "MaterialSupplies": null
}

MaterialSupplyPayedHook

{
  "Id": 8,
  "Description": "Material Task Supply",
  "WorkStation": "Injetora 1",
  "WorkStationCode": "INJ1",
  "UserTrigger": "superuser@plantscanner.io",
  "WorkOrders": null,
  "ProductionAlert": null,
  "MaterialSupplies": [
    {
      "WorkOrderCode": "68792",
      "OperationCode": null,
      "Code": "A572500095",
      "Description": "Material Fabiano",
      "Quantity": 1.4453,
      "IsCompleted": true,
      "Id": 78
    }
  ]
}

Limites e Restrições

Rate Limiting

Limite padrão: 100 requisições por minuto

Headers de resposta:

X-RateLimit-Limit: Limite total de requisições

X-RateLimit-Remaining: Requisições restantes

X-RateLimit-Reset: Timestamp de reset do limite

Paginação

Parâmetros padrão:

page: Número da página (começa em 1)

limit: Itens por página (máximo 100)

Headers de resposta:

X-Pagination-Total: Total de itens

X-Pagination-Pages: Total de páginas

X-Pagination-Current: Página atual

Tratamento de Erros

Códigos de Status HTTP

Código	Descrição	Exemplo de Resposta
200	Sucesso	`{ "data": { ... } }`
400	Requisição inválida	`{ "errors": ["Parâmetro inválido"] }`
401	Não autorizado	`{ "error": "Token inválido ou expirado" }`
403	Acesso negado	`{ "error": "Sem permissão para acessar este recurso" }`
404	Recurso não encontrado	`{ "error": "Ordem de serviço não encontrada" }`
412	Erro de validação	`{ "errors": ["Data de início inválida"] }`
429	Muitas requisições	`{ "error": "Limite de requisições excedido", "retryAfter": 60 }`
500	Erro interno	`{ "logId": "uuid", "message": ["Erro interno do servidor"] }`

Estrutura de Erro Padrão

{
  "logId": "550e8400-e29b-41d4-a716-446655440000",
  "message": [
    "Descrição detalhada do erro"
  ],
  "stackTrace": [
    "Detalhes do stack trace (apenas em ambiente de desenvolvimento)"
  ]
}

Erros de Validação

{
  "errors": [
    "O código da ordem de serviço é obrigatório",
    "A quantidade deve ser maior que zero",
    "A data de início deve ser anterior à data de fim"
  ]
}

Erros de Rate Limit

{
  "error": "Limite de requisições excedido",
  "retryAfter": 60,
  "limit": 100,
  "remaining": 0,
  "reset": "2024-03-20T11:00:00Z"
}

API REST

A API REST do PlantScanner fornece endpoints para gerenciamento de ordens de serviço, equipamentos, usuários e mais.

Propriedades Reservadas

O PlantScanner utiliza propriedades reservadas para controle e personalização de diferentes aspectos do sistema. Estas propriedades são identificadas pelo prefixo PS:.

Integrações

Serviços Suportados

Webhooks

Configuração de Integrações

Para configurar os seus próprios webhooks você pode usar a tela WebHooks

Logs

Os logs do sistema são armazenados em arquivos locais e podem ser solicitados através do nosso email contato@plantscanner.io.

Nota: Esta documentação é um documento vivo e será atualizada conforme novos recursos são adicionados ou modificados.

Developers

Documentação PlantScanner#

Visão Geral#

APIs#

Autenticação OAuth2#

Credenciais do Cliente#

Endpoints de Autenticação#

Fluxo de Autenticação (Authorization Code)#

GraphQL API#

Exemplo de Queries GraphQL#

Webhooks e Notificações#

Eventos Disponíveis#

Estruturas de Payload#

WorkOrderValidationDto#

WorkOrderHookDto#

ProductionAlertHookDto#

MaterialSupplyPayedHook#

Limites e Restrições#

Rate Limiting#

Paginação#

Tratamento de Erros#

Códigos de Status HTTP#

Estrutura de Erro Padrão#

Erros de Validação#

Erros de Rate Limit#

API REST#

Propriedades Reservadas#

Integrações#

Serviços Suportados#

Configuração de Integrações#

Logs#

Documentação PlantScanner

Visão Geral

APIs

Autenticação OAuth2

Credenciais do Cliente

Endpoints de Autenticação

Fluxo de Autenticação (Authorization Code)

GraphQL API

Exemplo de Queries GraphQL

Webhooks e Notificações

Eventos Disponíveis

Estruturas de Payload

WorkOrderValidationDto

WorkOrderHookDto

ProductionAlertHookDto

MaterialSupplyPayedHook

Limites e Restrições

Rate Limiting

Paginação

Tratamento de Erros

Códigos de Status HTTP

Estrutura de Erro Padrão

Erros de Validação

Erros de Rate Limit

API REST

Propriedades Reservadas

Integrações

Serviços Suportados

Configuração de Integrações

Logs