Criar cliente

POST/v1/clients

Cadastra um novo cliente (tenant) na sua conta — é nele que ficam o certificado digital e a configuração fiscal (UF, CSC/CSC ID, ambiente) usados em toda emissão feita em nome dele. Ao criar o cliente, a API já gera automaticamente os tokens nfe_test_.../nfe_live_... usados no header Authorization: Bearer das chamadas de emissão — veja Obter os tokens de um cliente para recuperá-los.

Autorização: só a Chave de Acesso (X-Access-Key) — não exige a Chave Restrita.

Nada sensível volta na resposta

IE, CSC, CSC ID, certificado e senha do certificado nunca são retornados por nenhum endpoint — tudo é criptografado (AES-256-GCM) antes de ser salvo. A resposta desta chamada também não traz os tokens do cliente; consulte-os separadamente em GET /v1/clients/{cnpj}/tokens.

Parâmetros do corpo

namestringobrigatório

Razão social do cliente. Não vazio, até 255 caracteres.

cnpjstringobrigatório

CNPJ do cliente, com ou sem máscara. O dígito verificador é validado.

iestringobrigatório

Inscrição Estadual. Não vazia, até 255 caracteres.

ufstringobrigatório

Uma das 27 UFs válidas.

cscstringobrigatório

Código de Segurança do Contribuinte (CSC), usado nas NFC-e. Não vazio, até 255 caracteres.

cscIdstringobrigatório

Identificador do CSC. Não vazio, até 255 caracteres.

certificateBase64stringobrigatório

Certificado digital A1 (.pfx/.p12) codificado em base64. Até ~512KB decodificado.

certificatePasswordstringobrigatório

Senha do certificado digital. Não vazia, até 255 caracteres.

environmentnumberpadrão: 2

Valores aceitos: 1 | 2

Ambiente da SEFAZ para as emissões deste cliente. 1: Produção · 2: Homologação.

Resposta

201 Created

idstring

UUID interno do cliente — use nas demais chamadas de gestão de clientes.

namestring

Razão social cadastrada.

cnpjstring

CNPJ normalizado (somente dígitos).

ufstring

UF cadastrada.

environmentnumber

Ambiente configurado (1 ou 2).

createdAtstring

Data e hora de criação do cliente (ISO 8601).

Erros: 400 (campo ausente/inválido, CNPJ inválido, UF inválida, certificado malformado), 401 (Chave de Acesso ausente ou inválida) — veja os formatos de erro.

cURL

curl -X POST https://app.nfe.tenzanlabs.com/v1/clients \
  -H "X-Access-Key: nfe_access_SUA_CHAVE_DE_ACESSO_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa Exemplo LTDA",
    "cnpj": "11.222.333/0001-81",
    "ie": "123456789",
    "uf": "SP",
    "csc": "meu-csc-secreto",
    "cscId": "1",
    "certificateBase64": "<arquivo .pfx/.p12 em base64>",
    "certificatePassword": "senha-do-certificado",
    "environment": 2
  }'

Node.js

import { ClientsClient } from '@tenzanlabs/nfe-node-sdk';

// Só a Access Key — essa API não opera sobre um tenant específico
const clients = new ClientsClient('nfe_access_SUA_CHAVE_DE_ACESSO_AQUI');

const cliente = await clients.createClient({
  name: 'Empresa Exemplo LTDA',
  cnpj: '11.222.333/0001-81',
  ie: '123456789',
  uf: 'SP',
  csc: 'meu-csc-secreto',
  cscId: '1',
  certificateBase64: '<arquivo .pfx/.p12 em base64>',
  certificatePassword: 'senha-do-certificado',
  environment: 2,
});
console.log(cliente.id);

Python

from nfe_sdk import ClientsClient

clients = ClientsClient(access_key='nfe_access_SUA_CHAVE_DE_ACESSO_AQUI')

cliente = clients.create_client({
    "name": "Empresa Exemplo LTDA",
    "cnpj": "11.222.333/0001-81",
    "ie": "123456789",
    "uf": "SP",
    "csc": "meu-csc-secreto",
    "cscId": "1",
    "certificateBase64": "<arquivo .pfx/.p12 em base64>",
    "certificatePassword": "senha-do-certificado",
    "environment": 2,
})
print(cliente["id"])

Java

import br.com.saascore.nfe.ClientsClient;
import br.com.saascore.nfe.model.CreateClientData;
import br.com.saascore.nfe.model.CreateClientResponse;

ClientsClient clients = new ClientsClient("nfe_access_SUA_CHAVE_DE_ACESSO_AQUI");

CreateClientData data = new CreateClientData();
data.name = "Empresa Exemplo LTDA";
data.cnpj = "11.222.333/0001-81";
data.ie = "123456789";
data.uf = "SP";
data.csc = "meu-csc-secreto";
data.cscId = "1";
data.certificateBase64 = "<arquivo .pfx/.p12 em base64>";
data.certificatePassword = "senha-do-certificado";
data.environment = 2;

CreateClientResponse cliente = clients.createClient(data);
System.out.println(cliente.id);

Exemplo de resposta

{
  "id": "183e2c79-7c26-4a9e-b20d-63ce5645497b",
  "name": "Empresa Exemplo LTDA",
  "cnpj": "11222333000181",
  "uf": "SP",
  "environment": 2,
  "createdAt": "2026-08-29T17:31:38.694Z"
}