Ga naar inhoud

Document templates via de API

Via de API kun je document templates aanmaken, hernoemen, aan bedrijven koppelen en het .docx-bestand downloaden en vervangen. Het bestand zelf gaat niet door GraphQL: je vraagt een link op en haalt of stuurt het bestand daarna met een gewoon HTTP-verzoek, bijvoorbeeld met curl.

  • Een link bestaat uit een url en een token, en geldt 30 seconden.
  • Een token werkt één keer. Wil je nog eens downloaden of uploaden, vraag dan een nieuwe link op.
  • Stuur het token altijd als header Authorization: Bearer [token], nooit in de URL.
  • Een downloadlink werkt alleen voor downloaden en een uploadlink alleen voor uploaden.
  • Een token dat verlopen, al gebruikt, aangepast of niet (meer) geldig is, krijgt 403. Dat gebeurt ook als de API-key intussen is verwijderd of geen toegang meer heeft tot het template.

Een template aanmaken

createDocumentTemplate maakt een template zonder bestand aan voor één of meer bedrijven van je API-key (firms, minstens één). Zolang er geen bestand is, staat hasFile op false en kun je er nog geen documenten mee maken. Per bedrijf kunnen er maximaal 100 templates van één soort zijn.

mutation {
    createDocumentTemplate(
        firms: [{ id: "1" }, { id: "2" }]
        name: "Arbeidsovereenkomst"
        documentTemplateType: CONTRACT
    ) {
        id
        hasFile
    }
}

Met updateDocumentTemplate wijzig je de naam en de bedrijven van een template dat aan minstens één bedrijf van je API-key gekoppeld is. Geef je firms mee, dan minstens één bedrijf. Bedrijven die niet bij je API-key horen, blijven gekoppeld.

Een bestand uploaden

Vraag een uploadlink op voor een template dat aan minstens één bedrijf van je API-key gekoppeld is (niet voor een globaal template):

query {
    documentTemplateUploadLink(documentTemplate: { id: "42" }) {
        url
        token
        expiresAt
    }
}

Stuur binnen 30 seconden het bestand als ruwe body met PUT:

curl --request PUT \
    --header "Authorization: Bearer [token]" \
    --data-binary @template.docx \
    https://cockpit.eyetelligence.nl/api/document_template_transfer/upload

Het bestand moet een .docx van hoogstens 5 MB zijn, zonder macro's, ingesloten objecten, externe koppelingen of velden die andere bestanden binnenhalen, en mag alleen de tags gebruiken die documentTemplateTags voor die soort template noemt. Een goedgekeurd bestand vervangt het huidige in één stap.

Mogelijke antwoorden:

  • 200 met {"id": ..., "name": ..., "documentTemplateType": ..., "updatedAt": ...}
  • 400 met {"error": "..."}: het bestand is geweigerd en het template is ongewijzigd. De melding zegt wat er mis is. Bij "Upload failed" is het bestand niet te controleren of verdacht.
  • 403: de link is ongeldig, verlopen of al gebruikt.

Een bestand downloaden

Vraag een downloadlink op voor een eigen template of een globaal template dat voor je bedrijven geldt. Het template moet een bestand hebben.

query {
    documentTemplateDownloadLink(documentTemplate: { id: "42" }) {
        url
        token
        expiresAt
    }
}

Haal het bestand binnen 30 seconden op:

curl --fail \
    --header "Authorization: Bearer [token]" \
    --output template.docx \
    https://cockpit.eyetelligence.nl/api/document_template_transfer/download

Mogelijke antwoorden:

  • 200 met het .docx-bestand
  • 403: de link is ongeldig, verlopen of al gebruikt.