REST API for Portugal procurement
Programmatic access to Corp-Merch — place orders, sync catalog, receive webhook events. JSON over HTTPS, Bearer auth, 99.95% SLA.
Authentication & rate limits
OAuth 2.0 client credentials or long-lived Bearer tokens (rotate every 90 days). Base URL: https://api.corp-merch.com/v1. Rate limit: 600 req/min per token, burst 60 req/sec. All payloads UTF-8 JSON; ISO 8601 timestamps. Errors follow RFC 7807 (application/problem+json).
Endpoints overview
POST /v1/orders — submit a purchase order. GET /v1/catalog — retrieve country-localised SKUs (priced in EUR/PLN incl. IVA 23%). GET /v1/orders/{id} — order status with tracking. POST /v1/webhooks — register a callback URL for order.shipped, invoice.issued (via Portal das Finanças (AT)), invoice.paid events. Full OpenAPI 3.1 spec at /v1/openapi.json.
Compliance & invoicing in Portugal
Every order auto-generates a IVA 23% invoice via Portal das Finanças (AT) (mandatory in Portugal). Invoice XML available via GET /v1/invoices/{id}; signed with QES per eIDAS. Archived 10 years. Webhook invoice.issued fires within 60 seconds of acknowledgement from Portal das Finanças (AT). Lisbon fulfilment hub processes API orders express if received before 14:00 local time.
FAQ
What authentication does the API use?
OAuth 2.0 client_credentials grant returning a Bearer token (expires 1 hour). Long-lived tokens available for server-to-server with 90-day rotation. We also support mTLS for enterprise customers.
How do I test before going live?
Sandbox at https://api.sandbox.corp-merch.com — full feature parity, sample catalog, mock invoices. Webhook events replayable for the last 30 days from the dashboard.
What's the SLA?
99.95% uptime on the v1 endpoints (measured monthly). Status page at status.corp-merch.com with RSS/webhook subscriptions for incidents.
Are invoices compliant with Portugal regulations?
Yes — all invoices routed via Portal das Finanças (AT) with IVA 23%. Format matches Portugal schema (FatturaPA / SAF-T PT / KSeF XML / Facturae as applicable), validated server-side before submission.
How are webhook retries handled?
Exponential backoff: 1m, 5m, 15m, 1h, 6h, 24h. After 6 failures the subscription pauses and we alert the registered email. Signed with HMAC-SHA256 in the X-Corp-Signature header.