es__get_face_invoice_status

Instructions

Implementation Reference

• mcp_facturacion_electronica_es/tools/facturae.py:496-545 (handler)

  The handler function that executes the es__get_face_invoice_status tool logic. Retrieves OAuth2 config from env vars (FACE_CLIENT_ID, FACE_CLIENT_SECRET, FACE_ENV), instantiates a BaseEInvoicingClient, makes a GET request to /facturas/{invoice_id}, and maps FACe status codes (1200=Registrada, 2400=Reconocida, 3100=Rechazada, 4100=Pagada).

  async def handle_es_get_face_invoice_status(
      arguments: dict[str, Any],
  ) -> list[types.TextContent]:
      try:
          from mcp_einvoicing_core.http_client import AuthMode, BaseEInvoicingClient, OAuthConfig
  
          invoice_id = arguments.get("invoice_id", "")
          if not invoice_id:
              return err("invoice_id is required", "MISSING_PARAM")
  
          client_id = os.environ.get("FACE_CLIENT_ID", "")
          client_secret = os.environ.get("FACE_CLIENT_SECRET", "")
          if not client_id or not client_secret:
              return err("FACE_CLIENT_ID y FACE_CLIENT_SECRET son obligatorios.", "MISSING_CONFIG")
  
          env = face_env()
          base_url = FACE_BASE_URLS[env]
          oauth_cfg = OAuthConfig(
              token_url=f"{base_url}/oauth/token",
              client_id=client_id,
              client_secret=client_secret,
          )
          client = BaseEInvoicingClient(
              base_url=base_url,
              auth_mode=AuthMode.OAUTH2_CLIENT_CREDENTIALS,
              oauth_config=oauth_cfg,
          )
  
          response = await client._request("GET", f"/facturas/{invoice_id}")
          body = response.json() if response.headers.get("content-type", "").startswith("application/json") else {"raw": response.text}
  
          # Map known FACe status codes
          status_codes = {
              "1200": "Registrada",
              "2400": "Reconocida por la unidad tramitadora",
              "3100": "Rechazada",
              "4100": "Pagada",
          }
          raw_status = str(body.get("codigo", body.get("status", "")))
          return ok({
              "invoice_id": invoice_id,
              "status_code": raw_status,
              "status_description": status_codes.get(raw_status, "Desconocido"),
              "environment": env,
              "response": body,
          })
  
      except Exception as exc:
          logger.exception("es__get_face_invoice_status failed")
          return err(str(exc))

• mcp_facturacion_electronica_es/tools/facturae.py:311-324 (schema)

  The Tool definition (schema) for es__get_face_invoice_status. Declares inputSchema requiring invoice_id (string). Description explains it consults the FACe invoice processing status with known status codes.

  TOOL_ES_GET_FACE_INVOICE_STATUS = types.Tool(
      name="es__get_face_invoice_status",
      description=(
          "Consulta el estado de tramitación de una factura en FACe. "
          "Códigos: 1200 Registrada, 2400 Reconocida, 3100 Rechazada, 4100 Pagada."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "invoice_id": {"type": "string", "description": "Número de registro FACe."},
          },
          "required": ["invoice_id"],
      },
  )

• mcp_facturacion_electronica_es/server.py:119-119 (registration)

  Registration of the tool in the _TOOL_HANDLERS dict, mapping name 'es__get_face_invoice_status' to handle_es_get_face_invoice_status.

  "es__get_face_invoice_status":        handle_es_get_face_invoice_status,

• mcp_facturacion_electronica_es/server.py:88-88 (registration)

  The Tool object imported and registered in the server's tools list (TOOL_ES_GET_FACE_INVOICE_STATUS).

  TOOL_ES_GET_FACE_INVOICE_STATUS,

• mcp_facturacion_electronica_es/_helpers.py:157-161 (helper)

  FACe base URLs for sandbox and production environments, used by the handler to determine the API endpoint.

  FACE_BASE_URLS: dict[str, str] = {
      "sandbox": "https://se-face.redsara.es/factura-face-b2b-api/api/v2",
      "production": "https://face.gob.es/factura-face-b2b-api/api/v2",
      # [NEED: verify — FACe may have changed API base path in 2025]
  }