API REST para procurement em Portugal
Acesso programático à Corp-Merch — submeter encomendas, sincronizar catálogo, receber eventos via webhook. JSON sobre HTTPS, autenticação Bearer, SLA 99,95%.
Autenticação e limites de taxa
OAuth 2.0 client credentials ou tokens Bearer de longa duração (rotação a cada 90 dias). Base URL: https://api.corp-merch.com/v1. Limite: 600 req/min por token, pico de 60 req/seg. Payloads em UTF-8 JSON; timestamps ISO 8601. Erros conforme RFC 7807.
Visão geral dos endpoints
POST /v1/orders — submeter ordem de compra. GET /v1/catalog — obter SKUs localizados (preços em EUR com IVA 23% incluído). GET /v1/orders/{id} — estado da encomenda com tracking. POST /v1/webhooks — registar URL de callback para order.shipped, invoice.issued (via Portal das Finanças (AT)), invoice.paid. Especificação OpenAPI 3.1 em /v1/openapi.json.
Conformidade e faturação em Portugal
Cada encomenda gera automaticamente uma fatura IVA 23% via Portal das Finanças (AT) (obrigatório em Portugal). XML disponível via GET /v1/invoices/{id}; assinada com QES segundo eIDAS. Arquivada 10 anos. Webhook invoice.issued dispara em 60 segundos após aceitação pelo Portal das Finanças (AT). Hub de Lisboa processa encomendas API no mesmo dia se recebidas até às 14:00 local.
FAQ
Que autenticação usa a API?
OAuth 2.0 client_credentials a devolver token Bearer (expira em 1 hora). Tokens de longa duração para servidor-a-servidor com rotação de 90 dias. Suportamos mTLS para clientes enterprise.
Como testar antes de produção?
Sandbox em https://api.sandbox.corp-merch.com — paridade total, catálogo de exemplo, faturas mock. Eventos webhook reproduzíveis para os últimos 30 dias via dashboard.
Qual é o SLA?
99,95% uptime nos endpoints v1 (medição mensal). Página de status em status.corp-merch.com com subscrições RSS/webhook.
As faturas são conformes com a legislação portuguesa?
Sim — todas as faturas via Portal das Finanças (AT) com IVA 23%. Formato SAF-T PT, certificado pela AT, com ATCUD e código QR obrigatórios.
Como gerem retries de webhooks?
Backoff exponencial: 1m, 5m, 15m, 1h, 6h, 24h. Após 6 falhas a subscrição é pausada e enviamos email de alerta. Assinados com HMAC-SHA256 no header X-Corp-Signature.