### Install Python Libraries (Bash)

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/test_with_python_script_eng/index.md

Command to install all required Python libraries for the testing script using a requirements file. This should be executed within the project's test directory.

```bash
cd docs/test_with_Python_script

pip3 install -r requirements.txt
```

--------------------------------

### Check Python and Pip Installation (Bash)

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/test_with_python_script_eng/index.md

Commands to verify if Python (version 3.6.X or higher) and pip are installed on your system. These are prerequisites for running the Python testing script.

```bash
python3 --version

pip3 --version
```

--------------------------------

### Install Python on macOS (Bash)

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/test_with_python_script_eng/index.md

Instructions for installing Python 3.8 and upgrading pip on macOS using Homebrew. This ensures the necessary Python environment for the testing script.

```bash
brew install python

python3 -m pip install --upgrade pip
```

--------------------------------

### Install Python on Linux Ubuntu (Bash)

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/test_with_python_script_eng/index.md

Commands to install Python 3.8 and pip on Ubuntu Linux systems. This is required to set up the Python environment for running the MVA-meldingen test script.

```bash
sudo apt-get update

sudo apt-get install python3.8

sudo apt install python3-pip
```

--------------------------------

### Example XML File for VAT Compensation Tax Return

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/kompensasjon_eng/informasjonsmodell/index.md

This snippet represents a sample XML file structure for the tax return for VAT compensation. It adheres to the Version 1.0 XSD and includes essential fields for reporting VAT compensation details.

```xml
<SkattemeldingForMerverdiavgiftKompensasjon xmlns="http://www.skatteetaten.no/mva/1.0">
    <meldingskategori>Kompensasjon</meldingskategori>
    <merknad>
        <kompensasjon>SANN</kompensasjon>
    </merknad>
    <organisasjonsnummer>123456789</organisasjonsnummer>
    <innsending>
        <regnskapssystemrefereanse>REF123</regnskapssystemrefereanse>
        <system>ERP System v2.0</system>
    </innsending>
    <betalingsinformasjon>
        <KID>987654321</KID>
    </betalingsinformasjon>
</SkattemeldingForMerverdiavgiftKompensasjon>
```

--------------------------------

### Download Feedback Files

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Downloads specific feedback documents from the Tax Administration using the URLs obtained from the `Retrieve Feedback` endpoint. This allows users to get detailed validation results, payment information, or receipts.

```APIDOC
## Download Feedback Files

### Description
Downloads feedback documents from Tax Administration using URLs from instance data elements.

### Method
GET

### Endpoint
`/skd/mva-melding-innsending-etm2/instances/{instanceId}/data/{dataElementId}`

### Parameters
#### Path Parameters
- **instanceId** (string) - Required - The unique identifier for the MVA-melding instance.
- **dataElementId** (string) - Required - The ID of the specific data element (feedback file) to download.

#### Query Parameters
None

### Request Example
```bash
# Download validation result
curl -X GET "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/data/82c96a52-ad0b-428f-8005-7f214daf367e" \
  -H "Authorization: Bearer {altinnToken}" \
  -o valideringsresultat.xml

# Download payment information
curl -X GET "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/data/726a315f-7e5e-4514-8ef1-5eda624407d4" \
  -H "Authorization: Bearer {altinnToken}" \
  -o betalingsinformasjon.xml
```

### Response
#### Success Response (200 OK)
- The response body will contain the content of the requested feedback file (e.g., XML, PDF).
```

--------------------------------

### Error Responses

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

This section details potential error responses, including Bad Request (400), Forbidden (403), and Not Found (404), along with explanations and examples.

```APIDOC
## Error Handling

### Response 400 - Bad Request
(Details not provided in the input text)

### Response 403 - Forbidden
This error occurs if the logged-in user lacks the necessary rights to the organization number specified in the request header, or if the user does not have the correct roles for creating an instance.

#### Response Example
```json
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
    "title": "Forbidden",
    "status": 403,
    "traceId": "00-44eab35cb9ca2049b24de316f380a774-a724e045b09dfc44-00"
}
```

### Response 404 - Not Found
This error can occur when an invalid organization number is provided in the request header.

#### Response Example
```json
"Cannot lookup party: Failed to lookup party by organisationNumber: 123456789. The exception was: 404 - Not Found - "
```
```

--------------------------------

### Integration and Authentication Parameters

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/idportenauthentication/index.md

Details on the various parameters required for setting up and configuring your integration, including organization identifiers, client ID, and authentication settings.

```APIDOC
## Integration and Authentication Parameters

### Description
This section outlines the key parameters to configure when setting up your integration with ID-Porten for MVA-meldingen.

### Kundens org.nr. (Customer Organization Number)
- **Type**: String
- **Description**: The organization number of your own organization that will be using the integration.

### Integrasjonens identifikator (Integration Identifier)
- **Type**: String (client_id)
- **Description**: This identifier is provided when the integration is created and appears in the "Guide". It serves as the `client_id` for your integration.

### Navn på integrasjonen & Beskrivelse (Integration Name and Description)
- **Type**: String
- **Description**: Sensible names and descriptions for your integration. The name will be visible in the list of integrations.

### Tillatte grant types (Allowed Grant Types)
- **Required**: `authorization_code`
- **Optional**: `refresh_token` (Use with caution, especially in public clients like SPAs or desktop applications where secrets cannot be securely stored. Recommended for server-side applications where secrets are protected.)
- **Description**: Defines the allowed authorization flows. `refresh_token` allows for obtaining new access tokens without user re-authentication but requires secure storage of tokens and secrets.

### Klientautentiseringsmetode (Client Authentication Method)
- **Type**: String
- **Description**: Determines how your integration authenticates itself to ID-Porten (not the end-user). Select 'none' if `refresh_token` is not used.

### Applikasjonstype (Application Type)
- **Type**: Enum
- **Options**: `native`, `browser` (public clients), `web` (private client if using `refresh_token`, otherwise can be public).
- **Description**: Specifies whether the application is considered public or private, impacting the availability and security considerations of `refresh_token` usage. `web` applications are typically private if using `refresh_token`.

### Gyldig(e) redirect uri-er (Valid Redirect URIs)
- **Type**: Array of Strings (URIs)
- **Description**: A list of valid URIs where users will be redirected after successful authentication with ID-Porten. The `redirect_uri` parameter used in the authentication request **must** be present in this list. Ensure your application has an endpoint to handle requests to these URIs. For managing a large number of URIs, consider dynamic solutions as per <a href="https://docs.digdir.no/docs/idporten/oidc/oidc_api_admin" target="_blank">Digdir documentation</a> (Note: Link is unavailable in English).
```

--------------------------------

### Create Instance for VAT Return Submission

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

This API call creates a new submission instance within the Altinn3 platform for a specified organization. It requires an Altinn token for authentication and the organization number as part of the request payload. A successful creation returns a 201 Created status with details of the instance, including its unique ID and self-links for further operations.

```bash
# Create instance
curl -X POST "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances" \
  -H "Authorization: Bearer {altinnToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceOwner": {
      "organisationNumber": "123456789"
    }
  }'
```

--------------------------------

### Upload VAT Return Submission

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

Uploads the VAT return submission metadata using a PUT request to update an existing data element. The `vatReturnSubmissionUrl` can be constructed using either the data GUID or the instance data app URL.

```APIDOC
## PUT /data/{dataGuid}

### Description
Uploads the VAT return submission metadata.

### Method
PUT

### Endpoint
`{instanceApiUrl}/{partyId}/{instanceGuid}/data/{dataGuid}` or `{instanceDataAppUrl}`

### Parameters
#### Path Parameters
- **instanceApiUrl** (string) - Required - The base URL for the instance API.
- **partyId** (string) - Required - The ID of the party.
- **instanceGuid** (string) - Required - The GUID of the instance.
- **dataGuid** (string) - Required - The GUID of the data object for the VAT return submission.
- **instanceDataAppUrl** (string) - Required - The app URL for the instance data.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (`Bearer {altinnToken}`).
- **content-type** (string) - Required - Must be `application/xml`.

### Request Body
- **mvameldinginnsending** (xml) - Required - The XML content of the VAT return submission.

### Request Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<mvameldinginnsending>
    ...
</mvameldinginnsending>
```

### Response
#### Success Response (200)
- The uploaded VAT return submission data.

#### Response Example
(No specific example provided, assumes a successful confirmation of the upload.)

### Error Handling
- **403 Forbidden**: Returned if the logged-in user lacks the correct roles to upload the file.
```

--------------------------------

### Download VAT Return Feedback Files

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Downloads specific feedback documents, such as validation results or payment information, using the provided URLs from instance data elements.

```bash
# Download validation result
curl -X GET "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/data/82c96a52-ad0b-428f-8005-7f214daf367e" \
  -H "Authorization: Bearer {altinnToken}" \
  -o valideringsresultat.xml

# Download payment information
curl -X GET "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/data/726a315f-7e5e-4514-8ef1-5eda624407d4" \
  -H "Authorization: Bearer {altinnToken}" \
  -o betalingsinformasjon.xml
```

--------------------------------

### Download Feedback Documents

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/implementationguide/index.md

This section outlines how to download feedback documents generated by the Tax Administration after a VAT Return submission. These documents include the submission status, PDF receipt, payment information in XML, and validation results in XML.

```APIDOC
## GET /api/submission/v1/vat-return/feedback/{documentType}/{documentId}

### Description
Downloads specific feedback documents related to a VAT Return submission. The feedback documents include submission status, receipt, payment information, and validation results.

### Method
GET

### Endpoint
/api/submission/v1/vat-return/feedback/{documentType}/{documentId}

### Parameters
#### Path Parameters
- **documentType** (string) - Required - The type of feedback document (e.g., 'receipt', 'paymentInfo', 'validationResult').
- **documentId** (string) - Required - The identifier for the specific document.

### Response
#### Success Response (200)
- The content of the requested feedback document (e.g., PDF, XML).

#### Response Example
(Returns the raw content of the requested document, e.g., a PDF file for a receipt.)
```

--------------------------------

### ID-Porten Integration Configuration (YAML)

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Configuration settings for integrating with ID-Porten using OpenID Connect. This includes required scopes, grant types, client authentication methods, application type, endpoint URLs, and token lifetimes.

```yaml
# Required ID-Porten Scopes
scopes:
  - openid
  - skatteetaten:mvameldingvalidering
  - skatteetaten:mvameldinginnsending

# Grant Types
allowed_grant_types:
  - authorization_code
  - refresh_token # Optional, only for web applications

# Client Authentication
client_authentication_method: none # For public clients without refresh_token

# Application Type
application_type: browser # or "web" for server-side apps with refresh tokens

# Endpoints (Test Environment Ver 2)
authorize_endpoint: https://oidc-ver2.difi.no/idporten-oidc-provider/authorize
token_endpoint: https://oidc-ver2.difi.no/idporten-oidc-provider/token

# Token Lifetimes
access_token_lifetime: 8h # Maximum for Tax Administration scopes
refresh_token_lifetime: 90d # If using reusable refresh tokens

# Example Authorization Request
# GET https://oidc-ver2.difi.no/idporten-oidc-provider/authorize?
#   client_id=23cc2587-ea4e-4a5f-aa5c-dfce3d6c5f09&
#   redirect_uri=http://localhost:8988/callback&
#   response_type=code&
#   scope=openid%20skatteetaten:mvameldingvalidering%20skatteetaten:mvameldinginnsending&
#   state=random_state_value&
#   code_challenge=BASE64URL(SHA256(code_verifier))&
#   code_challenge_method=S256

# Example Token Request
# POST https://oidc-ver2.difi.no/idporten-oidc-provider/token
# Content-Type: application/x-www-form-urlencoded
# 
# grant_type=authorization_code&
# code={authorization_code}&
# redirect_uri=http://localhost:8988/callback&
# client_id=23cc2587-ea4e-4a5f-aa5c-dfce3d6c5f09&
# code_verifier={code_verifier}
```

--------------------------------

### Complete Data Filling using Process API

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

This snippet demonstrates how to complete the data filling step for VAT return filing by calling the process API for an instance. It utilizes a PUT request to advance the instance to the next step, which is the confirmation stage. Requires an instance URL and an Altinn token for authorization.

```json
PUT {instanceUrl}/process/next
    HEADERS:
        "Authorization": "Bearer " + "{altinnToken}"
        "content-type": "application/json"
```

--------------------------------

### Upload Attachment (PDF)

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

This snippet illustrates how to upload an attachment, such as a PDF, to the instance data API. It uses a POST request with an Altinn token for authorization, a specified content type (e.g., 'application/pdf'), and a 'Content-Disposition' header for the filename. The content of the request is the binary data of the attachment.

```http
POST {instanceUrl}/data?datatype=binaerVedlegg
    HEADERS:
        "Authorization": "Bearer " + "{altinnToken}"
        "content-type": "application/pdf"
        "Content-Disposition": "attachment; filename=merknaderTilMvaMeldingen.pdf"
    Content:
    {pdf-attachment in binary format}
```

--------------------------------

### VAT Return Submission API - Integration Overview

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Overview of the VAT Return Submission API's integration patterns and workflow, including authentication, validation, and submission steps.

```APIDOC
## VAT Return Submission API - Integration Overview

### Description
This section provides a high-level overview of how to integrate with the VAT Return Submission API. It outlines the typical sequence of operations and recommended practices for accounting system providers.

### Workflow
1. **Authentication**: Obtain access tokens using ID-Porten.
2. **Validation (Optional)**: Validate VAT return content before submission.
3. **Instance Creation**: Create a new submission instance via Altinn3's Instance API.
4. **Metadata Upload**: Upload the VAT return submission metadata (konvolutt).
5. **Document Upload**: Upload the actual VAT return document.
6. **Attachment Upload (Optional)**: Attach supporting documents.
7. **Data Filling**: Complete the data filling step, triggering server-side validation.
8. **Submission Completion**: Finalize the submission, requiring appropriate signing rights.
9. **Feedback Polling**: Poll for feedback status or use the synchronous blocking endpoint for processing results.

### Recommended Integration Practices
- Implement token caching for efficient authentication.
- Utilize the validation API to prevent invalid filings.
- Display validation results contextually within the user interface.
- Handle asynchronous feedback with user notifications.

### Required Altinn Roles
- **Data Upload**: 'Regnskapsmedarbeider', 'Revisormedarbeider'
- **Submission Completion**: 'Regnskapsfører med signeringsrett', 'Begrenset signeringsrett'

### Testing
- Integrate with test environment (Ver 2 endpoints) using ID-Porten test credentials before production deployment.

### Data Formats
- Comprehensive XML examples are available for VAT returns, submission metadata, payment information, and validation results.
```

--------------------------------

### Download Receipt PDF

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

This endpoint allows you to download the receipt PDF for a submitted Mva-meldingen instance.

```APIDOC
## GET /instances/{instanceId}/data/{dataId}

### Description
Downloads the receipt PDF for a specific Mva-meldingen submission.

### Method
GET

### Endpoint
`https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/{instanceId}/data/{dataId}`

### Parameters
#### Path Parameters
- **instanceId** (string) - Required - The ID of the Mva-meldingen instance.
- **dataId** (string) - Required - The ID of the data to download (receipt PDF).

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer {altinnToken}`

### Response
#### Success Response (200)
- The response body will be the content of the `kvittering.pdf` file.

### Response Example
(Binary PDF content)
```

--------------------------------

### Create Instance Response

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

This section details the successful response (HTTP 201 Created) when an instance for an MVA declaration is created. It includes identifiers, links to the application and platform, and data related to the submitted declaration.

```APIDOC
## POST /instances

### Description
This endpoint is used to create a new instance for submitting an MVA declaration. The response provides details about the created instance, including its unique ID, owner information, application details, and links for further interaction.

### Method
POST

### Endpoint
/instances

### Request Body
(Not specified in the provided text)

### Request Example
(Not specified in the provided text)

### Response
#### Success Response (201 Created)
- **id** (string) - Unique identifier for the instance, in the format `{partyId}/{instanceGuid}`.
- **instanceOwner** (object) - Information about the owner of the instance.
  - **partyId** (string) - The party identifier.
  - **organisationNumber** (string) - The organization number.
- **appId** (string) - The application identifier, e.g., `skd/{ApplicationName}`.
- **org** (string) - The organization code, e.g., `skd`.
- **selfLinks** (object) - Links related to the instance.
  - **apps** (string) - URL to the application interface for the instance (`instanceUrl`).
  - **platform** (string) - URL to the Altinn3 platform for the instance.
- **data** (array) - An array of data objects associated with the instance.
  - **id** (string) - Unique identifier for the data element (`dataGuid`).
  - **instanceGuid** (string) - The GUID of the instance.
  - **dataType** (string) - The data type identifier, e.g., `no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v0.1`.
  - **contentType** (string) - The content type of the data, e.g., `application/xml`.
  - **blobStoragePath** (string) - Path in blob storage for the data.
  - **selfLinks** (object) - Links related to the data element.
    - **apps** (string) - Application-specific URL for the data (`instanceDataAppUrl`).
    - **platform** (string) - Platform-specific URL for the data (`instanceDataPlatformUrl`).
  - **size** (integer) - Size of the data in bytes.
  - **locked** (boolean) - Indicates if the data is locked.
  - **refs** (array) - References to other data elements.
  - **isRead** (boolean) - Indicates if the data has been read.
  - **created** (string) - Timestamp of creation.
  - **createdBy** (string) - Identifier of the user who created the data.
  - **lastChanged** (string) - Timestamp of the last change.
  - **lastChangedBy** (string) - Identifier of the user who last changed the data.

#### Response Example
```json
{
    "id": "{partyId}/{instanceGuid}",
    "instanceOwner": {
        "partyId": "{partyId}",
        "organisationNumber": "{organizationNumber}"
    },
    "appId": "skd/{ApplicationName}",
    "org": "skd",
    "selfLinks": {
        "apps": "{instanceUrl}",
        "platform": "{platformUrl}"
    },
    "data": [
        {
            "id": "{dataGuid}",
            "instanceGuid": "{instanceGuid}",
            "dataType": "no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v0.1",
            "contentType": "application/xml",
            "blobStoragePath": "skd/{ApplicationName}/{instanceGuid}/data/{dataGuid}",
            "selfLinks": {
                "apps": "{instanceDataAppUrl}",
                "platform": "{instanceDataPlatformUrl}"
            },
            "size": 273,
            "locked": false,
            "refs": [],
            "isRead": true,
            "created": "2021-03-01T08:15:25.1139057Z",
            "createdBy": "86257",
            "lastChanged": "2021-03-01T08:15:25.1139057Z",
            "lastChangedBy": "86257"
        }
    ]
}
```
```

--------------------------------

### Complete VAT Return Submission

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Submits the VAT return and moves the instance to the confirmation step. Requires appropriate Altinn roles and checks for duplicate filenames.

```bash
# Complete submission
curl -X PUT "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/process/next" \
  -H "Authorization: Bearer {altinnToken}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Gatsby Documentation Site Configuration

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Configuration and commands for building and deploying the Gatsby documentation site.

```APIDOC
## Gatsby Documentation Site Configuration

### Description
Configuration for building and deploying the documentation site using Gatsby.

### `gatsby-config.js`
```javascript
module.exports = {
  siteMetadata: {
    title: "Mva-meldingen",
    menu: [
      { href: "/", name: "Modernisering av Mva-området" },
      { href: "/documentation", name: "Felles " },
      { href: "/mvameldingen", name: "Mva-meldingen " },
      { href: "/english", name: "Documentation in English" }
    ]
  },
  pathPrefix: "/mva-meldingen",
  plugins: [
    "gatsby-plugin-react-helmet",
    {
      resolve: "gatsby-source-filesystem",
      options: {
        path: `${__dirname}/docs`,
        name: "markdown-pages"
      }
    },
    {
      resolve: "gatsby-transformer-remark",
      options: {
        plugins: [
          "gatsby-remark-prismjs",
          "gatsby-remark-autolink-headers",
          {
            resolve: "gatsby-remark-copy-linked-files",
            options: {
              ignoreFileExtensions: []
            }
          }
        ]
      }
    }
  ]
};
```

### Build and Deploy Commands
- `npm install` - Install dependencies
- `npm start` - Start development server with hot reload
- `npm run build` - Build production site
- `npm run deploy` - Deploy to GitHub Pages (requires PAT with repo scope)
```

--------------------------------

### Gatsby Documentation Site Configuration (JavaScript)

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Configuration file for a Gatsby-based documentation site. It defines site metadata, menu structure, file system sourcing for markdown pages, and remark plugins for processing markdown content.

```javascript
// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: "Mva-meldingen",
    menu: [
      { href: "/", name: "Modernisering av Mva-området" },
      { href: "/documentation", name: "Felles " },
      { href: "/mvameldingen", name: "Mva-meldingen " },
      { href: "/english", name: "Documentation in English" }
    ]
  },
  pathPrefix: "/mva-meldingen",
  plugins: [
    "gatsby-plugin-react-helmet",
    {
      resolve: "gatsby-source-filesystem",
      options: {
        path: `${__dirname}/docs`,
        name: "markdown-pages"
      }
    },
    {
      resolve: "gatsby-transformer-remark",
      options: {
        plugins: [
          "gatsby-remark-prismjs",
          "gatsby-remark-autolink-headers",
          {
            resolve: "gatsby-remark-copy-linked-files",
            options: {
              ignoreFileExtensions: []
            }
          }
        ]
      }
    }
  ]
};

// Build and deploy commands
// npm install           # Install dependencies
// npm start             # Start development server with hot reload
// npm run build         # Build production site
// npm run deploy        # Deploy to GitHub Pages (requires PAT with repo scope)
```

--------------------------------

### Retrieve feedback asynchronous towards Altinn3-App

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/Get-Feedback.txt

This endpoint retrieves the updated instance information, which includes the feedback, once it is ready. This is an asynchronous operation.

```APIDOC
## GET /instances/<partyId>/<instanceGuid>/feedback

### Description
Retrieves the feedback details for a specific instance once it has been processed.

### Method
GET

### Endpoint
/instances/{partyId}/{instanceGuid}/feedback

### Parameters
#### Path Parameters
- **partyId** (string) - Required - The party identifier.
- **instanceGuid** (string) - Required - The unique identifier for the instance.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Updated instance** (object) - The instance details including the feedback.

#### Response Example
{
  "instanceId": "<instanceGuid>",
  "partyId": "<partyId>",
  "feedback": {
    "message": "Feedback details here"
  }
}
```

--------------------------------

### Download Receipt PDF using cURL

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

This snippet demonstrates how to download a receipt PDF from the Mva-meldingen service using a cURL command. It requires an Altinn token for authorization and specifies the output file name.

```shell
curl -X GET "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50/data/cbce850a-a887-4598-aea4-710ea9ffdc7d" \
  -H "Authorization: Bearer {altinnToken}" \
  -o kvittering.pdf
```

--------------------------------

### ID-Porten Integration Configuration

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Configuration details for integrating with ID-Porten using OIDC.

```APIDOC
## ID-Porten Integration Configuration

### Description
Configuration requirements for ID-Porten OIDC client integration.

### Scopes
- `openid`
- `skatteetaten:mvameldingvalidering`
- `skatteetaten:mvameldinginnsending`

### Grant Types
- `authorization_code`
- `refresh_token` (Optional, for web applications)

### Client Authentication
- `none` (For public clients without refresh_token)

### Application Type
- `browser` (or `web` for server-side apps with refresh tokens)

### Endpoints (Test Environment Ver 2)
- **Authorize Endpoint**: `https://oidc-ver2.difi.no/idporten-oidc-provider/authorize`
- **Token Endpoint**: `https://oidc-ver2.difi.no/idporten-oidc-provider/token`

### Token Lifetimes
- **Access Token**: `8h` (Maximum for Tax Administration scopes)
- **Refresh Token**: `90d` (If using reusable refresh tokens)

### Example Authorization Request
```
GET https://oidc-ver2.difi.no/idporten-oidc-provider/authorize?client_id=23cc2587-ea4e-4a5f-aa5c-dfce3d6c5f09&redirect_uri=http://localhost:8988/callback&response_type=code&scope=openid%20skatteetaten:mvameldingvalidering%20skatteetaten:mvameldinginnsending&state=random_state_value&code_challenge=BASE64URL(SHA256(code_verifier))&code_challenge_method=S256
```

### Example Token Request
```
POST https://oidc-ver2.difi.no/idporten-oidc-provider/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code={authorization_code}&redirect_uri=http://localhost:8988/callback&client_id=23cc2587-ea4e-4a5f-aa5c-dfce3d6c5f09&code_verifier={code_verifier}
```
```

--------------------------------

### VAT Return Submission API - Create Instance for VAT Return Submission

Source: https://context7.com/skatteetaten/mva-meldingen/llms.txt

Creates a new submission instance within the Altinn3 platform for a specified organization. This instance serves as a container for the VAT return data to be submitted.

```APIDOC
## POST /skd/mva-melding-innsending-etm2/instances

### Description
Creates a new submission instance in Altinn3 for a specific organization.

### Method
POST

### Endpoint
`https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token obtained from Altinn.
- **Content-Type** (string) - Required - `application/json`

#### Request Body
- **instanceOwner** (object) - Required - Information about the instance owner.
  - **organisationNumber** (string) - Required - The organization number for which the instance is created.

### Request Example
```json
{
  "instanceOwner": {
    "organisationNumber": "123456789"
  }
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - Unique identifier for the created instance.
- **instanceOwner** (object) - Information about the instance owner.
  - **partyId** (string) - Party ID of the owner.
  - **organisationNumber** (string) - Organization number of the owner.
- **appId** (string) - The application identifier.
- **selfLinks** (object) - Links related to the instance.
  - **apps** (string) - URL to the instance within the Altinn apps.
- **data** (array) - Array of data elements within the instance.
  - **id** (string) - Identifier for the data element.
  - **dataType** (string) - The type of data.
  - **contentType** (string) - The content type of the data.
  - **selfLinks** (object) - Links related to the data element.

#### Response Example
```json
{
  "id": "3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50",
  "instanceOwner": {
    "partyId": "3949387",
    "organisationNumber": "123456789"
  },
  "appId": "skd/mva-melding-innsending-etm2",
  "selfLinks": {
    "apps": "https://skd.apps.tt02.altinn.no/skd/mva-melding-innsending-etm2/instances/3949387/abba061g-3abb-4bab-bab8-c9abbaf1ed50"
  },
  "data": [
    {
      "id": "28abba46-dea8-4ab7-ba90-433abba906df",
      "dataType": "no.skatteetaten.fastsetting.avgift.mva.mvameldinginnsending.v0.1",
      "contentType": "application/xml",
      "selfLinks": {
```
```

--------------------------------

### Upload VAT Return (XML)

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

This snippet shows how to upload the main VAT return using a POST request to the instance data API. It requires an Altinn token and specifies 'text/xml' as the content type, with a 'Content-Disposition' header for the filename. The payload is an XML document conforming to the mvaMeldingDto schema.

```http
POST {instanceUrl}/data?datatype=mvamelding
    HEADERS:
        "Authorization": "Bearer " + "{altinnToken}"
        "content-type": "text/xml"
        "Content-Disposition": "attachment; filename=mvaMelding.xml"

Content:
    <?xml version="1.0" encoding="UTF-8"?>
    <mvaMeldingDto xmlns="no:skatteetaten:fastsetting:avgift:mva:skattemeldingformerverdiavgift:v1.0">
        ...
    </mvaMeldingDto>
```

--------------------------------

### Requesting and Managing Scopes

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/idportenauthentication/index.md

Information on how to request scopes for your organization's integration by contacting the Norwegian Tax Administration and how these scopes are added to your integration and code.

```APIDOC
## Requesting Scopes

### Description
To obtain necessary scopes for your organization's integration with MVA-meldingen, you must contact the Norwegian Tax Administration via their 'Write to us' service. You will need to provide your organization number.

### Process
1. Contact the Norwegian Tax Administration via <a href="https://www.skatteetaten.no/en/contact/write/" target="_blank">Write to us</a>.
2. Provide the organization number for the entity managing the integration.
3. The tax authorities will grant access to the required scopes.
4. Add the granted scopes to your integration in the Samarbeidsportalen.
5. Update your integration code to include these scopes in the access token request to ID-Porten.

Refer to the sample Python script <a href="https://github.com/Skatteetaten/mva-meldingen/blob/master/test_with_python_script_files/Steg/hent_idporten_token.py" target="_blank">`hent_idporten_token.py`</a> for code implementation guidance.
```

--------------------------------

### Authentication API

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

Exchanges an ID-Porten token for an Altinn token.

```APIDOC
## GET /authentication/api/v1/exchange/id-porten

### Description
Exchanges an ID-Porten token for an Altinn token. This new token is used as the Bearer token for subsequent requests and has a duration of 8 hours.

### Method
GET

### Endpoint
`https://platform.tt02.altinn.no/authentication/api/v1/exchange/id-porten`

### Parameters
#### Headers
- **Authorization** (string) - Required - "Bearer " + {IDPortenToken}
- **content-type** (string) - Required - "application/json"

### Response
#### Success Response (200)
- **altinnToken** (string) - The new Altinn token.

### Response Example
```json
{
  "altinnToken": "ey..."
}
```
```

--------------------------------

### Upload Attachments

Source: https://github.com/skatteetaten/mva-meldingen/blob/master/docs/english/api/index.md

Uploads attachments to the instance data API. Multiple attachments are supported, with restrictions on the number of files and individual file size. The `content-type` and `Content-Disposition` headers are crucial for correct processing.

```APIDOC
## POST /data?datatype=binaerVedlegg

### Description
Uploads attachments to the instance.

### Method
POST

### Endpoint
`{instanceUrl}/data?datatype=binaerVedlegg`

### Parameters
#### Query Parameters
- **datatype** (string) - Required - Must be `binaerVedlegg`.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (`Bearer {altinnToken}`).
- **content-type** (string) - Required - The MIME type of the attachment (e.g., `application/pdf`, `text/xml`).
- **Content-Disposition** (string) - Required - Attachment information, including a unique filename (e.g., `attachment; filename=merknaderTilMvaMeldingen.pdf`).

### Request Body
- **Binary Data** - Required - The attachment file content in binary format.

### Request Example
```json
POST {instanceUrl}/data?datatype=binaerVedlegg
    HEADERS:
        "Authorization": "Bearer " + "{altinnToken}"
        "content-type": "application/pdf"
        "Content-Disposition": "attachment; filename=merknaderTilMvaMeldingen.pdf"
    Content:
    {pdf-attachment in binary format}
```

### Response
#### Success Response (200)
- Confirmation of successful attachment upload.

#### Response Example
(No specific example provided, assumes a successful confirmation of the upload.)

### Allowed Content Types
- text/xml
- application/pdf
- application/vnd.oasis.opendocument.formula
- application/vnd.oasis.opendocument.text
- application/vnd.oasis.opendocument.spreadsheet
- application/vnd.oasis.opendocument.presentation
- application/vnd.oasis.opendocument.graphics
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/msword
- application/vnd.ms-excel
- application/vnd.ms-powerpoint
- image/jpeg
- image/png

### Error Handling
- **403 Forbidden**: Returned if the logged-in user lacks the correct roles to upload the file.
```