# Avalara E-Invoicing API

An API that supports sending data for an E-Invoicing compliance use-case. 

  The ELR Postman collection is available here: [ELR Postman collection](https://documenter.getpostman.com/view/28852752/2s9YC7RW73).

Source: https://developer.avalara.com/products/e-invoicing/api/

**Version:** 1.0
**Base URL:** https://api.sbx.avalara.com/einvoicing

---

## Endpoints

### Documents

#### Returns a summary of documents for a date range

`GET /documents`

Get a list of documents on the Avalara E-Invoicing platform that have a processing date within the specified date range.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a "Fingerprint" |
| `startDate` | string | query | No | Start date of documents to return. This defaults to the previous month. |
| `endDate` | string | query | No | End date of documents to return. This defaults to the current date. |
| `flow` | string | query | No | Optionally filter by document direction, where issued = `out` and received = `in` |
| `$count` | string | query | No | When set to true, the count of the collection is also returned in the response body |
| `$countOnly` | string | query | No | When set to true, only the count of the collection is returned |
| `$filter` | string | query | No | Filter by field name and value. This filter only supports eq . Refer to [https://developer.avalara.com/avatax/filtering-in-rest/](https://developer.avalara.com/avatax/filtering-in-rest/) for more information on filtering. Filtering will be done over the provided startDate and endDate. If no startDate or endDate is provided, defaults will be assumed. |
| `$top` | string | query | No | If nonzero, return no more than this number of results. Used with $skip to provide pagination for large datasets. Unless otherwise specified, the maximum number of records that can be returned from an API call is 200 records. |
| `$skip` | string | query | No | If nonzero, skip this number of results before returning data. Used with $top to provide pagination for large datasets. |

#### Submits a document to Avalara E-Invoicing API

`POST /documents`

For both e-invoices and credit notes, when a document is sent to this endpoint, it generates an invoice or credit note in the required format as mandated by the specified country. Additionally, it initiates the workflow to transmit the generated document to the relevant tax authority, if necessary.The response from the endpoint contains a unique document ID, which can be used to request the status of the document and verify if it was successfully accepted at the destination.Furthermore, the unique ID enables the download of a copy of the e-invoice or credit note for reference purposes.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a "Fingerprint" |

#### Returns a copy of the document

`GET /documents/{documentId}/$download`

When the document is available, use this endpoint to download it as text, XML, or PDF. The output format needs to be specified in the Accept header and it will vary depending on the mandate. If the file has not yet been created, then status code 404 (not found) is returned.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `Accept` | string | header | Yes | This header indicates the MIME type of the document |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a "Fingerprint" |
| `documentId` |  | path | Yes | The unique ID for this document that was returned in the POST /einvoicing/document response body |

#### Checks the status of a document

`GET /documents/{documentId}/status`

Using the unique ID from POST /einvoicing/documents response body, request the current status of a document.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a "Fingerprint" |
| `documentId` |  | path | Yes | The unique ID for this document that was returned in the POST /einvoicing/documents response body |


### Data Input Fields

#### Returns the mandatory and conditional invoice or creditnote input fields for different country mandates

`GET /data-input-fields`

This endpoint provides a list of required, conditional, and optional fields for each country mandate. You can use the mandates endpoint to retrieve all available country mandates. You can use the $filter query parameter to retrieve fields for a particular mandate

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a "Fingerprint" |
| `$filter` | string | query | No | Filter by field name and value. This filter only supports eq and contains. Refer to [https://developer.avalara.com/avatax/filtering-in-rest/](https://developer.avalara.com/avatax/filtering-in-rest/) for more information on filtering. |
| `$top` | string | query | No | If nonzero, return no more than this number of results. Used with $skip to provide pagination for large datasets. Unless otherwise specified, the maximum number of records that can be returned from an API call is 1,000 records. |
| `$skip` | string | query | No | If nonzero, skip this number of results before returning data. Used with $top to provide pagination for large datasets. |
| `$count` | string | query | No | When set to true, the count of the collection is also returned in the response body |
| `$countOnly` | string | query | No | When set to true, only the count of the collection is returned |


### Mandates

#### List country mandates that are supported by the Avalara E-Invoicing platform

`GET /mandates`

This endpoint offers a list of country mandates supported by the Avalara E-Invoicing API.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a "Fingerprint" |
| `$filter` | string | query | No | Filter by field name and value. This filter only supports eq and contains. Refer to [https://developer.avalara.com/avatax/filtering-in-rest/](https://developer.avalara.com/avatax/filtering-in-rest/) for more information on filtering. |
| `$top` | string | query | No | If nonzero, return no more than this number of results. Used with $skip to provide pagination for large datasets. Unless otherwise specified, the maximum number of records that can be returned from an API call is 1,000 records. |
| `$skip` | string | query | No | If nonzero, skip this number of results before returning data. Used with $top to provide pagination for large datasets. |
| `$count` | string | query | No | When set to true, the count of the collection is also returned in the response body. |
| `$countOnly` | string | query | No | When set to true, only the count of the collection is returned |

---

## Models

### documentId

The unique ID for this document that was returned in the POST /einvoicing/documents response body. This is a UID created by the Avalara E-Invoicing platform.

### DocumentSubmitResponse

Returns the unique ID of a successful document submission

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique ID for this document that can be used for status checking and file downloads. This is a UID created by the Avalara E-Invoicing platform. |

### DocumentStatusResponse

Returns the current document ID and status

| Property | Type | Description |
|---|---|---|
| `id` | string | The unique ID for this document |
| `status` | string | Status of the transaction:  'Pending'  'Failed'  'Complete' |
| `events` | array |  |

### DocumentListResponse

Returns the requested list of documents

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | string | Count of collections for the given date range |
| `@nextLink` | string |  |
| `value` | array | Array of invoices matching query parameters |

### DocumentSummary

Displays a summary of information about the document

| Property | Type | Description |
|---|---|---|
| `id` | string | The unique ID for this document |
| `companyId` | string | Unique identifier that represents the company within the system. |
| `processDateTime` | string | The date and time when the document was processed, displayed in the format YYYY-MM-DDThh:mm:ss |
| `status` | string | The transaction status:  'Pending'  'Failed'  'Complete' |
| `supplierName` | string | The name of the supplier in the transaction |
| `customerName` | string | The name of the customer in the transaction |
| `documentNumber` | string | The invoice document number |
| `documentDate` | string | The invoice issue date |
| `flow` | string | The invoice direction, where issued = `out` and received = `in` |
| `countryCode` | string | The two-letter ISO-3166 country code for the country where the e-invoice is being submitted |
| `countryMandate` | string | The e-invoicing mandate for the specified country |
| `interface` | string | The interface where the invoice data is sent |
| `receiver` | string | The invoice recipient based on the interface |

### StatusEvent

Displays when a status event occurred

| Property | Type | Description |
|---|---|---|
| `eventDateTime` | string | The date and time when the status event occured, displayed in the format YYYY-MM-DDThh:mm:ss |
| `message` | string | A message describing the status event |
| `responseKey` | string | The type of number or acknowledgement returned by the tax authority (if applicable). For example, it could be an identification key, acknowledgement code, or any other relevant identifier. |
| `responseValue` | string | The corresponding value associated with the response key. This value is provided by the tax authority in response to the event. |

### SubmitDocument

Allows submission of a document.

| Property | Type | Description |
|---|---|---|
| `metadata` | object | Key value pairs of metadata for a document submission. dataFormat can be ubl-invoice or ubl-creditnote:  {  "workflowId": "partner-einvoicing", "dataFormat": "ubl-invoice", "dataFormatVersion": "2.1", "countryCode": "SA", "countryMandate": "SA-Phase1-B2B" } |
| `data` | object | The document to be submitted, as indicated by the metadata fields 'dataFormat' and 'dataFormatVersion' |

### ForbiddenError

Returns an optional message with a 'forbidden' response

| Property | Type | Description |
|---|---|---|
| `Message` | string | A message that informs the user that they may not access a resource |

### DocumentSubmissionError

Returns an HTTP status code and message for an 'exception'

| Property | Type | Description |
|---|---|---|
| `StatusCode` | string | The three-digit HTTP status code for the exception |
| `Message` | string | A message explaining the exception |

### BadRequest

Returns an HTTP status code and message for a 'bad request'

| Property | Type | Description |
|---|---|---|
| `error` | string | The three-digit HTTP error code for the bad request |
| `message` | string | A message explaining the bad request |

### NotFoundError

Returns an HTTP error code and message for a 'not found' error

| Property | Type | Description |
|---|---|---|
| `error` | string | The three-digit HTTP error code for a not found error |
| `message` | string | A message about the not found error |

### BadDownloadRequest

Returns an HTTP status code and message for a 'bad request'

| Property | Type | Description |
|---|---|---|
| `error` | string | The three-digit HTTP error code for the bad request |
| `message` | string | A message explaining the bad request |
| `supportedAcceptHeaders` | object | A message explaining the bad request |

### DataInputFieldsResponse

Response model providing a list of input fields required, optional, or conditional for different country mandates.

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | number | Total count of results |
| `@nextLink` | string |  |
| `value` | array | Array of Data Input Fields |

### DataInputField

The Data Input Field

| Property | Type | Description |
|---|---|---|
| `id` | string | Field UUID |
| `fieldId` | string | Field ID |
| `applicableDocumentRoots` | array |  |
| `path` | string | Path to this field |
| `nameSpace` | string | Namespace of this field |
| `fieldName` | string | Field name |
| `exampleOrFixedValue` | string | An example of the content for this field |
| `acceptedValues` | object | An object representing the acceptable values for this field |
| `documentationLink` | string | An example of the content for this field |
| `description` | string | A description of this field |
| `isSegment` | boolean | Is this a segment of the schema |
| `requiredFor` | object | Array of CountryMandate names for which this field is required. |
| `conditionalFor` | array |  |
| `notUsedFor` | object | Array of CountryMandate names for which this field is not used. |
| `optionalFor` | object | Array of CountryMandate names for which this field is optional. |

### ApplicableDocumentRootsField

Document types for which this field is applicable for

### ConditionalForField

Mandates for which this field is conditional

| Property | Type | Description |
|---|---|---|
| `countryMandate` | string |  |
| `requiredWhen` | array | Array of scenarios which describe when a particular field is conditional for a country mandate |

### RequiredWhenField

Mandates for which this field is required

| Property | Type | Description |
|---|---|---|
| `scenario` | string |  |

### OptionalForField

Mandates for which this field is optional

### NotUsedForField

Mandates for which this field is not used

| Property | Type | Description |
|---|---|---|
| `countryMandate` | string |  |

### InternalServerError

Returns an optional message with a 'InternalServerError' response

| Property | Type | Description |
|---|---|---|
| `error` | string | A bad request error code |
| `message` | string | A message explaining the bad request error |

### MandatesResponse

Mandate list response schema

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | number | Total count of results |
| `@nextLink` | string |  |
| `value` | array | Mandates schema |

### Mandate

An object representing the country mandate

| Property | Type | Description |
|---|---|---|
| `mandateId` | string | Mandate UUID |
| `countryMandate` | string | The `countryMandate` is comprised of the country code, mandate type, and the network or regulation type (for example, PT-B2C-PDF). Keep in mind the following when specifying a `countryMandate`.
- A country can have multiple mandate types (B2C, B2B, B2G).
- A entity/company can opt in for multiple mandates.
- A `countryMandate` is the combination of country + mandate type + network/regulation. |
| `countryCode` | string | Country code |
| `description` | string | Mandate description |
| `supportedByELRAPI` | boolean | Indicates whether this mandate supported by the ELR API |
| `mandateFormat` | string | Mandate format |
| `eInvoicingFlow` | string | The type of e-invoicing flow for this mandate |
| `eInvoicingFlowDocumentationLink` | string | Link to the documentation for this mandate's e-invoicing flow |
| `getInvoiceAvailableMediaType` | array | List of available media types for downloading invoices for this mandate |
| `supportsInboundDigitalDocument` | string | Indicates whether this mandate supports inbound digital documents |
| `inputDataFormats` | array | Format and version used when inputting the data |
| `workflowIds` | array | Workflow ID list |

### InputDataFormats

Format and version used when inputting the data

| Property | Type | Description |
|---|---|---|
| `format` | string | Invoice format |
| `versions` | array |  |

### InputDataFormatVersions

Invoice format version

### WorkflowIds

Workflow ID list

| Property | Type | Description |
|---|---|---|
| `name` | string | The name of this workflow |
| `description` | string | Workflow description |