jithox-com Peppol API

openapi: 3.2.0
info:
  title: Jithox REST — invoice checks for a backend Peppol 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: Peppol
paths:
  /api/v1/peppol/participant:
    post:
      operationId: lookupPeppolParticipant
      summary: Can this customer receive a Peppol e-invoice today, and if the send still…
      description: 'The lookup_peppol_participant MCP tool over plain HTTP: the same code, the same answer. Asks the live Peppol registers about a THIRD PARTY — the public directory, the lookup the network uses today and the lookup Peppol retired — and says who to call when a send still fails. A register that did not answer gives unknown, never no. It is not a promise that an invoice will arrive, be accepted or be paid; every answer carries doesNotProve. Source: Live: the Peppol Directory (directory.peppol.eu), the Peppol SML over DNS (current U-NAPTR and retired CNAME) and the receiver''s SMP. Price: Free. Always free: the Peppol registers are public and keyless. 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/LookupPeppolParticipantRequest'
            example:
              identifier: BE 0403.170.701
      responses:
        '200':
          description: The check ran. Branch on data.reachable (yes / no / unknown).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupPeppolParticipantResponse'
        '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/LookupPeppolParticipantRefusal'
        '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: lookup_peppol_participant
      x-jithox-pricing:
        tool: lookup_peppol_participant
        unit: call
        pricePerUnitCredits: 0
        pricePerUnitEur: EUR 0.00
        freeWhen: 'Always free: the Peppol registers are public and keyless. It still needs a connection key, so every call has a known caller.'
        source: TOOL_PRICE_CREDITS.lookup_peppol_participant — the same price the lookup_peppol_participant MCP tool charges on /api/mcp.
      tags:
      - Peppol
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
    LookupPeppolParticipantResponse:
      type: object
      description: Field for field the payload the lookup_peppol_participant MCP tool returns on /api/mcp.
      properties:
        kind:
          const: peppol_participant_lookup
        data:
          $ref: '#/components/schemas/LookupPeppolParticipantOutput'
      required:
      - kind
      - data
      additionalProperties: false
    LookupPeppolParticipantRefusal:
      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_peppol_participant_input
              - peppol_participant_empty
              - peppol_participant_too_long
              - peppol_participant_bad_characters
              - peppol_participant_unsupported_scheme
              - peppol_participant_checksum_failed
              - peppol_participant_wrong_length_for_scheme
            message:
              type: string
            status:
              const: 400
            issues:
              type: array
              items:
                type: string
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    LookupPeppolParticipantRequest:
      type: object
      properties:
        identifier:
          type: string
          minLength: 1
          maxLength: 60
          description: Enterprise/VAT number ("BE 0403.170.701" or "0403170701"), <scheme>:<id>, or iso6523-actorid-upis::<scheme>:<id>. Accepts the known EAS schemes, including 0208 (BE enterprise), 9925 (BE VAT), 0192 (NO organisation) and 0088 (GLN). Spaces/dots are removed; the ISO prefix is case-insensitive. A bare id uses the separate scheme, or defaults to 0208. If both schemes are given they must match.
        scheme:
          description: 'The four-digit Peppol scheme the number is registered under, when you know it: "0208" for a Belgian enterprise number (the mandatory primary scheme for Belgian businesses), "9925" for a Belgian VAT number, "0192" for a Norwegian organisation number. Left out, a Belgian enterprise number is assumed.'
          type: string
          maxLength: 10
      required:
      - identifier
    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
    LookupPeppolParticipantOutput:
      type: object
      properties:
        schemaVersion:
          const: jx.peppol-receiver-check/v1
        participantId:
          type: string
          description: The identifier looked up, as <scheme>:<value>.
        endpointId:
          type: string
          description: 'The literal UBL EndpointID value: participantId after its first '':''. Goes into customer.endpointId of check_peppol_ready as it is.'
        endpointScheme:
          type: string
          description: 'The scheme: participantId before its first '':''. Goes into customer.endpointScheme of check_peppol_ready.'
        reachable:
          enum:
          - 'yes'
          - 'no'
          - unknown
          description: 'The one word to branch on. yes: the network knows where to deliver. no: neither lookup finds the receiver. unknown: a register did not answer — never folded into no.'
        documentTypes:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              profile:
                type: string
              document:
                type: string
              raw:
                type: string
                description: The identifier exactly as the SMP published it.
            required:
            - profile
            - document
            - raw
            additionalProperties: false
          description: What the receiver's access point says it accepts; null when that could not be read (unknown, never an empty list).
        acceptsBis30Invoice:
          type:
          - boolean
          - 'null'
        smpHost:
          type:
          - string
          - 'null'
        lookups:
          type: object
          properties:
            addressBook:
              enum:
              - listed
              - not_listed
              - unknown
            currentMethod:
              enum:
              - found
              - absent
              - unknown
            retiredMethod:
              enum:
              - found
              - absent
              - unknown
          required:
          - addressBook
          - currentMethod
          - retiredMethod
          additionalProperties: false
        ifItStillFails:
          type: object
          description: Whose problem it is when the send still fails.
          properties:
            blame:
              enum:
              - receiver
              - sender_software
              - not_determinable
            explanation:
              type: string
          required:
          - blame
          - explanation
          additionalProperties: false
        summary:
          type: string
        doesNotProve:
          type: string
      required:
      - schemaVersion
      - participantId
      - endpointId
      - endpointScheme
      - reachable
      - documentTypes
      - acceptsBis30Invoice
      - smpHost
      - lookups
      - ifItStillFails
      - summary
      - doesNotProve
      additionalProperties: false
    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.