getpeppr

Returns the integration steps, code snippets and documentation links for adding Peppol to an application, for a single sender or for a platform that sends on behalf of its customers.

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "single_sender",
        "platform"
      ],
      "description": "\"single_sender\": your own company sends its invoices. \"platform\": your software sends for many customer companies."
    },
    "countries": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z]{2}$"
      },
      "description": "ISO 3166-1 alpha-2 codes of the senders' countries, e.g. [\"BE\", \"DE\"]."
    }
  },
  "required": [
    "mode",
    "countries"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Searches the prose of the public getpeppr documentation and returns up to 5 matching pages, each with its url and a short excerpt. Excerpts carry no code: open the returned url, or call plan_integration, for code.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "What to look for in the getpeppr documentation, e.g. \"CustomizationID\" or \"webhook retries\"."
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Validates a Peppol BIS Billing 3.0 UBL document against the Peppol rules, or a getpeppr invoice JSON against the SDK rules, and explains each violation. It does not check whether the invoice can be sent. Send sample or test invoices only, never a real invoice or real people's data.

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "ubl",
        "json"
      ],
      "description": "\"ubl\" for a Peppol BIS 3 UBL document, \"json\" for a getpeppr SDK invoice."
    },
    "xml": {
      "description": "A sample or test UBL document, never a real invoice, when format is \"ubl\" (at most 1 MiB).",
      "type": "string"
    },
    "invoice": {
      "type": "object",
      "description": "A sample or test invoice in the getpeppr SDK shape, never a real one, when format is \"json\"."
    }
  },
  "required": [
    "format"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Says whether a Peppol identifier (scheme:identifier) is registered to receive documents on the production Peppol network, and which ones. A sandbox test customer is never on it, and send_test_invoice only targets the test receiver 9925:BE0314595348 whatever this answers.

{
  "type": "object",
  "properties": {
    "peppolId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Peppol participant identifier, e.g. \"9925:BE0314595348\", \"0208:0685660237\" or \"GB:VAT:123456789\"."
    }
  },
  "required": [
    "peppolId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Platform accounts only: creates a test customer (sub-tenant legal entity) in the getpeppr sandbox and returns its registration state. Up to 10 active test customers per account; identifier rules per country: https://getpeppr.dev/docs/platform/legal-entities/. Calling it again with the same arguments returns the same test customer with its current status, never a second one. Pass the returned legalEntity.id as sender.legalEntityId to send_test_invoice once its status allows sending. Requires the admin role and signing in to getpeppr.

{
  "type": "object",
  "properties": {
    "externalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Your own id for this customer company. Calling again with the same arguments returns the same test customer, with its current status."
    },
    "companyName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The test customer company's legal name."
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "ISO 3166-1 alpha-2, e.g. \"BE\"."
    },
    "address": {
      "type": "object",
      "properties": {
        "line1": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Street and number."
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "zip": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Postal code."
        }
      },
      "required": [
        "line1",
        "city",
        "zip"
      ],
      "description": "The company's registered address."
    },
    "identifier": {
      "description": "One Peppol identifier, e.g. { \"scheme\": \"0208\", \"value\": \"0123456789\" }.",
      "type": "object",
      "properties": {
        "scheme": {
          "type": "string",
          "minLength": 1,
          "maxLength": 40
        },
        "value": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      },
      "required": [
        "scheme",
        "value"
      ]
    },
    "identifiers": {
      "description": "Several identifiers, in the order the country guide gives.",
      "minItems": 1,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "scheme": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          }
        },
        "required": [
          "scheme",
          "value"
        ]
      }
    }
  },
  "required": [
    "externalId",
    "companyName",
    "country",
    "address"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Sends an invoice in the getpeppr sandbox to the Belgian test receiver 9925:BE0314595348, for your own company or for one of your test customers. Never sends a real invoice. Lines without tax fields get your account's sandbox tax profile. While your sandbox tax profile is unchanged, calling it again with the same arguments returns the same document, never a second one. Returns a documentId to pass to get_document_status. Requires signing in to getpeppr.

{
  "type": "object",
  "properties": {
    "invoice": {
      "type": "object",
      "properties": {
        "to": {
          "type": "object",
          "properties": {
            "peppolId": {
              "type": "string"
            }
          },
          "required": [
            "peppolId"
          ],
          "additionalProperties": {}
        }
      },
      "required": [
        "to"
      ],
      "additionalProperties": {},
      "description": "An invoice in the getpeppr SDK shape (https://getpeppr.dev/docs/types/). Minimal example: {\"number\":\"INV-001\",\"to\":{\"name\":\"SPF Economie (test receiver)\",\"peppolId\":\"9925:BE0314595348\",\"street\":\"Rue du Progrès 50\",\"city\":\"Brussels\",\"postalCode\":\"1210\",\"country\":\"BE\"},\"lines\":[{\"description\":\"Consulting\",\"quantity\":1,\"unitPrice\":1000}]}. to.peppolId must be the sandbox test receiver 9925:BE0314595348. Omit \"from\": the sender is your registered company. Omit the line tax fields (vatRate, vatCategory, taxExemptReason): the server applies your account's sandbox tax profile to lines that carry none."
    },
    "sender": {
      "description": "Platform accounts: send as one of your test customers (the legalEntity.id create_test_customer returned). Its tax fields are then yours to set: O with vatRate 0 for a test customer without a VAT number, AE with vatRate 0 for one with a VAT number.",
      "type": "object",
      "properties": {
        "legalEntityId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        }
      },
      "required": [
        "legalEntityId"
      ]
    }
  },
  "required": [
    "invoice"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Returns the status and lifecycle events of a sandbox document sent from your getpeppr account; call it with the documentId send_test_invoice returned. submitted: getpeppr accepted it. delivered: the test receiver's access point received it, the goal of a sandbox test. failed: final, with a failureCategory. In application code, subscribe to webhooks instead of polling. Requires signing in to getpeppr.

{
  "type": "object",
  "properties": {
    "documentId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The documentId send_test_invoice returned."
    }
  },
  "required": [
    "documentId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}