Get details of an Invoice

GET/v2/invoices/{invoiceId}

API-Version

Request-Methode

GET

Operation-ID

invoice-detail

Request

invoiceIdstringrequired

Responses

Format

application/json

Beschreibung

amountPaidnumberrequired
cancellationobject
- cancellationIdstring (uuid)required
- cancelledAtstring (date-time)required
- correctionNumberstringrequired
- pdfIdstring (uuid)required
- reasonstring
- xRechnungIdstring (uuid)
  The ID of the XRechnung XML file. Only set when the recipient has a Leitweg-ID; the PDF is then only a visual copy.
cancellationOfstring (uuid)
The ID of the Invoice that this invoice cancels.
currencystringrequired
customerIdstringrequired
datestring (date-time)required
groupsArray von objectrequired
- Array[
  - *object
    - contractIdstring (uuid)
    - descriptionstring
    - itemsArray von objectrequired
      - Array[
        *object
        additionalDescriptionstring
        contractItemIdstring (uuid)required
        descriptionstringrequired
        itemCancelledOrCorrectedByArray von object
        Array[
        *object
        sourceInvoiceIdstring (uuid)
        sourceInvoiceItemIdstring (uuid)
        ]
        itemIdstring (uuid)required
        priceobjectrequired
        currency"EUR"required
        valueintegerrequired
        referenceobject
        sourceInvoiceIdstring (uuid)required
        sourceInvoiceItemIdstring (uuid)required
        serviceDatestring (date-time)
        servicePeriodobject
        endstring (date-time)required
        startstring (date-time)required
        vatRatenumberrequired
        ]
  ]
idstring (uuid)required
invoiceNumberstringrequired
invoiceTypestring (einer von: REGULAR, REISSUE, CORRECTION, CANCELLATION)required
paymentSettingseine von 2 Alternativen
- Alternativeobject
  - accountHolderstringrequired
  - bicstring
    Optional. Required for payments outside of the European Union.
  - ibanstringrequired
  - method"debit"required
- Alternativeobject
  - method"invoice"required
pdfIdstring (uuid)required
recipientobjectrequired
- addressobjectrequired
  - streetstringrequired
  - houseNumberstringrequired
  - citystringrequired
  - zipstringrequired
  - countryCodestringrequired
    ISO 3166-1 alpha-2 country code
  - addressPrefixstring
- companystring
- emailAddressstring (email)
- firstNamestring
- lastNamestring
- leitwegIdstring (≤ 46 Zeichen)
  German electronic invoicing routing ID (XRechnung). Only allowed for public authorities and requires a company.
- phoneNumbersArray von string
  - Array[
    - *string
    ]
- purchaseOrderReferencestring (≤ 200 Zeichen)
  Purchase order reference printed on the invoice. Not allowed together with a leitwegId.
- salutationstring (einer von: mr, ms, other)required
- titlestring
- useFormalTermboolean
reissuedBystring (uuid)
The ID of the Invoice that is a Reissue of this one.
statusstring (einer von: NEW, CONFIRMED, DENIED, PAID, PARTIALLY_PAID, OVERPAID)required
totalGrossnumberrequired
totalNetnumberrequired
vatIdstring
xRechnungIdstring (uuid)
The ID of the XRechnung XML file. Only set when the recipient has a Leitweg-ID; the PDF is then only a visual copy.

Content-Type: application/json

{
  "amountPaid": 500,
  "cancellation": {
    "cancellationId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "cancelledAt": "1985-10-26T01:21:00.000Z",
    "correctionNumber": "RG1234567",
    "pdfId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "reason": "Kulanz",
    "xRechnungId": "f0f86186-0a5a-45b2-aa33-502777496347"
  },
  "cancellationOf": "f0f86186-0a5a-45b2-aa33-502777496347",
  "currency": "EUR",
  "customerId": "e0a3b0e0-0e0e-0e0e-0e0e-0e0e0e0e0e0e",
  "date": "1985-10-26T01:21:00.000Z",
  "groups": [
    {
      "contractId": "f0f86186-0a5a-45b2-aa33-502777496347",
      "description": "Space-Server: \"Mein Space-Server\"",
      "items": [
        {
          "additionalDescription": "Short-ID: \"s-123456\"",
          "contractItemId": "f0f86186-0a5a-45b2-aa33-502777496347",
          "description": "Space-Server: \"Mein Space-Server\"",
          "itemCancelledOrCorrectedBy": [
            {
              "sourceInvoiceId": "f0f86186-0a5a-45b2-aa33-502777496347",
              "sourceInvoiceItemId": "f0f86186-0a5a-45b2-aa33-502777496347"
            }
          ],
          "itemId": "f0f86186-0a5a-45b2-aa33-502777496347",
          "price": {
            "currency": "EUR",
            "value": 1000
          },
          "reference": {
            "sourceInvoiceId": "f0f86186-0a5a-45b2-aa33-502777496347",
            "sourceInvoiceItemId": "f0f86186-0a5a-45b2-aa33-502777496347"
          },
          "serviceDate": "1985-10-26T01:21:00.000Z",
          "servicePeriod": {
            "end": "1985-10-26T01:21:00.000Z",
            "start": "1985-10-26T01:21:00.000Z"
          },
          "vatRate": 19
        }
      ]
    }
  ],
  "id": "f0f86186-0a5a-45b2-aa33-502777496347",
  "invoiceNumber": "RG1234567",
  "invoiceType": "REGULAR",
  "paymentSettings": {
    "accountHolder": "Ada Lovelace",
    "bic": "DEUTDEDB123",
    "iban": "DE12345678901234567890",
    "method": "debit"
  },
  "pdfId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "recipient": {
    "address": {
      "street": "Königsberger Straße",
      "houseNumber": "4-6",
      "city": "Espelkamp",
      "zip": "32339",
      "countryCode": "DE",
      "addressPrefix": "c/o Ada Lovelace"
    },
    "company": "Mittwald CM Service GmbH & Co. KG",
    "emailAddress": "email@mittwald.example",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "leitwegId": "string",
    "phoneNumbers": [
      "+49 123 4567890"
    ],
    "purchaseOrderReference": "string",
    "salutation": "mr",
    "title": "Dr.",
    "useFormalTerm": true
  },
  "reissuedBy": "f0f86186-0a5a-45b2-aa33-502777496347",
  "status": "NEW",
  "totalGross": 595,
  "totalNet": 500,
  "vatId": "DE123456789",
  "xRechnungId": "f0f86186-0a5a-45b2-aa33-502777496347"
}

{
  "properties": {
    "amountPaid": {
      "example": 500,
      "type": "number"
    },
    "cancellation": {
      "properties": {
        "cancellationId": {
          "format": "uuid",
          "type": "string"
        },
        "cancelledAt": {
          "format": "date-time",
          "type": "string"
        },
        "correctionNumber": {
          "example": "RG1234567",
          "type": "string"
        },
        "pdfId": {
          "format": "uuid",
          "type": "string"
        },
        "reason": {
          "example": "Kulanz",
          "type": "string"
        },
        "xRechnungId": {
          "description": "The ID of the XRechnung XML file. Only set when the recipient has a Leitweg-ID; the PDF is then only a visual copy.",
          "format": "uuid",
          "type": "string"
        }
      },
      "required": [
        "pdfId",
        "correctionNumber",
        "cancelledAt",
        "cancellationId"
      ],
      "type": "object"
    },
    "cancellationOf": {
      "description": "The ID of the Invoice that this invoice cancels.",
      "format": "uuid",
      "type": "string"
    },
    "currency": {
      "example": "EUR",
      "type": "string"
    },
    "customerId": {
      "example": "e0a3b0e0-0e0e-0e0e-0e0e-0e0e0e0e0e0e",
      "type": "string"
    },
    "date": {
      "format": "date-time",
      "type": "string"
    },
    "groups": {
      "items": {
        "properties": {
          "contractId": {
            "format": "uuid",
            "type": "string"
          },
          "description": {
            "example": "Space-Server: \"Mein Space-Server\"",
            "type": "string"
          },
          "items": {
            "items": {
              "properties": {
                "additionalDescription": {
                  "example": "Short-ID: \"s-123456\"",
                  "type": "string"
                },
                "contractItemId": {
                  "format": "uuid",
                  "type": "string"
                },
                "description": {
                  "example": "Space-Server: \"Mein Space-Server\"",
                  "type": "string"
                },
                "itemCancelledOrCorrectedBy": {
                  "items": {
                    "properties": {
                      "sourceInvoiceId": {
                        "format": "uuid",
                        "type": "string"
                      },
                      "sourceInvoiceItemId": {
                        "format": "uuid",
                        "type": "string"
                      }
                    },
                    "type": "object"
                  },
                  "type": "array"
                },
                "itemId": {
                  "format": "uuid",
                  "type": "string"
                },
                "price": {
                  "properties": {
                    "currency": {
                      "enum": [
                        "EUR"
                      ],
                      "type": "string"
                    },
                    "value": {
                      "example": 1000,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "value",
                    "currency"
                  ],
                  "type": "object"
                },
                "reference": {
                  "properties": {
                    "sourceInvoiceId": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "sourceInvoiceItemId": {
                      "format": "uuid",
                      "type": "string"
                    }
                  },
                  "required": [
                    "sourceInvoiceId",
                    "sourceInvoiceItemId"
                  ],
                  "type": "object"
                },
                "serviceDate": {
                  "format": "date-time",
                  "type": "string"
                },
                "servicePeriod": {
                  "properties": {
                    "end": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "start": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "required": [
                    "start",
                    "end"
                  ],
                  "type": "object"
                },
                "vatRate": {
                  "example": 19,
                  "type": "number"
                }
              },
              "required": [
                "itemId",
                "price",
                "vatRate",
                "contractItemId",
                "description"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "items"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "id": {
      "format": "uuid",
      "type": "string"
    },
    "invoiceNumber": {
      "example": "RG1234567",
      "type": "string"
    },
    "invoiceType": {
      "enum": [
        "REGULAR",
        "REISSUE",
        "CORRECTION",
        "CANCELLATION"
      ],
      "type": "string"
    },
    "paymentSettings": {
      "oneOf": [
        {
          "properties": {
            "accountHolder": {
              "example": "Ada Lovelace",
              "type": "string"
            },
            "bic": {
              "description": "Optional. Required for payments outside of the European Union.",
              "example": "DEUTDEDB123",
              "type": "string"
            },
            "iban": {
              "example": "DE12345678901234567890",
              "type": "string"
            },
            "method": {
              "enum": [
                "debit"
              ],
              "type": "string"
            }
          },
          "required": [
            "method",
            "iban",
            "accountHolder"
          ],
          "type": "object"
        },
        {
          "properties": {
            "method": {
              "enum": [
                "invoice"
              ],
              "type": "string"
            }
          },
          "required": [
            "method"
          ],
          "type": "object"
        }
      ]
    },
    "pdfId": {
      "format": "uuid",
      "type": "string"
    },
    "recipient": {
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "street": {
              "type": "string",
              "example": "Königsberger Straße"
            },
            "houseNumber": {
              "type": "string",
              "example": "4-6"
            },
            "city": {
              "type": "string",
              "example": "Espelkamp"
            },
            "zip": {
              "type": "string",
              "example": "32339"
            },
            "countryCode": {
              "type": "string",
              "example": "DE",
              "description": "ISO 3166-1 alpha-2 country code"
            },
            "addressPrefix": {
              "type": "string",
              "example": "c/o Ada Lovelace"
            }
          },
          "required": [
            "street",
            "houseNumber",
            "city",
            "zip",
            "countryCode"
          ]
        },
        "company": {
          "example": "Mittwald CM Service GmbH & Co. KG",
          "type": "string"
        },
        "emailAddress": {
          "format": "email",
          "type": "string"
        },
        "firstName": {
          "example": "Ada",
          "type": "string"
        },
        "lastName": {
          "example": "Lovelace",
          "type": "string"
        },
        "leitwegId": {
          "description": "German electronic invoicing routing ID (XRechnung). Only allowed for public authorities and requires a company.",
          "maxLength": 46,
          "type": "string"
        },
        "phoneNumbers": {
          "items": {
            "example": "+49 123 4567890",
            "type": "string"
          },
          "type": "array"
        },
        "purchaseOrderReference": {
          "description": "Purchase order reference printed on the invoice. Not allowed together with a leitwegId.",
          "maxLength": 200,
          "type": "string"
        },
        "salutation": {
          "type": "string",
          "enum": [
            "mr",
            "ms",
            "other"
          ]
        },
        "title": {
          "example": "Dr.",
          "type": "string"
        },
        "useFormalTerm": {
          "type": "boolean"
        }
      },
      "required": [
        "address",
        "salutation"
      ],
      "type": "object"
    },
    "reissuedBy": {
      "description": "The ID of the Invoice that is a Reissue of this one.",
      "format": "uuid",
      "type": "string"
    },
    "status": {
      "enum": [
        "NEW",
        "CONFIRMED",
        "DENIED",
        "PAID",
        "PARTIALLY_PAID",
        "OVERPAID"
      ],
      "type": "string"
    },
    "totalGross": {
      "example": 595,
      "type": "number"
    },
    "totalNet": {
      "example": 500,
      "type": "number"
    },
    "vatId": {
      "example": "DE123456789",
      "type": "string"
    },
    "xRechnungId": {
      "description": "The ID of the XRechnung XML file. Only set when the recipient has a Leitweg-ID; the PDF is then only a visual copy.",
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "id",
    "customerId",
    "invoiceNumber",
    "date",
    "pdfId",
    "groups",
    "status",
    "amountPaid",
    "recipient",
    "totalNet",
    "totalGross",
    "currency",
    "invoiceType"
  ],
  "type": "object"
}

Format

application/json

Beschreibung

Validation Error caused by invalid input data in the request

type"ValidationError"required
messagestring
validationErrorsArray von objectrequired
- Array[
  - *object
    - messagestringrequired
      The standard error message
    - pathstringrequired
      The path to the part of the data that was validated. JavaScript property access notation (e.g., ".prop[1].subProp") is used.
    - typestringrequired
      ajv validation error type (e.g. "format", "required", "type") or own validation error types
    - contextobject
      The object with the additional information about the error that can be used to create custom error messages. Keys depend on the type that failed validation (e.g. "missingProperty" for type "required")
      - *string
  ]

Content-Type: application/json

{
  "type": "ValidationError",
  "message": "Validation failed",
  "validationErrors": [
    {
      "message": "should be string",
      "path": ".address.street",
      "type": "format",
      "context": {
        "format": "email"
      }
    }
  ]
}

{
  "type": "object",
  "required": [
    "type",
    "validationErrors"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "ValidationError"
      ]
    },
    "message": {
      "type": "string",
      "example": "Validation failed"
    },
    "validationErrors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "message",
          "path",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The standard error message",
            "example": "should be string"
          },
          "path": {
            "type": "string",
            "description": "The path to the part of the data that was validated. JavaScript property access notation (e.g., \".prop[1].subProp\") is used.\n",
            "example": ".address.street"
          },
          "type": {
            "type": "string",
            "description": "ajv validation error type (e.g. \"format\", \"required\", \"type\") or own validation error types",
            "example": "format"
          },
          "context": {
            "type": "object",
            "example": {
              "format": "email"
            },
            "description": "The object with the additional information about the error that can be used to create custom error messages. Keys depend on the\ntype that failed validation (e.g. \"missingProperty\" for type \"required\")\n",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Format

application/json

Beschreibung

The requested resource was not found

messagestringrequired
typestringrequired

Content-Type: application/json

{
  "message": "Something went wrong",
  "type": "InternalServerError"
}

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "message": {
      "type": "string",
      "example": "Something went wrong"
    },
    "type": {
      "type": "string",
      "example": "InternalServerError"
    }
  }
}

Format

application/json

Beschreibung

Your request ran into a rate limit. You have to wait until rate limit expires

messagestring
typestring

Content-Type: application/json

{
  "message": "too many requests",
  "type": "RateLimitError"
}

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "too many requests"
    },
    "type": {
      "type": "string",
      "example": "RateLimitError"
    }
  }
}

Format

application/json

Beschreibung

An unexpected Error that occurred while handling the request

messagestringrequired
typestringrequired

Content-Type: application/json

{
  "message": "Something went wrong",
  "type": "InternalServerError"
}

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "message": {
      "type": "string",
      "example": "Something went wrong"
    },
    "type": {
      "type": "string",
      "example": "InternalServerError"
    }
  }
}

Nutzungsbeispiele

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/invoices/string

import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.contract.invoiceDetail({
  "invoiceId": "string"
});

assertStatus(response, 200);
  

use \Mittwald\ApiClient\Generated\V2\Clients\Contract\InvoiceDetail\InvoiceDetailRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new InvoiceDetailRequest(
  invoiceId: "string"
));
$response = $client->contract()->invoiceDetail($request);

var_dump($response->getBody();
  

Get details of an Invoice

Request​

Pfad-Parameterrequired

Responses​

OK200

Bad Request400

Not Found404

Too Many Requests429

default

Nutzungsbeispiele​

Auf dieser Seite

Request

Responses

Nutzungsbeispiele