Requests & responses

Requests

Basis-url

https://api.rompslomp.nl/api/v1

Acties

De Rompslomp API is RESTful. Resources, zoals facturen en betalingen, hebben een locatie die relatief is aan de basis-url. De HTTP methode die wordt gebruikt bij het request bepaalt de actie die wordt uitgevoerd.

Methode	Locatie	Actie
GET	/{company_id}/{resource_type}	Lijst van resources opvragen
GET	/{company_id}/{resource_type}/{id}	Resource opvragen
POST	/{company_id}/{resource_type}	Resource aanmaken
PATCH	/{company_id}/{resource_type}/{id}	Resource bijwerken
DELETE	/{company_id}/{resource_type}/{id}	Resource verwijderen

Toelichting bij plaatsvervangende aanduidingen:

{company_id}: Het unieke identificatienummer van een bedrijf.
{resource_type}: Het resource-type, zoals facturen (sales_invoices) of contacten (contacts).
{id}: Het unieke identificatienummer van een resource.

Welke acties beschikbaar zijn verschilt per resource-type. Bij API endpoints vind je het complete overzicht van alle resource-typen, acties en opties.

Dataformaat

Request bodies moeten als JSON worden opgemaakt. De 'Content-Type' request header moet zijn 'application/json'.

Voorbeeld-requests

Facturen ophalen

curl --request GET 'https://api.rompslomp.nl/api/v1/companies/54321/sales_invoices?per_page=1&page=2' \
  --header 'Authorization: Bearer NxtsAs1T6P9TcApiTl4DGcLulrLQDqzIWhdaOBI07gU'

Contact bijwerken

curl --request PATCH 'https://api.rompslomp.nl/api/v1/companies/654/contacts/321' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer NxtsAs1T6P9TcApiTl4DGcLulrLQDqzIWhdaOBI07gU' \
  --data-raw '{
    "contact": {
      "city": "Utrecht"
    }
  }'

Lees over het bijwerken van subresources op de Subresources pagina.

Responses

Dataformaat

Response bodies zijn altijd als JSON opgemaakt, ongeacht de gebruikte 'Accept' header.

Voorbeeld-response

Betalingen ophalen

// HTTP/1.1 200 OK
// X-Per-Page: 40
// X-Page: 1
// X-Total: 1
// Content-Type: application/json; charset=utf-8

{
  "payments": [
    {
      "id": 117603,
      "amount": "100.0",
      "description": "Reclamemateriaal",
      "account_id": 513025,
      "paid_at": "2020-03-12T11:53:27.000+01:00"
    }
  ]
}

(Niet-relevante headers zijn weggelaten.)

Foutmeldingen

Wanneer er een fout optreedt krijgt de response de relevante statuscode en bevat de response body een JSON object die de fout beschrijft. Elk foutobject bevat een vast type en een omschrijving of uitleg.

Voorbeeld error-response

// HTTP/1.1 401 Unauthorized
// WWW-Authenticate: Bearer realm="Rompslomp API v1", error="invalid_token", error_description="Het toegangstoken is ongeldig"
// Content-Type: application/json; charset=utf-8

{
  "error": {
    "message": "Het toegangstoken is ongeldig",
    "type": "client.authentication.invalid_token"
  }
}

(Niet-relevante headers zijn weggelaten.)

Error-responses

De volgende tabel geeft een overzicht van de mogelijke error-responses.

Status	Error-type(s)	Informatie
400	client.parameters.invalid_parameter_value client.parameters.unpermitted_parameters client.parameters.missing_parameter client.parameters.malformed_json
401	client.authentication.invalid_token	Het toegangstoken bestaat niet (meer).
403	client.authorization.invalid_scope client.authorization.access_denied	Het toegangstoken geeft niet voldoende toegang, de eigenaar van het API token heeft geen toegang (meer), óf de administratie heeft de API add-on niet geactiveerd.
404	client.not_found.resource client.not_found.endpoint
422	client.parameters.validation client.quota_reached	Een resource kan niet worden opgeslagen vanwege semantische fouten of het overschrijden van het quotum voor dat type resource.
429	client.rate_limit	Meer over request-begrenzing vind je bij de algemene informatie.
500	server	Onvoorziene fout in de Rompslomp API. Probeer het later nog eens.