Empresa e Estabelecimento

Estado explícito, não seed: a plataforma não conhece Company e não chama o Nexio ao criar tenant. Nesse estado nenhum documento é emitido e a única tela disponível é o cadastro da primeira empresa, com o CNPJ pedido ali — mesmo precedente da união vazia de escopos: o usuário não opera, e a interface diz por quê

No máximo uma: unicidade de (companyId) entre os estabelecimentos com type = Headquarters — índice único filtrado é exemplo de implementação. Pelo menos uma: POST /companies exige a matriz inline e grava as duas na mesma transação; estabelecimento criado depois nasce Branch; o PUT ignora type; a única troca é o PATCH /companies/{id}/headquarters (RN-EMP-38). ESTABLISHMENT_HEADQUARTERS_REQUIRED_UNPROCESSABLE guarda o agregado

Validação no agregado, 422 ESTABLISHMENT_CNPJ_ROOT_MISMATCH_UNPROCESSABLE. No esquema, a garantia é chave estrangeira composta, não check entre tabelas: o estabelecimento guarda cnpjRoot derivado do cnpj e referencia (tenantId, companyId, cnpjRoot) em companies(tenantId, id, cnpjRoot), com unicidade desse trio do lado da empresa

Na criação, pela matriz inline; depois, verificação na desativação do último estabelecimento ativo, 409. A desativação da empresa não passa por essa guarda: ela cascateia, e empresa inativa sem estabelecimento ativo é o estado correto

A mesma regra para empresa, estabelecimento e ponto de entrega. Criar ou submeter documento novo — submeter rascunho inclui — em estabelecimento inativo ou de empresa inativa é recusado com 422 ESTABLISHMENT_INACTIVE_UNPROCESSABLE ou 422 COMPANY_INACTIVE_UNPROCESSABLE. Todo documento já submetido segue até o fim: aprovação, pedido, recebimento, nota, devolução e estorno. A desativação nunca é recusada por haver documento em aberto. A resolução do UserCompanyScope não lê isActive: nenhuma leitura de histórico depende do estado

A fatia não tem coluna de empresa. A invariante do centro de custo e a resolução do Budget leem a empresa do documento. Não existe rateio entre empresas na v1

Ignorados no PUT. Não é erro pedir para mudar — é campo que não existe na atualização

Derivado no servidor do establishmentId, depois de validado contra o conjunto resolvido do usuário — fora dele, 404. O token não traz empresa, e o cliente nunca a informa como autoridade: companyId em query de listagem só intersecta com o conjunto

Regra da linha do documento. Alteração de cadastro não reescreve documento emitido

Critério Empresa em lista do Fluxo de Aprovação, avaliado sobre o companyId do documento. Quem opera a compra é usuário; não existe eixo de política pelo lado do comprador

Especificado no Centro de Custo, lido contra a empresa do documento e o companyId efetivo do nó

Validação na fatia, 422

Validação na submissão do documento, 422 ALLOCATION_GL_ACCOUNT_REQUIRED_UNPROCESSABLE; nulo só em rascunho (RN-CC-29)

Desenho. A tabela não dá organização, papel nem permissão — o token do GrydAuth continua decidindo isso. Linha de quem saiu da organização é encerrada (RN-EMP-24)

Resolvedor. Falha fechada, qualquer que seja o número de empresas do tenant; não existe concessão "todas as empresas". Ver a tabela de resolução em Escopo e segurança

Fronteira de camada. A plataforma não conhece Company, e não deve conhecer

PUT /establishments/{id} que altera cityIbgeCode, UF ou allowsReceiving revalida, na mesma transação, todos os pontos de entrega do estabelecimento, os de endereço próprio incluídos. Ponto sem endereço próprio copia o stateCode daqui, e só nele a UF é recalculada; isInterstate é recalculado em todos. A nota de cada ponto que passa a ser interestadual vem no mesmo corpo, em deliveryLocationInterstateNotes[] (deliveryLocationId + interstateNote); nota para ponto que não passa a interestadual é ignorada. A edição é recusada com 422 ESTABLISHMENT_ADDRESS_CHANGE_BREAKS_DELIVERY_LOCATIONS_UNPROCESSABLE, listando os pontos, quando algum ponto fica interestadual sem explicação — sem nota, fora de canteiro e sem recebedor distinto, ou canteiro sem centro de custo — ou quando allowsReceiving passa a falso com ponto ativo pendurado, que ficaria apontando para estabelecimento que deixou de receber: desative os pontos antes, o que nunca é recusado por documento (RN-DL-15). Passando, cada ponto afetado sobe a version e emite um evento. Escrita no Local de Entrega (RN-DL-19), com o mesmo gatilho e o mesmo código, aplicada aqui

Esquema: cnpjRoot varchar(8) e cnpj varchar(14), iguais aos do Fornecedor. Entrada: trim, sem máscara, letras em maiúsculas. Validação: 12 caracteres em 0–9A–Z e 2 dígitos verificadores, DV com ASCII − 48. Formato ou DV inválido é 400 ESTABLISHMENT_CNPJ_INVALID; raiz inválida, 400 COMPANY_CNPJ_ROOT_INVALID

PUT /users/{userId}/company-scopes só abre ou encerra linha de empresa que quem concede alcança no momento do ato. Empresa fora desse conjunto, no corpo, responde 404 COMPANY_NOT_FOUND e nada é gravado. Linhas da pessoa em empresas que quem concede não alcança não são lidas, não aparecem no GET e não mudam. Consequência: um administrador de uma empresa não entrega outra. E ninguém mexe nas próprias linhas (RN-EMP-41).

POST /companies exige, além de create:companies, update:company-scopes no token de quem cria, conferida antes de gravar — sem ela, 403 COMPANY_CREATION_SCOPE_PERMISSION_FORBIDDEN e nada é gravado. Com ela, grava na mesma transação uma linha de escopo para quem criou, com origin = CompanyCreation e sem validTo: a empresa nasce cumprindo a RN-EMP-24. Ninguém mais recebe a empresa — nem quem alcançava todas as outras. O evento é o mesmo de qualquer concessão (RN-EMP-21).

Toda linha aberta publica user-company-scope.granted e toda linha encerrada por ato ou pela remoção da pessoa da organização publica user-company-scope.revoked, depois do commit, com pessoa, empresa, vigência, origin e autor. O evento notifica, mede e integra; o efeito — a linha — já está gravado. Vencer pelo validTo informado na concessão não publica nada. Registro da trilha: o requisito é registro isolado por tenant, gravado na transação do ato; desde o Gryd.IO 11.1.0 ele é preparado por IAuditTrail.Stage junto com o evento. A própria linha, que não se apaga nem se reescreve, também guarda autor e instantes.

A linha vale em [validFrom, validTo), em instantes UTC. Para a mesma pessoa e empresa não há duas linhas com intervalos que se cruzem — 409 USER_COMPANY_SCOPE_DUPLICATE_CONFLICT. Encerrar grava validTo com o instante do ato, e a resolução seguinte já não a lê. Linha encerrada não reabre; reconceder é linha nova. validTo informado precisa ser posterior ao instante da concessão — 422 USER_COMPANY_SCOPE_VALIDITY_UNPROCESSABLE.

Lista vazia encerra todas as linhas vigentes da pessoa nas empresas que quem concede alcança — com escopo em todas, a pessoa fica sem empresa nenhuma. A escrita é serializada em duas camadas, adquiridas sempre nesta ordem: primeiro por (tenantId, userId) de cada pessoa cuja linha o ato grava, em ordem crescente de userId; depois por (tenantId, companyId) de cada empresa que o ato toca, em ordem crescente de companyId. A ordem é total nas duas camadas, e é por isso que o ato que grava linha de várias pessoas de uma vez — a carga da migração — não trava contra outro igual: duas cargas com as mesmas pessoas em ordens diferentes ficariam uma esperando a outra para sempre. No PUT, as empresas tocadas são as do corpo e as das linhas vigentes da pessoa que quem concede alcança; os cortes e as decisões da RN-EMP-42 ficam na empresa da linha de origem e por isso já estão cobertos. Só depois de adquirir todas as travas, e sob elas, o ato lê a linha de quem concede, as linhas dependentes em cadeia e as linhas que sustentam a invariante da RN-EMP-24, e confere expectedScopeHash; divergente, 409 USER_COMPANY_SCOPE_CONCURRENT_CHANGE_CONFLICT e nada é gravado. A trava da empresa é tomada, na mesma ordem, por todo ato que grava linha ou confere a invariante nela: PATCH /companies/{id}/activate, o encerramento por remoção da organização e a gravação do ato de suporte no fim da carência (RN-EMP-24), e a carga da migração. É requisito, não recurso de banco: trava de linha numa tabela de controle por empresa é exemplo de implementação; o equivalente é qualquer serialização com as mesmas chaves e a mesma ordem de aquisição. Caso de ataque. Com a trava só da pessoa, U1 e U2 têm as duas únicas linhas sem fim na empresa X; dois PUT simultâneos, um sobre U1 e outro sobre U2, encerram uma linha cada, cada um enxerga a do outro ainda vigente, os dois passam na guarda, e X fica sem administrador. Ou Z encurta a linha de B, travando só B, enquanto B concede a D até depois do novo fim, travando só D: a cascata de Z não enxerga D. Com a trava de X, o segundo ato espera o primeiro e lê o resultado dele. E, sem a trava da pessoa, "remover tudo" concorrente com "acrescentar B" terminava com a pessoa em B.

Invariante: toda empresa, ativa ou inativa, tem ao menos uma linha vigente sem validTo de pessoa ativa que tem update:company-scopes no GrydAuth. Ativa é quem tem vínculo ativo com a organização e não está bloqueada: linha de pessoa bloqueada ou removida não sustenta a invariante. Linha temporária nunca conta, por mais longa que seja: sem isso, A (sem fim) concede a C até 30/09, C encerra a linha de A, e em 30/09 a empresa fica sem ninguém. A invariante é conferida sob as travas da RN-EMP-23 — a de cada empresa tocada incluída —, com a permissão e o vínculo lidos no GrydAuth no instante do ato, em dois atos: no PUT /users/{userId}/company-scopes, recusado quando a empresa — ativa ou inativa — a cumpria antes e deixa de cumprir depois — encerrar, ou pôr validTo em, a última linha sem fim de quem tem a permissão, diretamente ou pelo corte em cadeia da RN-EMP-42 —; e no PATCH /companies/{id}/activate, recusado quando a empresa a reativar não a cumpre — só linhas temporárias, ou nenhuma linha sem fim de quem tem a permissão. Em qualquer caso, o ato que deixaria empresa, ativa ou inativa, sem nenhuma linha vigente, de ninguém, também é recusado. Todos respondem 409 USER_COMPANY_SCOPE_LAST_GRANT_CONFLICT, listando as empresas: conceda antes linha sem fim a outra pessoa com a permissão. A empresa inativa entra na guarda do PUT porque, fora dela, quem tem update:companies e só linha temporária desativaria a empresa, encerraria a última linha sem fim e deixaria a reativação em 409 para sempre — quem sobra não concede linha sem fim (RN-EMP-42). A guarda não segura o GrydAuth: a pessoa da linha sem fim pode sair da organização ou perder a permissão depois. Uma rotina diária — job com o tenant no payload, que não age em nome de ninguém — confere a invariante em toda empresa, ativa ou inativa, e, quando ela não se sustenta, avisa quem tem linha vigente e update:company-scopes na empresa, com destaque quando todas essas linhas terminam em até 7 dias; sem destinatário com linha e permissão, o aviso desce uma cadeia declarada, e só se cai num degrau quando o anterior não tem ninguém ativo: (1) quem tem linha vigente e update:company-scopes na empresa; (2) os administradores do tenant no GrydAuth — os membros elegíveis (vínculo ativo e dentro do período, conta ativa) que têm o papel Admin; o papel GroupAdmin não conta; (3) o canal de suporte da plataforma, que só recebe o aviso — com as empresas nomeadas e a lista das Restrict pendentes — e não abre o ato de suporte: o ato continua sendo pedido por um administrador do tenant, com confirmação no e-mail já cadastrado dele (adiante). O último degrau não depende de ninguém do tenant, e é por isso que a cadeia nunca termina sem destinatário — mas avisar não é conceder. Risco aceito, declarado aqui: tenant sem administrador ativo no GrydAuth (ninguém elegível com o papel Admin) não tem caminho pelo produto. A empresa segue sem administrador e as Restrict pendentes continuam órfãs até que o cliente devolva o papel Admin a alguém no GrydAuth, e nenhuma regra desta página compensa isso: abrir a porta pelo suporte recriaria a engenharia social que a exigência de quem pede fecha — recuperar superadministrador no Google Workspace e no Microsoft 365 exige outro superadministrador, e o suporte não concede escopo. A mitigação é o que se exige: o aviso é obrigatório, a lista das Restrict pendentes vai em todos os degraus e a rotina diária o repete enquanto a invariante não se sustentar, de modo que o estado fica visível em vez de silencioso. Quem é o administrador do tenant é leitura em processo do GrydAuth embutido, e o endereço do canal de suporte é configuração (Platform:SupportChannel); esta página declara a ordem e o que vai em cada degrau. Enquanto a invariante não se sustenta, o PUT que não a piora continua aceito, com uma exceção: encerrar ou pôr validTo na última linha sem fim da empresa, de quem quer que seja que continue na organização — inclusive a de quem perdeu a permissão ou está bloqueado —, é recusado com o mesmo 409, porque é por essa linha que a invariante volta. Tirar o acesso dessa pessoa não espera por isso: basta retirar os papéis dela, ou bloqueá-la, no GrydAuth, já que escopo sem permissão não dá acesso a nada. A invariante volta por dentro do produto só se o GrydAuth devolver a permissão, ou desbloquear, quem tem linha sem fim: quem só tem linha temporária não concede linha sem fim (RN-EMP-42). Fora disso, só o suporte da plataforma concede, fora da API de negócio, como ato de controle, com o mesmo evento e registro, e nunca para o próprio operador. O ato de suporte só é pedido por um administrador do tenant (papel Admin no GrydAuth), com confirmação no e-mail já cadastrado dele; todos que têm update:company-scopes no tenant recebem aviso; e a concessão só vale depois de uma carência de 24 h sem contestação. O beneficiário tem update:company-scopes, tem identidade verificada e, havendo outra pessoa ativa na organização com essa permissão, não pode ser quem pede; só sem ninguém mais quem pede é o beneficiário. A conta é por pessoa, não por usuário: "outra pessoa ativa com update:company-scopes" conta por CPF verificado — dois usuários do mesmo CPF são uma pessoa só e não fazem número —, e o CPF do beneficiário tem de ser diferente do CPF de quem pede. Beneficiário sem identidade verificada, ou com o CPF de quem pede, é recusado com 422 COMPANY_SCOPE_SUPPORT_GRANT_BENEFICIARY_UNPROCESSABLE, no pedido e de novo no fim da carência. Sem isso, quem pede cadastrava um segundo usuário com o próprio CPF, ele fazia número na conta e era o beneficiário do próprio ato de suporte. Nessa conta, quem teve update:company-scopes retirada nos 30 dias anteriores ao pedido conta como se ainda a tivesse, e recebe o aviso do pedido: sem isso, quem pede retiraria a permissão dos outros e passaria a ser o único. Retirada é a perda da permissão efetiva, por qualquer via — atribuição direta removida da pessoa, papel que a carrega retirado da pessoa, permissão retirada do papel, papel excluído: o que conta é a pessoa ter deixado de resolver update:company-scopes no GrydAuth, não o caminho pelo qual deixou. Sem essa amplitude, bastaria a quem pede tirar a permissão do papel, ou excluir o papel, para ninguém aparecer como retirado nos 30 dias e ele ficar sozinho na conta. Bloquear ou remover os outros da organização não entra nessa conta — risco aceito; o aviso e a carência continuam valendo. A linha nasce sem validTo e é gravada no fim da carência — o validFrom é esse instante, não o do pedido —, com as condições conferidas de novo nesse instante: se deixaram de valer, nada é gravado. Essas condições são regra da demanda de plataforma do Gryd.IO (ato de suporte "conceder escopo em empresa sem administrador"), e esta página só as cita. Não existe autoconcessão no produto.

Remoção da organização encerra; readmissão não revive. Quando a pessoa sai da organização no GrydAuth, as linhas alcançadas pela remoção são encerradas pelo primeiro de três caminhos. Alcançada se decide pelo vínculo da pessoa no instante em que o caminho roda, não pelo instante da remoção. Pessoa sem vínculo ativo com a organização: toda linha vigente dela é alcançada, qualquer que seja o validFrom. Pessoa com vínculo ativo, porque foi readmitida: alcançada é a linha vigente cujo validFrom é anterior ao início do vínculo vigente. Linha concedida depois da readmissão nunca é alcançada; linha anterior à remoção continua alcançada mesmo que a pessoa já tenha voltado. O instante da remoção informado pela plataforma fica no registro do encerramento e não recorta mais o alcance: linha aberta depois dele, na janela em que o Nexio ainda não sabia da saída, é alcançada como qualquer outra. Os três caminhos: (1) quem tem update:company-scopes trata a remoção pelo PUT /users/{userId}/company-scopes com lista vazia — o único PUT aceito sobre quem não está na organização; com empresa no corpo é 422 USER_NOT_IN_TENANT_UNPROCESSABLE — e decide no próprio ato as dependentes Restrict (RN-EMP-42); (2) o consumo do evento de remoção publicado pela plataforma; (3) a rotina diária, que procura linha alcançada em toda pessoa com linha vigente — a pessoa sem vínculo ativo e a pessoa com vínculo ativo que começou depois do validFrom da linha —, e não só quem está sem vínculo ativo. Em (2) e (3) o encerramento é de sistema: endedAt com o instante, endedByUserId nulo, user-company-scope.revoked com cause = UserRemovedFromTenant; as dependentes Cascade caem em cadeia e as Restrict ficam, com aviso a quem tem linha vigente e update:company-scopes na empresa listando-as para decisão. Sem destinatário com linha e permissão — o caso em que quem sai era o único administrador da empresa —, o aviso desce a mesma cadeia declarada do aviso da invariante — administradores do tenant e canal de suporte da plataforma —, e a lista das Restrict pendentes vai em todos os degraus, o último incluído — sem ele, quando quem saiu era também o administrador do tenant, ninguém ficaria sabendo que elas existem. O canal de suporte não decide nenhuma delas nem abre o ato de suporte: enquanto não houver administrador do tenant ativo para pedi-lo, as Restrict seguem pendentes e a empresa, sem administrador — é o risco aceito da cadeia, escrito na invariante. Enquanto houver Restrict pendente de decisão, a lista delas é repetida no aviso da rotina diária e no aviso do pedido do ato de suporte daquela empresa. Nos três caminhos o ato roda sob as travas da RN-EMP-23 e fora da guarda desta regra — linha de quem saiu não sustenta nada —; a empresa que ficar sem administrador entra no aviso da rotina e no ato de suporte. Readmitir a pessoa não revive escopo: a resolução não lê linha com validFrom anterior ao início do vínculo vigente da pessoa com a organização — a linha vale como encerrada até que um dos três caminhos a encerre —, e voltar a operar exige concessão nova. E o PUT não a revive: todo PUT /users/{userId}/company-scopes sobre pessoa readmitida encerra primeiro, no mesmo ato e como ato de sistema — endedAt com o instante, endedByUserId nulo, cause = UserRemovedFromTenant, Cascade em cadeia, Restrict mantidas com aviso —, as linhas alcançadas que ainda estiverem abertas, e só então compara o corpo com as linhas vigentes. Sem essa ordem, a empresa no corpo casaria com a linha antiga, que seria mantida, com o grantedByUserId e o validFrom de antes, em vez de concedida de novo por quem está gravando. Caso de ataque. Sem isso, a linha de quem saiu ficava vigente e inerte, e a readmissão meses depois, por engano ou de propósito, devolvia a empresa sem que ninguém concedesse nada. E sem o recorte por validFrom: a pessoa sai, é readmitida no mesmo dia e recebe linha nova, sem fim, na empresa X; o evento de remoção, atrasado, chega depois e encerra a linha nova — X fica sem administrador —, enquanto a rotina, que procurava só quem está sem vínculo ativo, nunca chega à linha antiga. E sem o corte pelo vínculo: a pessoa é removida no GrydAuth às 10h, o evento chega ao Nexio às 14h e, às 11h, quem ainda lia o vínculo antigo lhe concede a empresa Y — linha com validFrom posterior ao instante da remoção. Com o corte por esse instante, essa linha não era alcançada por caminho nenhum: a rotina não a achava, o PUT da readmissão não a encerrava, e a resolução a ignorava para sempre, por ser anterior ao início de qualquer vínculo futuro. Readmitida a pessoa, a linha — vigente, sem validTo, de pessoa de novo ativa com a permissão — passava a sustentar a invariante desta regra sem dar acesso a nada: um administrador fantasma. E o PUT normal nunca mais concedia Y àquela pessoa, porque a empresa no corpo casava com a linha morta e ela era mantida em vez de concedida de novo. Sem vínculo ativo, toda linha vigente é alcançada, e essa é encerrada com as demais.

Sem contexto de tenant ou com a leitura do escopo indisponível, a requisição falha com 500; não existe caminho que siga com conjunto mais amplo, com o conjunto de outra requisição ou sem filtro. Toda entidade com companyId ou establishmentId é registrada no filtro de escopo, e um teste de arquitetura quebra o build quando uma entidade nova com uma dessas colunas não está registrada. Critério de aceite: requisição sem linha vigente devolve lista vazia em toda rota de listagem de agregado por empresa, e 404 em toda leitura por id desses agregados.

Todo comando que grava dado por empresa resolve uma empresa — a do establishmentId validado, ou a do registro já existente — e confere que ela está no conjunto; nenhum comando recebe conjunto de empresas nem "todas". Leitura pode abranger várias empresas do conjunto; escrita, nunca. É o espelho do que a plataforma faz ao recusar escrita sob leitura de grupo.

Onde outra regra exige que a pessoa alcance todas as empresas — responsável de nó corporativo no Centro de Custo, aprovador de reserva e alvo de política no Fluxo de Aprovação —, a condição é ter linha vigente em cada empresa ativa do tenant no instante em que a regra é verificada. Não existe marca "irrestrito". Criar empresa tira essa condição de todos, menos de quem criou; por isso a tela de criação lista quem a tinha, com os vínculos de nó corporativo e as reservas afetados, para concessão explícita. Na execução, a defesa em profundidade do Fluxo continua valendo para quem ficou sem a empresa do documento.

Para cada (tenant, documentType) as vigências [effectiveFrom, retiredAt) das configurações não se sobrepõem — requisito de exclusão de faixas, a mesma mecânica do CostCenterAssignment. Criar configuração havendo vigente ou agendada, sem replacesSequenceId, é 409 NUMBER_SEQUENCE_ALREADY_EXISTS. A emissão usa a configuração vigente no instante da emissão.

scope, prefix, resetPolicy e timeZone não se editam: mudar qualquer um é criar a sucessora com replacesSequenceId e o expectedVersion da mais recente, e a substituída recebe retiredAt = effectiveFrom da sucessora na mesma transação. A sucessora é aceita só com prefixo novo — nunca usado por configuração daquele documentType no tenant — ou período novo: mesma resetPolicy (diferente de Never) e mesmo timeZone da substituída, e effectiveFrom exatamente no início de um período posterior ao corrente, nesse fuso, e posterior ao maior período já emitido por qualquer configuração daquele documentType com o mesmo prefixo e a mesma resetPolicy — o maior currentPeriodKey dos contadores de todas elas, não só os da substituída. Sem isso, a troca de fuso recompõe número: PC- em UTC+14 emite PC-2027-000001 quando São Paulo ainda está em 2026; a troca para PD- em UTC−11 é prefixo novo; a volta a PC- em UTC−11, no início de 2027 nesse fuso, seria período novo contra PD- e emitiria PC-2027-000001 de novo, recusado pela unicidade da RN-EMP-32 com 409 a cada emissão, em série. Configuração com a mesma resetPolicy e prefixo diferente, ou com o mesmo prefixo e outra resetPolicy, compõe número de outro formato e não entra na conta. Fora disso, 422 NUMBER_SEQUENCE_REPLACEMENT_UNPROCESSABLE; versão ou alvo divergente, 409 NUMBER_SEQUENCE_CONCURRENT_CHANGE_CONFLICT. Nos dois caminhos, o prefixo da sucessora, quando difere do de uma configuração já criada para o documentType no tenant, não pode começar com ele nem ser começo dele — senão 422 NUMBER_SEQUENCE_PREFIX_OVERLAP_UNPROCESSABLE, nomeando a configuração anterior, na criação da configuração e não na emissão. É o que impede recompor número já emitido: S1 com PC- em Establishment emite PC-SP01-2026-000001, e S2 com PC-SP01- em Company emitiria o mesmo número. Dois prefixos em que nenhum é começo do outro nunca produzem o mesmo número. A regra é a mesma em qualquer troca, sem simular formato de número. Publica number-sequence.replaced depois do commit.

Tenant tem um contador; Company, um por empresa; Establishment, um por estabelecimento. O contador é criado na primeira emissão da partição, sob a unicidade (sequenceId, partitionKey), e nunca é compartilhado entre configurações.

O período de cada emissão é calculado pelo relógio do servidor no timeZone da configuração — nunca em UTC, nunca pela data do documento. Maior que o guardado: grava e zera. Igual ou menor — relógio atrasado de outro servidor —: usa o guardado e incrementa. Na mesma operação atômica, sempre. Documento retroativo recebe o período da emissão.

Unicidade de (tenantId, documentType, companyId, number) no documento, em qualquer escopo — é o que garante a composição com o código do estabelecimento e o que pega colisão residual depois de uma troca. Colisão recusa a emissão com 409 DOCUMENT_NUMBER_ALREADY_EXISTS, sem gravar; o número consumido não volta e repetir emite o próximo. Lacunas são permitidas: o número não é fiscal, e a emissão confirma em transação própria antes do documento, então número consumido por documento que falhou não é reaproveitado.

establishmentId exige estabelecimento ativo, de empresa ativa, com allowsReceiving — senão 422 ESTABLISHMENT_INACTIVE_UNPROCESSABLE, 422 COMPANY_INACTIVE_UNPROCESSABLE ou 422 ESTABLISHMENT_RECEIVING_NOT_ALLOWED_UNPROCESSABLE. requestingEstablishmentId exige estabelecimento ativo com allowsPurchasing — senão 422 ESTABLISHMENT_PURCHASING_NOT_ALLOWED_UNPROCESSABLE. Verificado na criação e na submissão do documento novo; documento já submetido não é reavaliado (RN-EMP-05). O lookup aplica o mesmo filtro pelo purpose.

requestingEstablishmentId nunca é nulo: quando quem pede é quem recebe, é igual ao establishmentId. Estabelecimento de outra empresa é recusado com 422 REQUESTING_ESTABLISHMENT_COMPANY_MISMATCH_UNPROCESSABLE. Não existe rateio nem pedido entre empresas na v1; como demanda de várias empresas se consolida é decisão da spec da Cotação, dentro da RN-EMP-26 e desta regra.

Company.functionalCurrency nasce BRL e não muda: outro valor na criação é 422 COMPANY_FUNCTIONAL_CURRENCY_UNPROCESSABLE, e o PUT ignora o campo. Documentos, preços, limites e cotações continuam multimoeda, com conversão para a moeda do limite na submissão.

Criar ou submeter documento novo com estabelecimento — como establishmentId ou requestingEstablishmentId — em Suspended, Unfit ou ClosedDown é 422 ESTABLISHMENT_REGISTRATION_STATUS_UNPROCESSABLE. Null não bloqueia: é o estado de estabelecimento recém-cadastrado que o espelho da Receita ainda não traz, e o risco aqui é fiscal, não de fraude — a empresa não ganha nada mentindo sobre o próprio CNPJ. A situação vem do provedor de consulta ao CNPJ ou de PATCH /establishments/{id}/registration-status, que exige data da situação e nota do comprovante; entre os dois vale a data de situação mais recente, e a consulta seguinte com data posterior substitui a correção manual. Toda mudança publica establishment.registration-status-changed. Documento já submetido não é reavaliado (RN-EMP-05).

Na submissão, o documento congela taxRegime da empresa e icmsTaxpayerStatus, stateRegistration e suframaCode do estabelecimento. Mudança de cadastro vale para documento novo e nunca reescreve documento submetido — o Simples é opção anual, e a nota de um pedido de dezembro não muda de tratamento porque o regime mudou em janeiro.

PATCH /companies/{id}/headquarters com { establishmentId, expectedVersion }: na mesma transação, a matriz atual vira Branch, o estabelecimento indicado vira Headquarters e headquartersId é regravado — a empresa nunca passa por "sem matriz" nem por "duas matrizes". Estabelecimento de outra empresa ou fora do escopo é 404 ESTABLISHMENT_NOT_FOUND; inativo, 422 ESTABLISHMENT_INACTIVE_UNPROCESSABLE; versão divergente, 409 COMPANY_CONCURRENT_CHANGE_CONFLICT; indicar a matriz atual devolve 200 sem mudança. Publica company.headquarters-changed. Documento emitido não muda: ele aponta para estabelecimento, não para "a matriz".

Para a conta de uma fatia, o código externo é GLAccountCompany.externalCode da empresa do documento; ausente a linha ou o código, GLAccount.externalCode. Sem nenhum dos dois, o movimento não sai para o ERP e fica visível como aguardando código externo, com a conta e a empresa nomeadas — nunca descartado e nunca enviado sem código. Preencher o código libera o envio.

Company e Establishment têm version int. PUT, /activate, /deactivate, /headquarters e /registration-status exigem expectedVersion — divergente, 409 COMPANY_CONCURRENT_CHANGE_CONFLICT ou 409 ESTABLISHMENT_CONCURRENT_CHANGE_CONFLICT, sem gravar nada. É o mesmo token do plano de contas, do Centro de Custo, do Item e do Fornecedor.

Quem concede não abre, não encerra e não altera a vigência das próprias linhas de UserCompanyScope — nem para ampliar validTo, nem para repetir o que já tem. PUT /users/{userId}/company-scopes com o userId de quem concede é recusado com 403 USER_COMPANY_SCOPE_SELF_CHANGE_FORBIDDEN, com ou sem mudança no corpo, antes de qualquer outra guarda. As únicas linhas que nascem para a própria pessoa são as de sistema: a de quem cria a empresa (RN-EMP-20) e a do suporte da plataforma (RN-EMP-24). Sem esta regra, um administrador com acesso temporário a uma empresa estenderia o próprio prazo sem ninguém ver.

"Só se concede o que está no próprio escopo" vale também no tempo. Na empresa em que a linha vigente de quem concede tem validTo, toda linha que o PUT /users/{userId}/company-scopes abre ou reabre para outra pessoa precisa de validTo menor ou igual ao dela; sem validTo, ou com validTo posterior, é 422 USER_COMPANY_SCOPE_BEYOND_GRANTOR_UNPROCESSABLE, nomeando a empresa, e nada é gravado. Quem concede com linha sem fim concede qualquer vigência. A comparação usa a linha de quem concede no instante do ato, e a regra continua valendo depois dele pelo onGrantorChange, gravado na concessão: Cascade quando a linha de quem concede tem validTo, Restrict quando não tem. (1) Cascade: sempre que o fim da vigência de quem concedeu, naquela empresa, diminui — validTo encurtado ou linha encerrada —, a linha dependente cujo validTo passa do novo fim é cortada no mesmo ato e na mesma transação: encerrada, se o novo fim é o instante do ato; encerrada e reaberta com o novo fim, se ele é futuro, conservando grantedByUserId e onGrantorChange. O corte segue em cadeia pelas linhas que ela concedeu, alcança inclusive a linha de quem faz o ato, e cada linha cortada publica user-company-scope.revoked com cause = GrantorChange e a linha de origem. (2) Restrict: o PUT que encerra ou encurta a linha de quem concedeu exige, em dependentGrantDecisions, uma decisão — Keep, End ou Trim — para cada linha Restrict que o novo fim alcança, também em cadeia (as dependentes de uma linha encerrada por End, cortada por Trim ou cortada por Cascade entram na conta). Trim corta a linha até o novo fim de quem concedeu: encerrada e reaberta com esse fim, conservando grantedByUserId e onGrantorChange; quando o novo fim é o instante do ato, vale como End. Cada linha entra uma vez: linha que o ato já alcançou — a encerrada ou encurtada pelo corpo, uma dependente já listada, decidida ou cortada — não volta à lista nem é cortada de novo, e a cadeia para nela; é o que fecha o ciclo em que A concede a B e B reabre a linha de A. Faltando decisão, ou sobrando, 409 USER_COMPANY_SCOPE_DEPENDENT_GRANTS_CONFLICT com a lista, e nada é gravado. A própria linha de quem faz o ato só admite Keep; End ou Trim nela é 403 USER_COMPANY_SCOPE_SELF_CHANGE_FORBIDDEN (RN-EMP-41). Aumentar a vigência, ou encerrar e reabrir sem encurtar, não corta nada. A guarda da RN-EMP-24 é conferida sobre o resultado do ato inteiro, cortes incluídos. Exemplo. A tem linha sem fim na empresa X e concede a B até 30/09 (Restrict: a linha de A não tem fim). B concede a C até 20/09 (Cascade: a de B tem). Em 10/09, Z encurta B para 15/09: C é cortada para 15/09 no mesmo ato, sem pergunta — sem o corte, C, ainda com linha até 20/09, devolveria a B o acesso até 20/09. Em 12/09, Z encerra a linha de A: o PUT sem decisão volta 409 USER_COMPANY_SCOPE_DEPENDENT_GRANTS_CONFLICT listando B; com End, B é encerrada e C cai junto, por Cascade; com Keep, B e C seguem até 15/09. Se, em vez de encerrar, Z encurtasse A para 14/09, a lista seria a mesma, e Trim levaria B a 14/09 e C, por Cascade, também. Ciclo: A concede a B, e B reabre a linha de A, que passa a ter B como quem concedeu; Z encerra A e decide End em B — a linha de A, dependente de B, já foi alcançada pelo ato e não volta à lista. Sem esta regra, um acesso temporário viraria permanente por interposta pessoa, e revogar alguém não revogaria o que ele espalhou.