Referência: Itens de serviço

Atualizado em 11/11/2026

Nesta página

O objeto item
Criar um item
Consultar um item
Listar itens
Alterar um item
Excluir um item
Erros específicos
Próximos passos

Um item de serviço guarda o que se repete em toda nota de um mesmo serviço: a descrição padrão, o código de tributação nacional (cTribNac), o NBS, a alíquota e o valor. Na emissão, você envia o item_id e a Emitra preenche o resto.

Método	Rota	Escopo
`POST`	`/integracao/itens`	`items:write`
`GET`	`/integracao/itens`	`items:read`
`GET`	`/integracao/itens/{id}`	`items:read`
`PATCH`	`/integracao/itens/{id}`	`items:write`
`DELETE`	`/integracao/itens/{id}`	`items:write`

O objeto item#

Item

{
  "id": "8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42",
  "tipo": "servico",
  "codigo": "CONS-TI",
  "descricao": "Consultoria em tecnologia da informação",
  "codigo_tributacao_nacional": "010601",
  "codigo_tributacao_municipal": null,
  "codigo_nbs": "115011000",
  "aliquota_iss": "2.00",
  "valor_unitario": "1500.00",
  "ativo": true,
  "is_test": true,
  "created_at": "2026-11-11T10:13:40-03:00",
  "updated_at": "2026-11-11T10:13:40-03:00"
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do item
`tipo`	`servico` · `produto`	Tipo do item. A NFS-e usa `servico`
`codigo`	string	Seu código interno (até 60 caracteres). Útil para casar com o ERP
`descricao`	string	Descrição padrão do serviço. Obrigatório
`codigo_tributacao_nacional`	string	cTribNac, 6 dígitos (item, subitem e desdobro da lista nacional)
`codigo_tributacao_municipal`	string	cTribMun, até 3 dígitos, quando o município usa
`codigo_nbs`	string	NBS, 9 dígitos, sem pontos
`aliquota_iss`	string decimal	Alíquota padrão do ISS, em %
`valor_unitario`	string decimal	Valor padrão, não negativo
`ativo`	boolean	Itens inativos não aparecem no painel

Os códigos do exemplo são ilustrativos. Confira o cTribNac e o NBS do seu serviço nas tabelas oficiais.

Criar um item#

POST /integracao/itens → 201 Created

cURL

curl https://emitra.com.br/api/v1/integracao/itens \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "servico",
    "codigo": "CONS-TI",
    "descricao": "Consultoria em tecnologia da informação",
    "codigo_tributacao_nacional": "010601",
    "codigo_nbs": "115011000",
    "aliquota_iss": "2.00",
    "valor_unitario": "1500.00"
  }'

Python

r = requests.post(f"{API}/itens", headers=H, json={
    "tipo": "servico",
    "codigo": "CONS-TI",
    "descricao": "Consultoria em tecnologia da informação",
    "codigo_tributacao_nacional": "010601",
    "codigo_nbs": "115011000",
    "aliquota_iss": "2.00",
    "valor_unitario": "1500.00",
})
item = r.json()["data"]

JavaScript

const r = await fetch(`${API}/itens`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    tipo: "servico",
    codigo: "CONS-TI",
    descricao: "Consultoria em tecnologia da informação",
    codigo_tributacao_nacional: "010601",
    codigo_nbs: "115011000",
    aliquota_iss: "2.00",
    valor_unitario: "1500.00",
  }),
});
const { data: item } = await r.json();

PHP

<?php
$ch = curl_init("$api/itens");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode([
        "tipo" => "servico",
        "codigo" => "CONS-TI",
        "descricao" => "Consultoria em tecnologia da informação",
        "codigo_tributacao_nacional" => "010601",
        "codigo_nbs" => "115011000",
        "aliquota_iss" => "2.00",
        "valor_unitario" => "1500.00",
    ]),
]);
$item = json_decode(curl_exec($ch), true)["data"];

O cTribNac é normalizado para 6 dígitos com zeros à esquerda (10601 vira 010601).

Consultar um item#

GET /integracao/itens/{id} → 200

cURL

curl https://emitra.com.br/api/v1/integracao/itens/8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42 \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Listar itens#

GET /integracao/itens → 200, paginado por cursor com limit e cursor.

cURL

curl "https://emitra.com.br/api/v1/integracao/itens?limit=100" \
  -H "Authorization: Bearer $EMITRA_API_KEY"

Alterar um item#

PATCH /integracao/itens/{id} → 200. Envie só os campos que mudam.

cURL

curl -X PATCH https://emitra.com.br/api/v1/integracao/itens/8a3e6d21-4f9b-4b2a-bc17-0e5d9c3a6f42 \
  -H "Authorization: Bearer $EMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "valor_unitario": "1650.00" }'

Notas já emitidas e agendamentos recorrentes guardam uma cópia do item e não mudam com a alteração. Para reajustar uma recorrência, edite o agendamento no painel.

Excluir um item#

DELETE /integracao/itens/{id} → 200. A exclusão é lógica e preserva o histórico.

Erros específicos#

`code`	HTTP	Causa
`DESCRIPTION_REQUIRED`	422	`descricao` vazia
`INVALID_CTRIBNAC`	422	cTribNac sem 6 dígitos
`INVALID_CTRIBMUN`	422	cTribMun vazio ou com mais de 3 dígitos
`INVALID_NBS`	422	NBS sem 9 dígitos
`INVALID_ISS_RATE`	422	Alíquota fora de 0 a 100
`INVALID_PRICE`	422	Valor negativo

Próximos passos#

Esta página foi útil?