Referência: Tomadores
Atualizado em
Nesta página
O tomador é o cliente que recebe o serviço e a nota. Cadastrar o tomador antes permite emitir só com o tomador_id e reaproveitar os dados em todas as notas.
| Método | Rota | Escopo |
|---|---|---|
POST |
/integracao/tomadores |
customers:write |
GET |
/integracao/tomadores |
customers:read |
GET |
/integracao/tomadores/{id} |
customers:read |
PATCH |
/integracao/tomadores/{id} |
customers:write |
DELETE |
/integracao/tomadores/{id} |
customers:write |
O objeto tomador#
Tomador
{
"id": "5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10",
"tipo_pessoa": "PJ",
"documento": "11444777000161",
"nome": "Padaria Silva Ltda",
"email": "financeiro@padariasilva.com.br",
"telefone": "11999990000",
"inscricao_municipal": null,
"endereco": {
"logradouro": "Rua das Flores",
"numero": "100",
"complemento": null,
"bairro": "Centro",
"cep": "01001000",
"municipio_ibge": "3550308",
"uf": "SP"
},
"pais": "BR",
"ativo": true,
"is_test": true,
"created_at": "2026-11-11T10:12:04-03:00",
"updated_at": "2026-11-11T10:12:04-03:00"
}| Campo | Tipo | Descrição |
|---|---|---|
id |
uuid | Identificador do tomador |
tipo_pessoa |
PF · PJ · EXT |
Pessoa física, jurídica ou estrangeiro |
documento |
string | CPF (11 dígitos), CNPJ (14 posições, aceita alfanumérico) ou NIF do estrangeiro (até 40). Sem pontuação. Opcional só para EXT |
nome |
string | Nome ou razão social, até 200 caracteres. Obrigatório |
email |
string | E-mail para envio da nota |
telefone |
string | Só dígitos |
inscricao_municipal |
string | Inscrição municipal do tomador, se houver |
endereco |
objeto | Endereço. municipio_ibge tem 7 dígitos |
pais |
string | ISO 3166-1 alfa-2. Sempre BR para PF e PJ; obrigatório e diferente de BR para EXT |
ativo |
boolean | Tomadores inativos não aparecem na busca do painel |
is_test |
boolean | true se criado com chave de teste |
Criar um tomador#
POST /integracao/tomadores → 201 Created
cURL
curl https://emitra.com.br/api/v1/integracao/tomadores \
-H "Authorization: Bearer $EMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tipo_pessoa": "PJ",
"documento": "11444777000161",
"nome": "Padaria Silva Ltda",
"email": "financeiro@padariasilva.com.br",
"endereco": { "logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
"cep": "01001000", "municipio_ibge": "3550308", "uf": "SP" }
}'Python
r = requests.post(f"{API}/tomadores", headers=H, json={
"tipo_pessoa": "PJ",
"documento": "11444777000161",
"nome": "Padaria Silva Ltda",
"email": "financeiro@padariasilva.com.br",
"endereco": {"logradouro": "Rua das Flores", "numero": "100", "bairro": "Centro",
"cep": "01001000", "municipio_ibge": "3550308", "uf": "SP"},
})
tomador = r.json()["data"]JavaScript
const r = await fetch(`${API}/tomadores`, {
method: "POST",
headers,
body: JSON.stringify({
tipo_pessoa: "PJ",
documento: "11444777000161",
nome: "Padaria Silva Ltda",
email: "financeiro@padariasilva.com.br",
endereco: { logradouro: "Rua das Flores", numero: "100", bairro: "Centro",
cep: "01001000", municipio_ibge: "3550308", uf: "SP" },
}),
});
const { data: tomador } = await r.json();PHP
<?php
$ch = curl_init("$api/tomadores");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => json_encode([
"tipo_pessoa" => "PJ",
"documento" => "11444777000161",
"nome" => "Padaria Silva Ltda",
"email" => "financeiro@padariasilva.com.br",
"endereco" => ["logradouro" => "Rua das Flores", "numero" => "100", "bairro" => "Centro",
"cep" => "01001000", "municipio_ibge" => "3550308", "uf" => "SP"],
]),
]);
$tomador = json_decode(curl_exec($ch), true)["data"];Resposta: 201 com o objeto tomador em data.
Tomador estrangeiro#
Corpo
{
"tipo_pessoa": "EXT",
"documento": "DE123456789",
"nome": "Beispiel GmbH",
"pais": "DE"
}Consultar um tomador#
GET /integracao/tomadores/{id} → 200
cURL
curl https://emitra.com.br/api/v1/integracao/tomadores/5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10 \
-H "Authorization: Bearer $EMITRA_API_KEY"Listar tomadores#
GET /integracao/tomadores → 200, paginado por cursor.
| Parâmetro | Descrição |
|---|---|
documento |
Filtra pelo CPF, CNPJ ou NIF exato, sem pontuação |
limit, cursor |
Paginação |
cURL
curl "https://emitra.com.br/api/v1/integracao/tomadores?documento=11444777000161" \
-H "Authorization: Bearer $EMITRA_API_KEY"Python
r = requests.get(f"{API}/tomadores", headers=H, params={"documento": "11444777000161"})
encontrados = r.json()["data"]["items"]JavaScript
const r = await fetch(`${API}/tomadores?documento=11444777000161`, { headers });
const { data } = await r.json();PHP
<?php
$ch = curl_init("$api/tomadores?" . http_build_query(["documento" => "11444777000161"]));
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true]);
$encontrados = json_decode(curl_exec($ch), true)["data"]["items"];Alterar um tomador#
PATCH /integracao/tomadores/{id} → 200. Envie só os campos que mudam.
cURL
curl -X PATCH https://emitra.com.br/api/v1/integracao/tomadores/5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10 \
-H "Authorization: Bearer $EMITRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "nfe@padariasilva.com.br" }'A alteração vale para as próximas notas. As notas já emitidas guardam uma cópia dos dados do tomador do momento da emissão e não mudam.
Excluir um tomador#
DELETE /integracao/tomadores/{id} → 200
A exclusão é lógica: o tomador some das listas e não pode mais ser usado em novas notas, mas o histórico fiscal continua intacto.
cURL
curl -X DELETE https://emitra.com.br/api/v1/integracao/tomadores/5f0c2a8e-1b7d-4c3e-9a51-2d6e8f4b7c10 \
-H "Authorization: Bearer $EMITRA_API_KEY"Erros específicos#
code |
HTTP | Causa |
|---|---|---|
INVALID_CNPJ |
422 | CNPJ com dígito verificador inválido |
INVALID_CPF |
422 | CPF com dígito verificador inválido |
INVALID_NIF |
422 | NIF com mais de 40 caracteres |
INVALID_EMAIL |
422 | E-mail inválido |
INVALID_IBGE |
422 | municipio_ibge sem 7 dígitos |
NAME_REQUIRED |
422 | nome vazio |
COUNTRY_REQUIRED |
422 | Estrangeiro sem pais ou com pais = BR |
CONFLICT |
409 | Já existe tomador com o mesmo documento |
Os erros gerais estão em Erros.
Próximos passos#
Esta página foi útil?