Send a new NFSe invoice to the selected city
POST {{baseUrl}}/NFSe/v1/invoice
Send a new NFSe invoice to the selected city.
Schema Definitions
Request
Attribute | Data type | Description |
---|---|---|
invoiceCity | String | City where the invoice took place. |
invoiceState | String | State where he invoice took place. |
lotNumber | Integer | Lot number for the receipt. This is just a key for the NFSe. |
companyTaxCode | String | The CNPJ number for the lot number. Could be the provider CNPJ or the company's own CNPJ. |
companyStateTaxCode | String | Company's State tax code (inscrição estadual). |
companyCityTaxCode | String | City Tax Code for the company (inscrição municipal). |
companyName | String | Company name or provider's name. |
companyShortName | String | Nickname for the company. |
companyAddressType | String | Company's address type. Accepted values are: Avenida, Rua, Rodovia, Ruela, Rio, Sitio, Sup Quadra, Travessa, Vale, Via, Viaduto, Viela, Vila, Vargem. |
companyAdddress | String | Home address for the company. |
companyAddressNumber | String | Company's address. |
companyAddressCompl | String | Company's address aditional info. |
companyDistrictType | String | Company's district type. |
companyDistrict | String | Company's address district. |
companyCityPostalCode | Integer | IBGE code for the company. |
companyCity | String | Home city for the company. |
companyState | String | Home state for the company. |
companyPostCode | String | Postal code for the company (CEP). |
companyCityPhoneCode | Integer | Phone code for the company home address (DDD). |
companyPhone | Integer | Phone number for the company. No DDD allowed here. |
companyEmail | String | E-mail for the company. |
serviceReceipt | Type | |
{ | ||
receiptNumber | Integer | Receipt Number (RPS). |
receiptSerie | String | Receipt series. |
receiptType | String | Receipt type. Send '1' here. |
issueDate | String ($date-time) | Issue date for the receipt. Format: 2019-09-11T00:00:00. |
customerSimpleTax | Boolean | Indicates that the provider uses Simple Tax (Simples nacional). |
customerCulturalIncentive | Boolean | Indicates that the provider uses Taxes Cultural Incentives. |
invoiceStatus | Integer | Invoice status. 1 - OK, 2 - Cancelled. |
receiptTypeTax | Integer | Recipe tax type. Accepted values: 1 - No ISS 2 - Immune 3 - No city taxes 4 -Cannot be taxed 5 - Taxes withheld 6 - Taxable inside he city 7 - Taxable outside the city 8 - Taxable inside the city by the taker. |
receiptNatureTax | Integer | Tax nature. Accepted values: 1 - Simple tax (Simples Nacional), 2 - Fixed (Fixo), 3 - Deposited in the court (Depósito em juízo), 4 - Retained by court decision (Exilibilidade suspensa por decisão judicial), 5 - Retained by administrative procedure (Exigibilidade suspensa por procedimento adm), 6 - Partial excemption (Isenção parcial). |
receiptSpecialTaxRRegime | Integer | Special tax regime. Accepted values: 1 - Small city company (Microempresa municipal), 2 - Estimate (Estimativa), 3 - Professional group (Sociedade de profissionais), 4 - Cooperative (Cooperativa), 5 - MEI, 6 - ME EPP, 7 - Real profit (Lucro Real), 8 - Estimate profit (Lucro presumido), 9 - Normal tax (Tributação Normal). |
substitutedReceiptNumber | Integer | Needed only when this is a substitute. |
substitutedReceiptSerie | String | Needed only when this is a substitute. |
substitutedReceiptType | String | Needed only when this is a substitute. |
serviceAmount | Number ($double) | Service rice for the receipt. |
serviceDeduction | Number ($double) | Service price deduction. |
pisAmount | Number ($double) | PIS value. |
cofinsAmount | Number ($double) | COFINS value. |
inssAmount | Number ($double) | INSS value. |
irAmount | Number ($double) | IR value. |
csllAmount | Number ($double) | CSLL value. |
issWithhold | Boolean | Flag for ISS withhold. |
issAmount | Number ($double) | ISS value. |
issWithholdAmount | Number ($double) | ISS withheld value. |
otherRetentions | Number ($double) | Other retentions. |
taxBasis | Number ($double) | Tax basis for the receipt. |
invoiceNetAmount | Number ($double) | Total invoice net amount. ServiceAmount - (PISAmount - COFINSAmount - INSSAmount - IRAmount - CSLLAmount - OtherRetentions - ISSWithheld - ConditionalDiscount - UnconditionalDiscount). |
conditionalDiscount | Number ($double) | Invoice conditional discount. Apply this discount if.... |
unconditionalDiscount | Number ($double) | Invoice unconditional discount. |
issPercentage | Number ($double) | Value for ISS percentage. 5.00 for 5%. |
pisPercentage | Number ($double) | Value for PIS percentage. 5.00 for 5%. |
cofinsPercentage | Number ($double) | Value for COFINS percentage. 5.00 for 5%. |
inssPercentage | Number ($double) | Value for INSS percentage. 5.00 for 5%. |
irPercentage | Number ($double) | Value for IR Percentage. 5.00 for 5%. |
csllPercentage | Number ($double) | Value for CSLL percentage. 5.00 for 5%. |
serviceCodeItemList | String | Service code. This can be obtained from the city council. |
economicActivitieCode | String | CNAE code. This can be obtained from the city council. |
cityTaxCode | String | City tax code. This can be obtained from the city council. |
serviceDescription | String | Service description. |
additionalInformation | String | Additional information. |
taxLoadAmount | Number ($double) | Value for the tax load. |
taxLoadAmountPercentage | Number ($double) | Tax load percentage value. |
taxLoadReference | String | Tax load reference. |
serviceCityPostalCode | Integer | IBGE code where the service took place. |
serviceCityName | String | City name where the service took place. |
customerTaxCode | String | CPF/CNPJ for the customer. |
customerName | String | Customer name. |
customerCityTaxCode | String | City tax code for the customer (inscrição municipal). |
customerStateTaxCode | String | Customer province tax code (ìnscrição estadual). |
customerForeignID | String | Provide only if the customer is a foreign. |
customerAddressType | String | Customer address type. Accepted values: Valores aceitos: Avenida, Rua, Rodovia, Ruela, Rio, Sitio, Sub Quadra, Travessa, Vale, Via, Viaduto, Viela, Vila, Vargem. |
customerAddress | String | Customer address. |
customerAddressNumber | String | Customer address number. |
customerAddressCompl | String | Customer address additional info. |
customerDistrictType | String | District type for the customer. Accepted values: Bairro, Bosque, Chácara, Conjunto, Desmembramento, Distrito, Favela, Fazenda, Gleba, Horto, Jardim, Loteamento, Núcle, Parque, Residencial, Sítio, Tropical, Vila, Zona. |
customerDistrict | String | Customer district. |
customerCityPostalCode | Integer | Customer address IBGE number. |
customerCity | String | Customer city. |
customerState | String | Customer province. |
customerPostCode | String | Customer postal code (CEP). |
customerCityPhoneCode | Integer | Phone code for the customer (DDD). |
customerPhone | Integer | Customer phone. Don't use DDD here. |
customerPhoneType | Integer | Customer phone type. Accepted values: 1 - cell phone 2 - comercial 3 - home phone. |
customerEmail | String | Customer e-mail. |
interCustomerName | String | Intermediary customer name. |
interCustomerTaxCode | String | Intermediary customer tax code (CPF/CNPJ). |
interCustomerCityTaxCode | String | Intermediary customer tax code (Inscrição municipal). |
invoiceNumberReplaced | Integer | Number for the invoice being replaced. |
issueDateInvoiceReplaced | String ($date-time) | Issue date for the invoice being replaced. |
invoiceSerieReplaced | String | Series for the invoice being replaced. |
cancelReason | String | Reason to cancel the invoice. |
operationType | String | Operation type. Accepted values: A - Np deduction (Sem dedução) B - With deduction (Com dedução) C - Imune D - Devolution (Devolução/Simples remessa) J - Intermediation (Intermediação). |
customerCEI | String | |
constructionCode | String | Construction code. This field is used by civil engineering. |
authConstructionCode | String | Authorization to the construction code. This field is used by civil engineering. |
deductionMode | String | Deduction mode. Accepted values: 'Valor' (Value) 'Percentual'. |
deductionType | String | Deduction type. Accepted values are: - if Deduction mode is 'Valor': - 'Despesas com materiais' - 'Despesas com sub-empreitada' - if Deduction mode is 'Percentual', keep this field empty. |
referenceTaxCode | String | Reference tax code (CPF/CNPJ). |
referenceInvoiceNumber | String | Reference Invoice number. |
referenceAmount | Number ($double) | Reference amount. |
deductionPercentage | Number ($double) | Deduction percentage. |
receiptDescription | String | This field is mainly used to describe the receipt as a whole when there are multiple services in it. |
serviceQty | Integer | Number of services. |
serviceUnitPrice | Number ($double) | Service unit price. |
taxable | String | Flag if the service is taxable. |
erpReferenceCode | String | ERP Reference code. Use to reference the ERP's invoice. |
signature | String | Signature. |
receiptNumberIssuing | String | Number to the receipt in the issuing end. |
customerCompanyType | String | Type to the customer's document. Accepted values: 1 - CPF 2 - CNPJ 3 - Foreigner. |
customerDocumentDescription | String | Customer document description. |
customerIntlCity | String | Customer's foreign city. |
customerCountry | String | Customer contry. Use BACEN codes. |
serviceCodeSubItemList | String | Subitem service code. |
deductionReason | String | Deduction reason. Required for EQUIPLANO when field DeductionAmount is not null. |
taxIncentive | Boolean | Flag to indicate there are tax cuts. |
competencyDate | String ($date-time) | Competency date for the service taxes. |
incidenceCityPostalCode | String | IBGE code where the taxes are being paid. Used when the taxes are withheld. |
eligibilityISS | Integer | ISS Eligibility. Accepted values are: 1 - Obligatory (Exigível) 2 - Doesn't match (Não incidência) 3 - Excempted (Isenção) 4 - Export (Exportação) 5 - Imuune (Imunidade) 6 - Retained by court decision (Eligibilidade suspensa por decisão judicial) 7 - Retained by administrative process (Eligibiildade suspensa por processo administrativo). |
responsibleRetentition | Integer | Accepted values: Proper (Próprio) 1 - Provider (Tomador) 2 - Intermediary (Intermediário). |
invoiceNumber | Integer | Invoice number. |
invoiceSerie | String | Invoice series. |
invoiceIssueDate | String ($date-time) | Invoice issue date. |
simpleTaxPercentage | Number ($double) | Simple Tax percentage (Simples nacional). |
invoiceNumberCanceled | Integer | Invoice number being cancelled. |
invoiceIssueDateCanceled | String ($date-time) | Invoice date being cancelled. |
serviceAddress | String | Address where the service took place. |
dueDate | String ($date-time) | Due date. |
customerTaxSituation | String | Customer tax situation. |
additionalServiceReceiptList | Array | |
[ | ||
AdditionalServiceReceipt | Type | |
{ | ||
serviceUnitPrice | Number ($double) | Service unit price. |
serviceDescription | String | Service description. |
serviceQty | Integer | Number of services. |
serviceUnitMeasure | String | Service unit measure. |
serviceAmount | Number ($double) | Service price. |
serviceNetAmount | Number ($double) | Service net price. |
taxable | Boolean | Flag if the service is taxable. |
serviceCodeItemList | String | Service code item list. |
deductionType | String | Service deduction type. |
economicActivitieCode | Integer | CNAE code. |
issAmount | Number ($double) | ISS value for the service. |
serviceCityPostalCode | String | IBGE code where the service took place. |
issPercentage | Number ($double) | ISS Percentage. |
taxBasis | Number ($double) | Tax Basis for the service. |
issWithhold | Number ($double) | Tax withheld for the service. |
} | ||
] | ||
} |
Response
Attribute | Data type | Description |
---|---|---|
success | Boolean | Boolean indicating if the operation was sucessfull. |
message | String | Operation custom message. |
data | Type | |
{ | ||
integrationKey | String | Integration Key generated for sending invoice. This information is important for you to be able to recover the return of the note processing for asynchronous requests. |
processStatus | Integer | Processing status. Possible values: 1 - Processed 2 - Waiting for process. Use get method later 3 - Error |
status | Integer | HTTP status code. Possible values: 200 - OK 400 - Error |
returnType | String | Return type. Possible values: 1 - Invoice 2 - None 3 - None D - Delivery text file |
deliveryTTextFile | String | Delivered text file for the city. Only provided when return type = D. Text or XML file in Base64. |
invoiceList | Array | List of invoices consulted by the informed criteria. |
[ | ||
{ | ||
receiptNumber | Integer | Receipt Number (RPS). |
receiptSerie | String | Receipt series. |
receiptType | String | Receipt type. Send '1' here. |
issueDate | String ($date-time) | Issue date for the receipt. Format: 2019-09-11T00:00:00. |
erpReferenceCode | String | ERP Reference code. Use to reference the ERP's invoice. |
invoiceNumber | Integer | Invoice number. |
invoiceSerie | String | Invoice series. |
invoiceIssueDate | String ($date-time) | Invoice issue date. |
authorizationNumber | String | Authorization number returned by the tax entity proving the authenticity of the invoice. |
keyNumber | String | Invoice processing protocol. |
errorCode | String | Error code returned by the tax entity as a result of invoice processing. |
errorMessage | String | Error message returned by the fiscal entity as a result of invoice processing. |
invoiceReport | String | PDF file in Base64 containing the printout of the authorized invoice. |
invoiceStatus | String | Status of the invoice returned by the tax entity. |
cancelDate | String ($date-time) | Invoice cancellation date. |
cancelKey | String | Invoice cancellation protocol. |
authorizationDate | String ($date-time) | Invoice authorization date. |
invoiceXMLReport | String | XML file in Base64 containing the return information of the processed invoice. |
} | ||
] | ||
} |
Request Body
{"invoiceCity"=>"<string>", "invoiceState"=>"<string>", "lotNumber"=>"<integer>", "companyTaxCode"=>"<string>", "companyStateTaxCode"=>"<string>", "companyCityTaxCode"=>"<string>", "companyName"=>"<string>", "companyShortName"=>"<string>", "companyAddressType"=>"<string>", "companyAdddress"=>"<string>", "companyAddressNumber"=>"<string>", "companyAddressCompl"=>"<string>", "companyDistrictType"=>"<string>", "companyDistrict"=>"<string>", "companyCityPostalCode"=>"<integer>", "companyCity"=>"<string>", "companyState"=>"<string>", "companyPostCode"=>"<string>", "companyCityPhoneCode"=>"<integer>", "companyPhone"=>"<integer>", "companyEmail"=>"<string>", "serviceReceipt"=>{"receiptNumber"=>"<integer>", "receiptSerie"=>"<string>", "receiptType"=>"<string>", "issueDate"=>"<dateTime>", "customerSimpleTax"=>"<boolean>", "customerCulturalIncentive"=>"<boolean>", "invoiceStatus"=>"<integer>", "receiptTypeTax"=>"<integer>", "receiptNatureTax"=>"<integer>", "receiptSpecialTaxRRegime"=>"<integer>", "substitutedReceiptNumber"=>"<integer>", "substitutedReceiptSerie"=>"<string>", "substitutedReceiptType"=>"<string>", "serviceAmount"=>"<double>", "serviceDeduction"=>"<double>", "pisAmount"=>"<double>", "cofinsAmount"=>"<double>", "inssAmount"=>"<double>", "irAmount"=>"<double>", "csllAmount"=>"<double>", "issWithhold"=>"<boolean>", "issAmount"=>"<double>", "issWithholdAmount"=>"<double>", "otherRetentions"=>"<double>", "taxBasis"=>"<double>", "invoiceNetAmount"=>"<double>", "conditionalDiscount"=>"<double>", "unconditionalDiscount"=>"<double>", "issPercentage"=>"<double>", "pisPercentage"=>"<double>", "cofinsPercentage"=>"<double>", "inssPercentage"=>"<double>", "irPercentage"=>"<double>", "csllPercentage"=>"<double>", "serviceCodeItemList"=>"<string>", "economicActivitieCode"=>"<string>", "cityTaxCode"=>"<string>", "serviceDescription"=>"<string>", "additionalInformation"=>"<string>", "taxLoadAmount"=>"<double>", "taxLoadAmountPercentage"=>"<double>", "taxLoadReference"=>"<string>", "serviceCityPostalCode"=>"<integer>", "serviceCityName"=>"<string>", "customerTaxCode"=>"<string>", "customerName"=>"<string>", "customerCityTaxCode"=>"<string>", "customerStateTaxCode"=>"<string>", "customerForeignID"=>"<string>", "customerAddressType"=>"<string>", "customerAddress"=>"<string>", "customerAddressNumber"=>"<string>", "customerAddressCompl"=>"<string>", "customerDistrictType"=>"<string>", "customerDistrict"=>"<string>", "customerCityPostalCode"=>"<integer>", "customerCity"=>"<string>", "customerState"=>"<string>", "customerPostCode"=>"<string>", "customerCityPhoneCode"=>"<integer>", "customerPhone"=>"<integer>", "customerPhoneType"=>"<integer>", "customerEmail"=>"<string>", "interCustomerName"=>"<string>", "interCustomerTaxCode"=>"<string>", "interCustomerCityTaxCode"=>"<string>", "invoiceNumberReplaced"=>"<integer>", "issueDateInvoiceReplaced"=>"<dateTime>", "invoiceSerieReplaced"=>"<string>", "cancelReason"=>"<string>", "operationType"=>"<string>", "customerCEI"=>"<string>", "constructionCode"=>"<string>", "authConstructionCode"=>"<string>", "deductionMode"=>"<string>", "deductionType"=>"<string>", "referenceTaxCode"=>"<string>", "referenceInvoiceNumber"=>"<string>", "referenceAmount"=>"<double>", "deductionPercentage"=>"<double>", "receiptDescription"=>"<string>", "serviceQty"=>"<integer>", "serviceUnitPrice"=>"<double>", "taxable"=>"<string>", "erpReferenceCode"=>"<string>", "signature"=>"<string>", "receiptNumberIssuing"=>"<string>", "customerCompanyType"=>"<string>", "customerDocumentDescription"=>"<string>", "customerIntlCity"=>"<string>", "customerCountry"=>"<string>", "serviceCodeSubItemList"=>"<string>", "deductionReason"=>"<string>", "taxIncentive"=>"<boolean>", "competencyDate"=>"<dateTime>", "incidenceCityPostalCode"=>"<string>", "eligibilityISS"=>"<integer>", "responsibleRetentition"=>"<integer>", "invoiceNumber"=>"<integer>", "invoiceSerie"=>"<string>", "invoiceIssueDate"=>"<dateTime>", "simpleTaxPercentage"=>"<double>", "invoiceNumberCanceled"=>"<integer>", "invoiceIssueDateCanceled"=>"<dateTime>", "serviceAddress"=>"<string>", "dueDate"=>"<dateTime>", "customerTaxSituation"=>"<string>", "additionalServiceReceiptList"=>[{"serviceUnitPrice"=>"<double>", "serviceDescription"=>"<string>", "serviceQty"=>"<integer>", "serviceUnitMeasure"=>"<string>", "serviceAmount"=>"<double>", "serviceNetAmount"=>"<double>", "taxable"=>"<boolean>", "serviceCodeItemList"=>"<string>", "deductionType"=>"<string>", "economicActivitieCode"=>"<integer>", "issAmount"=>"<double>", "serviceCityPostalCode"=>"<string>", "issPercentage"=>"<double>", "taxBasis"=>"<double>", "issWithhold"=>"<double>"}, {"serviceUnitPrice"=>"<double>", "serviceDescription"=>"<string>", "serviceQty"=>"<integer>", "serviceUnitMeasure"=>"<string>", "serviceAmount"=>"<double>", "serviceNetAmount"=>"<double>", "taxable"=>"<boolean>", "serviceCodeItemList"=>"<string>", "deductionType"=>"<string>", "economicActivitieCode"=>"<integer>", "issAmount"=>"<double>", "serviceCityPostalCode"=>"<string>", "issPercentage"=>"<double>", "taxBasis"=>"<double>", "issWithhold"=>"<double>"}]}}
HEADERS
Key | Datatype | Required | Description |
---|---|---|---|
CustomerApplicationID | null | (Required) Customer Application ID provided by the API's owner | |
ResponseDemo | null | Enter "ReturnTypeD", "ReturnTypeI", "ProcessStatus2" or "ProcessStatus3" for demo values | |
Content-Type | string | The Content-Type header field is used to specify the nature of the data in the body of an entity. OAS REST APIs support application/json. | |
Accept | string | The Accept request HTTP header indicates which content types, expressed as MIME types, the client is able to understand. OAS REST APIs support text/plain. |
RESPONSES
status: OK
{"success":true,"message":"Processed","data":{"integrationKey":"7921759c-a042-45ca-8b75-94945df38a4e","processStatus":3,"status":200,"returnType":"N","deliveryTTextFile":null,"invoiceList":[{"receiptNumber":48801,"receiptSerie":"1","receiptType":"1","issueDate":"2023-07-18T00:00:00","erpReferenceCode":"123456","invoiceNumber":0,"invoiceSerie":null,"invoiceIssueDate":null,"authorizationNumber":null,"keyNumber":null,"errorCode":"0","errorMessage":"0: Existe Mês Anterior em Aberto!.","invoiceReport":null,"invoiceStatus":null,"cancelDate":null,"cancelKey":null,"authorizationDate":null,"invoiceXMLReport":null}]}}