Organization

Com estas rotas você cadastra e mantém a estrutura organizacional na HAASS — Company, BusinessUnit, FranchiseGroup e Store — usando o seu próprio identificador (refId) como chave. Para cada entidade há as operações de listar, buscar (por id ou por refId), criar, atualizar e upsert.

Todas as rotas exigem Authorization: Bearer <token> (ver Autenticação) e as listagens são paginadas por cursor — detalhes em Essencial para todas as rotas.

Essencial para todas as rotas

A tabela de campos (tipo / obrigatório / validação) fica junto de cada rota na seção detalhada abaixo. Aqui só o que é reutilizado entre rotas.

Legenda das tabelas de payload: ✔ obrigatório · ○ opcional. Campos read-only (id, active) nunca são enviados pelo parceiro — só aparecem na response.

AddressDto (objeto reutilizado no Store)

Campo	Tipo	Obrig.	Validação-alvo
zipCode	string	✔	CEP 00000-000 (8 dígitos, hífen opc.).
state	string	✔	UF, 2 letras maiúsculas (SP, RJ).
city	string	✔	1–120 chars.
street	string	✔	1–200 chars.
number	string	✔	1–20 chars (string p/ suportar s/n).
district	string	✔	1–120 chars.

Validação = contrato-alvo. Esta casca não aplica validação (retorna sample fixo); os limites/formatos documentados alimentam o schema Swagger. A checagem efetiva (422) e a resolução refId → Id são spec futura.

Hierarquia: esta spec mantém o modelo em que BusinessUnit e FranchiseGroup são filhos diretos de Company (Store referencia os três refs). Há divergência com domain-model-context.md (cadeia linear Company → FranchiseeGroup → BusinessUnit → Store); o ajuste é futuro e fica contido nesta spec — não propagar para domínio/outras specs por ora.

---

Convenções desta seção:

• {version} na rota real é 1.0; nos exemplos usa-se v1.
• Header de auth (Bearer) é obrigatório em todos os endpoints; nos verbos com corpo soma-se Content-Type: application/json. Bloco de headers padrão:

Authorization: Bearer <access_token> # obtido em POST /oauth/token (spec 023) Content-Type: application/json # apenas POST/PUT

Token ausente/inválido/expirado → 401 (WWW-Authenticate: Bearer); escopo insuficiente → 403. Esses status vêm do middleware, não do AppResult.

• Sucesso de recurso único devolve o objeto bare; sucesso de listagem devolve o envelope com cursor <E>ListResponse ({ items, hasMore, nextCursor }) — nunca array no root. Erro devolve AppError { "code": "...", "message": "..." }.
• Nesta casca todo endpoint responde o sample fixo com status 200/201; os códigos 404/409/422 são o contrato-alvo (documentados) e serão produzidos na spec de persistência.