API

Guia de API WAMA REST

Integre os seus sistemas com o WAMA a usar a API HTTPS JSON em https://www.wama.cloud.

Esta página cobre API chave autenticação, multi-tenant ponto de venda contexto, paginação, e erros. Para campos de solicitação e resposta, abra a referência interativa OpenAPI (ecrã completa).

Abra a referência interativa da API

Começar

Crie uma chave API na aplicação WAMA (Definições → Integrações). Preferir Ler apenas a menos que a sua integração deva escrever dados.
Chamada /api/** com cabeçalho Autorização: Carregador <api_key> (ou X-Api-Key).
Utilizar o interactive API reference campos de pedido/resposta.

Base URL: https://www.wama.cloud

Dica

As chaves de API são a maneira suportada para scripts, aplicações de parceiros e IA / MCP. Não use login de utilizador interativo (email/password OAuth) para integrações de máquina.

Autenticação

Criar uma chave de API

Entre no WAMA no navegador como administrador de contas (ROLE USER / Administrador).
Abrir Definições → Integrações.
Escolha Criar chave API, definir um nome, o ** ponto de venda** a chave está ligada a, um scópio, e uma data de validade opcional.
Copie a chave imediatamente — o segredo completo é mostrado ** apenas uma vez**.

Formato chave:

wama_<publicId>_<secret>

Armazená-lo como uma palavra-passe (variável de ambiente ou gerenciador secreto). Nunca commit chaves para controlar ou colar fonte em tickets públicos.

Âmbito de aplicação

Âmbito	Valor do fio	Comportamento
Só leitura	«ler»	`GET` / `HEAD' /` OPTIONS’ apenas; métodos de mutação devolvem 403
Leitura e escrita	«read write»	Mesmo acesso que de criação para esse ponto de venda (exceto gestão de chaves)

Preferir Ler apenas para reportar, sincronizar e assistentes de IA a menos que as gravações sejam necessárias.

Chamar a API

Enviar a chave como um cabeçalho HTTP em cada pedido:

Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET

Alias opcionais (mesma chave):

X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET

Se tanto um JWT Autorization: Bearer ... e X-Api-Key estão presentes, o JWT ganha e `X-Api-Key’ é ignorado.

Exemplo:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Equivalente com «X-Api-Key»:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Revogar ou rodar

Revogar chaves de Definições → Integrações. Chaves revogadas ou expiradas devolvem 401. Crie uma nova chave para rodar; atualize o seu cliente e revogue a antiga.

Chaves de API ** não podem criar, listar ou revogar outras chaves de API — gere chaves apenas a partir da aplicação web (sessão login).

Ligar o WAMA (PKCE)

Os anfitriões MCP podem obter uma chave sem colar a usar OAuth Authorization Code + PKCE contra o cliente público wama-mcp (sem segredo do cliente). Após login e consentimento do navegador (ponto de venda + escopo, padrão read), a resposta do token access token é a chave wama ... de longa duração (também retornada como integration api key para compatibilidade).

Para umas definições simples em cada ferramenta de IA, consulte guia MCP. Colar de Definições → Integrações permanece totalmente suportado.

Ponto de venda (concessão)

Todos os inventários, vendas e dados relacionados pertencem a um ** ponto de venda** (POS).

Cada chave API é associada a um POS na criação. Solicitações autenticadas com essa chave sempre usam esse POS — não mude de POS com POST /api/point-of-sales/... ao usar uma chave API.

As chaves API ** não podem listar, obter por id, alternar ou gerir pontos de venda em /api/ponto de venda/**. Eles **podem chamar GET /api/point-of-sales/current para um snapshot fino do POS fixado (id, nome, código, moedas, endereço).

Crie uma chave separada por armazém/armazém se precisar de vários contextos POS.

Paginação

Endpoints da lista aceitam parâmetros de consulta de paginação de dados de primavera:

Parâmetro	Descrição
«página»	Índice de página com base em zero
«tamanho»	Tamanho da página
«sorte»	Campo e direcção, por exemplo, «timeModified,desc»

As respostas à lista de sucesso incluem:

Cabeçalho	Descrição
«X-Total-Count»	Total de itens correspondentes em todas as páginas

Erros

A maioria das falhas devolvem JSON em forma de:

{
  "message": "error.validation",
  "description": "Optional human-readable text",
  "fieldErrors": [
    {
      "objectName": "productDTO",
      "field": "barcode",
      "message": "NotNull",
      "defaultMessage": "must not be null"
    }
  ]
}

Erros de domínio parametrizados podem retornar { "mensagem": "...", "param": ["..."]} em vez disso.

Resultados frequentes da autenticação:

Estado	Significado
401	Chave de API em falta, inválida, revogada ou expirada
403	O escopo chave é apenas leitura e o método muda dados

Convenções

JSON request and response bodies («Content-Type: application/json»)
** Datas** como ISO-8601 com deslocamento (por exemplo, 2026-03-15T10:30:00000Z)
Dinheiro como quantias decimais emparelhadas com objetos monetários, quando aplicável
Ids são atribuídos ao servidor; omiti-los (ou enviar null) ao criar recursos

Exemplo: produtos de lista

curl 'https://www.wama.cloud/api/products?page=0&size=20&sort=timeModified,desc' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET'

Referência do OpenAPI

Navegue por cada ponto público:

Abra a referência interativa da API