Cadastros (upsert)

Os cadastros usam PUT com o identificador do seu sistema na rota — upsert idempotente: não existe → cria (201); existe → atualiza (200). Ideal para sincronização contínua a partir do seu ERP, sem você precisar guardar IDs do Notavia.

Recurso	Rota	Identificador
Grupos de produto	`PUT /grupos-produto/{codigo}`	código
Grupos de cliente	`PUT /grupos-cliente/{codigo}`	código
Produtos	`PUT /produtos/{codigo}`	código (SKU)
Clientes	`PUT /clientes/{cpfCnpj}`	CPF ou CNPJ (só dígitos)
Operações fiscais	`PUT /operacoes-fiscais/{codigo}`	código
Transportadoras	`PUT /transportadoras/{cpfCnpj}`	CPF ou CNPJ (só dígitos)

Cada recurso também tem GET de listagem paginada: ?pagina=1&tamanho=50 (máx. 200), resposta { "items": [...], "total": 123, "pagina": 1, "tamanho": 50 }.

Formatos dos campos

A API normaliza os campos com formato fixo (remove pontos, traços e barras) e valida antes de gravar — pode enviar com ou sem máscara. Valor inválido retorna 400 (problem-details) apontando o campo.

Campo	Formato esperado
`cpfCnpj` (cliente, transportadora)	CPF (11 díg.) ou CNPJ (14) com dígito verificador válido. Aceita CNPJ alfanumérico (ver abaixo).
`cep`	8 dígitos
`codigoMunicipioIbge`	7 dígitos
`ncm`	8 dígitos
`cest`	7 dígitos (quando houver ST)
`cfopDentroEstado` / `cfopForaEstado`	4 dígitos
`uf`	2 letras (UF)

CNPJ alfanumérico (Receita, a partir de jul/2026)

Novas inscrições passam a ter CNPJ alfanumérico: 12 posições alfanuméricas ([0-9A-Z]) + 2 dígitos verificadores numéricos. A API já aceita e valida o DV (algoritmo módulo 11 com valor do caractere = ASCII − 48). Use letras maiúsculas; o CNPJ numérico é um caso particular e continua válido. O identificador na rota (/clientes/{cpfCnpj}, /transportadoras/{cpfCnpj}) também aceita o alfanumérico — ex.: PUT /api/integracao/clientes/12ABC34501DE35.

Grupos

PUT /api/integracao/grupos-produto/PAPELARIA
{ "nome": "Papelaria", "descricao": null }

(Mesmo payload para grupos-cliente.) A resposta inclui o id (GUID) do grupo — é ele que você referencia em produtos/clientes.

Produtos

PUT /api/integracao/produtos/CANETA-AZ
{
  "descricao": "Caneta esferográfica azul",
  "ncm": "96081000",
  "cest": null,
  "unidadeComercial": "UN",
  "gtin": null,
  "valorUnitario": 2.50,
  "origemMercadoria": 0,
  "grupoProdutoId": null
}

ncm: 8 dígitos, validado.
origemMercadoria: tabela orig do ICMS (0 = nacional; 1/2/6/7 = estrangeira; 3/5/8 = nacional com conteúdo de importação — 1/2/3/8 usam a alíquota IBPT de importados).
gtin: código de barras (EAN), opcional.
grupoProdutoId: GUID do grupo (obtido no GET /grupos-produto ou na resposta do upsert do grupo); null = sem grupo.

Clientes

PUT /api/integracao/clientes/12345678000190
{
  "tipoPessoa": 1,
  "razaoSocial": "Cliente Exemplo LTDA",
  "nomeFantasia": null,
  "inscricaoEstadual": null,
  "indicadorIe": 9,
  "inscricaoSuframa": null,  // 8-9 dígitos — venda isenta p/ ZFM (CFOP 5110/6110); a SEFAZ valida o DV
  "email": "fiscal@cliente.com.br",
  "telefone": null,
  "grupoClienteId": null,
  "endereco": {
    "logradouro": "Av. Exemplo", "numero": "100", "complemento": null,
    "bairro": "Centro", "municipio": "São Paulo",
    "codigoMunicipioIbge": "3550308", "uf": "SP", "cep": "01000-000"
  }
}

tipoPessoa: 0 = física (CPF), 1 = jurídica (CNPJ).
indicadorIe (campo indIEDest da NF-e): 1 = contribuinte, 2 = isento, 9 = não contribuinte — afeta o destaque do ICMS e o DIFAL.
email: se preenchido, o cliente recebe XML + DANFE automaticamente na autorização.
codigoMunicipioIbge: 7 dígitos (obrigatório para a NF-e).

Cliente no exterior (importação/exportação)

Para um fornecedor/destinatário estrangeiro, informe paisCodigoBacen (código BACEN do país; ≠ 1058) e idEstrangeiro (identificação no exterior, até 20 caracteres) no lugar do CPF/CNPJ. O identificador na rota passa a ser o idEstrangeiro. O CpfCnpj é dispensado e o endereço sai como exterior (UF EX, município/IBGE de exterior).

PUT /api/integracao/clientes/US-TAXID-99887766
{
  "razaoSocial": "Global Supplier Inc",
  "indicadorIe": 9,
  "paisCodigoBacen": 2496,
  "paisNome": "Estados Unidos",
  "idEstrangeiro": "US-TAXID-99887766",
  "endereco": { "logradouro": "500 Tech Ave", "numero": "12", "bairro": "Bay Area",
    "municipio": "EXTERIOR", "codigoMunicipioIbge": "9999999", "uf": "EX", "cep": "" }
}

Operações fiscais

PUT /api/integracao/operacoes-fiscais/VENDA
{
  "descricao": "Venda de mercadoria",
  "tipoOperacao": 1,
  "finalidade": 1,
  "consumidorFinal": true,
  "cfopDentroEstado": "5102",
  "cfopForaEstado": "6102"
}

tipoOperacao: 0 = entrada, 1 = saída.
finalidade (campo finNFe): 1 = normal, 2 = complementar, 3 = ajuste, 4 = devolução.
O CFOP usado em cada item é escolhido pela UF do destinatário (cfopDentroEstado × cfopForaEstado).

A operação é referenciada na emissão por codigoOperacao.

Transportadoras

PUT /api/integracao/transportadoras/11222333000144
{
  "razaoSocial": "Transportes Veloz LTDA",
  "inscricaoEstadual": "ISENTO",
  "endereco": "Rod. BR-116, km 10",
  "municipio": "Curitiba",
  "uf": "PR"
}

Cadastradas uma vez, reaproveite no payload de emissão em transporte.transportadora. O identificador é o CPF/CNPJ (só dígitos); razão social e CPF/CNPJ são obrigatórios.

Validações

Erros de payload retornam 400 no formato problem-details com o campo apontado — veja Erros. Os campos exatos de cada recurso estão na referência interativa em /docs; para experimentar sem escrever código, use o Sandbox.