Koppelingen

Eyetelligence is te koppelen aan externe applicaties, zoals bijvoorbeeld Sjapo. Dezelfde gegevens zijn zowel via onze API als via een MCP-server te benaderen. Beide gebruiken dezelfde API-key.

Informatie voor managers

Om te koppelen zul je een API-key moeten aanmaken en deze verstrekken aan de applicatie waarmee je koppelt (bijvoorbeeld Sjapo) zodat ze bij jouw gegevens kunnen. Neem contact met ons op zodat we jouw API-key kunnen verstrekken, dit kun je (nog) niet zelf doen. Dezelfde API-key werkt zowel voor de API als voor de MCP-server.

API

Voor specifiek maatwerk of concullega-applicaties bieden we een GraphQL API aan.

• We maken gebruik van GraphQL
• Het schema is beschikbaar op https://cockpit.eyetelligence.nl/api/api/schema
• Het endpoint is: https://cockpit.eyetelligence.nl/api/api/query
• De API-key moet als header meegegeven worden in de vorm: Authorization: Bearer [mijn token]
• Er geldt een fair-use policy
• Gebruik onderstaande query om de relevante data op te halen:

query ($period: Period!, $year: Int!) {
    sjapo(period: $period) {
        id
        employee {
            id
            employeeNumber
            name
            givenNames
            prefix
            surname
            email
            dateOfBirth
            address {
                country
                region
                city
                street
                houseNumber
                houseNumberAddition
                postcode
            }
        }
        startDate
        endDate
        hours(period: $period)
        attendances(period: $period) {
            id
            startCorrected
        }
        overtimeHours(period: $period)
        illnessHours(period: $period)
        shifts(period: $period) {
            id
            start
            end
            comment
            breakDuration
            shiftType
        }
        availabilities(period: $period) {
            id
            start
            end
            isAvailable
            comment
        }
        todos(period: $period) {
            label
        }
    }
    journals(year: $year) {
        employeeName
        employeeNumber
        period
        year
        run
        department
        costCenter
        costUnit
        percentage
        generalLedgerAccount
        componentName
        debit
        credit
        total
    }
}

Bijvoorbeeld:

curl https://cockpit.eyetelligence.nl/api/api/query \
    -H 'Authorization: Bearer apitoken' \
    --data-urlencode 'query=
        query ($period: Period!, $year: Int!) {
            sjapo (period: $period) {
                id
                employee {
                    id
                    employeeNumber
                    name
                    givenNames
                }
                startDate
                endDate
                hours(period: $period)
                shifts(period: $period) {
                    id
                    start
                    end
                    comment
                    shiftType
                }
                availabilities(period: $period) {
                    id
                    start
                    end
                    isAvailable
                    comment
                }
                todos(period: $period) {
                    label
                }
            }
            journals(year: $year) {
                employeeName
                employeeNumber
                period
                year
                run
                department
                costCenter
                costUnit
                percentage
                generalLedgerAccount
                componentName
                debit
                credit
                total
            }
        }
    ' \
    --data-urlencode 'variables={"period":{"year":2023,"period":7},"year":2024}'

Omzet

Gebruik de receiptItems-query om de verkochte regels over een datumbereik op te halen: per regel het aantal, de prijzen, het btw-percentage en de categorie. De omzetdag volgt de POS-instelling van het bedrijf, zodat dit overeenkomt met de overige omzetrapportages. Optellen per dag, categorie of vestiging doe je zelf.

query ($firm: FirmInputType!, $fromDate: Date!, $toDate: Date!) {
    receiptItems(firm: $firm, fromDate: $fromDate, toDate: $toDate) {
        id
        name
        quantity
        createdAt
        taxPercentage
        totalTaxExclusivePrice
        totalTaxInclusivePrice
        category
        categoryType
    }
}

Bijvoorbeeld:

curl https://cockpit.eyetelligence.nl/api/api/query \
    -H 'Authorization: Bearer apitoken' \
    --data-urlencode 'query=
        query ($firm: FirmInputType!, $fromDate: Date!, $toDate: Date!) {
            receiptItems(firm: $firm, fromDate: $fromDate, toDate: $toDate) {
                name
                quantity
                createdAt
                totalTaxInclusivePrice
                category
            }
        }
    ' \
    --data-urlencode 'variables={"firm":{"id":1},"fromDate":"2024-01-01","toDate":"2024-01-31"}'

Diensten

Gebruik de shifts-query om de geplande diensten uit het gepubliceerde rooster op te halen over een datumbereik. Per dienst krijg je start, eind, pauze, duur, het id van de ingeroosterde medewerker (of null bij een open dienst) en de verwachte loonkosten.

query ($firm: FirmInputType!, $fromDate: Date!, $toDate: Date!) {
    shifts(firm: $firm, fromDate: $fromDate, toDate: $toDate) {
        id
        start
        end
        breakDuration
        durationHours
        employeeId
        expectedCost
    }
}

Gewerkte diensten

Gebruik de attendances-query om de daadwerkelijk gewerkte diensten op te halen over een datumbereik. Alleen gereviewde diensten worden teruggegeven; startCorrected en endCorrected zijn de gecorrigeerde (gereviewde) tijden. Per dienst krijg je start, eind, pauze, netto gewerkte uren, het id van de medewerker en de werkelijke loonkosten. Voor de definitieve cijfers — inclusief de reservering van vakantie-uren — gebruik je de journals.

query ($firm: FirmInputType!, $fromDate: Date!, $toDate: Date!) {
    attendances(firm: $firm, fromDate: $fromDate, toDate: $toDate) {
        id
        startCorrected
        endCorrected
        breakDuration
        durationHoursCorrected
        employeeId
        actualCost
    }
}

MCP

Dezelfde GraphQL API is ook beschikbaar via een MCP-server (Model Context Protocol), zodat AI-clients zoals Claude Code het schema kunnen ontdekken en zelf queries en mutaties kunnen uitvoeren.

• Het endpoint is: https://cockpit.eyetelligence.nl/mcp
• Het transport is streamable HTTP
• De API-key moet als header meegegeven worden in de vorm: Authorization: Bearer [mijn token]
• De koppeling scoping (welke firma) en rechten volgen automatisch uit de API-key, precies zoals bij de API
• De server ondersteunt introspectie, zoeken in het schema, en het uitvoeren van queries en mutaties
• Er geldt een fair-use policy

Configureer de server bijvoorbeeld in een .mcp.json voor Claude Code:

{
  "mcpServers": {
    "cockpit-eyetelligence": {
      "type": "http",
      "url": "https://cockpit.eyetelligence.nl/mcp",
      "headers": { "Authorization": "Bearer apitoken" }
    }
  }
}