jithox-com Iban API

openapi: 3.2.0
info:
  title: Jithox REST — invoice checks for a backend Iban API
  version: 1.2.0
  summary: EU VAT numbers (VIES), Peppol receivers and IBANs, checked from a backend with a connection credential a person creates.
  description: 'A person creates a Jithox connection at https://jithox.com/mcp/account#connection and gives its secret (jxc_live_…) to the backend, which sends it as a Bearer token on every route except POST /api/invoice/review. POST /api/v1/vat/verify checks EU VAT numbers against VIES. Price: 1 credits (EUR 0.01) per row VIES answered (valid or invalid), charged once per delivery from the workspace''s prepaid credits; credits are added at https://jithox.com/plan. New workspaces get 100 free VAT checks against the EU VIES register, once per workspace, no card. They pay for VAT checks on the REST API and on the Jithox MCP at https://jithox.com/api/mcp, not for the E-Invoice server''s tools. Granted when the workspace creates a connection and has had no trial before, within a limit per network and per day. Bought credits are spent first. A company lookup by VAT number on the Jithox MCP uses 2 of the 100. Without a trial, or once it is used up, the normal 402 applies. A row VIES did not answer (unavailable), a malformed or duplicate number, or a number VIES does not cover costs nothing. The answer carries the ledger booking id (billing.receiptRunId), which is not a signed receipt; no signed or hash-bound receipt is returned. With the optional requesterVatId (your own EU VAT number), a valid row also carries the European Commission''s consultation number for that lookup — the Commission''s record that it took place, not a receipt from Jithox. Not legal or tax advice: VIES states whether a number is registered for intra-EU trade at the moment it answered. The other routes are the MCP tools of the same name over plain HTTP, with the same answer: POST /api/v1/peppol/participant (lookup_peppol_participant, free); POST /api/v1/iban/verify (verify_iban, free); POST /api/v1/payment/preflight (preflight_payment, free). POST /api/invoice/review checks one invoice before it is sent or paid; it is free and needs no credential. No route returns a signed or hash-bound payment receipt. With a signing key configured, POST /api/v1/payment/preflight also return `evidence`: a signed statement of the verdict and the checks (Ed25519 compact JWS), verifiable offline against https://jithox.com/.well-known/jwks.json or at https://jithox.com/api/v1/evidence/verify. It proves what Jithox decided, not that the decision is right.'
  contact:
    url: https://jithox.com/rest-api
servers:
- url: https://jithox.com
tags:
- name: Iban
paths:
  /api/v1/iban/verify:
    post:
      operationId: verifyIban
      summary: Check an IBAN's structure and check digits (ISO 13616, ISO 7064), offline
      description: 'The verify_iban MCP tool over plain HTTP: the same code, the same answer. Offline arithmetic for the countries in the IBAN registry — no network, no bank is asked. It never says the account exists, is open or belongs to the party being paid; every answer carries doesNotProve. Source: Offline: the IBAN registry''s country formats and ISO 7064 MOD-97-10. No bank or register is asked. Price: Free. Always free: offline arithmetic with no provider cost. It still needs a connection key, so every call has a known caller.'
      security:
      - jithoxConnection: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyIbanRequest'
            example:
              iban: BE68 5390 0754 7034
      responses:
        '200':
          description: The check ran. Branch on data.status (valid / invalid / unknown).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyIbanResponse'
        '400':
          description: The body is not a JSON object, or the check refused the input. Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyIbanRefusal'
        '401':
          description: No credential, or not an active connection (unknown, revoked, expired). Nothing ran; nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          headers:
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer realm="jithox-connection"
        '413':
          description: A body over 16384 bytes. Nothing ran; nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestTooLarge'
        '429':
          description: Too many requests for this workspace. Nothing ran; nothing was charged.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimited'
        '503':
          description: The connection store is not answering, so the credential cannot be checked. Nothing ran; nothing was charged.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreUnavailable'
      x-jithox-mcp-tool: verify_iban
      x-jithox-pricing:
        tool: verify_iban
        unit: call
        pricePerUnitCredits: 0
        pricePerUnitEur: EUR 0.00
        freeWhen: 'Always free: offline arithmetic with no provider cost. It still needs a connection key, so every call has a known caller.'
        source: TOOL_PRICE_CREDITS.verify_iban — the same price the verify_iban MCP tool charges on /api/mcp.
      tags:
      - Iban
components:
  schemas:
    RestTooLarge:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              const: request_too_large
            message:
              type: string
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    VerifyIbanOutput:
      type: object
      properties:
        status:
          enum:
          - valid
          - invalid
          - unknown
          description: 'The one word to branch on. valid: structure and check digits are right. invalid: they are not. unknown: the country is not in the registry this check uses — nothing either way, never a failure.'
        reason:
          enum:
          - empty
          - charset
          - format
          - length
          - structure
          - check_digits
          - country_not_in_registry
          - null
          description: Why not valid; null when valid.
        iban:
          type:
          - string
          - 'null'
          description: The IBAN in groups of four, as printed; null when nothing usable was read.
        countryCode:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
          description: The registry's country name.
        bankIdentifier:
          type:
          - string
          - 'null'
          description: The national bank identifier, where the registry defines its position.
        detail:
          type: string
          description: One sentence, safe to show a customer.
        countryMatches:
          type: boolean
          description: 'Only when expectedCountry was sent: whether the account is issued in that country. An observation, not a fraud verdict.'
        proves:
          type: string
        doesNotProve:
          type: string
      required:
      - status
      - reason
      - iban
      - countryCode
      - country
      - bankIdentifier
      - detail
      - proves
      - doesNotProve
      additionalProperties: false
    VerifyIbanResponse:
      type: object
      description: Field for field the payload the verify_iban MCP tool returns on /api/mcp.
      properties:
        kind:
          const: iban_verification
        data:
          $ref: '#/components/schemas/VerifyIbanOutput'
      required:
      - kind
      - data
      additionalProperties: false
    VerifyIbanRefusal:
      type: object
      description: The request could not be judged. The check's own refusals are the MCP tool's error, unchanged.
      properties:
        error:
          type: object
          properties:
            code:
              enum:
              - bad_request
              - invalid_iban_input
            message:
              type: string
            status:
              const: 400
            issues:
              type: array
              items:
                type: string
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    StoreUnavailable:
      type: object
      properties:
        ok:
          const: false
        error:
          type: object
          properties:
            code:
              const: connection_store_unavailable
            message:
              type: string
          required:
          - code
          - message
          additionalProperties: false
      required:
      - ok
      - error
      additionalProperties: false
    VerifyIbanRequest:
      type: object
      properties:
        iban:
          type: string
          minLength: 1
          maxLength: 64
          description: The account number to check, as written — spaces and dashes are fine, e.g. "BE68 5390 0754 7034".
        expectedCountry:
          description: Optional ISO 3166-1 alpha-2 country of the party being paid. When given, the answer reports whether the account is issued in that country — as an observation with both countries named, never as a fraud verdict.
          type: string
          minLength: 2
          maxLength: 2
      required:
      - iban
    Unauthorized:
      type: object
      properties:
        ok:
          const: false
        error:
          type: object
          properties:
            code:
              const: unauthorized
            reason:
              enum:
              - missing_credential
              - invalid_credential
            message:
              type: string
          required:
          - code
          - reason
          - message
          additionalProperties: false
        authorization:
          type: object
          properties:
            scheme:
              const: Bearer
            credentialPrefix:
              const: jxc_live_
            createAt:
              const: https://jithox.com/mcp/account#connection
              description: Where a person creates (and revokes) the credential.
            howToCreate:
              type: string
          required:
          - scheme
          - credentialPrefix
          - createAt
          - howToCreate
          additionalProperties: false
      required:
      - ok
      - error
      - authorization
      additionalProperties: false
    RateLimited:
      type: object
      description: The shared rate limiter's answer. See the Retry-After header.
      properties:
        error:
          const: rate_limited
        retryAfterSeconds:
          type: integer
          minimum: 0
      required:
      - error
      - retryAfterSeconds
      additionalProperties: false
  securitySchemes:
    jithoxConnection:
      type: http
      scheme: bearer
      description: A Jithox connection secret (jxc_live_…). A person signs in at https://jithox.com/mcp/account#connection, creates a connection and copies the secret (shown once); the same page revokes it. It bills that person's workspace.