Começar

Estabelecimentos

Como a API trata uma empresa com várias lojas: qual usar, o que é de cada uma e como prender uma chave a uma loja.

Uma empresa pode ter vários estabelecimentos (lojas). Cada um tem os seus armazéns, a sua numeração de documentos («FR LC2026/25», onde LC é o código da loja) e os seus utilizadores. Os pedidos que emitem documentos têm de saber em que estabelecimento actuam.

#Qual estabelecimento usa um pedido

SituaçãoO que acontece
A chave está presa a um estabelecimentoÉ sempre esse. Indicar outro lojaId dá 403 ESTABELECIMENTO_NAO_PERMITIDO.
Sem prisão, e o titular só tem acesso a um estabelecimentoUsa-se esse; lojaId é opcional.
Sem prisão, e o titular tem acesso a várioslojaId é obrigatório. Sem ele: 400 ESTABELECIMENTO_OBRIGATORIO.
lojaId de um estabelecimento a que o titular não tem acesso403 ESTABELECIMENTO_NAO_PERMITIDO.

Esquecer o estabelecimento numa empresa com duas lojas

Pedido
curl -X POST 'https://<endereço-da-API>/api/documentos' \
  -H 'Idempotency-Key: 8fb181f0-b12e-4314-8c47-8d6a62469467' \
  -H 'X-Api-Key: assw_v1_<chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
  "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
  "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
  "observacao": "Pedido #4821 da loja online",
  "itens": [
    {
      "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
      "quantidade": 2,
      "precoUnitario": 6500,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
      "valor": 14820
    }
  ]
}'
Pedido
const resposta = await fetch('https://<endereço-da-API>/api/documentos', {
  method: 'POST',
  headers: {
    "Idempotency-Key": "8fb181f0-b12e-4314-8c47-8d6a62469467",
    "X-Api-Key": "assw_v1_<chave>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
    "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
    "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
    "observacao": "Pedido #4821 da loja online",
    "itens": [
      {
        "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
        "quantidade": 2,
        "precoUnitario": 6500,
        "descontoPercentual": 0
      }
    ],
    "pagamentos": [
      {
        "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
        "valor": 14820
      }
    ]
  }),
})
const dados = await resposta.json()
Pedido
import requests

resposta = requests.post(
    'https://<endereço-da-API>/api/documentos',
    headers={
        'Idempotency-Key': '8fb181f0-b12e-4314-8c47-8d6a62469467',
        'X-Api-Key': 'assw_v1_<chave>',
        'Content-Type': 'application/json'
    },
    json={
        'tipoDocumentoId': '6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52',
        'clienteId': '01a12f69-98f8-7688-85b9-8d829c101c8b',
        'armazemId': '01a12201-f4d4-78a0-8dde-1efc41b94776',
        'observacao': 'Pedido #4821 da loja online',
        'itens': [
            {
                'produtoId': '01a12201-fa97-7f9b-8eec-2f731b91a53b',
                'quantidade': 2,
                'precoUnitario': 6500,
                'descontoPercentual': 0
            }
        ],
        'pagamentos': [
            {
                'metodoPagamentoId': '9dde532b-0092-4a68-b2dc-18649f0c97c4',
                'valor': 14820
            }
        ]
    },
)
dados = resposta.json()
Pedido
using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Post, "/api/documentos");
pedido.Headers.Add("Idempotency-Key", "8fb181f0-b12e-4314-8c47-8d6a62469467");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
pedido.Content = new StringContent("""
{
  "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
  "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
  "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
  "observacao": "Pedido #4821 da loja online",
  "itens": [
    {
      "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
      "quantidade": 2,
      "precoUnitario": 6500,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
      "valor": 14820
    }
  ]
}
""", Encoding.UTF8, "application/json");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

400 Bad Request Resposta

Resposta
content-type: application/problem+json
x-mucanda-api-version: 1

{
  "title": "Regra de negócio violada",
  "status": 400,
  "detail": "Indique o estabelecimento: o seu utilizador tem acesso a mais do que uma.",
  "codigo": "ESTABELECIMENTO_OBRIGATORIO",
  "traceId": "00-4c90a798ed97c8890c633c53120c9ec6-0ae5997e0ff5a6e0-01"
}

#O armazém é do estabelecimento

Um documento que movimenta stock tem de usar um armazém do mesmo estabelecimento. Peça GET /api/estoque/armazens e use o lojaId de cada armazém para escolher o certo. Usar o armazém de outra loja dá ARMAZEM_DE_OUTRO_ESTABELECIMENTO; esquecê-lo, ARMAZEM_OBRIGATORIO.

#Prender uma chave a uma loja

Ao criar a chave, escolha o estabelecimento. É o ideal para uma loja online de uma loja física, ou para um programa que só deve ver uma filial: mesmo que o perfil tenha mais acesso, a chave não sai dali. A pessoa que cria a chave tem de ter ela própria acesso ao estabelecimento.