Docs/NFS-e
NFS-e — Nota Fiscal de Serviços Eletrônica
Endpoints para emissão, consulta e cancelamento de notas fiscais de serviço. A emissão é sempre em produção.
Ver requisitos de autenticaçãoHeaders
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros do body
serviceDescription
stringobrigatórioDiscriminação completa do serviço na nota (até 2000 chars). Aceita variáveis como {nomeProduto}. Não use como nome curto do catálogo.
name
stringopcionalNome do item no catálogo (3–64). Se omitido, usa os primeiros 64 caracteres de serviceDescription. Default implícito: slice da discriminação.
sku
stringopcionalSKU do serviço no catálogo. Default: direct-api-nfse.
category
stringopcionalCategoria do catálogo (ex.: subscription, saas, online_course, other_service). Default: other_service.
guarantee
numberopcionalGarantia em dias (1–365).
cityServiceCode
stringobrigatórioCódigo do serviço municipal (ex.: 02800). Não herda padrão da empresa.
federalServiceCode
stringobrigatórioItem da lista LC 116 (ex.: 01.05). Vai para cTribNac no DPS nacional.
nbs
stringopcionalCódigo NBS (reforma tributária). Vai para cNBS quando informado.
cnaeCode
stringopcionalCNAE do serviço (7 dígitos).
iss
objectobrigatórioISS do serviço. iss.rate é obrigatório (0 permitido). A emissão não herda alíquotas da empresa.
rate
numberobrigatórioAlíquota ISS em % (0–100). Zero é válido.
isWithheld
booleanopcionalISS retido. Default: false.
ibsCbs
objectopcionalGrupo IBS/CBS (reforma). Defaults na emissão: cst 000, taxClassCode 000001, operationIndicator 100301.
cst
stringopcionalCST IBS/CBS. Default: 000.
taxClassCode
stringopcionalClassificação tributária (cClassTrib). Default: 000001.
operationIndicator
stringopcionalIndicador de operação (cIndOp). Default: 100301.
natureOfOperation
stringopcionalNatureza da operação ISS (1–6). Default na emissão: 1.
serviceLocation
stringopcionalLocal de prestação (1 ou 2). Default na emissão: 1.
municipalityOfIncidence
stringopcionalMunicípio de incidência (0, 1 ou 2). Default na emissão: 0.
taxes
objectopcionalRetenções federais opcionais: pis, cofins, csll, ir, inss — cada um { rate, isWithheld }. O ISS canônico é o campo iss no topo.
amount
numberobrigatórioValor do serviço em reais.
issueDate
string (ISO 8601)opcionalData da venda / competência. Padrão: data atual.
externalId
stringopcionalIdentificador externo para idempotência.
borrower
objectobrigatórioDados do tomador do serviço.
taxId
stringopcionalCPF ou CNPJ do tomador.
name
stringobrigatórioNome do tomador.
E-mail do tomador.
curl -X POST "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfse" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
-H "Idempotency-Key: pedido-001" \
-H "Content-Type: application/json" \
-d '{
"name": "Desenvolvimento sob demanda",
"category": "systems_development",
"serviceDescription": "Desenvolvimento de software sob demanda",
"cityServiceCode": "02800",
"federalServiceCode": "01.05",
"natureOfOperation": "1",
"iss": { "rate": 2.9, "isWithheld": false },
"amount": 2500.00,
"borrower": {
"taxId": "12.345.678/0001-90",
"name": "Empresa Cliente LTDA",
"email": "[email protected]"
}
}'{
"success": true,
"data": {
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "processing",
"type": "nfse",
"externalId": "pedido-001",
"amount": 2500.00,
"createdAt": "2026-07-06T10:28:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "borrower.name", "error": "..." }]
}
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Query params
page
numberopcionalPágina atual. Padrão: 1.
pageSize
numberopcionalItens por página. Padrão: 20.
status
stringopcionalFiltra por status (processing, authorized, rejected, canceled).
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfse?page=1&pageSize=20" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"success": true,
"data": [
{
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "authorized",
"type": "nfse",
"amount": 2500.00,
"createdAt": "2026-07-06T10:28:00.000Z"
}
],
"pageInfo": {
"page": 1,
"pageSize": 20,
"total": 1
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "borrower.name", "error": "..." }]
}
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador único da NFS-e.
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfse/018f6e3b-0000-0000-0000-000000000000" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"success": true,
"data": {
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "processing",
"type": "nfse",
"externalId": "pedido-001",
"amount": 2500.00,
"createdAt": "2026-07-06T10:28:00.000Z"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "borrower.name", "error": "..." }]
}
}
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador único da NFS-e.
curl -X DELETE "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/nfse/018f6e3b-0000-0000-0000-000000000000" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"success": true,
"data": {
"id": "018f6e3b-0000-0000-0000-000000000000",
"status": "canceled",
"type": "nfse"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos contém erros de validação. Por favor, revise os dados informados.",
"details": {
"fields": [{ "field": "borrower.name", "error": "..." }]
}
}
}