Consultar facturas Verifactu — invoices_read MCP

Read-only actions. Read invoices and prepare unnumbered drafts or corrections. issue submits the exact saved version when the owner asks, through their external OAuth connection, with paid tools and verified supplier authority. Pass the version from get as expected_version. A reserved number or pending provider is not confirmed registration; inspect verifactu_status, pdf_ready and delivery state. Configured payment-link creation and email delivery may follow registration. Retry only the same invoice and version after an uncertain response. request_approval offers web review instead. No action approves, files or pays a tax return. Each action accepts only its own fields (* required): get(id*); request_approval(id*); list(contact_id, cursor, document_number, due_date_end, due_date_start, end_date, limit, q, sort, start_date, status). Availability: Autónomo / Empresa. Access: Live in the Melso app and over MCP for a signed-in person. Where the partner REST API covers the same area, that path is private beta until Melso enables your account. See Access and pricing. Without a plan that includes the tools, only the read actions are listed: get, list. The live tool list is authoritative: the company’s plan and your role can narrow this contract. Understand access.

When to use

Use invoices_read for get, list, request_approval. Use invoices for the companion actions. The live tool list determines availability.

Input

{
  "additionalProperties": false,
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "get"
        },
        "id": {
          "description": "Invoice UUID in this company.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "request_approval"
        },
        "id": {
          "description": "Invoice UUID in this company.",
          "type": "string"
        }
      },
      "required": [
        "action",
        "id"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "action": {
          "const": "list"
        },
        "contact_id": {
          "description": "Customer or supplier contact UUID from contacts_read; includes its merged identities.",
          "type": "string"
        },
        "cursor": {
          "description": "Opaque next_cursor from the previous page; keep every filter and sort unchanged.",
          "type": "string"
        },
        "document_number": {
          "description": "Literal substring of the document number, case insensitive.",
          "type": "string"
        },
        "due_date_end": {
          "description": "Inclusive due-date upper bound, YYYY-MM-DD.",
          "type": "string"
        },
        "due_date_start": {
          "description": "Inclusive due-date lower bound, YYYY-MM-DD.",
          "type": "string"
        },
        "end_date": {
          "description": "Inclusive issue/expense date upper bound, YYYY-MM-DD.",
          "type": "string"
        },
        "limit": {
          "default": 50,
          "maximum": 200,
          "minimum": 1,
          "type": "integer"
        },
        "q": {
          "description": "Literal words of the counterparty name, tax ID or document number.",
          "type": "string"
        },
        "sort": {
          "default": "-date",
          "enum": [
            "date",
            "-date",
            "due_date",
            "-due_date",
            "total",
            "-total"
          ],
          "type": "string"
        },
        "start_date": {
          "description": "Inclusive issue/expense date lower bound, YYYY-MM-DD.",
          "type": "string"
        },
        "status": {
          "description": "pending: no payment; partial: partly paid; completed: settled; outstanding: positive balance excluding drafts; overdue: outstanding and due before today in Europe/Madrid. Expense due dates come from saved maturities. Balances include recorded reconciliations; they do not confirm a bank transfer.",
          "enum": [
            "pending",
            "partial",
            "completed",
            "outstanding",
            "overdue"
          ],
          "type": "string"
        }
      },
      "required": [
        "action"
      ],
      "type": "object"
    }
  ],
  "properties": {
    "action": {
      "enum": [
        "get",
        "request_approval",
        "list"
      ],
      "type": "string"
    },
    "contact_id": {
      "description": "Customer or supplier contact UUID from contacts_read; includes its merged identities.",
      "type": "string"
    },
    "cursor": {
      "description": "Opaque next_cursor from the previous page; keep every filter and sort unchanged.",
      "type": "string"
    },
    "document_number": {
      "description": "Literal substring of the document number, case insensitive.",
      "type": "string"
    },
    "due_date_end": {
      "description": "Inclusive due-date upper bound, YYYY-MM-DD.",
      "type": "string"
    },
    "due_date_start": {
      "description": "Inclusive due-date lower bound, YYYY-MM-DD.",
      "type": "string"
    },
    "end_date": {
      "description": "Inclusive issue/expense date upper bound, YYYY-MM-DD.",
      "type": "string"
    },
    "id": {
      "description": "Invoice UUID in this company.",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    },
    "q": {
      "description": "Literal words of the counterparty name, tax ID or document number.",
      "type": "string"
    },
    "sort": {
      "default": "-date",
      "enum": [
        "date",
        "-date",
        "due_date",
        "-due_date",
        "total",
        "-total"
      ],
      "type": "string"
    },
    "start_date": {
      "description": "Inclusive issue/expense date lower bound, YYYY-MM-DD.",
      "type": "string"
    },
    "status": {
      "description": "pending: no payment; partial: partly paid; completed: settled; outstanding: positive balance excluding drafts; overdue: outstanding and due before today in Europe/Madrid. Expense due dates come from saved maturities. Balances include recorded reconciliations; they do not confirm a bank transfer.",
      "enum": [
        "pending",
        "partial",
        "completed",
        "outstanding",
        "overdue"
      ],
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "type": "object"
}

Actions

The tool’s schema combines the fields of every action. Each action accepts only its own fields below; send action with them.

Read actions

These actions only read. They change nothing.

get

Read one of the company’s invoices including its current reviewed-content version and totals.

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Invoice UUID in this company.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

list

List this company’s local invoice summaries with settlement balances. Follow next_cursor while has_more; keep filters unchanged. The invoice record holds the legal registration and PDF.

{
  "additionalProperties": false,
  "properties": {
    "contact_id": {
      "description": "Customer or supplier contact UUID from contacts_read; includes its merged identities.",
      "type": "string"
    },
    "cursor": {
      "description": "Opaque next_cursor from the previous page; keep every filter and sort unchanged.",
      "type": "string"
    },
    "document_number": {
      "description": "Literal substring of the document number, case insensitive.",
      "type": "string"
    },
    "due_date_end": {
      "description": "Inclusive due-date upper bound, YYYY-MM-DD.",
      "type": "string"
    },
    "due_date_start": {
      "description": "Inclusive due-date lower bound, YYYY-MM-DD.",
      "type": "string"
    },
    "end_date": {
      "description": "Inclusive issue/expense date upper bound, YYYY-MM-DD.",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 200,
      "minimum": 1,
      "type": "integer"
    },
    "q": {
      "description": "Literal words of the counterparty name, tax ID or document number.",
      "type": "string"
    },
    "sort": {
      "default": "-date",
      "enum": [
        "date",
        "-date",
        "due_date",
        "-due_date",
        "total",
        "-total"
      ],
      "type": "string"
    },
    "start_date": {
      "description": "Inclusive issue/expense date lower bound, YYYY-MM-DD.",
      "type": "string"
    },
    "status": {
      "description": "pending: no payment; partial: partly paid; completed: settled; outstanding: positive balance excluding drafts; overdue: outstanding and due before today in Europe/Madrid. Expense due dates come from saved maturities. Balances include recorded reconciliations; they do not confirm a bank transfer.",
      "enum": [
        "pending",
        "partial",
        "completed",
        "outstanding",
        "overdue"
      ],
      "type": "string"
    }
  },
  "type": "object"
}

request_approval

Read the draft preview and return Emitir/Cambiar actions for authenticated web review. Present the preview and approval URL when the person prefers reviewing in Melso. This action does not issue the invoice; the owner’s external OAuth connection can issue its exact version with issue.

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Invoice UUID in this company.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "type": "object"
}

Output

list and get return invoices with their totals and status. request_approval returns the saved preview and the signed-in page where the owner issues the exact version. The result uses MCP content blocks; JSON payloads are encoded in text and may also appear in structuredContent. Check isError before reading a success payload. When the server declares an outputSchema, it is reproduced below. Check the action result and its declared fields before reporting success.

Declared output schema

{
  "anyOf": [
    {
      "properties": {
        "corrects_invoice_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "currency": {
          "type": "string"
        },
        "customer_id": {
          "type": "string"
        },
        "customer_name": {
          "type": "string"
        },
        "customer_tax_id": {
          "type": "string"
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "email_delivery_error": {
          "type": [
            "string",
            "null"
          ]
        },
        "email_delivery_status": {
          "type": "string"
        },
        "fiscal_network": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "irpf_amount": {
          "type": "string"
        },
        "irpf_rate": {
          "type": "string"
        },
        "issue_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "lines": {
          "items": {
            "properties": {
              "description": {
                "type": "string"
              },
              "quantity": {
                "type": "string"
              },
              "unit_price": {
                "type": "string"
              },
              "vat_rate": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "notes": {
          "type": "string"
        },
        "number": {
          "type": [
            "integer",
            "null"
          ]
        },
        "paid_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_link": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_link_error": {
          "type": [
            "string",
            "null"
          ]
        },
        "payment_link_status": {
          "type": "string"
        },
        "pdf_ready": {
          "type": "boolean"
        },
        "sent_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "series": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "subtotal": {
          "type": "string"
        },
        "tax_label": {
          "type": "string"
        },
        "total": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "vat_amount": {
          "type": "string"
        },
        "verifactu_status": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "version",
        "status",
        "total",
        "verifactu_status",
        "pdf_ready",
        "email_delivery_status"
      ],
      "type": "object"
    },
    {
      "properties": {
        "approval_required": {
          "type": "boolean"
        },
        "approval_url": {
          "type": "string"
        },
        "invoice": {
          "properties": {
            "corrects_invoice_id": {
              "type": [
                "string",
                "null"
              ]
            },
            "created_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "currency": {
              "type": "string"
            },
            "customer_id": {
              "type": "string"
            },
            "customer_name": {
              "type": "string"
            },
            "customer_tax_id": {
              "type": "string"
            },
            "due_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "email_delivery_error": {
              "type": [
                "string",
                "null"
              ]
            },
            "email_delivery_status": {
              "type": "string"
            },
            "fiscal_network": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "irpf_amount": {
              "type": "string"
            },
            "irpf_rate": {
              "type": "string"
            },
            "issue_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "lines": {
              "items": {
                "properties": {
                  "description": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "string"
                  },
                  "unit_price": {
                    "type": "string"
                  },
                  "vat_rate": {
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "type": "array"
            },
            "notes": {
              "type": "string"
            },
            "number": {
              "type": [
                "integer",
                "null"
              ]
            },
            "paid_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "payment_link": {
              "type": [
                "string",
                "null"
              ]
            },
            "payment_link_error": {
              "type": [
                "string",
                "null"
              ]
            },
            "payment_link_status": {
              "type": "string"
            },
            "pdf_ready": {
              "type": "boolean"
            },
            "sent_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "series": {
              "type": [
                "string",
                "null"
              ]
            },
            "status": {
              "type": "string"
            },
            "subtotal": {
              "type": "string"
            },
            "tax_label": {
              "type": "string"
            },
            "total": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "updated_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "vat_amount": {
              "type": "string"
            },
            "verifactu_status": {
              "type": "string"
            },
            "version": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "version",
            "status",
            "total",
            "verifactu_status",
            "pdf_ready",
            "email_delivery_status"
          ],
          "type": "object"
        }
      },
      "required": [
        "invoice",
        "approval_required",
        "approval_url"
      ],
      "type": "object"
    },
    {
      "properties": {
        "has_more": {
          "type": "boolean"
        },
        "invoices": {
          "items": {
            "properties": {
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "date": {
                "type": "string"
              },
              "deductible": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "document_number": {
                "type": "string"
              },
              "due_date": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "id": {
                "type": "string"
              },
              "party": {
                "type": "string"
              },
              "payment_status": {
                "type": "string"
              },
              "payments_pending": {
                "type": "string"
              },
              "payments_total": {
                "type": "string"
              },
              "total": {
                "type": "string"
              },
              "version": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "date",
              "party",
              "total",
              "payments_total",
              "payments_pending",
              "payment_status"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "invoices",
        "has_more",
        "next_cursor"
      ],
      "type": "object"
    }
  ],
  "type": "object"
}

Example

Use the actions of this tool in the order shown; its companion tool covers the other actions. These are the arguments of each call, in order.

Get the approval page for that draft

{
  "action": "request_approval",
  "id": "11111111-1111-4111-8111-111111111111"
}

Read it again later to see whether it was issued

{
  "action": "get",
  "id": "11111111-1111-4111-8111-111111111111"
}

The first call as a request. Use an OAuth access token issued for this MCP resource and replace the example identifiers with values from your own company.

curl --fail-with-body https://mcp.melso.ai/mcp \
  -H "Authorization: Bearer $MELSO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data-binary @- <<'JSON'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "invoices_read",
    "arguments": {
      "action": "request_approval",
      "id": "11111111-1111-4111-8111-111111111111"
    }
  }
}
JSON

Connect

Clients

Use

Reference

Tools

Consultar facturas Verifactu — invoices_read MCP

When to use

Input

Actions

Read actions

Output

Declared output schema

Example

​When to use

​Input

​Actions

​Read actions

​Output

​Declared output schema

​Example

When to use

Input

Actions

Read actions

Output

Declared output schema

Example