API: cadastro completo de empresa — guia para o frontend (Nova empresa)

Contrato: apis/16-cadastro-company.md · catálogo.

Integração do formulário Nova empresa (/directories) com o backend CentralCRM.

Endpoint

Item	Valor
Método	`POST`
URL	`{BASE_URL}/api/centralcrm/cadastrocompany`
Exemplo local	`http://localhost:3000/api/centralcrm/cadastrocompany`

Não usa prefixo v1 — rota neutra em /api/centralcrm/....

Autenticação

Authorization: Bearer <sessionHash>
Content-Type: application/json

JWT assinado com o JWT_SECRET do CentralCRM (sessionHash da sessão).
Permissão obrigatória: perm-user-edit (módulo users), salvo bypass para N0 / admin.

Autorização

Cenário	Quem pode
Empresa raiz (`isFilial: false`)	Apenas N0 ou admin (`role` / `role_code` no JWT)
Filial (`isFilial: true` + `parentCompanyUuid`)	Utilizador vinculado à empresa-mãe ou N0/admin

Resposta

HTTP	Significado
201	Cadastro completo (company + endereço + branding + documentos)
400	Validação ou filial sem `parentCompanyUuid`
401	JWT inválido
403	Sem `perm-user-edit` ou regra raiz/filial
409	CNPJ ou subdomínio já existem

Corpo de sucesso: mesmo formato do detalhe do diretório (company, branding, addresses, documents).

Exemplo (fetch)

const baseUrl = import.meta.env.VITE_API_URL ?? 'http://localhost:3000';

const res = await fetch(`${baseUrl}/api/centralcrm/cadastrocompany`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${sessionHash}`,
  },
  body: JSON.stringify({
    isFilial: false,
    tipoEstabelecimento: 'pessoa_juridica',
    tipoEmpresaCodigo: '2',
    cnpj: '12.345.678/0001-90',
    razaoSocial: 'ACME Serviços LTDA',
    nomeFantasia: 'ACME',
    telefone: '(11) 3333-4444',
    email: 'contato@acme.com.br',
    dataFundacao: '2010-05-20',
    mcc: '5411',
    cnae: '6201-5/00',
    site: 'https://www.acme.com.br',
    subdominio: 'minha-empresa',
    espacoBaseDadosMb: 512,
    contatos: [
      {
        nome: 'João Silva',
        cpfCnpj: '123.456.789-00',
        email: 'joao@acme.com.br',
        tipoResponsavel: 'sócio',
        funcaoCargo: 'Diretor',
        telefone: '(11) 99999-8888',
        criarUsuarioNoSistema: false,
      },
    ],
    contasBancarias: [
      {
        tipoConta: 'corrente',
        codigoBanco: '001',
        agencia: '1234',
        numeroConta: '567890',
        digito: '1',
      },
    ],
    endereco: {
      tipoEndereco: 'instalacao',
      cep: '01310-100',
      logradouro: 'Avenida Paulista',
      numero: '1000',
      bairro: 'Bela Vista',
      cidade: 'São Paulo',
      uf: 'SP',
      pais: 'Brasil',
    },
    branding: {
      logotipo: 'https://cdn.example.com/logo.png',
      marca: 'ACME',
      corPrincipal: '#191B1F',
    },
    documentos: [
      { tipo: 'contrato', caminhoArquivo: 'https://cdn.example.com/doc.pdf' },
    ],
  }),
});

if (!res.ok) {
  const err = await res.json().catch(() => ({}));
  throw new Error(err.message ?? res.statusText);
}

const detail = await res.json();

O que substituir no front

Em vez de POST /api/v1/companies ou POST /api/v1/company/directory com payloads parciais, use este endpoint no submit do wizard Nova empresa para gravar tudo de uma vez.

Swagger: /api/docs → tag CentralCRM — Empresas.

Endpoint​

Autenticação​

Autorização​

Resposta​

Exemplo (fetch)​

O que substituir no front​