Transactions
This section provides an overview of the requirements for using the TaxDocs APIs for Electronic invoice for goods (NFE). Review this section to help you plan your integration.
All calls to our API use HTTPS encrypted environment.
Using the Avalara APIs you can perform the following operations:
- Retrieve the list of electronic invoices
- Retrieve the content of the electronic invoice
- Retrieve the XML of the electronic invoice
- Retrieve the DANFE of the electronic invoice
- Retrieve the list of canceled invoices
- Register the Electronic Invoice Manifest event
- Retrieve the XML of the electronic invoice correction letter
To consult the list of invoices (NFE)
To consult available invoices, you need to use the mandatory parametersstartEntryDateandendEntryDate. Below are other parameters for using the API.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFE
startEntryDate*
Sends the invoice entry start date and time within the applicationFormat: YYYY-MM-DDT00:00:00
endEntryDate*
Sends the invoice entry end date and time within the applicationFormat: YYYY-MM-DDT00:00:00
$subscriptionId
Subscription ID corresponding to the customer for which the query will be made
$top
Sends the maximum amount of invoices that are returned by search
$skip
Field used to control the pagination of returns
Example: Returning 0 to 100 in the first query
From 101 to 200 on Monday, and so on until you reach the total “count”
$filter
Can be used for a more specific search
Example: Search for notes of only one CNPJ, among several owned by the client
$orderby
Ordering fields that come in JSON
Example1: Sort by Invoice Key
Example 2: Sort by entry date
$count
Shows the amount of existing available notes, according to the requested return parameters
$select
To customize which fields are returned in the response
Example: invoiceKey, invoiceNumber, cnpjCpfRecipient
$expand
Unsupported option
$apply
Unsupported option
*Asterisk fields are required.
Below is an example of use of the endpoint /api/v1/NFE in cURL using only the required parameters:
Example of use of the endpoint /api/v1/NFE in C#:
The expected return of the invoice list query contains the parameters below:
- invoiceKey
Invoice access key
- invoiceNumber
Invoice number
- cnpjCpfIssuer
Issuer’s CNPJ/CPF
- cnpjCpfRecipient
Recipient’s CNPJ/CPF
- validSefaz
Return of note status within SEFAZ
True - Document valid at SEFAZ, that is, it is not a canceled or denied document
False - The result of the last query reported that the key refers to a canceled or denied tax document
- hasServices
Field to identify service note
True - The document is an NFSE
False - The document is an NFE
- operationType
0 - Exit
1 - Entry
3 - Transfer
- totalInvoice
Total invoice amount
- availableXML
When the value is “X”, tax Document has XML
- issueDate
Tax document issue date
- entryDate
Document entry date in TaxDocs Monitor
- cancellationDate
Tax document cancellation date
- validXmlStructure
True - Document XML is valid
False - Document XML is structurally invalid
Null - There is no XML for the document
The API return is in JSON format as shown below:
To retrieve the content of the electronic invoice (NFE)
To retrieve the content of the electronic invoice, is necessary to know the electronic invoice key.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFE/{invoiceKey}
invoiceKey*
Invoice access key
subscriptionId
Subscription ID corresponding to the customer for which the query is made
*Asterisk fields are required.
Below is an example of use of the endpoint /api/v1/NFE/{invoiceKey} in cURL using only the required parameters:
Example of using the endpoint /api/v1/NFE/{invoiceKey} in C#:
The expected return of the consultation of the electronic invoice content contains the parameters below:
invoiceKey
Invoice access key
invoiceNumber
Invoice number
cpfcnpj
Issuer’s CPF/CNPJ
businessName
Issuer’s business name
phoneNumber
Issuer’s telephone number
commercialName
Issuer’s commercial name
stateRegistration
Issuer’s state registration
cityRegistration
Issuer’s municipal registration
address
Issuer’s Address Group Information
street
Name of the issuer’s address
town
Issuer’s city
state
Issuer’s UF code
zipCode
Issuer’s zip code
neighborhood
Issuer’s neighborhood
complement
Complement of the issuer’s street address
number
Issuer’s street number
recipient
Recipient’s Group Information
cpfcnpj
Recipient’s CPF/CNPJ
businessName
Recipient’s business name
phoneNumber
Recipient’s telephone number
commercialName
Recipient’s commercial name
stateRegistration
Recipient’s state registration
cityRegistration
Recipient’s municipal registration
address
Recipient’s Address Group Information
street
Recipient’s street name
town
Recipient’s city
state
Recipient’s UF code
zipCode
Recipient’s zip code
neighborhood
Recipient’s neighborhood
complement
Complement of the recipient’s street address
number
Recipient’s street number
validSefaz
Return of note status within SEFAZ
True - Document valid at SEFAZ, that is, it is not a canceled or denied document
False - The result of the last query reported that the key refers to a canceled or denied tax document
hasServices
Field to identify service note
True - The document is an NFSE
False - The document is an NFE
operationType
0 - Exit
1 - Entry
3 - Transfer
totalInvoice
Total invoice amount
availableXML
When the value is “X”, tax Document has XML,
issueDate
Tax document issue date
entryDate
Document entry date in TaxDocs Monitor
cancellationDate
Tax document cancellation date
validXmlStructure
True - Document XML is valid
False - Document XML is structurally invalid
Null - There is no XML for the document
The API return is in JSON format as shown below:
To retrieve the XML of the electronic invoice (NFE)
To retrieve the XML of the electronic invoice, is necessary to know the electronic key of the invoice.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFE/{invoiceKey}/XML
invoiceKey*
Invoice access key
subscriptionId
Subscription ID corresponding to the customer for which the query is made
*Asterisk fields are required.
Below is an example of use of the endpoint /api/v1/NFE/{invoiceKey}/XML in cURL using only the required parameters:
Example of use of the endpoint /api/v1/NFE/{invoiceKey}/XML in C#:
The expected return from the XML query contains the parameters below:
Returns a JSON with XML data in BASE64
BASE64 is a method for encoding data for transfer over the Internet, which transforms binary or text content into a format that can be decoded by the recipient, preserving the content.
Example of BASE64 content that returns:
To retrieve DANFE from the electronic invoice (NFE)
To retrieve DANFE (auxiliary document of the electronic invoice) in a PDF format, is necessary to know the electronic key of the invoice.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFE/{invoiceKey}/PDF
invoiceKey*
Invoice access key
subscriptionId
Subscription ID corresponding to the customer for which the query is made
*Asterisk fields are required.
Below is an example of use of the endpoint /api/v1/NFE/{invoiceKey}/PDF in cURL using only the required parameters:
Example of use of the endpoint /api/v1/NFE/{invoiceKey}/XML in C#:
The expected return of the DANFE query contains the parameters below:
Returns a JSON with XML data in BASE64
BASE64 is a method for encoding data for transfer over the Internet, which transforms binary or text content into a format that can be decoded by the recipient, preserving the content.
Example of BASE64 content that returns:
To consult the list of canceled invoices
For the consultation of canceled invoices, is necessary to use the mandatory parametersstartEntryDateandendEntryDate. Below are other parameters for using the API.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFEEvent
startEntryDate*
Send the invoice entry start date and time within the applicationFormat: YYYY-MM-DDT00:00:00
endEntryDate*
Send the invoice entry end date and time within the applicationFormat: YYYY-MM-DDT00:00:00
$subscriptionId
Subscription ID corresponding to the customer for which the query is made
$top
Send the maximum amount of invoices that is returned by search
$skip
Field used to control the pagination of returns
Example: Returning 0 to 100 in the first query
From 101 to 200 on Monday, and so on until you reach the total “count”
$filter
Can be used for a more specific search
Example: Search for notes of only one CNPJ, among several owned by the client
$orderby
Ordering fields that come in JSON
Example 1: Sort by invoice key
Example 2: Sort by entry date
$count
Shows the amount of existing notes available, according to the requested return parameters
$select
To customize which fields return in the response
Example: invoiceKey, invoiceNumber, cnpjCpfRecipient
$expand
Unsupported option
$apply
Unsupported option
*Asterisk fields are required.
Below is an example of use of the endpoint /api/v1/NFEEvent in cURL using only the required parameters:
Example of use of the endpoint /api/v1/NFEEvent in C#:
The expected return from the canceled invoice list query contains the parameters below.
You must note thecancellationDatefield.
If there is a date, use theinvoiceKeyfield to retrieve the most up-to-date information on the invoice.
You can follow the examples shown above at:
- Retrieve the content of the electronic invoice (NFE)
- Retrieve the XML of the electronic invoice (NFE)
- Retrieve DANFE from the electronic invoice (NFE)
eventCode
Event code:
- 210210 = knowledge
- 210200 = confirmation
- 210220 = unawareness
- 210240 = non-fulfillment
returnDate
Return date:
Format: YYYY-MM-DDT00:00:00.000Z
description
Event name:
Knowledge
Unawareness
sefaz
true - event sent to Sefaz
false - event not sent to Sefaz
Event user email
isCorrectionInvoice
If it returns the value “true” it means it is a correction letter
invoiceKey
Invoice access key
correctionInvoiceId
Correction letter unique identifier (GUID)
Return example: 96a56493-43a0-4183-a2fd-f312898b23c6
isPdfAvailable
If it returns a “true” value it means that the correction letter PDF is available
cancellationDate
Data do cancelamento do documento fiscal
eventStatus
Status do evento
eventJustification
Justificativa do evento
manifestDate
Data do manifesto do evento
The API return is in JSON format as shown below:
To register the Electronic Invoice Manifest (NFE) event
To register the Electronic Invoice Manifest event, is necessary to know the electronic invoice key.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFE/{invoiceKey}/event
invoiceKey
Electronic Invoice Key
subscriptionId
JSON statement containing the Manifest event parameters
- eventCode - event code:
- 210210 = knowledge
- 210200 = confirmation
- 210220 = unawareness
- 210240 = non-fulfillment
eventReason - event description
Theevent parameter is a JSON content and must be sent as follows:
The return from the API is the HTTP status as below:
HTTP code
Message
200
Submission of successful manifestation
400
Bad Request - The server did not understand the request due to invalid syntax
401
Missing or Incorrect Authentication Credentials
404
Requested URL is invalid or requested resource does not exist.
To retrieve the XML of the Electronic Invoice Correction Letter (NFE)
To retrieve the XML of the electronic invoice correction letter, it is necessary to know the electronic invoice key.
URL: https://api-gateway.avalarabrasil.com.br/taxdocs/api/v1/NFECorrection/{invoiceKey}/XML
invoiceKey*
Invoice access key
subscriptionId
Subscription ID corresponding to the customer for which the query is made
*Asterisk fields are required.
Below is an example of use of the endpoint /api/v1/NFECorrection/{invoiceKey}/XML in cURL using only the required parameters:
Example of use of the endpoint /api/v1/NFECorrection/{invoiceKey}/XML in C#:
The expected return of the XML query of the electronic invoice correction letter contains the parameters below:
Returns a JSON with XML data in BASE64
BASE64 is a method for encoding data for transfer over the Internet, which transforms binary or text content into a format that can be decoded by the recipient, preserving the content.
Example of BASE64 content that returns:
Part of the TaxDocs integration guide. Open the full “Transactions” milestone on Avalara to see every page in this section.