> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts. Melso API: https://api.melso.ai/v1, invoicing only, with a company API key.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# Anular una factura VERI*FACTU — Void an invoice

> Voids an issued invoice that should never have existed, such as a duplicate or a test.

Melso sends the VERI\*FACTU cancellation and keeps your `reason`.

A wrong amount needs a [corrective invoice](https://docs.melso.ai/api/reference/invoices/correct-invoice.md) instead. Melso answers `409` for an invoice that is paid, collected, already corrected, in a filed quarter, not issued through Melso's VERI\*FACTU sender, or still waiting for the AEAT.


## OpenAPI

````yaml api/openapi.yaml POST /companies/{company_id}/invoices/{invoice_id}/void
openapi: 3.1.0
info:
  title: Melso API
  version: 1.0.0
  summary: Invoicing for one Melso company, from your own system.
  description: |
    The Melso API lets your system invoice as a Melso company: keep its
    customers, prepare invoice drafts, issue them through VERI*FACTU, correct,
    void and mark them paid, and download their PDF.

    A company API key, which the company's owner creates in the Melso app,
    authenticates every call. It works in that one company, with the owner's
    authority. See [Authentication](/api/authentication).

    Tax returns, books and gestiones are not on the API. They live in the
    Melso app and, for an AI assistant the person connects, on the MCP server
    at `https://mcp.melso.ai/mcp`.
  contact:
    name: Melso
    email: hello@melso.ai
    url: https://docs.melso.ai/api/overview
servers:
  - url: https://api.melso.ai/v1
security:
  - companyApiKey: []
tags:
  - name: Companies
    description: The company the key works in.
  - name: Customers
    description: The company's invoice customers.
  - name: Invoices
    description: >-
      Drafts, issuing through VERI*FACTU, corrections, voiding, payment and the
      PDF.
paths:
  /companies/{company_id}/invoices/{invoice_id}/void:
    parameters:
      - $ref: '#/components/parameters/CompanyId'
      - $ref: '#/components/parameters/InvoiceId'
    post:
      tags:
        - Invoices
      summary: Void an invoice
      description: >
        Voids an issued invoice that should never have existed, such as a
        duplicate or a test. Melso sends the VERI*FACTU cancellation and keeps
        your `reason`.


        A wrong amount needs a [corrective
        invoice](/api/reference/invoices/correct-invoice) instead. Melso answers
        `409` for an invoice that is paid, collected, already corrected, in a
        filed quarter, not issued through Melso's VERI*FACTU sender, or still
        waiting for the AEAT.
      operationId: voidInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - expected_version
                - reason
              additionalProperties: false
              properties:
                expected_version:
                  type: string
                  minLength: 64
                  maxLength: 64
                  description: The `version` of the invoice you read.
                reason:
                  type: string
                  minLength: 1
                  description: >-
                    Why the operation never happened, in a sentence. Blank or
                    longer than 500 bytes answers `400` `invoice_void_reason`.
            example:
              expected_version: 4f0d8a6b2c1e9f7a5d3b0c8e6f4a2d1b9c7e5a3f1d0b8c6e4a2f0d9b7c5e3a1f
              reason: La misma venta se facturó dos veces.
      responses:
        '200':
          description: The invoice, with `status` `void`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    CompanyId:
      name: company_id
      in: path
      required: true
      description: >-
        The company's ID. Every company-scoped call works in exactly this
        company.
      schema:
        type: string
        format: uuid
    InvoiceId:
      name: invoice_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Invoice:
      type: object
      required:
        - id
        - version
        - type
        - status
        - series
        - number
        - issue_date
        - due_date
        - customer_id
        - customer_name
        - customer_tax_id
        - lines
        - subtotal
        - vat_amount
        - irpf_rate
        - irpf_amount
        - total
        - currency
        - notes
        - verifactu_status
        - fiscal_network
        - tax_label
        - pdf_ready
        - payment_link
        - payment_link_status
        - payment_link_error
        - email_delivery_status
        - email_delivery_error
        - sent_at
        - paid_at
        - corrects_invoice_id
        - activity_id
        - outstanding
        - collections
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        version:
          type: string
          description: >-
            A fingerprint of the invoice's fiscal content. Issuing and voiding
            take the exact `version` you read.
        type:
          type: string
          enum:
            - standard
            - proforma
            - corrective
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        series:
          type:
            - string
            - 'null'
          description: >-
            Set at issue. The issue year, such as `2026`, unless the company set
            its own series; `R-` before it for a corrective invoice.
        number:
          type:
            - integer
            - 'null'
          description: Set at issue, the next in the series.
        issue_date:
          type: string
          format: date
        due_date:
          type:
            - string
            - 'null'
          format: date
        customer_id:
          type: string
          format: uuid
        customer_name:
          type: string
          description: The customer's name when the invoice was drafted.
        customer_tax_id:
          type: string
          description: The customer's tax ID when the invoice was drafted.
        lines:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLine'
        subtotal:
          $ref: '#/components/schemas/Amount'
        vat_amount:
          $ref: '#/components/schemas/Amount'
        irpf_rate:
          $ref: '#/components/schemas/Decimal'
        irpf_amount:
          $ref: '#/components/schemas/Amount'
        total:
          $ref: '#/components/schemas/Amount'
          description: What the invoice charges, IRPF withheld already taken off.
        currency:
          type: string
          const: EUR
        notes:
          type: string
        verifactu_status:
          type: string
          enum:
            - pending
            - registered
            - error
            - none
          description: >
            The AEAT's answer to the invoice's VERI*FACTU record: `pending`
            until

            it answers (and on a draft), `registered` once it accepted it,

            `error` if it refused it, the invoice keeping its number. `none` for

            an invoice issued without VERI*FACTU, as the Melso app issues before

            the owner authorizes a certificate.
        fiscal_network:
          type: string
          enum:
            - verifactu
            - ''
          description: >
            `verifactu` for an invoice issued through VERI*FACTU, or a draft
            that

            would go there. Empty for an invoice issued without it.
        tax_label:
          type: string
          enum:
            - IVA
            - IGIC
          description: '`IGIC` for a company in the Canary Islands.'
        pdf_ready:
          type: boolean
          description: The legal PDF is stored. Download it with Download the invoice PDF.
        payment_link:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The invoice's payment link, when the owner has connected a Stripe
            account.
        payment_link_status:
          type: string
          enum:
            - pending
            - creating
            - active
            - inactive
            - error
            - unknown
          description: >-
            `inactive` once Melso switched the link off, as when the invoice is
            paid or voided.
        payment_link_error:
          type:
            - string
            - 'null'
        email_delivery_status:
          type: string
          enum:
            - pending
            - sending
            - sent
            - error
            - unknown
          description: >
            The email of the issued invoice to the customer. `error` when it
            could

            not go out, such as a customer without an email. `unknown` when the

            answer was lost and the email may have reached the customer.
        email_delivery_error:
          type:
            - string
            - 'null'
        sent_at:
          type:
            - string
            - 'null'
          format: date-time
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When it was first marked paid.
        corrects_invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          description: On a corrective invoice, the invoice it corrects.
        activity_id:
          type:
            - string
            - 'null'
          format: uuid
        outstanding:
          $ref: '#/components/schemas/Amount'
          description: >-
            What an issued or sent invoice still owes after the bank movements
            reconciled with it. `0.00` for any other status.
        collections:
          type: array
          description: >-
            The bank movements reconciled with the invoice. Empty except on Get
            an invoice and Mark an invoice as paid.
          items:
            $ref: '#/components/schemas/InvoiceCollection'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    InvoiceStatus:
      type: string
      enum:
        - draft
        - issued
        - sent
        - paid
        - void
      description: |
        `draft` until it is issued; `issued` once numbered; `sent` once emailed
        to the customer; `paid` once marked paid; `void` once voided.
    InvoiceLine:
      type: object
      properties:
        description:
          type: string
        quantity:
          $ref: '#/components/schemas/Decimal'
        unit_price:
          $ref: '#/components/schemas/Decimal'
        vat_rate:
          $ref: '#/components/schemas/Decimal'
        product_kind:
          type: string
          enum:
            - goods
            - services
          description: Absent when the line has none.
        amount:
          $ref: '#/components/schemas/Amount'
    Amount:
      type: string
      pattern: ^-?[0-9]+\.[0-9]{2}$
      description: >-
        An amount in euros as a decimal string with two decimals, such as
        `"121.00"`.
      examples:
        - '121.00'
    Decimal:
      type: string
      pattern: ^-?[0-9]{1,10}(\.[0-9]{1,6})?$
      description: A decimal number as a string, such as `"21"` or `"0.5"`.
    InvoiceCollection:
      type: object
      required:
        - date
        - amount
        - movement_id
      properties:
        date:
          type: string
          format: date
        amount:
          $ref: '#/components/schemas/Decimal'
          description: What this bank movement settled of the invoice.
        movement_id:
          type: string
          format: uuid
    Error:
      type: object
      required:
        - error
        - code
        - request_id
      properties:
        error:
          type: string
          description: What went wrong, for a person to read.
        code:
          type: string
          description: >-
            A stable code to branch on, such as `invoicing_not_ready` or
            `version_conflict`.
        request_id:
          type: string
          description: >-
            The same value as the `X-Request-Id` header. Quote it when you
            contact Melso.
        field:
          type: string
          description: The field, query parameter or header at fault, when there is one.
        next_action:
          type: string
          description: >-
            A stable hint of what to do next, such as `review_plan`, when the
            operation gives one.
        payment_url:
          type: string
          format: uri
          description: >-
            Where the company's owner pays its plan, on `plan_required` when its
            plan is unpaid.
  responses:
    BadRequest:
      description: |
        The request is malformed or a field is invalid. Unknown body fields and
        query parameters are refused too, with `field` naming them where it can.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_invoice:
              summary: A field the invoice cannot take
              value:
                error: vat_rate must be 21, 10, 4 or 0 (exempt)
                code: invalid_invoice
                next_action: review_request
                request_id: req_8f14e45fceea167a5a36dedd
            unknown_field:
              summary: A field the operation does not take
              value:
                error: Unknown field iban
                code: invalid_arguments
                field: iban
                request_id: req_8f14e45fceea167a5a36dedd
    Unauthorized:
      description: |
        The key is missing, revoked or invalid (`invalid_api_key`), or it is a
        test key, which Melso does not issue (`test_keys_unavailable`).
      headers:
        WWW-Authenticate:
          description: '`Bearer realm="api.melso.ai"` on `invalid_api_key`.'
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: The API key is missing, revoked or invalid
            code: invalid_api_key
            request_id: req_8f14e45fceea167a5a36dedd
    PaymentRequired:
      description: |
        The company's plan does not cover this write (`plan_required`): its plan
        is unpaid, and `payment_url` is where its owner pays it, or the plan's
        invoice allowance is used up. An autónomo whose plan lacks Melso's
        tools gets `paid_manual_tools_required`. Reads keep working.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: >-
              invoices issue needs the company's plan, which is not paid: its
              records stay readable, and the owner pays the plan at
              https://app.melso.ai/setup?workspace_id=00000000-0000-4000-8000-000000000001.
            code: plan_required
            next_action: review_plan
            payment_url: >-
              https://app.melso.ai/setup?workspace_id=00000000-0000-4000-8000-000000000001
            request_id: req_8f14e45fceea167a5a36dedd
    Forbidden:
      description: |
        Refused in this company: the operation is not available in it, such as
        invoices before its VERI*FACTU set-up (`tool_unavailable`); an
        autónomo's setup in Melso is pending (`onboarding_required`); or the
        key's creator lacks the role the operation needs, such as the owner's
        for issuing (`forbidden`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invoices is not available in this company
            code: tool_unavailable
            next_action: check_company_and_access
            request_id: req_8f14e45fceea167a5a36dedd
    NotFound:
      description: >-
        No such object in this company, or `company_id` is not the key's
        company.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invoice not found
            code: not_found
            next_action: refresh_record
            request_id: req_8f14e45fceea167a5a36dedd
    Conflict:
      description: |
        The object changed or is not in a state that allows this: read it again
        and decide. Also the first request with this `Idempotency-Key` still
        running (`idempotency_key_in_use`, with `Retry-After: 1`).
      headers:
        Retry-After:
          description: Seconds to wait, on `idempotency_key_in_use`.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'invoice changed: review the current draft'
            code: version_conflict
            field: expected_version
            next_action: refresh_and_request_authorization
            request_id: req_8f14e45fceea167a5a36dedd
    RateLimited:
      description: >-
        The key made more than 600 requests in a minute. Wait `Retry-After`
        seconds.
      headers:
        Retry-After:
          description: Seconds to wait, `60`.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Too many requests: a key makes at most 600 a minute'
            code: rate_limited
            request_id: req_8f14e45fceea167a5a36dedd
  securitySchemes:
    companyApiKey:
      type: http
      scheme: bearer
      description: |
        A company API key, `mk_live_…`, that the company's owner creates in the
        Melso app under Settings, Connect your AI, API keys. It works in that
        one company with the owner's authority. Test keys (`mk_test_…`) are not
        issued. Keep the key on your servers. See
        [Authentication](/api/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.