Entwickler, sei gegrüßt! Die mite.api freut sich auf deine Hacks. Welche Funktionen wie zur Verfügung stehen, erfährst du hier im Dokumentationsbereich.

Bitte beachten: Kunden können von Zeiterfassern nicht modifiziert, erstellt oder gelöscht werden. Lesen können Zeiterfasser lediglich Kunden der für sie freigegebenen Projekte.

Alle aktiven Kunden auflisten

Liste alle aktiven Kunden sortiert nach deren Namen auf:

GET /customers.xml
GET /customers.json

Parameter

name Gibt nur die Einträge zurück, deren Namen den übergebenen String enthalten. Groß- und Kleinschreibung wird ignoriert.
limit Mit dem Parameter limit ist es möglich, die maximale Anzahl der ausgegebenen Einträge zu begrenzen.
Default: unbegrenzt
page In Kombination mit dem Parameter limit können Folgeseiten ausgegeben werden.
Default: 1

Antwort

Status: 200 OK
[
   {
      "customer": {...}
   },
   {
      "customer": {...}
   }
]
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<customers type="array">
   <customer>
      ...
   </customer>
   <customer>
      ...
   </customer>
</customers>

Alle archivierten Kunden auflisten

Liste alle archivierten Kunden sortiert nach deren Namen auf:

GET /customers/archived.xml
GET /customers/archived.json

Es können die gleichen Parameter wie bei den aktiven Kunden verwendet werden.

Einzelnen Kunden anzeigen

Rufe einen Kunden nach dessen id auf:

GET /customers/:id.xml
GET /customers/:id.json

Antwort

Status: 200 OK
{
   "customer": {
      "id": 83241,
      "name": "Acme Inc.",
      "note": "",
      "archived": false,
      "active_hourly_rate": "hourly_rates_per_service",
      "hourly_rate": null,
      "hourly_rates_per_service": [
         {
            "service_id": 742,
            "hourly_rate": 4500
         },
         {
            "service_id": 43212,
            "hourly_rate": 5500
         }
      ],
      "created_at": "2015-10-15T14:33:19+02:00",
      "updated_at": "2015-10-15T14:29:03+02:00"
   }
}
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<customer>
   <id type="integer">83241</id>
   <name>Acme Inc.</name>
   <note>Sehr wankelmütig!</note>
   <archived type="boolean">false</archived>
   <hourly-rate type="integer" nil="true"/>
   <active-hourly-rate>hourly_rates_per_service</active-hourly-rate>
   <hourly-rates-per-service type="array">
      <hourly-rate-per-service>
         <service-id type="integer">742</service-id>
         <hourly-rate type="integer">4500</hourly-rate>
      </hourly-rate-per-service>
      <hourly-rate-per-service>
         <service-id type="integer">43212</service-id>
         <hourly-rate type="integer">5500</hourly-rate>
      </hourly-rate-per-service>
   </hourly-rates-per-service>
   <updated-at type="datetime">2015-10-15T14:33:19+02:00</updated-at>
   <created-at type="datetime">2015-10-15T14:29:03+02:00</created-at>
</customer>

Einen Kunden erstellen

Erstellt einen neuen Kunden; alle Attribute – bis auf name – sind optional.

POST /customers.xml
POST /customers.json

Attribute

name Darf nicht leer sein!
note Default: "" (leerer String)
active_hourly_rate null (Default), "hourly_rate" oder "hourly_rates_per_service"
hourly_rate Stundensatz in Cent (ein Hundertstel der Basiseinheit, unabhängig von der Währung). Wird verwendet wenn active_hourly_rate auf "hourly_rate" gesetzt ist.
Default: null
hourly_rates_per_service Liste der Stundensätze je nach Leistung. Wird verwendet wenn active_hourly_rate auf "hourly_rates_per_service" gesetzt ist.
Default: [] (leerer Array)
archived true oder false
Default: false

Anfrage

Content-Type: application/json
{
   "customer": {
      "name": "Acme"
   }
}
Content-Type: application/xml
<customer>
   <name>Acme</name>
</customer>

Antwort

Status: 201 Created
Location: https://demo.mite.de/customers/42313.json
{
   "customer": {
      "id": 42313,
      "name": "Acme",
      "note": "",
      "archived": false,
      "active_hourly_rate": null,
      "hourly_rate": null,
      "hourly_rates_per_service": [],
      "created_at": "2015-10-15T11:40:49+02:00",
      "updated_at": "2015-10-15T11:40:49+02:00"
   }
}
Status: 201 Created
Location: https://demo.mite.de/customers/42313.xml
<?xml version="1.0" encoding="UTF-8"?>
<customer>
   <id type="integer">42313</id>
   <name>Acme</name>
   <note></note>
   <archived type="boolean">false</archived>
   <hourly-rate type="integer" nil="true"/>
   <active-hourly-rate nil="true"/>
   <hourly-rates-per-service type="array"/>
   <updated-at type="datetime">2015-10-15T11:40:49+02:00</updated-at>
   <created-at type="datetime">2015-10-15T11:40:49+02:00</created-at>
</customer>

Einen Kunden bearbeiten

Aktualisiere einen Kunden mit den übergebenen Attributen:

PATCH /customers/:id.xml
PATCH /customers/:id.json

Anfrage

Content-Type: application/json
{
   "customer": {
      "archived": true
   }
}
Content-Type: application/xml
<customer>
   <archived>true</archived>
</customer>

Antwort

Status: 200 OK
{leer}

Wenn du eines der für den Stundensatz ausschlaggebenden Attribute (active_hourly_rate, hourly_rate und/oder hourly_rates_per_service) änderst, wird sich diese Änderung per Default nur auf Zeiteinträge auswirken, die von jetzt an erstellt werden. Wenn du den neuen Stundensatz auch auf bereits vorhandene Zeiteinträge anwenden möchtest, setze bitte das zusätzliche Attribut update_hourly_rate_on_time_entries auf true:

Content-Type: application/json
{
   "customer": {
      "hourly_rate": 12000,
      "update_hourly_rate_on_time_entries": true
   }
}
Content-Type: application/xml
<customer>
   <hourly-rate>12000</hourly-rate>
   <update-hourly-rate-on-time-entries>12000</update-hourly-rate-on-time-entries>
</customer>

Einen Kunden löschen

Lösche einen Kunden:

DELETE /customers/:id.xml
DELETE /customers/:id.json

Antwort

Status: 200 OK
{leer}

Du kannst einen Kunden nur löschen, wenn ihm keine Projekte zugeordnet sind. Ansonsten erhältst du folgende Antwort:

Status: 422 Unprocessable Entity
{
   "error": "Dieser Kunde kann nicht gelöscht werden, \
da an ihm Projekte hängen. Archiviere es stattdessen."
}
Status: 422 Unprocessable Entity
<?xml version="1.0" encoding="UTF-8"?>
<errors>
   <error>Dieser Kunde kann nicht gelöscht werden, \
da an ihm Projekte hängen. Archiviere es stattdessen.</error>
</errors>