Invoices

Change Invoice State

Changes the state of invoice documents.

From	To	State on Request Body	Notes
draft	final	finalized	All documents.
draft	settled	finalized	Only invoice_receipt.
draft	deleted	deleted	All documents.
final	canceled	canceled	All documents.
settled	canceled	canceled	Only invoice_receipt.
final	settled	settled	All documents.
settled	final	unsettled	Only credit_note and debit_note.

put/{invoices-type}/{document-id}/change-state.json

Path parameters

invoices-type'invoices' | 'invoice_receipts' | 'simplified_invoices' | 'credit_notes' | 'debit_notes' required

The type of the invoice document.

document-idinteger required

Example:1050

The ID of the document.

Query parameters

api_keystring required

Example:YOUR_API_KEY

Your API Key.

Request body

Example request

{
  "invoice": {
    "state": "finalized",
    "message": "Wrong value"
  }
}

Response

SUCCESS

Possible values for field atcud:

ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.
N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.
N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.

Response wrapper key

The parent key shown in the example below as invoice is only an example — it always matches the singular of the requested {invoices-type} path parameter: invoice for invoices, invoice_receipt for invoice_receipts, simplified_invoice for simplified_invoices, credit_note for credit_notes, and debit_note for debit_notes. The nested object shape is identical in every case.

Example response

{
  "invoice": {
    "id": 2137287,
    "status": "final",
    "type": "Invoice",
    "sequence_number": "6/G",
    "inverted_sequence_number": "G/6",
    "atcud": "ABCD1234-6",
    "sequence_id": 12345,
    "tax_exemption": "M01",
    "date": "04/08/2016",
    "due_date": "19/08/2016",
    "reference": "ref123",
    "observations": "Observations",
    "cancel_reason": "API test cancellation",
    "permalink": "https://web.invoicexpress.com/documents/...",
    "saft_hash": "J4ay",
    "sum": 24.39,
    "before_taxes": 24.39,
    "taxes": 5.61,
    "total": 30,
    "currency": "Euro",
    "client": {
      "id": 628535,
      "name": "John Doe",
      "code": "C1",
      "country": "Portugal",
      "email": "john@example.com"
    },
    "items": [
      {
        "name": "Product A",
        "description": "Big Product",
        "unit_price": "100.0",
        "quantity": "1.0",
        "unit": "un",
        "tax": {
          "id": 756700,
          "name": "IVA23",
          "value": 23
        },
        "subtotal": 100,
        "tax_amount": 23,
        "total": 123
      }
    ],
    "mb_reference": {
      "entity": "10611",
      "reference": "123 456 789",
      "value": 123.45
    }
  }
}

Changes

Changed in 1 of the 3 revisions of this API.1015

Aug 25, 20265b82d4eb0d9f1015See the full diff
- ▲
  the response property invoice/discount became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property invoice/items/items/description became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property invoice/observations became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property invoice/reference became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property invoice/retention became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property invoice/sequence_id became nullable for the status 200
  response-property-became-nullable
- ▲
  the errors response's property type/format changed from object/ to array/ for status 401
  response-property-type-changed
- ▲
  the invoice/items/items/quantity response's property type/format changed from number/ to string/ for status 200
  response-property-type-changed
- ▲
  the invoice/items/items/unit_price response's property type/format changed from number/ to string/ for status 200
  response-property-type-changed
- ▲
  the invoice/sequence_id response's property type/format changed from string/ to integer null/ for status 200
  response-property-type-changed
- ●
  removed the optional property errors/error from the response with the 401 status
  response-optional-property-removed
- ○
  added the optional property invoice/cancel_reason to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/items/items/discount_amount to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/items/items/subtotal to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/items/items/tax/id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/items/items/tax_amount to the response with the 200 status
  response-optional-property-added
This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history