OpenAPI-spec & developer sandbox

Machineleesbaar contract voor de PROFOYO Public API: compliance-classificatie, WTTA-lookup, rate-benchmarks, Compliance Passport-verificatie en DAC7 seller data. Klaar voor Postman, Insomnia, openapi-generator en LLM-agent tools.

OpenAPI-contract

Volledige spec, geldig OpenAPI 3.1, versie-gepind op datum in bestandsnaam.

Bekijk openapi.json

Sandbox base URL

https://sandbox-api.profoyo.com/v1

Gebruik tokens met prefix sk_test_. Data in de sandbox wordt maximaal 30 dagen bewaard en wordt daarna gewist.

Authenticatie

Alle endpoints vereisen een bearer token, gemint op /freelancer/api-tokens. Tokens zijn scoped per gebruiker en per omgeving:

sk_live_ — productiedata; alleen op api.profoyo.com.
sk_test_ — sandbox; alleen op sandbox-api.profoyo.com. Nooit gemixt.

Tokens worden geheim opgeslagen (bcrypt-hash) en één keer getoond bij aanmaak; kwijt = intrekken en opnieuw aanmaken.

Rate limits

Tier	Requests / min	Burst	Toelichting
Sandbox	60	120	Alleen test-tokens (sk_test_...), sandbox-project.
Production — Free	60	120	Inbegrepen bij elk betaald plan.
Production — Pro	600	1200	Inbegrepen bij Pro Lifetime en Team-plannen.
Production — Partner	3000	6000	Vereist een getekende partnerovereenkomst; mail info@profoyo.com.

Response headers

Elke response bevat X-RateLimit-Limit, X-RateLimit-Remaining en, bij een 429, Retry-After in seconden. Gebruik exponential backoff.

Voorbeeld — Zelfstandigenwet-classifier

curl -X POST https://sandbox-api.profoyo.com/v1/classify/zelfstandigenwet \
  -H "Authorization: Bearer sk_test_your_sandbox_token" \
  -H "Content-Type: application/json" \
  -d '{
    "engagement": {
      "hourly_rate_eur": 85,
      "months_duration": 6,
      "days_per_week": 3,
      "other_clients_count": 4,
      "own_tools": true,
      "own_liability": true,
      "sets_own_hours": true,
      "can_delegate": true,
      "profit_risk": true
    }
  }'

Response: JSON met verdict (safe/risky/unsafe), score, geraakte criteria en tekstueel advies.

Doorstart-recepten

Postman

/openapi.json — Importeer als "OpenAPI 3.1"; sandbox-token in de Authorization variabele.

openapi-generator

openapi-generator-cli generate -i https://profoyo.nl/openapi.json -g typescript-fetch -o ./profoyo

LLM-agents

De MCP-server biedt dezelfde endpoints; zie /developers.

Wijzigingsproces

Nieuwe endpoints en niet-brekende veldtoevoegingen: aangekondigd op /status, direct live.
Brekende wijzigingen: minimaal 90 dagen deprecation-window, response-header Sunset, mail aan alle token-eigenaren.
De spec zelf is versie-gepind per datum; historische versies staan op /openapi/YYYY-MM-DD.json.

Partnersleutels nodig?

Bouw je een VMS-, ATS- of accountancy-integratie? Vraag Partner-tier aan met verhoogde rate limits en co-branded sandbox.

Contact opnemen