DOCUMENTAÇÃO AINDA EM CONSTRUÇÃO

📚 Índice Geral da Documentação

Este documento serve como índice para toda a documentação da API do Document Hub. A documentação foi dividida em módulos para facilitar a navegação e proporcionar detalhes aprofundados sobre cada funcionalidade.

🎯 Visão Geral

O Document Hub é uma API REST robusta para gerenciamento de documentos JSON multi-tenant. Oferece recursos avançados de:

• ✅ Armazenamento hierárquico de documentos
• ✅ Versionamento automático com histórico completo
• ✅ Validação de esquema JSON Schema
• ✅ Sistema de webhooks para notificações
• ✅ Autenticação baseada em tokens com escopos granulares
• ✅ Filtragem avançada de dados
• ✅ Soft delete e recuperação de documentos

📖 Documentação por Módulo

1. Primeiros Passos

• Introdução ao Document Hub
• Conceitos fundamentais
• Estrutura hierárquica
• Como criar seu primeiro cliente
• Como criar seu primeiro documento

2. Gestão de Documentos

• Criar documentos (CREATE)
• Ler documentos (READ)
• Atualizar documentos (UPDATE)
• Deletar documentos (DELETE)
• Listagem e paginação
• Operações em lote (BULK)
• Histórico e versionamento
• Restauração de versões anteriores
• TTL e expiração de documentos
• Soft delete e recuperação

3. Sistema de Tokens e Autenticação

• Como funciona a autenticação
• Tipos de escopos disponíveis
• Escopos simples vs. granulares
• Regras de documentos específicas
• Criar tokens
• Listar tokens
• Atualizar tokens
• Revogar tokens
• Boas práticas de segurança

4. Esquemas JSON (Schemas)

• O que são esquemas JSON
• JSON Schema v4+
• Criar/atualizar esquemas
• Obter esquemas
• Deletar esquemas
• Validação automática de documentos
• Exemplos práticos
• Casos de uso avançados

5. Webhooks

• Como funcionam os webhooks
• Eventos disponíveis
• Criar webhooks
• Listar webhooks
• Atualizar webhooks
• Deletar webhooks
• Formato do payload
• Sistema de retry
• Dead Letter Queue
• Segurança e verificação

6. Filtragem Avançada

• Filtros em campos do modelo
• Filtros em campos JSON
• Operadores de comparação
• Filtros combinados
• Filtragem de datas
• Filtragem numérica

7. Referência Completa da API

• Todos os endpoints disponíveis
• Parâmetros de cada endpoint
• Códigos de resposta HTTP
• Exemplos de requisição/resposta
• Headers necessários
• Tratamento de erros

🚀 Quick Start

1. Crie um Cliente

php artisan client:create --name="Minha Empresa" --full-access

Isso retornará um token de acesso. Guarde-o em local seguro!

2. Faça sua Primeira Requisição

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/{CLIENT_ID}/production/context/orders/type/invoice/INV-001" \
  -H "Authorization: Bearer {SEU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "orders",
    "type": "invoice",
    "key": "INV-001",
    "data": {
      "customer": "Empresa XYZ",
      "amount": 1500.00,
      "status": "pending"
    }
  }'

3. Recupere o Documento

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/{CLIENT_ID}/production/context/orders/type/invoice/INV-001" \
  -H "Authorization: Bearer {SEU_TOKEN}"

🏗️ Estrutura Hierárquica

A API organiza documentos em uma estrutura hierárquica:

Cliente (UUID)
└── Ambiente (environment)
    └── Contexto (context)
        └── Tipo (type)
            └── Documento (key)

Exemplo:

9fc42fe9-a4fd-443c-8d49-b85ece2151b9 (cliente)
└── production (ambiente)
    └── orders (contexto)
        └── invoice (tipo)
            ├── INV-001 (documento)
            ├── INV-002 (documento)
            └── INV-003 (documento)

🔐 Autenticação

Todas as requisições à API (exceto /api/health e /api/) requerem autenticação via Bearer Token:

Authorization: Bearer {TOKEN_ID}|{PLAIN_TEXT_TOKEN}

Exemplo:

Authorization: Bearer 9fc42fe9-1234-5678-9abc-def123456789|abcdef1234567890abcdef1234567890abcdef12

📊 Escopos de Permissão

🌐 URL Base da API

https://document-hub-api-xp.wake.tech/api/v1

📝 Formato de Dados

• Content-Type: application/json
• Accept: application/json
• Todas as respostas são em formato JSON
• Datas no formato ISO 8601: YYYY-MM-DD HH:MM:SS

⚡ Rate Limiting

A API implementa rate limiting para prevenir abuso:

• Requisições gerais: 1000 por minuto
• Endpoints de autenticação: 60 por minuto

Headers de resposta incluem:

• X-RateLimit-Limit: Limite total
• X-RateLimit-Remaining: Requisições restantes
• X-RateLimit-Reset: Timestamp de reset

🔍 Paginação

Endpoints que retornam listas são paginados automaticamente:

{
  "current_page": 1,
  "data": [...],
  "first_page_url": "https://...",
  "from": 1,
  "last_page": 10,
  "last_page_url": "https://...",
  "next_page_url": "https://...",
  "path": "https://...",
  "per_page": 15,
  "prev_page_url": null,
  "to": 15,
  "total": 150
}

Parâmetros de paginação:

• page: Número da página (padrão: 1)
• per_page: Itens por página (padrão: 15)

🚨 Códigos de Resposta HTTP

📚 Documentação Interativa

A API possui documentação Swagger/OpenAPI interativa:

• Swagger UI: <Anchor label="https://document-hub-api-xp.wake.tech/api/docs" target="_blank" href="https://document-hub-api-xp.wake.tech/api/docs">https://document-hub-api-xp.wake.tech/api/docs</Anchor>
• OpenAPI JSON: <Anchor label="https://document-hub-api-xp.wake.tech/api/openapi.json" target="_blank" href="https://document-hub-api-xp.wake.tech/api/openapi.json">https://document-hub-api-xp.wake.tech/api/openapi.json</Anchor>

💡 Exemplos Práticos

Criar um Documento com TTL

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/{CLIENT_ID}/production/context/cache/type/session/user-123" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "cache",
    "type": "session",
    "key": "user-123",
    "data": {
      "user_id": 123,
      "session_token": "xyz789",
      "ip": "192.168.1.1"
    },
    "ttl": 3600
  }'

Buscar Documentos com Filtros

curl -G "https://document-hub-api-xp.wake.tech/api/v1/client/{CLIENT_ID}/production/context/orders/type/invoice" \
  -H "Authorization: Bearer {TOKEN}" \
  --data-urlencode "filter[amount_gt]=1000" \
  --data-urlencode "filter[status]=paid"

Criar Token com Permissões Granulares

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/{CLIENT_ID}/tokens" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Token Faturas Produção",
    "scopes": {
      "document_rules": [
        {
          "environment": "production",
          "context": "invoices",
          "permissions": ["document:read", "document:update"]
        }
      ]
    }
  }'

🛠️ SDKs e Ferramentas

cURL

Todos os exemplos desta documentação utilizam cURL por ser universal.

Postman

Importe o OpenAPI JSON no Postman:

1. File → Import
2. Cole a URL: `https://document-hub-api-xp.wake.tech/api/openapi.json

Insomnia

Similar ao Postman, suporta importação de OpenAPI.

🆘 Suporte e Recursos

• Documentação: Esta documentação completa
• Swagger UI: Interface interativa para testar endpoints
• Issues: Reporte bugs no repositório
• Logs: storage/logs/laravel.log

📜 Versionamento

A API utiliza versionamento na URL:

• Versão atual: v1
• URL Base: /api/v1/...

Mudanças breaking criarão novas versões (v2, v3, etc.)