API HTTP — AMPLIA
Última atualização: 16/09/2026.
Não há front controller: cada arquivo em backend/api/ é um endpoint.
Catálogo completo: endpoints.md. Máquina:
openapi.yaml.
Base
| Prefixo | {APP_URL}/backend/api/ |
| Formato | JSON UTF-8 (Content-Type: application/json) |
| Sessão | cookie PHP (httponly, SameSite=Lax) |
| CSRF | header X-CSRF-Token (ou campo csrf_token) em mutações |
| Auth alternativa | token em financeiro_api_tokens (só API externa de comissões) |
| Webhook | X-Autentique-Signature |
Obter CSRF (sessão já aberta ou login): GET /backend/api/auth/csrf-token.php.
O JS (frontend/assets/js/core/csrf.js) injeta o header em fetch/jQuery.
Envelope
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"success","message":"…","data":{}}
Erro:
{"status":"error","message":"…","code":"db_connection_limit"}
O campo de payload não é 100% uniforme: módulos novos usam data; alguns
legado usam dados ou chaves soltas (permissoes, csrf_token). O OpenAPI
documenta o mais comum; o arquivo PHP é a fonte da verdade.
Status HTTP
| Código | Quando |
|---|---|
| 200 | sucesso (mesmo em alguns erros legado que ainda devolvem 200 + status=error) |
| 400 | validação |
| 401 | sem sessão / token / HMAC |
| 403 | sem permissão, módulo desligado, CSRF |
| 405 | método fora da lista (backend_require_method) |
| 503 | health/banco |
Nem todo arquivo chama backend_require_method. Nesses casos o PHP
executa GET ou POST conforme o caller. A coluna “Método” em endpoints.md
usa o verbo intencional (pelo nome e pelo código); “enforced” diz se o
servidor rejeita os outros.
Autorização
- Bootstrap com
session => true(salvo exceções). backend_permission_require/assert_can/ helpers de módulo (backend_leads_*,backend_tasks_*,backend_users_require_auth).- Super-admin bypass em
backend_permission_user_can(). - Recorte de linhas por
white_label_id/ hierarquia.
Matriz flag × endpoint: permissoes-matriz-endpoints.md.
Público (sem sessão de operador)
| Método | Path | Auth |
|---|---|---|
| GET | /backend/api/health.php | nenhuma (não vaza senha; só has_db_password) |
| POST | /backend/api/auth/login.php | credencial + rate limit |
| POST | /backend/api/auth/forgot-password.php | |
| POST | /backend/api/auth/reset-password.php | token |
| POST | /backend/api/assinaturas/webhook.php | HMAC Autentique |
| GET | /backend/api/financeiro/external/comissoes.php | token de API + user_id |
Convenção de nomes
/backend/api/{modulo}/{recurso?}/{acao}.php
Exemplos: estabelecimentos/listar-locais.php, propostas/simulador/calcular.php.
Módulo novo (Tarefas/Comercial): endpoint fino, CSRF em POST, ensure_schema,
assert_module_enabled.
Eventos / AsyncAPI
Não há broker. O único “evento inbound” documentável é o webhook Autentique.
Polling: transacoes/polling.php e rotinas de credenciamento no serviço
(não há pasta api/estabelecimentos/credenciamento/ neste snapshot).
Como atualizar este contrato
- Criar o PHP em
backend/api. - Linha em api/endpoints.md e na matriz de permissões.
- Regenerar ou editar api/openapi.yaml.
- Se a decisão for estrutural (novo tipo de auth), abra um ADR.