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

AttributeData typeDescription
invoiceCityStringCity where the invoice took place.
invoiceStateStringState where he invoice took place.
lotNumberIntegerLot number for the receipt. This is just a key for the NFSe.
companyTaxCodeStringThe CNPJ number for the lot number. Could be the provider CNPJ or the company's own CNPJ.
companyStateTaxCodeStringCompany's State tax code (inscrição estadual).
companyCityTaxCodeStringCity Tax Code for the company (inscrição municipal).
companyNameStringCompany name or provider's name.
companyShortNameStringNickname for the company.
companyAddressTypeStringCompany's address type. Accepted values are: Avenida, Rua, Rodovia, Ruela, Rio, Sitio, Sup Quadra, Travessa, Vale, Via, Viaduto, Viela, Vila, Vargem.
companyAdddressStringHome address for the company.
companyAddressNumberStringCompany's address.
companyAddressComplStringCompany's address aditional info.
companyDistrictTypeStringCompany's district type.
companyDistrictStringCompany's address district.
companyCityPostalCodeIntegerIBGE code for the company.
companyCityStringHome city for the company.
companyStateStringHome state for the company.
companyPostCodeStringPostal code for the company (CEP).
companyCityPhoneCodeIntegerPhone code for the company home address (DDD).
companyPhoneIntegerPhone number for the company. No DDD allowed here.
companyEmailStringE-mail for the company.
serviceReceiptType
{
receiptNumberIntegerReceipt Number (RPS).
receiptSerieStringReceipt series.
receiptTypeStringReceipt type. Send '1' here.
issueDateString ($date-time)Issue date for the receipt. Format: 2019-09-11T00:00:00.
customerSimpleTaxBooleanIndicates that the provider uses Simple Tax (Simples nacional).
customerCulturalIncentiveBooleanIndicates that the provider uses Taxes Cultural Incentives.
invoiceStatusIntegerInvoice status. 1 - OK, 2 - Cancelled.
receiptTypeTaxIntegerRecipe 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.
receiptNatureTaxIntegerTax 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).
receiptSpecialTaxRRegimeIntegerSpecial 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).
substitutedReceiptNumberIntegerNeeded only when this is a substitute.
substitutedReceiptSerieStringNeeded only when this is a substitute.
substitutedReceiptTypeStringNeeded only when this is a substitute.
serviceAmountNumber ($double)Service rice for the receipt.
serviceDeductionNumber ($double)Service price deduction.
pisAmountNumber ($double)PIS value.
cofinsAmountNumber ($double)COFINS value.
inssAmountNumber ($double)INSS value.
irAmountNumber ($double)IR value.
csllAmountNumber ($double)CSLL value.
issWithholdBooleanFlag for ISS withhold.
issAmountNumber ($double)ISS value.
issWithholdAmountNumber ($double)ISS withheld value.
otherRetentionsNumber ($double)Other retentions.
taxBasisNumber ($double)Tax basis for the receipt.
invoiceNetAmountNumber ($double)Total invoice net amount. ServiceAmount - (PISAmount - COFINSAmount - INSSAmount - IRAmount - CSLLAmount - OtherRetentions - ISSWithheld - ConditionalDiscount - UnconditionalDiscount).
conditionalDiscountNumber ($double)Invoice conditional discount. Apply this discount if....
unconditionalDiscountNumber ($double)Invoice unconditional discount.
issPercentageNumber ($double)Value for ISS percentage. 5.00 for 5%.
pisPercentageNumber ($double)Value for PIS percentage. 5.00 for 5%.
cofinsPercentageNumber ($double)Value for COFINS percentage. 5.00 for 5%.
inssPercentageNumber ($double)Value for INSS percentage. 5.00 for 5%.
irPercentageNumber ($double)Value for IR Percentage. 5.00 for 5%.
csllPercentageNumber ($double)Value for CSLL percentage. 5.00 for 5%.
serviceCodeItemListStringService code. This can be obtained from the city council.
economicActivitieCodeStringCNAE code. This can be obtained from the city council.
cityTaxCodeStringCity tax code. This can be obtained from the city council.
serviceDescriptionStringService description.
additionalInformationStringAdditional information.
taxLoadAmountNumber ($double)Value for the tax load.
taxLoadAmountPercentageNumber ($double)Tax load percentage value.
taxLoadReferenceStringTax load reference.
serviceCityPostalCodeIntegerIBGE code where the service took place.
serviceCityNameStringCity name where the service took place.
customerTaxCodeStringCPF/CNPJ for the customer.
customerNameStringCustomer name.
customerCityTaxCodeStringCity tax code for the customer (inscrição municipal).
customerStateTaxCodeStringCustomer province tax code (ìnscrição estadual).
customerForeignIDStringProvide only if the customer is a foreign.
customerAddressTypeStringCustomer address type. Accepted values: Valores aceitos: Avenida, Rua, Rodovia, Ruela, Rio, Sitio, Sub Quadra, Travessa, Vale, Via, Viaduto, Viela, Vila, Vargem.
customerAddressStringCustomer address.
customerAddressNumberStringCustomer address number.
customerAddressComplStringCustomer address additional info.
customerDistrictTypeStringDistrict 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.
customerDistrictStringCustomer district.
customerCityPostalCodeIntegerCustomer address IBGE number.
customerCityStringCustomer city.
customerStateStringCustomer province.
customerPostCodeStringCustomer postal code (CEP).
customerCityPhoneCodeIntegerPhone code for the customer (DDD).
customerPhoneIntegerCustomer phone. Don't use DDD here.
customerPhoneTypeIntegerCustomer phone type. Accepted values: 1 - cell phone 2 - comercial 3 - home phone.
customerEmailStringCustomer e-mail.
interCustomerNameStringIntermediary customer name.
interCustomerTaxCodeStringIntermediary customer tax code (CPF/CNPJ).
interCustomerCityTaxCodeStringIntermediary customer tax code (Inscrição municipal).
invoiceNumberReplacedIntegerNumber for the invoice being replaced.
issueDateInvoiceReplacedString ($date-time)Issue date for the invoice being replaced.
invoiceSerieReplacedStringSeries for the invoice being replaced.
cancelReasonStringReason to cancel the invoice.
operationTypeStringOperation 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).
customerCEIString
constructionCodeStringConstruction code. This field is used by civil engineering.
authConstructionCodeStringAuthorization to the construction code. This field is used by civil engineering.
deductionModeStringDeduction mode. Accepted values: 'Valor' (Value) 'Percentual'.
deductionTypeStringDeduction 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.
referenceTaxCodeStringReference tax code (CPF/CNPJ).
referenceInvoiceNumberStringReference Invoice number.
referenceAmountNumber ($double)Reference amount.
deductionPercentageNumber ($double)Deduction percentage.
receiptDescriptionStringThis field is mainly used to describe the receipt as a whole when there are multiple services in it.
serviceQtyIntegerNumber of services.
serviceUnitPriceNumber ($double)Service unit price.
taxableStringFlag if the service is taxable.
erpReferenceCodeStringERP Reference code. Use to reference the ERP's invoice.
signatureStringSignature.
receiptNumberIssuingStringNumber to the receipt in the issuing end.
customerCompanyTypeStringType to the customer's document. Accepted values: 1 - CPF 2 - CNPJ 3 - Foreigner.
customerDocumentDescriptionStringCustomer document description.
customerIntlCityStringCustomer's foreign city.
customerCountryStringCustomer contry. Use BACEN codes.
serviceCodeSubItemListStringSubitem service code.
deductionReasonStringDeduction reason. Required for EQUIPLANO when field DeductionAmount is not null.
taxIncentiveBooleanFlag to indicate there are tax cuts.
competencyDateString ($date-time)Competency date for the service taxes.
incidenceCityPostalCodeStringIBGE code where the taxes are being paid. Used when the taxes are withheld.
eligibilityISSIntegerISS 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).
responsibleRetentitionIntegerAccepted values: Proper (Próprio) 1 - Provider (Tomador) 2 - Intermediary (Intermediário).
invoiceNumberIntegerInvoice number.
invoiceSerieStringInvoice series.
invoiceIssueDateString ($date-time)Invoice issue date.
simpleTaxPercentageNumber ($double)Simple Tax percentage (Simples nacional).
invoiceNumberCanceledIntegerInvoice number being cancelled.
invoiceIssueDateCanceledString ($date-time)Invoice date being cancelled.
serviceAddressStringAddress where the service took place.
dueDateString ($date-time)Due date.
customerTaxSituationStringCustomer tax situation.
additionalServiceReceiptListArray
[
AdditionalServiceReceiptType
{
serviceUnitPriceNumber ($double)Service unit price.
serviceDescriptionStringService description.
serviceQtyIntegerNumber of services.
serviceUnitMeasureStringService unit measure.
serviceAmountNumber ($double)Service price.
serviceNetAmountNumber ($double)Service net price.
taxableBooleanFlag if the service is taxable.
serviceCodeItemListStringService code item list.
deductionTypeStringService deduction type.
economicActivitieCodeIntegerCNAE code.
issAmountNumber ($double)ISS value for the service.
serviceCityPostalCodeStringIBGE code where the service took place.
issPercentageNumber ($double)ISS Percentage.
taxBasisNumber ($double)Tax Basis for the service.
issWithholdNumber ($double)Tax withheld for the service.
}
]
}

Response

AttributeData typeDescription
successBooleanBoolean indicating if the operation was sucessfull.
messageStringOperation custom message.
dataType
{
integrationKeyStringIntegration 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.
processStatusIntegerProcessing status. Possible values:
1 - Processed
2 - Waiting for process. Use get method later
3 - Error
statusIntegerHTTP status code. Possible values:
200 - OK
400 - Error
returnTypeStringReturn type. Possible values:
1 - Invoice
2 - None
3 - None
D - Delivery text file
deliveryTTextFileStringDelivered text file for the city. Only provided when return type = D. Text or XML file in Base64.
invoiceListArrayList of invoices consulted by the informed criteria.
[
{
receiptNumberIntegerReceipt Number (RPS).
receiptSerieStringReceipt series.
receiptTypeStringReceipt type. Send '1' here.
issueDateString ($date-time)Issue date for the receipt. Format: 2019-09-11T00:00:00.
erpReferenceCodeStringERP Reference code. Use to reference the ERP's invoice.
invoiceNumberIntegerInvoice number.
invoiceSerieStringInvoice series.
invoiceIssueDateString ($date-time)Invoice issue date.
authorizationNumberStringAuthorization number returned by the tax entity proving the authenticity of the invoice.
keyNumberStringInvoice processing protocol.
errorCodeStringError code returned by the tax entity as a result of invoice processing.
errorMessageStringError message returned by the fiscal entity as a result of invoice processing.
invoiceReportStringPDF file in Base64 containing the printout of the authorized invoice.
invoiceStatusStringStatus of the invoice returned by the tax entity.
cancelDateString ($date-time)Invoice cancellation date.
cancelKeyStringInvoice cancellation protocol.
authorizationDateString ($date-time)Invoice authorization date.
invoiceXMLReportStringXML 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

KeyDatatypeRequiredDescription
CustomerApplicationIDnull(Required) Customer Application ID provided by the API's owner
ResponseDemonullEnter "ReturnTypeD", "ReturnTypeI", "ProcessStatus2" or "ProcessStatus3" for demo values
Content-TypestringThe 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.
AcceptstringThe 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

{&quot;success&quot;:true,&quot;message&quot;:&quot;Processed&quot;,&quot;data&quot;:{&quot;integrationKey&quot;:&quot;7921759c-a042-45ca-8b75-94945df38a4e&quot;,&quot;processStatus&quot;:3,&quot;status&quot;:200,&quot;returnType&quot;:&quot;N&quot;,&quot;deliveryTTextFile&quot;:null,&quot;invoiceList&quot;:[{&quot;receiptNumber&quot;:48801,&quot;receiptSerie&quot;:&quot;1&quot;,&quot;receiptType&quot;:&quot;1&quot;,&quot;issueDate&quot;:&quot;2023-07-18T00:00:00&quot;,&quot;erpReferenceCode&quot;:&quot;123456&quot;,&quot;invoiceNumber&quot;:0,&quot;invoiceSerie&quot;:null,&quot;invoiceIssueDate&quot;:null,&quot;authorizationNumber&quot;:null,&quot;keyNumber&quot;:null,&quot;errorCode&quot;:&quot;0&quot;,&quot;errorMessage&quot;:&quot;0: Existe Mês Anterior em Aberto!.&quot;,&quot;invoiceReport&quot;:null,&quot;invoiceStatus&quot;:null,&quot;cancelDate&quot;:null,&quot;cancelKey&quot;:null,&quot;authorizationDate&quot;:null,&quot;invoiceXMLReport&quot;:null}]}}