API

Liga a tua loja a software externo sem remendos

A API publica da Revolio permite consultar reparacoes, criar orcamentos, gerir pagamentos, mensagens, clientes, pecas e sincronizacoes WooCommerce a partir do teu stack.

Atualizado em abril de 2026

Esta pagina organiza a documentacao publica da API num formato mais claro do que o resumo atual do dashboard. O objetivo e dar-te uma vista operacional rapida sobre o que ja podes integrar hoje.

Toda a autenticacao e feita por chave API, cada pedido e isolado por loja e cada operacao respeita scopes dedicados para manter a integracao controlada desde o primeiro pedido.

Autenticacao e arranque

Aprende a criar a tua chave, autenticar pedidos e validar o acesso com a primeira chamada.

  • Chaves API por loja
  • Header X-API-Key ou Bearer
  • Scopes por operacao
  • Primeira chamada em /health
Ver arranque rapido

Reparacoes, clientes e operacoes

Consulta reparacoes, atualiza estados, gere mensagens, pagamentos e le indicadores chave da loja.

  • Listagem e detalhe de reparacoes
  • Mensagens e pagamentos por reparacao
  • Clientes e estatisticas da loja
  • Orcamentos e pricing por servico
Explorar capacidades

Catalogo, pecas e integracoes

Liga catalogo, fornecedores, encomenda pecas e conecta fluxos WooCommerce com scopes dedicados.

  • Modelos, marcas e avarias
  • Pecas, stock, shipping e pedido
  • Fornecedores e ofertas
  • Endpoints WooCommerce para sync
Ver acessos e limites

Arranque rapido

Se queres validar uma integracao em menos de 10 minutos, este e o fluxo minimo para autenticar, confirmar scopes e fazer a primeira chamada.

Passo 1

Criar a chave API

Entra no dashboard do lojista, abre Configuracoes e gera uma chave para a tua integracao.

Passo 2

Autenticar cada pedido

Envia a chave em X-API-Key ou Authorization: Bearer. Cada chave fica associada a uma loja e aos respetivos scopes.

Passo 3

Validar antes de integrar

Comeca em /health para confirmar que a chave esta valida e que os scopes devolvidos cobrem a operacao que vais executar.

Base URL

https://www.revolio.io/api/public/v1

Headers aceites

X-API-Key: rvl_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer rvl_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxx

Exemplo de Pedido

curl -X GET https://www.revolio.io/api/public/v1/health \
  -H "X-API-Key: rvl_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxx"

Acesso e suporte

As chaves sao geridas no dashboard do lojista. Se precisares de ajustar scopes, validar a tua integracao ou discutir um fluxo especifico, usa os acessos abaixo.

Gerir chaves API no dashboardDownload OpenAPIDownload Postman CollectionFalar com a equipa

Capacidades atuais da API

Esta lista resume as familias de endpoints que hoje ja estao disponiveis para integracao. Os caminhos abaixo seguem o que o backend expõe atualmente.

Fluxo de reparacoes

Acompanha o ciclo completo de uma reparacao: listagem, criacao, detalhe, eventos, servicos, items, estados e pagamentos.

GET/api/public/v1/repairs

Listar reparacoes da sua loja. Suporta paginacao e filtros.

Scope necessario: repairs.read

POST/api/public/v1/repairs

Criar uma reparacao (checkout nativo WooCommerce).

Scope necessario: repairs.write

POST/api/public/v1/repairs/quote

Obter orcamento (precos) para servicos de reparacao.

Scope necessario: pricing.read

POST/api/public/v1/repairs/{id}/status

Atualizar o estado da reparacao e registar notas operacionais.

Scope necessario: repairs.write

Clientes, mensagens e pagamentos

Cruza relacao com cliente e operacao: lista clientes, consulta indicadores, envia mensagens e regista pagamentos por reparacao.

GET/api/public/v1/customers

Listar clientes da loja com pesquisa, contagem de reparacoes e ultima atividade.

Scope necessario: customers.read

GET/api/public/v1/stats

Obter resumo de reparacoes, clientes e receita agregada da loja.

Scope necessario: repairs.read

POST/api/public/v1/repairs/{id}/messages

Enviar uma mensagem no thread da reparacao.

Scope necessario: messages.write

POST/api/public/v1/repairs/{id}/payments

Registar um pagamento numa reparacao.

Scope necessario: payments.write

Pecas e fornecedores

Pesquisa catalogo de pecas, compara ofertas, calcula shipping e cria pedidos com validacao de stock.

GET/api/public/v1/spare-parts

Listar pecas com filtros por marca, equipamento, categoria, componente e pesquisa livre.

Scope necessario: parts.read

POST/api/public/v1/spare-parts/order

Criar um pedido de pecas com validacao de stock, tax e total final.

Scope necessario: parts.read + orders.write

POST/api/public/v1/spare-parts/shipping

Calcular custo de envio de pecas antes de fechar a encomenda.

Scope necessario: parts.read

GET/api/public/v1/suppliers

Listar fornecedores aprovados e filtrar por pesquisa.

Scope necessario: suppliers.read

Catalogo tecnico e WooCommerce

Usa o catalogo tecnico da Revolio para alimentar o teu checkout e liga o plugin WooCommerce para sincronizacoes operacionais.

GET/api/public/v1/catalog/device-models

Listar modelos de equipamento por marca, categoria ou pesquisa.

Scope necessario: repairs.read

GET/api/public/v1/catalog/problem-types

Obter tipos de avaria para alimentar orcamentos e fluxos de criacao.

Scope necessario: repairs.read

GET/api/public/v1/woocommerce/capabilities

Consultar o que a instalacao WooCommerce pode sincronizar com a tua chave atual.

Scope necessario: products.read

POST/api/public/v1/woocommerce/connect

Ligar uma instalacao WooCommerce, gerar credenciais e preparar webhooks de sincronizacao.

Referencia detalhada por endpoint

Cada bloco abaixo usa exemplos de request e response alinhados com os route handlers atuais. Quando um endpoint nao aceita body, isso aparece explicitamente.

Referencia verificada diretamente a partir dos route handlers atuais e usada tambem nos downloads publicos.

Acesso e contexto

Valida a chave, inspeciona o contexto autenticado e confirma que a tua loja responde com o scope esperado antes de passares para operacoes mais sensiveis.

GET/api/public/v1/health

Validar a chave API e devolver o contexto autenticado da loja.

Auth por API key

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "status": "ok",
  "version": "v1",
  "time": "2026-04-05T12:00:00.000Z",
  "context": {
    "repairShopId": "shop_123",
    "keyId": "key_123",
    "keyName": "WooCommerce sync",
    "scopes": [
      "repairs.read",
      "repairs.write",
      "products.write"
    ]
  }
}
GET/api/public/v1/me

Obter um resumo do perfil autenticado da loja.

Scope necessario: parts.readAuth por API key

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "ok": true,
  "data": {
    "countryCode": "PT",
    "country": "Portugal",
    "companyName": "Loja Exemplo",
    "city": "Lisboa",
    "postalCode": "1000-001",
    "street": "Rua da Revolio 10"
  }
}

Catalogo tecnico

Consulta o catalogo que suporta os fluxos publicos e operacionais: marcas, categorias, modelos, tipos de avaria, estados e componentes.

GET/api/public/v1/catalog/brands

Listar marcas ativas do catalogo.

Scope necessario: repairs.readAuth por API key

Parametros de Query:

limit=100 max 200offset=0search=name

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "brand_apple",
      "name": "Apple",
      "logo": "https://cdn.revolio.io/brands/apple.svg"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/catalog/categories

Listar categorias ativas do catalogo.

Scope necessario: repairs.readAuth por API key

Parametros de Query:

limit=100 max 200offset=0search=name

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "cat_phone",
      "name": "Smartphones",
      "description": "Telemoveis e smartphones",
      "image": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/catalog/component-types

Listar tipos de componente usados nos filtros de pecas.

Scope necessario: parts.readAuth por API key

Parametros de Query:

limit=100 max 200offset=0search=name

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "component_screen",
      "name": "Ecra",
      "icon": "monitor",
      "color": "#0F766E"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/catalog/device-models

Listar modelos de equipamento por marca, categoria ou pesquisa.

Scope necessario: repairs.readAuth por API key

Parametros de Query:

limit=100 max 200offset=0id=deviceModelIdsearch=namebrandId=brand_applecategoryId=cat_phone

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "dm_iphone_14_pro",
      "name": "iPhone 14 Pro",
      "releaseYear": 2022,
      "image": "https://cdn.revolio.io/device-models/iphone-14-pro.png",
      "brand": {
        "id": "brand_apple",
        "name": "Apple"
      },
      "category": {
        "id": "cat_phone",
        "name": "Smartphones"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/catalog/problem-types

Obter tipos de avaria para alimentar orcamentos e fluxos de criacao.

Scope necessario: repairs.readAuth por API key

Parametros de Query:

limit=100 max 200offset=0id=problemTypeIdsearch=name

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "problem_screen",
      "name": "Ecra partido",
      "description": "Substituicao de ecra ou vidro",
      "icon": "smartphone",
      "categoryIds": [
        "cat_phone"
      ],
      "mappingTags": [
        "screen",
        "display"
      ]
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/catalog/repair-statuses

Listar todos os estados de reparacao suportados.

Scope necessario: repairs.readAuth por API key

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    "PENDING_PAYMENT",
    "PAYMENT_FAILED",
    "PAID",
    "CONFIRMED",
    "IN_REPAIR",
    "COMPLETED",
    "DELIVERED"
  ]
}

Reparacoes e operacao

Toda a camada operacional de reparacoes: listagem, criacao, detalhe, timeline, items, servicos, mensagens, pagamentos e alteracao de estado.

GET/api/public/v1/repairs

Listar reparacoes da sua loja. Suporta paginacao e filtros.

Scope necessario: repairs.readAuth por API key

Parametros de Query:

limit=20 max 100offset=0status=PENDING_PAYMENTtrackingCode=REP-ABC123

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "repair_123",
      "trackingCode": "REP-ABC123",
      "status": "PENDING_PAYMENT",
      "customerName": "Joao Silva",
      "customerPhone": "+351912345678",
      "deviceDescription": "iPhone 14 Pro",
      "description": "Ecra partido",
      "estimatedPrice": 129.9,
      "finalPrice": 129.9,
      "createdAt": "2026-04-05T12:00:00.000Z",
      "updatedAt": "2026-04-05T12:00:00.000Z",
      "completedDate": null,
      "deliveredAt": null,
      "device": {
        "id": "dm_iphone_14_pro",
        "name": "iPhone 14 Pro",
        "brand": {
          "id": "brand_apple",
          "name": "Apple"
        }
      },
      "problemType": {
        "id": "problem_screen",
        "name": "Ecra partido"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
POST/api/public/v1/repairs

Criar uma reparacao (checkout nativo WooCommerce).

Scope necessario: repairs.writeAuth por API key

Exemplo de request

{
  "customer": {
    "name": "Joao Silva",
    "email": "joao@example.com",
    "phone": "+351912345678",
    "city": "Lisboa",
    "postalCode": "1000-001",
    "country": "PT"
  },
  "device": {
    "deviceModelId": "dm_iphone_14_pro",
    "description": "iPhone 14 Pro 128GB"
  },
  "imei": "490154203237518",
  "services": [
    {
      "problemTypeId": "problem_screen",
      "description": "Substituicao de ecra",
      "price": 129.9,
      "estimatedTime": 60
    }
  ],
  "deliveryMethod": "STORE_PICKUP",
  "description": "Cliente deixou o equipamento no balcao",
  "external": {
    "source": "woocommerce",
    "orderId": "WC-1001"
  }
}

Exemplo de response

{
  "data": {
    "repairId": "repair_123",
    "trackingCode": "REP-ABC123",
    "total": 129.9,
    "currency": "EUR",
    "status": "PENDING_PAYMENT"
  }
}
POST/api/public/v1/repairs/quote

Obter orcamento (precos) para servicos de reparacao.

Scope necessario: pricing.readAuth por API key

Exemplo de request

{
  "services": [
    {
      "problemTypeId": "problem_screen",
      "deviceModelId": "dm_iphone_14_pro"
    }
  ]
}

Exemplo de response

{
  "data": {
    "currency": "EUR",
    "total": 129.9,
    "lines": [
      {
        "problemTypeId": "problem_screen",
        "repairShopPriceId": "price_123",
        "basePrice": 129.9,
        "hasVariants": false,
        "variants": [],
        "selectedVariantId": null,
        "resolvedPrice": 129.9,
        "estimatedTime": 60,
        "warrantyMonths": 6
      }
    ]
  }
}
GET/api/public/v1/repairs/{id}

Obter o detalhe completo de uma reparacao.

Scope necessario: repairs.readAuth por API key

Path params

id=repairId

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": {
    "id": "repair_123",
    "trackingCode": "REP-ABC123",
    "status": "PENDING_PAYMENT",
    "priority": "NORMAL",
    "customer": {
      "name": "Joao Silva",
      "phone": "+351912345678",
      "email": "joao@example.com"
    },
    "device": {
      "id": "dm_iphone_14_pro",
      "name": "iPhone 14 Pro",
      "brand": {
        "id": "brand_apple",
        "name": "Apple"
      },
      "description": "iPhone 14 Pro 128GB"
    },
    "problemType": {
      "id": "problem_screen",
      "name": "Ecra partido"
    },
    "description": "Cliente deixou o equipamento no balcao",
    "internalNotes": null,
    "pricing": {
      "estimated": 129.9,
      "final": 129.9,
      "paid": 0
    },
    "parts": [
      {
        "id": "repair_part_1",
        "name": "Ecra OLED",
        "quantity": 1,
        "unitPrice": 79.9,
        "totalPrice": 79.9
      }
    ],
    "dates": {
      "created": "2026-04-05T12:00:00.000Z",
      "updated": "2026-04-05T12:00:00.000Z",
      "estimatedCompletion": null,
      "completed": null,
      "delivered": null
    },
    "statusHistory": [
      {
        "id": "hist_1",
        "status": "PENDING_PAYMENT",
        "notes": "Created via Public API",
        "timestamp": "2026-04-05T12:00:00.000Z"
      }
    ]
  }
}
POST/api/public/v1/repairs/{id}/status

Atualizar o estado da reparacao e registar notas operacionais.

Scope necessario: repairs.writeAuth por API key

Path params

id=repairId

Exemplo de request

{
  "status": "IN_REPAIR",
  "notes": "Equipamento em bancada"
}

Exemplo de response

{
  "data": {
    "id": "repair_123",
    "status": "IN_REPAIR"
  }
}
GET/api/public/v1/repairs/{id}/items

Listar items associados a uma reparacao.

Scope necessario: repairs.readAuth por API key

Path params

id=repairId

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "repair_item_1",
      "name": "Ecra OLED",
      "description": "Ecra premium",
      "quantity": 1,
      "price": 79.9,
      "createdAt": "2026-04-05T12:05:00.000Z",
      "updatedAt": "2026-04-05T12:05:00.000Z",
      "part": {
        "id": "part_1",
        "sku": "SCR-IPH14PRO",
        "name": "Ecra OLED"
      }
    }
  ]
}
GET/api/public/v1/repairs/{id}/services

Listar servicos associados a uma reparacao.

Scope necessario: repairs.readAuth por API key

Path params

id=repairId

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "service_1",
      "description": "Substituicao de ecra",
      "price": 129.9,
      "estimatedTime": 60,
      "sortOrder": 0,
      "createdAt": "2026-04-05T12:00:00.000Z",
      "updatedAt": "2026-04-05T12:00:00.000Z",
      "problemType": {
        "id": "problem_screen",
        "name": "Ecra partido"
      },
      "selectedVariant": null,
      "selectedSparePart": null,
      "supplier": null
    }
  ]
}
GET/api/public/v1/repairs/{id}/messages

Listar mensagens do thread da reparacao.

Scope necessario: messages.readAuth por API key

Path params

id=repairId

Parametros de Query:

limit=50 max 100offset=0

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "msg_1",
      "message": "A reparacao ja entrou em bancada.",
      "createdAt": "2026-04-05T13:00:00.000Z",
      "updatedAt": "2026-04-05T13:00:00.000Z",
      "sender": {
        "id": "shop_123",
        "name": "Loja Exemplo",
        "email": "loja@example.com",
        "role": "REPAIR_SHOP"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
POST/api/public/v1/repairs/{id}/messages

Enviar uma mensagem no thread da reparacao.

Scope necessario: messages.writeAuth por API key

Path params

id=repairId

Exemplo de request

{
  "message": "A reparacao ja entrou em bancada."
}

Exemplo de response

{
  "data": {
    "id": "msg_1",
    "message": "A reparacao ja entrou em bancada.",
    "createdAt": "2026-04-05T13:00:00.000Z",
    "updatedAt": "2026-04-05T13:00:00.000Z"
  }
}
GET/api/public/v1/repairs/{id}/payments

Listar pagamentos de uma reparacao.

Scope necessario: payments.readAuth por API key

Path params

id=repairId

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "payment_1",
      "amount": 129.9,
      "currency": "eur",
      "status": "COMPLETED",
      "method": "woocommerce",
      "paymentMethodType": "card",
      "paymentMethodDetails": {
        "orderId": "WC-1001"
      },
      "platformFee": null,
      "shopAmount": null,
      "failureReason": null,
      "createdAt": "2026-04-05T14:00:00.000Z",
      "updatedAt": "2026-04-05T14:00:00.000Z",
      "releasedAt": null
    }
  ]
}
POST/api/public/v1/repairs/{id}/payments

Registar um pagamento numa reparacao.

Scope necessario: payments.writeAuth por API key

Path params

id=repairId

Exemplo de request

{
  "amount": 129.9,
  "currency": "EUR",
  "status": "COMPLETED",
  "method": "woocommerce",
  "paymentMethodType": "card",
  "details": {
    "orderId": "WC-1001"
  }
}

Exemplo de response

{
  "data": {
    "id": "payment_1",
    "amount": 129.9,
    "currency": "eur",
    "status": "COMPLETED",
    "method": "woocommerce",
    "createdAt": "2026-04-05T14:00:00.000Z",
    "repair": {
      "id": "repair_123",
      "status": "PAID"
    }
  }
}
GET/api/public/v1/repairs/{id}/events

Obter a timeline de eventos de uma reparacao.

Scope necessario: repairs.readAuth por API key

Path params

id=repairId

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "hist_1",
      "type": "status_changed",
      "status": "IN_REPAIR",
      "notes": "Equipamento em bancada",
      "updatedBy": "shop_123",
      "updatedByType": "REPAIR_SHOP",
      "employee": null,
      "createdAt": "2026-04-05T14:10:00.000Z"
    }
  ]
}

Clientes e analitica

Consulta o relacionamento da loja com os clientes e os indicadores operacionais agregados sem sair do canal da API publica.

GET/api/public/v1/customers

Listar clientes da loja com pesquisa, contagem de reparacoes e ultima atividade.

Scope necessario: customers.readAuth por API key

Parametros de Query:

limit=20 max 100offset=0search=name|email|phone

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "customer_1",
      "name": "Joao Silva",
      "email": "joao@example.com",
      "phone": "+351912345678",
      "nif": "123456789",
      "address": "Rua da Revolio 10",
      "city": "Lisboa",
      "postalCode": "1000-001",
      "country": "PT",
      "repairsCount": 3,
      "lastRepairAt": "2026-04-05T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/customers/{id}

Obter o detalhe de um cliente e as suas reparacoes recentes.

Scope necessario: customers.readAuth por API key

Path params

id=customerId

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": {
    "id": "customer_1",
    "name": "Joao Silva",
    "email": "joao@example.com",
    "phone": "+351912345678",
    "nif": "123456789",
    "address": "Rua da Revolio 10",
    "city": "Lisboa",
    "postalCode": "1000-001",
    "country": "PT",
    "repairsCount": 3,
    "recentRepairs": [
      {
        "id": "repair_123",
        "trackingCode": "REP-ABC123",
        "status": "PENDING_PAYMENT",
        "deviceDescription": "iPhone 14 Pro",
        "estimatedPrice": 129.9,
        "finalPrice": 129.9,
        "createdAt": "2026-04-05T12:00:00.000Z"
      }
    ],
    "createdAt": "2025-10-12T09:00:00.000Z",
    "updatedAt": "2026-04-05T12:00:00.000Z"
  }
}
GET/api/public/v1/stats

Obter resumo de reparacoes, clientes e receita agregada da loja.

Scope necessario: repairs.readAuth por API key

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": {
    "repairs": {
      "total": 340,
      "thisMonth": 25,
      "lastMonth": 21,
      "byStatus": {
        "pending": 9,
        "inProgress": 7,
        "completed": 17
      }
    },
    "customers": {
      "total": 210
    },
    "revenue": {
      "total": 48210.5,
      "thisMonth": 3290.2
    },
    "generatedAt": "2026-04-05T12:00:00.000Z"
  }
}
GET/api/public/v1/analytics/repairs

Obter analitica agregada de reparacoes por intervalo temporal.

Scope necessario: repairs.readAuth por API key

Parametros de Query:

from=ISO dateto=ISO date

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": {
    "range": {
      "from": "2026-03-01T00:00:00.000Z",
      "to": "2026-03-31T23:59:59.999Z"
    },
    "repairs": {
      "created": 25,
      "completed": 18,
      "byStatus": {
        "PAID": 4,
        "IN_REPAIR": 7,
        "COMPLETED": 10
      },
      "avgCompletionDays": 2.4
    },
    "customers": {
      "unique": 21
    },
    "revenue": {
      "total": 3290.2
    },
    "series": {
      "dailyCreatedRepairs": [
        {
          "date": "2026-03-01",
          "count": 2
        },
        {
          "date": "2026-03-02",
          "count": 1
        }
      ]
    }
  }
}

Pecas, ofertas e fornecedores

Tens duas camadas de pecas na API: a lista legacy `/parts` e o catalogo expandido `/spare-parts` com shipping, ordering e comparacao de ofertas.

GET/api/public/v1/parts

Listar a camada legacy de pecas.

Scope necessario: parts.readAuth por API key

Parametros de Query:

limit=20 max 100offset=0search=name|skubrandId=brand_appledeviceId=device_123

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "part_1",
      "sku": "SCR-IPH14PRO",
      "name": "Ecra OLED",
      "description": "Ecra premium",
      "category": "Displays",
      "price": 79.9,
      "stock": 12,
      "images": [
        "https://cdn.revolio.io/parts/scr-iph14pro.png"
      ],
      "brand": {
        "id": "brand_apple",
        "name": "Apple"
      },
      "device": {
        "id": "device_123",
        "name": "iPhone 14 Pro"
      },
      "createdAt": "2026-04-05T12:00:00.000Z",
      "updatedAt": "2026-04-05T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
GET/api/public/v1/spare-parts

Listar pecas com filtros por marca, equipamento, categoria, componente e pesquisa livre.

Scope necessario: parts.readAuth por API key

Parametros de Query:

limit=20 max 100offset=0search=name|sku|descriptionbrandId=brand_appledeviceId=device_123categoryId=cat_phonecomponentTypeId=component_screensortBy=price_asc

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "spare_part_1",
      "sku": "SCR-IPH14PRO",
      "ean": "1234567890123",
      "name": "Ecra OLED",
      "description": "Ecra premium",
      "price": 74.9,
      "originalPrice": 79.9,
      "stock": 12,
      "images": [
        "https://cdn.revolio.io/parts/scr-iph14pro.png"
      ],
      "availability": true,
      "deliveryTime": 1,
      "category": {
        "id": "cat_phone",
        "name": "Smartphones"
      },
      "brand": {
        "id": "brand_apple",
        "name": "Apple",
        "logo": "https://cdn.revolio.io/brands/apple.svg"
      },
      "device": {
        "id": "dm_iphone_14_pro",
        "name": "iPhone 14 Pro",
        "image": "https://cdn.revolio.io/device-models/iphone-14-pro.png"
      },
      "componentType": {
        "id": "component_screen",
        "name": "Ecra"
      },
      "compatibility": [
        "iPhone 14 Pro"
      ],
      "createdAt": "2026-04-05T12:00:00.000Z",
      "offers": [
        {
          "source": "SPARE_PART",
          "partId": "spare_part_1",
          "supplierName": "Revolio",
          "isOfficialSupplier": true,
          "price": 79.9,
          "stock": 12,
          "availability": true,
          "deliveryTime": 1
        },
        {
          "source": "SUPPLIER_PRODUCT",
          "supplierProductId": "sup_prod_1",
          "supplierId": "supplier_1",
          "supplierName": "Distribuidor X",
          "supplierLogo": null,
          "isOfficialSupplier": false,
          "price": 74.9,
          "stock": 5,
          "availability": true,
          "deliveryTime": 2
        }
      ]
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}
POST/api/public/v1/spare-parts/order

Criar um pedido de pecas com validacao de stock, tax e total final.

Scope necessario: parts.read + orders.writeAuth por API key

Exemplo de request

{
  "items": [
    {
      "partId": "spare_part_1",
      "quantity": 1
    }
  ],
  "notes": "Pedido para bancada 3"
}

Exemplo de response

{
  "data": {
    "id": "sp_order_1",
    "orderNumber": "SP1712323123ABCD",
    "status": "PENDING",
    "items": [
      {
        "id": "item_1",
        "name": "Ecra OLED",
        "sku": "SCR-IPH14PRO",
        "quantity": 1,
        "price": 79.9,
        "totalPrice": 79.9
      }
    ],
    "shippingCost": 5.5,
    "tax": 19.66,
    "total": 105.06,
    "currency": "EUR",
    "createdAt": "2026-04-05T15:00:00.000Z"
  }
}
POST/api/public/v1/spare-parts/shipping

Calcular custo de envio de pecas antes de fechar a encomenda.

Scope necessario: parts.readAuth por API key

Exemplo de request

{
  "items": [
    {
      "partId": "spare_part_1",
      "quantity": 1
    }
  ]
}

Exemplo de response

{
  "ok": true,
  "data": {
    "shippingCost": 5.5,
    "breakdown": [
      {
        "supplierId": "REVOLIO",
        "cost": 5.5
      }
    ]
  }
}
GET/api/public/v1/suppliers

Listar fornecedores aprovados e filtrar por pesquisa.

Scope necessario: suppliers.readAuth por API key

Parametros de Query:

limit=20 max 100offset=0search=name

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "data": [
    {
      "id": "supplier_1",
      "name": "Distribuidor X",
      "email": "comercial@distribuidorx.pt",
      "phone": "+351210000000",
      "website": "https://distribuidorx.pt",
      "taxId": "PT123456789",
      "address": "Av. Central 20",
      "city": "Porto",
      "postalCode": "4000-100",
      "country": "PT",
      "contactPerson": "Ana Costa",
      "paymentTerms": "30 dias",
      "rating": 4.8,
      "isReparia": false,
      "isActive": true,
      "createdAt": "2025-11-10T10:00:00.000Z",
      "updatedAt": "2026-04-05T11:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

WooCommerce e sync

Endpoints para ligar uma instalacao WooCommerce, sincronizar clientes, encomendas e produtos e promover scopes sem reinstalar a chave.

GET/api/public/v1/woocommerce/capabilities

Consultar o que a instalacao WooCommerce pode sincronizar com a tua chave atual.

Scope necessario: products.readAuth por API key

Exemplo de request

Este endpoint nao recebe body JSON.

Exemplo de response

{
  "ok": true,
  "data": {
    "repairShopId": "shop_123",
    "siteUrl": "https://lojaexemplo.pt",
    "integration": {
      "appId": "woocommerce",
      "installationId": "install_1",
      "status": "ACTIVE"
    },
    "apps": {
      "inventoryManager": true
    }
  }
}
POST/api/public/v1/woocommerce/connect

Ligar uma instalacao WooCommerce, gerar credenciais e preparar webhooks de sincronizacao.

Auth por email e password

Exemplo de request

{
  "email": "owner@lojaexemplo.pt",
  "password": "password-super-segura",
  "siteUrl": "https://lojaexemplo.pt",
  "installationName": "Woo principal"
}

Exemplo de response

{
  "ok": true,
  "data": {
    "installationId": "install_1",
    "webhookSecret": "whsec_xxxxxxxxxxxxxxxxx",
    "publicApiKey": {
      "token": "rvl_abcd_xxxxxxxxxxxxxxxxxxxxxx",
      "keyName": "WooCommerce",
      "scopes": [
        "repairs.read",
        "repairs.write",
        "customers.read",
        "products.write"
      ]
    }
  }
}
POST/api/public/v1/woocommerce/customers/upsert

Criar ou atualizar clientes vindos do WooCommerce.

Scope necessario: customers.writeAuth por API key

Exemplo de request

{
  "siteUrl": "https://lojaexemplo.pt",
  "wooCustomerId": 501,
  "email": "cliente@example.com",
  "name": "Joao Silva",
  "phone": "+351912345678",
  "city": "Lisboa",
  "postalCode": "1000-001",
  "country": "PT"
}

Exemplo de response

{
  "ok": true,
  "data": {
    "revolioCustomerId": "customer_1"
  }
}
POST/api/public/v1/woocommerce/orders/upsert

Criar ou atualizar encomendas vindas do WooCommerce.

Scope necessario: orders.writeAuth por API key

Exemplo de request

{
  "siteUrl": "https://lojaexemplo.pt",
  "wooOrderId": 1001,
  "wooOrderNumber": "1001",
  "status": "processing",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@example.com",
    "phone": "+351912345678",
    "nif": "123456789"
  },
  "currency": "EUR",
  "items": [
    {
      "name": "Ecra OLED",
      "sku": "SCR-IPH14PRO",
      "quantity": 1,
      "unitPrice": 79.9,
      "taxRate": 23
    }
  ]
}

Exemplo de response

{
  "ok": true,
  "data": {
    "posOrderId": "pos_order_1",
    "status": "PAID"
  }
}
POST/api/public/v1/woocommerce/products/upsert

Criar ou atualizar produtos vindos do WooCommerce.

Scope necessario: products.writeAuth por API key

Exemplo de request

{
  "siteUrl": "https://lojaexemplo.pt",
  "wooProductId": 2001,
  "sku": "SCR-IPH14PRO",
  "name": "Ecra OLED",
  "description": "Ecra premium",
  "salePrice": 79.9,
  "stock": 12,
  "images": [
    "https://lojaexemplo.pt/wp-content/uploads/scr-iph14pro.png"
  ]
}

Exemplo de response

{
  "ok": true,
  "data": {
    "inventoryProductId": "inventory_1",
    "marketplaceProductId": "marketplace_1"
  }
}
POST/api/public/v1/woocommerce/upgrade-scopes

Promover uma chave existente com os scopes necessarios para WooCommerce.

Auth por email e password

Exemplo de request

{
  "email": "owner@lojaexemplo.pt",
  "password": "password-super-segura",
  "apiKey": "rvl_abcd_xxxxxxxxxxxxxxxxxxxxxx"
}

Exemplo de response

{
  "ok": true,
  "upgraded": true,
  "added": [
    "orders.write",
    "products.write"
  ],
  "scopes": [
    "repairs.read",
    "repairs.write",
    "orders.write",
    "products.write"
  ]
}

Acessos, scopes e limites

A API foi desenhada para ser segura por defeito: cada chave pertence a uma loja, os scopes limitam operacoes e o rate limit protege o backend contra abuso.

Autenticacao

Usa o principio do menor privilegio: ativa apenas os scopes que a tua integracao precisa e mantem chaves separadas por sistema ou ambiente.

repairs.readrepairs.writepricing.readcustomers.readmessages.readmessages.writepayments.readpayments.writeparts.readsuppliers.readproducts.readproducts.writeorders.write

As chaves criadas por defeito arrancam num perfil mais conservador, centrado em leitura operacional. Se precisares de escrita ou sync mais profunda, ajusta os scopes no dashboard.

Limites de Taxa

Os pedidos API estao limitados a 100 pedidos por minuto por chave. Exceder este limite resulta num codigo 429.

Codigos de Erro

401

Chave API em falta ou invalida

403

Permissoes de scope insuficientes

429

Limite de taxa excedido

500

Erro interno do servidor

Queres ativar a API na tua operacao?

Gera a tua chave, testa a autenticacao e fala connosco se precisares de mapear um fluxo especifico de checkout, POS, CRM ou WooCommerce.

Abrir dashboard do lojistaFalar com a equipa