Gestão de Documentos

📚 Índice

Introdução
Estrutura do Documento
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
TTL e Expiração
Soft Delete
Boas Práticas

Introdução

Este guia cobre todas as operações CRUD (Create, Read, Update, Delete) de documentos no Document Hub, além de recursos avançados como versionamento, operações em lote e soft delete.

Escopo Necessário

Para realizar operações com documentos, você precisa de um token com os seguintes escopos:

Operação	Escopo Requerido
Criar	`document:create`
Ler	`document:read`
Atualizar	`document:update`
Deletar	`document:delete`

Estrutura do Documento

Todo documento no Document Hub possui a seguinte estrutura:

{
  "id": "9fc43d2a-8e4f-4a3b-9d2e-1a2b3c4d5e6f",
  "client_id": "9fc42fe9-a4fd-443c-8d49-b85ece2151b9",
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "key": "INV-001",
  "data": {
    /* Seus dados JSON aqui */
  },
  "version": 1,
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z",
  "expires_at": null,
  "deleted_at": null
}

Campos do Documento

Campo	Tipo	Descrição
`id`	UUID	Identificador único do documento (gerado automaticamente)
`client_id`	UUID	ID do cliente proprietário
`environment`	string	Ambiente (production, staging, etc.)
`context`	string	Contexto de negócio (orders, customers, etc.)
`type`	string	Tipo do documento (invoice, receipt, etc.)
`key`	string	Chave única dentro do escopo
`data`	object	Objeto JSON com os dados do documento
`version`	integer	Versão atual do documento (incrementa a cada atualização)
`created_at`	timestamp	Data/hora de criação
`updated_at`	timestamp	Data/hora da última atualização
`expires_at`	timestamp	Data/hora de expiração (opcional)
`deleted_at`	timestamp	Data/hora de exclusão (soft delete)

Criar Documentos (CREATE)

Endpoint

POST /api/v1/client/{client}/{environment}/context/{context}/type/{type}/{key}

Headers Necessários

Authorization: Bearer {SEU_TOKEN}
Content-Type: application/json

Body da Requisição

{
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "key": "INV-001",
  "data": {
    /* Seus dados aqui */
  }
}

⚠️ IMPORTANTE: Os valores de environment, context, type e key no body devem corresponder exatamente aos valores na URL. Isso é uma validação de segurança.

Exemplo Completo

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/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": {
        "name": "Empresa XYZ Ltda",
        "document": "12.345.678/0001-90",
        "email": "[email protected]"
      },
      "invoice_number": "2024/001",
      "issue_date": "2024-01-15",
      "due_date": "2024-02-15",
      "amount": 1500.00,
      "currency": "BRL",
      "status": "pending",
      "items": [
        {
          "id": 1,
          "description": "Serviço de Consultoria",
          "quantity": 10,
          "unit_price": 150.00,
          "subtotal": 1500.00
        }
      ],
      "payment": {
        "method": "bank_transfer",
        "bank": "Banco do Brasil",
        "agency": "1234",
        "account": "56789-0"
      },
      "notes": "Pagamento via transferência bancária"
    }
  }'

Resposta de Sucesso (201 Created)

{
  "id": "9fc43d2a-8e4f-4a3b-9d2e-1a2b3c4d5e6f",
  "client_id": "9fc42fe9-a4fd-443c-8d49-b85ece2151b9",
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "key": "INV-001",
  "data": {
    "customer": {
      "name": "Empresa XYZ Ltda",
      "document": "12.345.678/0001-90",
      "email": "[email protected]"
    },
    "invoice_number": "2024/001",
    "issue_date": "2024-01-15",
    "due_date": "2024-02-15",
    "amount": 1500.00,
    "currency": "BRL",
    "status": "pending",
    "items": [...],
    "payment": {...},
    "notes": "Pagamento via transferência bancária"
  },
  "version": 1,
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z",
  "expires_at": null
}

Erros Comuns

Código	Motivo	Solução
`400`	Parâmetros da URL não correspondem ao body	Certifique-se de que environment, context, type e key são iguais
`401`	Token inválido	Verifique seu token
`403`	Sem permissão `document:create`	Use um token com o escopo correto
`409`	Documento já existe	Use PUT para atualizar ou escolha outra key
`422`	Validação de schema falhou	Corrija os dados conforme o schema definido

Ler Documentos (READ)

Obter Um Documento Específico

Endpoint

GET /api/v1/client/{client}/{environment}/context/{context}/type/{type}/{key}

Exemplo

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Resposta (200 OK)

Retorna o documento completo no formato descrito anteriormente.

Incluir Documentos Deletados

Por padrão, documentos deletados (soft delete) não aparecem. Para incluí-los:

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001?deleted=true" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Atualizar Documentos (UPDATE)

Endpoint

PUT /api/v1/client/{client}/{environment}/context/{context}/type/{type}/{key}

Como Funciona

Quando você atualiza um documento:

📸 O estado atual é salvo no histórico
🔢 A versão é incrementada automaticamente
💾 Os novos dados são salvos
🔔 Um evento document.updated é disparado (para webhooks)

Exemplo

curl -X PUT "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/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": {
        "name": "Empresa XYZ Ltda",
        "document": "12.345.678/0001-90",
        "email": "[email protected]"
      },
      "invoice_number": "2024/001",
      "issue_date": "2024-01-15",
      "due_date": "2024-02-15",
      "amount": 1500.00,
      "currency": "BRL",
      "status": "paid",
      "payment_date": "2024-01-20",
      "items": [...],
      "payment": {...},
      "notes": "Pagamento recebido via transferência"
    }
  }'

Resposta (200 OK)

Retorna o documento atualizado com a versão incrementada:

{
  "id": "9fc43d2a-8e4f-4a3b-9d2e-1a2b3c4d5e6f",
  "version": 2,
  "updated_at": "2024-01-20T14:45:00.000000Z",
  ...
}

Otimização de Performance

O sistema detecta automaticamente se houve mudanças reais nos dados. Se você enviar os mesmos dados, nenhuma versão nova será criada.

Deletar Documentos (DELETE)

Endpoint

DELETE /api/v1/client/{client}/{environment}/context/{context}/type/{type}/{key}

Como Funciona (Soft Delete)

O Document Hub usa soft delete por padrão:

✅ O documento não é removido fisicamente
✅ O campo deleted_at é preenchido
✅ O documento deixa de aparecer em buscas normais
✅ Pode ser recuperado se necessário
🔔 Um evento document.deleted é disparado

Exemplo

curl -X DELETE "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Resposta (200 OK)

{
  "message": "Document deleted successfully"
}

Ver Documentos Deletados

Para buscar documentos deletados, use o parâmetro deleted=true:

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001?deleted=true" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Listagem e Paginação

Endpoint

GET /api/v1/client/{client}/{environment}/context/{context}/type/{type}

Note que o {key} é omitido para listar todos os documentos de um tipo.

Exemplo Básico

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Resposta Paginada

{
  "current_page": 1,
  "data": [
    {
      "id": "9fc43d2a-...",
      "client_id": "9fc42fe9-...",
      "environment": "production",
      "context": "orders",
      "type": "invoice",
      "key": "INV-001",
      "data": {...},
      "version": 2,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-20T14:45:00.000000Z"
    },
    {
      "id": "9fc43d2b-...",
      "key": "INV-002",
      ...
    }
  ],
  "first_page_url": "https://api.../invoice?page=1",
  "from": 1,
  "last_page": 10,
  "last_page_url": "https://api.../invoice?page=10",
  "links": [...],
  "next_page_url": "https://api.../invoice?page=2",
  "path": "https://api.../invoice",
  "per_page": 15,
  "prev_page_url": null,
  "to": 15,
  "total": 150
}

Parâmetros de Paginação

# Página 2
curl -X GET "https://api.../invoice?page=2" \
  -H "Authorization: Bearer {TOKEN}"

# 50 itens por página
curl -X GET "https://api.../invoice?per_page=50" \
  -H "Authorization: Bearer {TOKEN}"

# Página 3 com 25 itens
curl -X GET "https://api.../invoice?page=3&per_page=25" \
  -H "Authorization: Bearer {TOKEN}"

Filtragem

Veja o Guia de Filtragem Avançada para detalhes completos.

Exemplo rápido:

# Faturas pagas com valor > 1000
curl -G "https://api.../invoice" \
  -H "Authorization: Bearer {TOKEN}" \
  --data-urlencode "filter[status]=paid" \
  --data-urlencode "filter[amount_gt]=1000"

Operações em Lote (BULK)

O endpoint bulk permite criar ou atualizar múltiplos documentos em uma única transação atômica.

Endpoint

POST /api/v1/client/{client}/{environment}/context/{context}/type/{type}/bulk

Como Funciona

✅ Transação atômica: Todos os documentos são processados ou nenhum é
✅ Upsert automático: Cria se não existe, atualiza se existe
✅ Versionamento: Versões são incrementadas automaticamente
✅ Eventos: Dispara document.created ou document.updated para cada documento

Exemplo

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/products/type/item/bulk" \
  -H "Authorization: Bearer {SEU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "key": "PROD-001",
        "data": {
          "name": "Notebook Dell",
          "price": 3500.00,
          "stock": 10
        }
      },
      {
        "key": "PROD-002",
        "data": {
          "name": "Mouse Logitech",
          "price": 150.00,
          "stock": 50
        }
      },
      {
        "key": "PROD-003",
        "data": {
          "name": "Teclado Mecânico",
          "price": 450.00,
          "stock": 25
        }
      }
    ]
  }'

Resposta (200 OK)

[
  {
    "id": "9fc43d2a-...",
    "key": "PROD-001",
    "version": 1,
    "data": {...},
    ...
  },
  {
    "id": "9fc43d2b-...",
    "key": "PROD-002",
    "version": 1,
    "data": {...},
    ...
  },
  {
    "id": "9fc43d2c-...",
    "key": "PROD-003",
    "version": 1,
    "data": {...},
    ...
  }
]

Validação de Schema

Se você tem um schema definido para o tipo de documento, todos os documentos no bulk serão validados. Se qualquer um falhar, a transação inteira é revertida.

Limite Recomendado

Embora não haja um limite técnico, recomendamos:

✅ Até 100 documentos por requisição bulk
✅ Para mais documentos, divida em múltiplas requisições

Histórico e Versionamento

Como Funciona

Toda vez que um documento é atualizado:

A versão atual é salva na tabela documents_history
O documento principal recebe os novos dados
O campo version é incrementado

Visualizar Histórico

Endpoint

GET /api/v1/client/{client}/{environment}/context/{context}/type/{type}/{key}/history

Exemplo

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001/history" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Resposta (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": "hist-123",
      "client_id": "9fc42fe9-...",
      "environment": "production",
      "context": "orders",
      "type": "invoice",
      "key": "INV-001",
      "data": {
        "status": "paid",
        "amount": 1500.00,
        ...
      },
      "version": 2,
      "created_at": "2024-01-20T14:45:00.000000Z"
    },
    {
      "id": "hist-122",
      "data": {
        "status": "pending",
        "amount": 1500.00,
        ...
      },
      "version": 1,
      "created_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "per_page": 15,
  "total": 2
}

As versões são retornadas em ordem decrescente (mais recente primeiro).

Restauração de Versões

Você pode restaurar qualquer versão anterior de um documento.

Endpoint

POST /api/v1/client/{client}/{environment}/context/{context}/type/{type}/{key}/history/{history_id}/restore

Como Funciona

A versão atual é salva no histórico
Os dados da versão selecionada são restaurados
A versão do documento é incrementada (não volta ao número antigo)

Exemplo

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001/history/hist-122/restore" \
  -H "Authorization: Bearer {SEU_TOKEN}"

Resposta (200 OK)

{
  "id": "9fc43d2a-...",
  "key": "INV-001",
  "data": {
    "status": "pending",
    ...
  },
  "version": 3,
  "updated_at": "2024-01-21T09:00:00.000000Z"
}

Note que a versão foi para 3 (não voltou para 1).

TTL e Expiração

Documentos podem ter um tempo de vida (TTL - Time To Live) definido.

Opção 1: TTL em Segundos

curl -X POST "https://api.../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": "abc123"
    },
    "ttl": 3600
  }'

O documento expirará em 3600 segundos (1 hora) a partir de agora.

Opção 2: Data/Hora Específica

curl -X POST "https://api.../promotions/type/coupon/SUMMER2024" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "promotions",
    "type": "coupon",
    "key": "SUMMER2024",
    "data": {
      "code": "SUMMER2024",
      "discount": 20
    },
    "expires_at": "2024-03-31T23:59:59Z"
  }'

O documento expirará em 31 de março de 2024 às 23:59:59.

Comportamento

⏰ Documentos expirados não são deletados automaticamente
✅ Eles permanecem no banco de dados
🔍 Você pode filtrá-los usando filter[expires_at_lt]=now
🗑️ Recomenda-se criar um job periódico para limpar documentos expirados

Soft Delete

O que é Soft Delete?

Soft delete significa que o documento não é removido fisicamente do banco de dados, apenas marcado como deletado.

Vantagens

✅ Recuperação: Documentos podem ser recuperados
✅ Auditoria: Histórico completo é mantido
✅ Conformidade: Atende requisitos legais de retenção de dados

Listar Apenas Deletados

curl -X GET "https://api.../invoice?deleted=true" \
  -H "Authorization: Bearer {TOKEN}"

Retorna apenas documentos deletados.

Incluir Deletados na Listagem

Por padrão, documentos deletados não aparecem. Para incluí-los:

curl -X GET "https://api.../invoice?deleted=true" \
  -H "Authorization: Bearer {TOKEN}"

Boas Práticas

1. Escolha de Keys

✅ Boas práticas:

Use IDs únicos e previsíveis: INV-001, ORDER-2024-001
Evite caracteres especiais
Seja consistente no formato

❌ Evite:

Keys muito longas (> 255 caracteres)
Caracteres especiais que precisam encoding (espaços, /, ?, etc.)
UUIDs se você não precisa deles (use identificadores mais legíveis)

2. Organização Hierárquica

✅ Boa organização:
production/
  └── orders/
       ├── invoice/
       ├── quote/
       └── receipt/

❌ Má organização:
production/
  └── all-documents/
       └── mixed-types/

3. Uso de Ambientes

✅ Separe por ambiente:
- production: Dados reais
- staging: Testes pré-produção
- development: Desenvolvimento
- testing: Testes automatizados

❌ Não misture:
- Não use production para testes
- Não use development para dados reais

4. Versionamento

✅ O versionamento é automático, você não precisa gerenciá-lo
✅ Use o histórico para auditoria
✅ Restaure versões quando necessário

5. Performance

# ✅ Bom: Busca específica
GET .../invoice/INV-001

# ❌ Ruim: Lista tudo sem filtros
GET .../invoice?per_page=10000

# ✅ Bom: Lista com filtros e paginação
GET .../invoice?filter[status]=paid&page=1&per_page=50

6. Bulk Operations

# ✅ Bom: Até 100 documentos
POST .../bulk
{ "documents": [ /* 50 documentos */ ] }

# ❌ Ruim: Muito grande
POST .../bulk
{ "documents": [ /* 10000 documentos */ ] }

7. TTL

Use TTL para:

✅ Sessões temporárias
✅ Cache
✅ Tokens temporários
✅ Promoções com data de término

8. Schemas

✅ Defina schemas para tipos importantes
✅ Valide dados críticos
✅ Use required fields
✅ Documente seus schemas

Exemplos Práticos Completos

Caso de Uso 1: Sistema de Pedidos

# 1. Criar pedido
curl -X POST "https://api.../production/context/orders/type/order/ORD-2024-001" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "orders",
    "type": "order",
    "key": "ORD-2024-001",
    "data": {
      "customer_id": "CUST-123",
      "status": "pending",
      "items": [
        {"product_id": "PROD-001", "quantity": 2, "price": 100.00}
      ],
      "total": 200.00,
      "created_by": "user-456"
    }
  }'

# 2. Atualizar status para "processing"
curl -X PUT "https://api.../production/context/orders/type/order/ORD-2024-001" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "orders",
    "type": "order",
    "key": "ORD-2024-001",
    "data": {
      "customer_id": "CUST-123",
      "status": "processing",
      "items": [
        {"product_id": "PROD-001", "quantity": 2, "price": 100.00}
      ],
      "total": 200.00,
      "created_by": "user-456",
      "processed_at": "2024-01-15T14:30:00Z",
      "processed_by": "user-789"
    }
  }'

# 3. Listar todos os pedidos em processamento
curl -G "https://api.../production/context/orders/type/order" \
  -H "Authorization: Bearer {TOKEN}" \
  --data-urlencode "filter[status]=processing"

# 4. Ver histórico do pedido
curl -X GET "https://api.../production/context/orders/type/order/ORD-2024-001/history" \
  -H "Authorization: Bearer {TOKEN}"

Caso de Uso 2: Cache com TTL

# Criar entrada de cache que expira em 5 minutos
curl -X POST "https://api.../production/context/cache/type/api-response/user-123-profile" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "cache",
    "type": "api-response",
    "key": "user-123-profile",
    "data": {
      "user_id": 123,
      "name": "João Silva",
      "email": "[email protected]",
      "cached_at": "2024-01-15T10:00:00Z"
    },
    "ttl": 300
  }'

Caso de Uso 3: Importação em Massa

# Importar 50 produtos de uma vez
curl -X POST "https://api.../production/context/catalog/type/product/bulk" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "key": "PROD-001",
        "data": {"name": "Produto 1", "price": 10.00, "stock": 100}
      },
      {
        "key": "PROD-002",
        "data": {"name": "Produto 2", "price": 20.00, "stock": 50}
      }
      /* ... mais 48 produtos ... */
    ]
  }'