Org API · Enterprise

Gestão via API

Gerencie projetos, API keys, certificados A1 e configurações white-label da sua organização programaticamente. Ideal para plataformas que fazem onboarding autônomo de sub-clientes.

Autenticação

Todos os endpoints desta seção exigem um Organization Token (prefixo ntaas_org_) no header x-api-key. Tokens de projeto (ntaas_) não são aceitos nestas rotas.

curl -H "x-api-key: ntaas_org_XXXXXXXXXXXXXXXXXXXXXXXX" \
  https://platform.notaas.com.br/api/v1/org/projects

Scope	Permissão
projects:read	Listar e visualizar projetos
projects:write	Criar e atualizar projetos
api_keys:manage	Criar, listar e revogar API keys
settings:read	Ler configurações da organização
settings:write	Configurar domínio white-label
certificates:write	Upload de certificado A1

Projetos

POST/org/projects🔑 x-api-key

Cria um novo projeto (empresa fiscal) na organização. Verifica limite do plano e duplicidade de CNPJ.

Body (JSON)

Campo	Tipo	Req?	Descrição
name	string	sim	Nome do projeto (ex: "Filial SP")
cnpj	string	sim	CNPJ com 14 dígitos (formatado ou não). Validado com dígitos verificadores.
razaoSocial	string	sim	Razão social da empresa
inscricaoMunicipal	string	não	Inscrição municipal
inscricaoEstadual	string	não	Inscrição estadual
regimeTributario	"1"\|"2"\|"3"\|"3e"	não	"1" = Não Optante, "2" = MEI, "3" = SN ME/EPP, "3e" = SN Excesso de Sublimite
codigoMunicipio	string	não	Código IBGE 7 dígitos (ex: "4113700"). Validado contra a tabela de municípios.
email	string	não	E-mail da empresa
telefone	string	não	Telefone da empresa
description	string	não	Descrição do projeto
endereco.logradouro	string	não	Logradouro
endereco.numero	string	não	Número
endereco.complemento	string	não	Complemento
endereco.bairro	string	não	Bairro
endereco.cidade	string	não	Nome da cidade
endereco.uf	string	não	Sigla do estado (ex: "SP")
endereco.cep	string	não	CEP (apenas dígitos)
codigoTributacao	string	não	Código de Tributação Nacional (LC 116/2003). Pré-preenche ao emitir NFS-e.
tributacaoIss	1\|2\|3\|4	não	Tributação ISSQN: 1=Tributável, 2=Fora do campo, 3=Exportação, 4=Não Incidência
serieNfse	string	não	Série da NFS-e (padrão: "1608", máx 5 dígitos)
aliquotaSimples	number	não	Alíquota efetiva DAS (%) para empresas SN ME/EPP
regimeIss	1\|2\|3	não	Apuração ISS no SN: 1=ISS no DAS, 2=ISS separado, 3=Ambos separados
codigoServicoSp	string	não	Código de serviço da Prefeitura SP (5 dígitos). Obrigatório para município SP.
cnae	string	não	CNAE principal. Obrigatório para GINFES e Brasília/DF.
centiUsuario	string	não	Usuário para municípios com sistema Centi
centiSenha	string	não	Senha Centi (write-only)
ambiente	1\|2	não	Ambiente: 1=Produção, 2=Homologação
serieNfe	number	não	Série NF-e mod. 55 (1-999)
serieNfce	number	não	Série NFC-e mod. 65 (1-999)
cscId	string	não	ID do CSC obtido no portal SEFAZ do estado
cscToken	string	não	Token CSC (write-only — nunca retornado)

{
  "name": "Filial São Paulo",
  "cnpj": "12345678000195",
  "razaoSocial": "Acme Sistemas Ltda",
  "regimeTributario": "3",
  "codigoMunicipio": "3550308",
  "email": "[email protected]",
  "endereco": {
    "logradouro": "Av Paulista",
    "numero": "1000",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  }
}

// Response 201
{
  "id": "a1b2c3d4-...",
  "name": "Filial São Paulo",
  "cnpj": "12345678000195",
  "razaoSocial": "Acme Sistemas Ltda",
  "codigoMunicipio": "3550308",
  "active": true,
  "createdAt": "2026-04-21T20:30:00Z"
}

Erros

Campo	Tipo	Req?	Descrição
400	Bad Request	não	CNPJ inválido, campo obrigatório ausente, código IBGE inexistente
403	Forbidden	não	Limite de projetos do plano atingido
409	Conflict	não	CNPJ já cadastrado na organização (retorna existingProjectId)

GET/org/projects🔑 x-api-key

Lista todos os projetos da organização com paginação e status de certificado/API key.

Query Params

Campo	Tipo	Req?	Descrição
page	number	não	Página (padrão: 1)
limit	number	não	Itens por página (padrão: 20, máx: 100)
active	boolean	não	Filtrar por ativos (padrão: true). Use active=false para incluir inativos.

// Response 200
{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Filial SP",
      "cnpj": "12345678000195",
      "codigoMunicipio": "3550308",
      "active": true,
      "hasCertificate": true,
      "hasApiKey": true,
      "createdAt": "2026-04-21T20:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3 }
}

GET/org/projects/{id}🔑 x-api-key

Retorna os dados completos de um projeto (exceto certificado e senha).

// Response 200
{
  "id": "a1b2c3d4-...",
  "name": "Filial SP",
  "cnpj": "12345678000195",
  "razaoSocial": "Acme Sistemas Ltda",
  "inscricaoMunicipal": "12345",
  "inscricaoEstadual": "123456789",
  "regimeTributario": "3",
  "crt": 1,
  "codigoMunicipio": "3550308",
  "endereco": {
    "logradouro": "Av Paulista",
    "numero": "1000",
    "complemento": null,
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "email": "[email protected]",
  "telefone": "11999999999",
  "codigoTributacao": null,
  "tributacaoIss": 1,
  "serieNfse": "1608",
  "aliquotaSimples": 3.5,
  "regimeIss": null,
  "codigoServicoSp": "01015",
  "cnae": "6201501",
  "centiUsuario": null,
  "ambiente": 2,
  "serieNfe": 1,
  "serieNfce": 1,
  "cscId": "000001",
  "hasCscToken": true,
  "active": true,
  "createdAt": "2026-04-21T20:30:00Z",
  "updatedAt": "2026-04-21T20:30:00Z"
}

PATCH/org/projects/{id}🔑 x-api-key

Atualiza campos do projeto. O CNPJ é imutável após criação.

Body (JSON) — campos opcionais

Campo	Tipo	Req?	Descrição
name	string	não	Novo nome do projeto
razaoSocial	string	não	Nova razão social
inscricaoMunicipal	string	não	Inscrição municipal
inscricaoEstadual	string	não	Inscrição estadual
regimeTributario	"1"\|"2"\|"3"\|"3e"	não	Regime tributário ("1"=Não Optante, "2"=MEI, "3"=SN ME/EPP, "3e"=SN Excesso)
codigoMunicipio	string	não	Código IBGE do município
email	string	não	E-mail
telefone	string	não	Telefone
description	string	não	Descrição do projeto
endereco.*	object	não	Campos de endereço (logradouro, numero, bairro, cidade, uf, cep)
codigoTributacao	string	não	Código de Tributação Nacional (LC 116/2003)
tributacaoIss	1\|2\|3\|4	não	Tributação ISSQN: 1=Tributável, 2=Fora do campo, 3=Exportação, 4=Não Incidência
serieNfse	string	não	Série da NFS-e (padrão: "1608", máx 5 dígitos)
aliquotaSimples	number \| null	não	Alíquota efetiva DAS (%) para empresas SN ME/EPP
regimeIss	1\|2\|3 \| null	não	Apuração ISS no SN: 1=ISS no DAS, 2=ISS separado, 3=Ambos separados
codigoServicoSp	string	não	Código de serviço da Prefeitura SP (5 dígitos)
cnae	string	não	CNAE principal
centiUsuario	string	não	Usuário para municípios com sistema Centi
centiSenha	string	não	Senha Centi (write-only)
ambiente	1\|2	não	Ambiente: 1=Produção, 2=Homologação
serieNfe	number \| null	não	Série NF-e mod. 55 (1-999)
serieNfce	number \| null	não	Série NFC-e mod. 65 (1-999)
cscId	string \| null	não	ID do CSC
cscToken	string \| null	não	Token CSC (write-only)

// Request
{ "name": "Filial SP - Centro", "regimeTributario": "1" }

// Response 200
{ "updated": true, "id": "a1b2c3d4-..." }

API Keys de Projeto

POST/org/projects/{id}/api-keys🔑 x-api-key

Cria uma API key para o projeto. A chave completa é retornada apenas nesta resposta — nunca mais.

Body (JSON)

Campo	Tipo	Req?	Descrição
name	string	sim	Nome descritivo da chave (ex: "Produção Backend")

// Response 201
{
  "id": "key-uuid-...",
  "name": "Produção Backend",
  "key": "ntaas_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "keyPrefix": "ntaas_XXXX",
  "scopes": ["emit", "cancel", "query"],
  "rateLimitPerMinute": 60,
  "createdAt": "2026-04-21T20:35:00Z"
}

⚠️ Atenção

O campo key é exibido apenas nesta resposta. Armazene-o com segurança. Se perdido, revogue e crie uma nova chave.

GET/org/projects/{id}/api-keys🔑 x-api-key

Lista as API keys do projeto (sem expor a chave completa).

// Response 200
{
  "data": [
    {
      "id": "key-uuid-...",
      "name": "Produção Backend",
      "keyPrefix": "ntaas_XXXX",
      "scopes": ["emit", "cancel", "query"],
      "rateLimitPerMinute": 60,
      "active": true,
      "lastUsedAt": "2026-04-21T20:40:00Z",
      "createdAt": "2026-04-21T20:35:00Z"
    }
  ]
}

DELETE/org/projects/{id}/api-keys/{keyId}🔑 x-api-key

Revoga (desativa) uma API key. A chave para de funcionar imediatamente.

// Response 200
{ "revoked": true, "id": "key-uuid-..." }

Certificado Digital A1

POST/org/projects/{id}/certificate🔑 x-api-key

Upload de certificado digital A1 (.pfx/.p12). Substitui atomicamente o certificado anterior.

Body (multipart/form-data)

Campo	Tipo	Req?	Descrição
file	File (.pfx/.p12)	sim	Arquivo do certificado A1 (máx. 50KB)
password	string	sim	Senha do certificado

curl -X POST https://platform.notaas.com.br/api/v1/org/projects/{id}/certificate \
  -H "x-api-key: ntaas_org_XXXXXXXX..." \
  -F "[email protected]" \
  -F "password=minhaSenha123"

// Response 201
{
  "id": "cert-uuid-...",
  "fileName": "certificado.pfx",
  "subjectCN": "ACME SISTEMAS LTDA:12345678000195",
  "validFrom": "2026-01-15T00:00:00Z",
  "validUntil": "2027-01-15T23:59:59Z",
  "daysUntilExpiration": 269,
  "active": true
}

Erros

Campo	Tipo	Req?	Descrição
400	Bad Request	não	Arquivo inválido, senha incorreta, certificado expirado
413	Payload Too Large	não	Arquivo excede 50KB

Configurações da Organização

GET/org/settings🔑 x-api-key

Retorna configurações atuais da organização e resumo de uso do plano.

// Response 200
{
  "name": "Acme Sistemas",
  "slug": "acme-sistemas",
  "storageBaseUrl": "https://storage.acmesistemas.com.br",
  "subscription": {
    "planName": "Pro",
    "planSlug": "pro",
    "creditsUsed": 42,
    "creditsLimit": 500,
    "daysLeft": 18
  }
}

PATCH/org/settings🔑 x-api-key

Configura o domínio white-label para documentos (PDF/XML). O CNAME deve apontar para backbone.notaas.com.br.

Body (JSON)

Campo	Tipo	Req?	Descrição
storageBaseUrl	string \| null	sim	URL HTTPS do domínio customizado (ex: "https://storage.acme.com.br"). Envie null para remover.

// Request
{ "storageBaseUrl": "https://storage.acmesistemas.com.br" }

// Response 200
{
  "storageBaseUrl": "https://storage.acmesistemas.com.br",
  "status": "pending_verification",
  "message": "Configure o CNAME do domínio apontando para backbone.notaas.com.br."
}

Validações

Campo	Tipo	Req?	Descrição
HTTPS	obrigatório	não	Apenas URLs com protocolo https: são aceitas
Domínio público	obrigatório	não	Sem localhost, IPs, .local ou hostnames sem domínio
CNAME	manual	não	Configure o registro CNAME apontando para backbone.notaas.com.br

Rate Limiting

Org Tokens possuem rate limit de 120 requisições/minuto por padrão. Ao exceder, a API retorna 429 Too Many Requests com o header Retry-After.

Fluxo Completo de Onboarding

PASSO A PASSO

Criar org token no dashboard (Settings → API Tokens → Novo)
POST /org/projects — criar projeto do sub-cliente
POST /org/projects/:id/certificate — upload do certificado A1
POST /org/projects/:id/api-keys — criar API key do projeto
Usar a ntaas_ key retornada para emitir notas via POST /emitir