Pular para o conteúdo
notemnotemDocumentação

Referência da API › Tomadores

Cadastrar tomador

Guarda os dados de um cliente para usar nas próximas notas.

POST/api/v1/empresas/{id}/tomadores

Use para não repetir os dados do cliente em cada emissão: depois, basta informar tomador_id ou tomador_id_externo em Emitir nota. Os campos são os mesmos do tomador da nota.

O id_externo é opcional e não pode se repetir na mesma empresa.

Parâmetros

idtextono caminhoobrigatório
Empresa da organização da chave (de outra organização → 404). UUID (RFC 9562); fora do padrão → 400 REQUISICAO_INVALIDA com campo id. · UUID
Idempotency-Keytextono cabeçalho
Chave de idempotência (até 100 caracteres) aceita em POST, PATCH, PUT e DELETE; vale 24 h por integração e ambiente, exceto emissão, cancelamento, análise e substituição de notas (associação duradoura ao pedido). Mesmo conteúdo devolve a mesma resposta (cabeçalho Idempotent-Replayed true); conteúdo diferente devolve 409 IDEMPOTENCIA_CONFLITO. Obrigatória em emissão, cancelamento e substituição. · até 100 caracteres

Corpo da requisição

id_externotexto ou null
Único por empresa · até 100 caracteres
tipotextoobrigatório
Valores: pj, pf, estrangeiro
nometextoobrigatório
1 a 150 caracteres
documentotexto ou null
CPF (11 números) ou CNPJ (14 posições, numérico ou alfanumérico) com dígitos verificadores válidos; máscara e minúsculas são normalizadas · até 18 caracteres
niftexto ou null
até 40 caracteres
motivo_sem_niftexto ou null
Valores: dispensado, nao_exigido
emailtexto ou null
telefonetexto ou null
inscricao_municipaltexto ou null
até 15 caracteres
enderecoobjeto ou null
Nacional exige CEP/logradouro/número/bairro/IBGE. Exterior exige país/cidade/código postal/província/logradouro ou endereço livre/número/bairro. Complemento opcional.
endereco.ceptexto
Formato: ^[0-9]{8}$
endereco.codigo_municipiotexto
Formato: ^[0-9]{7}$
endereco.paistexto
Formato: ^[A-Z]{2}$
endereco.cidadetexto
endereco.codigo_postaltexto
endereco.estado_provincia_regiaotexto
endereco.logradourotexto
endereco.endereco_livretexto
endereco.numerotexto
endereco.bairrotexto
endereco.complementotexto ou null

Respostas

201 Tomador criado

Campos da resposta
idtexto
UUID
id_externotexto ou null
Único por empresa · até 100 caracteres
tipotexto
Valores: pj, pf, estrangeiro
nometexto
1 a 150 caracteres
documentotexto ou null
CPF (11 números) ou CNPJ (14 posições, numérico ou alfanumérico) com dígitos verificadores válidos; máscara e minúsculas são normalizadas · até 18 caracteres
niftexto ou null
até 40 caracteres
motivo_sem_niftexto ou null
Valores: dispensado, nao_exigido
emailtexto ou null
telefonetexto ou null
inscricao_municipaltexto ou null
até 15 caracteres
enderecoobjeto ou null
Nacional exige CEP/logradouro/número/bairro/IBGE. Exterior exige país/cidade/código postal/província/logradouro ou endereço livre/número/bairro. Complemento opcional.
endereco.ceptexto
Formato: ^[0-9]{8}$
endereco.codigo_municipiotexto
Formato: ^[0-9]{7}$
endereco.paistexto
Formato: ^[A-Z]{2}$
endereco.cidadetexto
endereco.codigo_postaltexto
endereco.estado_provincia_regiaotexto
endereco.logradourotexto
endereco.endereco_livretexto
endereco.numerotexto
endereco.bairrotexto
endereco.complementotexto ou null
criada_emtexto
data e hora ISO 8601
atualizada_emtexto
data e hora ISO 8601

400 Erro no formato padrão

409 ID_EXTERNO_DUPLICADO por empresa ou IDEMPOTENCIA_CONFLITO

Limites

Valem também os limites gerais da chave. Veja Limites de uso.