Visão Geral da REST API v1

URL base: /wp-json/middag-account/v1/

A REST API do middag-account expõe 79 endpoints em 18 grupos. Todos os endpoints utilizam a infraestrutura de REST API do WordPress com permission_callback em toda rota.

Métodos de Autenticação

A API suporta autenticação tripla dependendo do contexto:

Método	Header / Mecanismo	Utilizado Por
JWT RS256	Authorization: Bearer {token}	Portal, mobile, terceiros
WordPress Nonce	X-WP-Nonce baseado em cookie	wp-admin (Inertia UI)
WC API Keys	Consumer key + secret (nativo WooCommerce)	Integrações WooCommerce

Detalhes do JWT

• Algoritmo: RS256 (RSA + SHA-256). Nunca HS256.
• TTL do access token: 24 horas
• TTL do refresh token: 7 dias (rotacao obrigatoria)
• Chave privada armazenada fora do webroot
• Campos do payload no nivel raiz: sub, org, roles, scopes, company

{
    "sub": 42,
    "org": 15,
    "roles": [
        "admin"
    ],
    "scopes": [
        "organization",
        "finances",
        "orders"
    ],
    "company": "middag_br",
    "iat": 1714200000,
    "exp": 1714286400
}

Headers Obrigatórios

Header	Direção	Obrigatório	Valor
Authorization	Request	Sim *	Bearer {jwt_token}
X-Middag-Organization	Request	Sim **	ID da organização (int)
X-Middag-Company	Request	Não	middag_br ou middag_global
Content-Type	Request	Sim (POST/PUT)	application/json

* Exceto /auth/login, /auth/register e outros endpoints publicos. ** Exceto endpoints que não operam com dados de escopo organizacional.

Envelope de Resposta

Todo endpoint retorna um envelope JSON consistente:

{
    "success": true,
    "data": {},
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 100,
        "pages": 5
    },
    "message": null,
    "errors": null
}

Campo	Tipo	Sempre Presente	Descrição
success	boolean	Sim	true para 2xx, false para erros
data	`object	array`	Sim
meta	`object	null`	Sim
message	`string	null`	Sim
errors	`object	null`	Sim

Paginação

Endpoints de listagem aceitam estes parâmetros de query:

Parâmetro	Tipo	Padrão	Descrição
page	int	1	Pagina atual
per_page	int	20	Itens por pagina (max: 100)
order	string	desc	Direção de ordenação: asc ou desc
orderby	string	created_at	Campo de ordenação
search	string	--	Busca textual (quando suportado)

Códigos de Erro

Código	HTTP	Quando
VALIDATION_ERROR	422	Campos de entrada invalidos
AUTHENTICATION_ERROR	401	Token ausente, expirado ou inválido
AUTHORIZATION_ERROR	403	Permissões insuficientes
NOT_FOUND	404	Recurso não existe
CONFLICT	409	Estado conflitante
RATE_LIMIT	429	Limite de requisicoes excedido
INTERNAL_ERROR	500	Erro inesperado no servidor

Exemplo de Resposta de Erro

{
    "success": false,
    "data": null,
    "meta": null,
    "message": "Validation failed",
    "errors": {
        "code": "VALIDATION_ERROR",
        "fields": {
            "email": [
                "Email is required"
            ],
            "name": [
                "Name must be at least 2 characters"
            ]
        }
    }
}

Rate Limiting

Endpoint	Limite	Janela	Por
/auth/login	5	1 minuto	IP
/auth/register	3	1 minuto	IP
/auth/forgot-password	3	5 minutos	IP
/auth/resend-verification	3	5 minutos	Email
/auth/refresh	10	1 minuto	User ID
Outros endpoints autenticados	60	1 minuto	User ID

Requisicoes excedidas recebem HTTP 429 com um header Retry-After.

Pipeline de Middleware

Toda requisição autenticada passa por esta cadeia de middleware em ordem:

1. AuthMiddleware -- Extrair e validar JWT, definir WP_User no contexto da requisição
2. PermissionsMiddleware -- Validar cargo e escopos contra os requisitos da rota
3. OrganizationMiddleware -- Validar header X-Middag-Organization e associação
4. CompanyMiddleware -- Validar header X-Middag-Company (se a rota tem escopo de empresa)

Contrato de Estabilidade

A REST API v1 garante nenhuma quebra de compatibilidade dentro da v1. Novos endpoints são aditivos. Campos existentes nunca são removidos. Deprecação vem com 6 meses de aviso previo.

Grupos de Endpoints

Grupo	Endpoints	Referência
Auth	12	/auth/*
Organizations	7	organizations.md
Collaborators	8	collaborators.md
Entitlements	6	entitlements.md
Orders	4	orders.md
Invoices	4	invoices.md
Tax Invoices	4	invoices.md
Quotes	5	quotes.md
Licenses	4	licenses.md
Contracts	3	contracts.md
Environments	4	environments.md
Services	3	services.md
Service Requests	4	services.md
Documents	3	--
Downloads	2	--
Affiliates	2	--
Admin	2	--
Webhooks	2	--