Naar de inhoud
Menu

Zoeken op de site

Typ om te zoeken in handleidingen, blog, API en product.

↑ ↓ om te bewegen · Enter om te openen · Esc om te sluiten

API-referentie

API

Afspraken

Diensten, team en afspraken in bulk voor je agenda

Bekijken als Markdown

Wat je nodig hebt om de agenda van je bedrijf vanuit een ander systeem te beheren: de diensten die worden ingepland met wie ze uitvoert, het team, en het in bulk laden van afspraken. Het is hetzelfde als wat de MCP-tools list_services, list_collaborators en import_appointments doen, met dezelfde veldnamen.

MethodeRouteBeschrijving
GET/v1/servicesDe diensten die je plant, met wie ze uitvoert
GET/v1/collaboratorsHet team: naam, e-mail, rol en diensten die iemand uitvoert
POST/v1/appointments/importLaad tot 200 afspraken in één aanroep

Diensten opvragen

Elke dienst bevat id, name, duration_minutes, price, currency, location, active en collaborators (id, name en email van wie hem uitvoert). Het id is wat je als service_id opgeeft bij het importeren van afspraken. Diensten die je verhuurt (kamers, zalen, voertuigen) staan hier niet.

GET/v1/services
curl "https://rest-api.tbit.app/v1/services" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/services', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/services',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/services',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/services');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Response
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab34cd",
      "name": "Endodoncia",
      "duration_minutes": 60,
      "price": 350000,
      "currency": "COP",
      "location": "Sede norte · Calle 72 # 7-41",
      "active": true,
      "collaborators": [
        {
          "id": "6a0f3c2e9b1d4a0012ab0001",
          "name": "Geral Díaz",
          "email": "[email protected]"
        }
      ]
    }
  ]
}

Het team opvragen

Elke persoon bevat id, name, email, role, attends_appointments (of die afspraken uitvoert) en service_ids (de diensten die die persoon uitvoert). Als een persoon geen naam heeft, is name leeg: herken die persoon aan het e-mailadres.

GET/v1/collaborators
curl "https://rest-api.tbit.app/v1/collaborators" \
  -H "X-API-Key: $TBIT_API_KEY"
const response = await fetch('https://rest-api.tbit.app/v1/collaborators', {
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
  },
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.get(
  'https://rest-api.tbit.app/v1/collaborators',
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.get(
    'https://rest-api.tbit.app/v1/collaborators',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/collaborators');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Response
{
  "data": [
    {
      "id": "6a0f3c2e9b1d4a0012ab0001",
      "name": "Geral Díaz",
      "email": "[email protected]",
      "role": "ADMIN",
      "attends_appointments": true,
      "service_ids": [
        "6a0f3c2e9b1d4a0012ab34cd"
      ]
    }
  ]
}

Afspraken importeren

Stuur tot 200 afspraken per aanroep in appointments. Elke rij heeft phone (met landcode, bijvoorbeeld 573001234567: het contact wordt op telefoonnummer gezocht en, als het niet bestaat, aangemaakt) of contact_id (een contact dat al bestaat: de afspraak gaat naar dat profiel ook als het geen telefoonnummer heeft, zoals iemand die schrijft met een WhatsApp-gebruiker; als je ook phone meestuurt, wordt dat alleen gebruikt om te melden), contact_name en email optioneel, de service (service_id of service_name, de exacte naam ongeacht hoofdletters), wie het verzorgt (collaborator_id of collaborator_email; als de service door één persoon wordt verzorgd kun je het weglaten), start in ISO 8601 (zonder zone wordt het in de zone van het bedrijf gelezen), end optioneel (standaard start plus de duur van de service), external_id (de sleutel van het event in jouw systeem: opnieuw importeren dupliceert niet) en notes.

Opties, allemaal op het eerste niveau van de body: notify_customer (standaard false: de klant krijgt geen bevestiging; true stuurt die zoals bij elke afspraak), send_reminders (standaard true), release_blocks (true haalt de blokkades van die persoon weg die met de afspraak overlappen), on_existing (skip of update: als er al een afspraak met hetzelfde external_id bestaat, laat hij die staan of verplaatst hij die zonder iemand te waarschuwen) en dry_run (true controleert alles en zegt wat hij zou doen, zonder iets te schrijven). Begin altijd met dry_run.

De reactie zegt per rij wat er gebeurde: status is created, updated, skipped of failed (would_create of would_update met dry_run), met appointment_id, contact_id en, als het mislukte, error met de reden in woorden («Andrés voert Endodoncia niet uit; dat doen: Geral Díaz.»). Een slechte rij stopt de andere niet. Bewaar import_id: dat heb je nodig om het ongedaan te maken.

POST/v1/appointments/import
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "appointments": [
      {
        "phone": "573001234567",
        "contact_name": "Ana Pérez",
        "service_name": "Endodoncia",
        "collaborator_email": "[email protected]",
        "start": "2026-11-20T10:00",
        "external_id": "gcal-7f3k2"
      }
    ]
  }'
const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dry_run: true,
    appointments: [
      {
        phone: '573001234567',
        contact_name: 'Ana Pérez',
        service_name: 'Endodoncia',
        collaborator_email: '[email protected]',
        start: '2026-11-20T10:00',
        external_id: 'gcal-7f3k2',
      },
    ],
  }),
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.post(
  'https://rest-api.tbit.app/v1/appointments/import',
  {
    dry_run: true,
    appointments: [
      {
        phone: '573001234567',
        contact_name: 'Ana Pérez',
        service_name: 'Endodoncia',
        collaborator_email: '[email protected]',
        start: '2026-11-20T10:00',
        external_id: 'gcal-7f3k2',
      },
    ],
  },
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.post(
    'https://rest-api.tbit.app/v1/appointments/import',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
    json={
        'dry_run': True,
        'appointments': [
            {
                'phone': '573001234567',
                'contact_name': 'Ana Pérez',
                'service_name': 'Endodoncia',
                'collaborator_email': '[email protected]',
                'start': '2026-11-20T10:00',
                'external_id': 'gcal-7f3k2',
            },
        ],
    },
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'dry_run' => true,
        'appointments' => [
            [
                'phone' => '573001234567',
                'contact_name' => 'Ana Pérez',
                'service_name' => 'Endodoncia',
                'collaborator_email' => '[email protected]',
                'start' => '2026-11-20T10:00',
                'external_id' => 'gcal-7f3k2',
            ],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Response
{
  "data": {
    "import_id": null,
    "dry_run": true,
    "created": 1,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "results": [
      {
        "index": 0,
        "external_id": "gcal-7f3k2",
        "status": "would_create",
        "contact_id": "6a0f3c2e9b1d4a0012ab9f10"
      }
    ]
  }
}

Een import ongedaan maken

Stuur alleen undo_import_id met het import_id dat de import teruggaf: alle afspraken die die import aanmaakte worden geannuleerd, zonder iemand te waarschuwen, en hun external_id komt vrij om ze opnieuw te importeren.

POST/v1/appointments/import
curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "undo_import_id": "6a1e0b7c5d4f3a0012cd5678"
  }'
const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TBIT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
  }),
});
const data = await response.json();
import axios from 'axios';

const { data } = await axios.post(
  'https://rest-api.tbit.app/v1/appointments/import',
  {
    undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
  },
  {
    headers: {
      'X-API-Key': process.env.TBIT_API_KEY,
    },
  },
);
import os
import requests

response = requests.post(
    'https://rest-api.tbit.app/v1/appointments/import',
    headers={'X-API-Key': os.environ['TBIT_API_KEY']},
    json={
        'undo_import_id': '6a1e0b7c5d4f3a0012cd5678',
    },
)
data = response.json()
<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('TBIT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'undo_import_id' => '6a1e0b7c5d4f3a0012cd5678',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
Response
{
  "data": {
    "import_id": "6a1e0b7c5d4f3a0012cd5678",
    "cancelled": 198,
    "already_cancelled": 2,
    "failed": []
  }
}
  • De persoon moet die dienst uitvoeren. Zo niet, mislukt de rij en zegt de fout wie hem wel uitvoert.
  • Een afspraak mag niet overlappen met een andere van dezelfde persoon, noch met een andere rij uit dezelfde batch. Als hij overlapt met een agendablokkade, mislukt de rij tenzij je release_blocks: true meestuurt.
  • Een batch die niet helemaal leesbaar is (leeg, meer dan 200 rijen, een onbekend veld in de body) antwoordt 400 VALIDATION_ERROR en schrijft niets.
  • Een grote batch kan even duren: elke afspraak maakt zijn bestelling en zijn contact aan. Als je batches meer dan 100 afspraken bevatten, splits ze dan in kleinere aanroepen.