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}]}}