Briefverzenden — fysieke post

De landen waarheen een brief verstuurd kan worden, met per land of aangetekend beschikbaar is, of daar een handtekening bij hoort, en welke verzendtarieven er te kiezen zijn.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Wat kost het versturen van een brief? Geef het aantal pagina’s en de bestemming. Het antwoord is de eindprijs inclusief printen, envelop en porto.

{
  "type": "object",
  "properties": {
    "paginas": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Aantal pagina’s van het document."
    },
    "land": {
      "type": "string",
      "description": "Bestemmingsland in het Nederlands, bijv. \"Duitsland\". Zie de tool landen."
    },
    "speed": {
      "description": "Verzendtarief. Laat leeg voor het standaardtarief van dat land.",
      "type": "string",
      "enum": [
        "traag",
        "standaard",
        "snel"
      ]
    },
    "kleur": {
      "default": false,
      "description": "In kleur drukken in plaats van zwart-wit.",
      "type": "boolean"
    },
    "dubbelzijdig": {
      "default": true,
      "description": "Beide zijden van het vel bedrukken. Standaard aan: het halveert het aantal vellen en houdt de brief vaker onder de volgende portoklasse. Zet op false voor enkelzijdig.",
      "type": "boolean"
    },
    "aangetekend": {
      "default": false,
      "description": "Aangetekend versturen; niet in elk land beschikbaar.",
      "type": "boolean"
    }
  },
  "required": [
    "paginas",
    "land"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Levert de PDF aan die verstuurd moet worden, als base64 of als publieke https-URL. Geeft een verwijzing terug die je aan bestellen meegeeft, plus het getelde aantal pagina’s.

{
  "type": "object",
  "properties": {
    "fileBase64": {
      "description": "De PDF als base64.",
      "type": "string"
    },
    "fileUrl": {
      "description": "Publieke https-URL waar de PDF staat.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Maakt de bestelling aan en geeft een betaallink terug. De brief gaat pas de deur uit nadat de klant die link heeft betaald — geef de link dus aan de gebruiker en vraag hem af te rekenen. Vat eerst samen wat er verstuurd wordt.

{
  "type": "object",
  "properties": {
    "documentRef": {
      "type": "string",
      "description": "De verwijzing uit de tool document. Alleen een URL die die tool heeft teruggegeven."
    },
    "paginas": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Aantal pagina’s, zoals document teruggaf."
    },
    "ontvanger": {
      "type": "object",
      "properties": {
        "naam": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Naam van de ontvanger, zoals op de envelop."
        },
        "adres": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "Straat en huisnummer, of postbus."
        },
        "postcode": {
          "type": "string",
          "minLength": 1,
          "maxLength": 16
        },
        "woonplaats": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "land": {
          "type": "string",
          "description": "Bestemmingsland in het Nederlands, bijv. \"Duitsland\". Zie de tool landen."
        }
      },
      "required": [
        "naam",
        "adres",
        "postcode",
        "woonplaats",
        "land"
      ]
    },
    "email": {
      "type": "string",
      "description": "E-mailadres van de klant, voor bevestiging en status."
    },
    "speed": {
      "type": "string",
      "enum": [
        "traag",
        "standaard",
        "snel"
      ]
    },
    "idempotencyKey": {
      "description": "Verzin één unieke sleutel per bestelling, minstens 16 tekens (een UUID is prima), en hergebruik die bij opnieuw proberen. Voorkomt dubbele brieven.",
      "type": "string"
    },
    "kleur": {
      "default": false,
      "description": "In kleur drukken in plaats van zwart-wit.",
      "type": "boolean"
    },
    "dubbelzijdig": {
      "default": true,
      "description": "Beide zijden van het vel bedrukken. Standaard aan: het halveert het aantal vellen en houdt de brief vaker onder de volgende portoklasse. Zet op false voor enkelzijdig.",
      "type": "boolean"
    },
    "aangetekend": {
      "default": false,
      "description": "Aangetekend versturen; niet in elk land beschikbaar.",
      "type": "boolean"
    }
  },
  "required": [
    "documentRef",
    "paginas",
    "ontvanger",
    "email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Hoe ver is een verstuurde brief? Geef het sessie-id uit de betaallink of de referentie.

{
  "type": "object",
  "properties": {
    "sessie": {
      "description": "Het session_id uit de betaallink (cs_live_…).",
      "type": "string"
    },
    "referentie": {
      "description": "De referentie uit de bevestiging.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}