Notas fiscais

NFS-e: emissão, PDF, XML, e-mail e cancelamento.

10 rotas. Todas exigem a chave de API no header Authorization, salvo quando marcadas como públicas. Abrir este módulo no Swagger.

Listar notas fiscais por período e status

GET /companie/financial/serviceInvoiceCompany/list

As notas ficam no provedor de NFS-e; o LeadSim acrescenta cliente, lançamento e contrato da empresa.

• status: aba da tela (emitidas, processando, canceladas, falhas). type: avulsa ou vinculada.
• date_start/date_end em YYYY-MM-DD. client_id filtra pelo CPF/CNPJ do cliente; cliente sem documento devolve lista vazia.
• Paginação por skip/take. O padrão é 20 e o provedor limita a 100 por página, mesmo com take até 200.
• indicators vale para o filtro inteiro, sem considerar status.
• Exige a NFS-e configurada na empresa.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
client_id	query	número
date_start	query	string
date_end	query	string
status	query	emitidas · processando · canceladas · falhas
type	query	avulsa · vinculada
q	query	string
skip	query	número
take	query	número

Respostas

Status	Descrição
200	Página de notas.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)
502	O provedor de NFS-e não respondeu.

Testar no Swagger

Listar lançamentos elegíveis para nota vinculada

GET /companie/financial/serviceInvoiceCompany/financialOptions

Receitas não canceladas da empresa, das mais recentes para as mais antigas. q busca por nome, CPF/CNPJ do cliente ou número do contrato. take até 100 (padrão 20). Os produtos do contrato vêm junto para preencher contractProductIds na emissão.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
q	query	string
client_id	query	número
skip	query	número
take	query	número

Respostas

Status	Descrição
200	Lançamentos.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Emitir nota fiscal de serviço

POST /companie/financial/serviceInvoiceCompany/issue

Emite uma NFS-e avulsa (só com o cliente) ou vinculada a um lançamento de receita.

• O tomador é montado a partir do cadastro do cliente (customerId): ele precisa ter CPF/CNPJ, e-mail e endereço completo (CEP, rua, número, bairro, cidade e UF).
• customerServiceId é a atividade econômica do cliente. Os demais campos fiscais seguem para o provedor como vieram.
• Todas as pendências voltam juntas em validation.body.errors.
• Exige saldo de créditos de nota (GET /companie/user/invoiceCreditBalance). O crédito é debitado quando a nota é confirmada como emitida.
• A chamada espera até cerca de 20 segundos pela prefeitura. Se a nota não sair nesse tempo, volta ok: false e processing: true; acompanhe pelo detalhe ou pela listagem.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
type	avulsa · vinculada	sim	avulsa: só com o cliente. vinculada: ligada a um lançamento de receita.
customerId	número	sim	Id do cliente tomador. Na nota vinculada, precisa ser o cliente do lançamento (ou do contrato dele).
financialId	número		Obrigatório quando type = vinculada e proibido na avulsa. Tire de GET .../serviceInvoiceCompany/financialOptions.
contractProductIds	número[]		Só na vinculada: ids de contract.contract_products[] do lançamento, para registrar quais produtos a nota cobre.
customerServiceId	número	sim	Id da atividade econômica (serviço) cadastrada para o cliente. Sem ela a emissão é recusada.
cityServiceCode	string		Código do serviço. Se a atividade já tem cityServiceCodeId, ele prevalece.
description	string		Descrição do serviço na nota.
servicesAmount	número	sim	Valor dos serviços, em reais.
issRate	número		Alíquota do ISS em fração (5% = 0.05).
issTaxAmount	número		Valor do ISS.
retentionType	WithheldByBuyer · NotWithheld		WithheldByBuyer retém o ISS no tomador; exige a inscrição municipal do emitente nas Configurações de NFS-e.
issAmountWithheld	número		ISS retido. Ignorado quando não há retenção.
pisAmountWithheld	número
cofinsAmountWithheld	número
csllAmountWithheld	número
irAmountWithheld	número
inssAmountWithheld	número
additionalInformation	string		Informações complementares.
nbsCode	string		Código NBS (IBS/CBS). Exigido quando a empresa tem IBS/CBS habilitado e a atividade não tem o código.
ibsCbsClassCode	string ou null		Classificação tributária IBS/CBS.
ibsCbsOperationIndicator	string ou null		Indicador de operação IBS/CBS.
construction	object		Só para serviços de construção civil: informe workId (CNO/CEI com 12 dígitos) ou o endereço completo da obra.
construction.workId	object
construction.workId.scheme	string
construction.workId.value	string
construction.siteAddress	object
construction.siteAddress.country	string
construction.siteAddress.postalCode	string
construction.siteAddress.street	string
construction.siteAddress.number	string
construction.siteAddress.district	string
construction.siteAddress.state	string
construction.siteAddress.city	object

Respostas

Status	Descrição
200	Nota emitida (ok: true) ou ainda em processamento (processing: true).
400	Pendências de cadastro, saldo ou recusa do provedor, em validation.body.message e validation.body.errors. Erros do Joi seguem o formato ValidationError.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Baixar o PDF da nota

GET /companie/financial/serviceInvoiceCompany/{serviceInvoiceId}/pdf

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
serviceInvoiceId	URL	string	sim	Id da nota no provedor de NFS-e (string). É o nfe_id do lançamento, o id/nfe_id da listagem e o nfe_id devolvido na emissão. Não é um id numérico do LeadSim.

Respostas

Status	Descrição
200	PDF da NFS-e. (application/pdf)
400	O provedor recusou (ex.: nota não emitida).
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)
500	Falha inesperada, em texto.

Testar no Swagger

Baixar o XML da nota

GET /companie/financial/serviceInvoiceCompany/{serviceInvoiceId}/xml

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
serviceInvoiceId	URL	string	sim	Id da nota no provedor de NFS-e (string). É o nfe_id do lançamento, o id/nfe_id da listagem e o nfe_id devolvido na emissão. Não é um id numérico do LeadSim.

Respostas

Status	Descrição
200	XML da NFS-e. (application/xml)
400	O provedor recusou (ex.: nota não emitida).
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Enviar a nota por e-mail

POST /companie/financial/serviceInvoiceCompany/{serviceInvoiceId}/sendEmail

Envia para email uma mensagem com o PDF e o XML da nota anexados. Só funciona para nota vinculada a um lançamento da empresa: nota avulsa volta 404. Notas com falha ou canceladas são recusadas.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
serviceInvoiceId	URL	string	sim	Id da nota no provedor de NFS-e (string). É o nfe_id do lançamento, o id/nfe_id da listagem e o nfe_id devolvido na emissão. Não é um id numérico do LeadSim.

Corpo (application/json)

Campo	Tipo	Obrigatório	Descrição
email	string	sim

Respostas

Status	Descrição
200	E-mail enviado.
400	Parâmetros inválidos. (ValidationError)
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	Nenhum lançamento da empresa aponta para esta nota.
429	Limite de requisições excedido. (ErrorCode)
502	Falha ao obter PDF/XML do provedor ou ao enviar o e-mail.

Testar no Swagger

Cancelar nota fiscal

PUT /companie/financial/serviceInvoiceCompany/{serviceInvoiceId}/cancel

Pede o cancelamento ao provedor e marca o lançamento ligado à nota como Cancelled. O crédito usado na emissão não é devolvido.

Os erros não seguem o formato ErrorCode: vêm como { "validation": { "body": { "message": "..." } } }, com a mensagem do provedor (400) ou Houve um erro inesperado (500).

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
serviceInvoiceId	URL	string	sim	Id da nota no provedor de NFS-e (string). É o nfe_id do lançamento, o id/nfe_id da listagem e o nfe_id devolvido na emissão. Não é um id numérico do LeadSim.

Respostas

Status	Descrição
200	Cancelamento aceito. Corpo vazio ({}).
400	O provedor recusou o cancelamento.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)
500	Falha inesperada.

Testar no Swagger

Consultar nota fiscal

GET /companie/financial/serviceInvoiceCompany/{serviceInvoiceId}

Consulta a nota no provedor na hora. Efeito colateral: atualiza o status no lançamento e, se a nota estiver emitida e ainda não tiver sido cobrada, debita o crédito de nota.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
serviceInvoiceId	URL	string	sim	Id da nota no provedor de NFS-e (string). É o nfe_id do lançamento, o id/nfe_id da listagem e o nfe_id devolvido na emissão. Não é um id numérico do LeadSim.

Respostas

Status	Descrição
200	Nota no provedor.
400	O provedor não encontrou a nota ou falhou.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)
500	Falha inesperada.

Testar no Swagger

Consultar saldo de créditos de nota fiscal

GET /companie/user/invoiceCreditBalance

Cada nota emitida consome 1 crédito. Sem saldo, a emissão é recusada.

Respostas

Status	Descrição
200	Saldo da empresa.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
404	Empresa não encontrada.
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger

Listar pacotes de créditos de nota ativos

GET /companie/invoiceCredit/active

Pacotes comprados pela empresa com status active, com as cobranças de cada um. Para o saldo disponível, use GET /companie/user/invoiceCreditBalance.

Respostas

Status	Descrição
200	Pacotes ativos.
401	Chave ausente, inválida, revogada ou vencida. (ErrorCode)
403	Acesso via API desligado, empresa inativa ou rota não permitida. (ErrorCode)
429	Limite de requisições excedido. (ErrorCode)

Testar no Swagger