Documentação
Start typing to search…

Primeiros Passos

📚 Índice

Introdução

Bem-vindo ao Document Hub! Este guia vai ajudá-lo a começar a usar a API rapidamente.

O que é o Document Hub?

O Document Hub é uma API REST para armazenamento e gerenciamento de documentos JSON. Ele oferece:

  • 🗂️ Organização hierárquica: Cliente → Ambiente → Contexto → Tipo → Documento
  • 📝 Versionamento automático: Histórico completo de todas as alterações
  • ✅ Validação de dados: Usando JSON Schema
  • 🔔 Notificações em tempo real: Via webhooks
  • 🔐 Controle de acesso granular: Sistema de tokens com permissões específicas
  • 🔍 Busca avançada: Filtros poderosos para encontrar documentos

Para quem é o Document Hub?

  • Desenvolvedores que precisam armazenar dados JSON de forma estruturada
  • Equipes que necessitam de multi-tenancy (isolamento por cliente)
  • Aplicações que requerem versionamento e histórico de alterações
  • Sistemas que precisam de notificações em tempo real via webhooks

Conceitos Fundamentais

1. Cliente (Client)

Um cliente representa uma organização ou tenant no sistema. Cada cliente é completamente isolado dos demais.

  • Identificador: UUID (ex: 9fc42fe9-a4fd-443c-8d49-b85ece2151b9)
  • Uso: Segregar dados entre diferentes empresas/projetos

2. Ambiente (Environment)

Ambientes permitem separar dados por contexto de execução.

Exemplos comuns:

  • production - Dados de produção
  • staging - Dados de homologação
  • development - Dados de desenvolvimento
  • testing - Dados de testes

3. Contexto (Context)

O contexto representa o domínio de negócio ou módulo da aplicação.

Exemplos:

  • orders - Pedidos
  • customers - Clientes
  • invoices - Faturas
  • products - Produtos
  • users - Usuários

4. Tipo (Type)

O tipo especifica a categoria do documento dentro de um contexto.

Exemplos no contexto orders:

  • invoice - Fatura
  • receipt - Recibo
  • quote - Orçamento

5. Chave (Key)

A chave é o identificador único do documento dentro de seu escopo (cliente/ambiente/contexto/tipo).

Exemplos:

  • INV-001, INV-002 - Faturas
  • user-123, user-456 - Usuários
  • order-2024-001 - Pedidos

6. Documento (Document)

O documento é o objeto JSON que contém os dados reais.

Estrutura:

{
  "id": "uuid-do-documento",
  "client_id": "uuid-do-cliente",
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "key": "INV-001",
  "data": {
    "customer": "Empresa XYZ",
    "amount": 1500.00,
    "items": [...]
  },
  "version": 1,
  "created_at": "2024-01-15 10:30:00",
  "updated_at": "2024-01-15 10:30:00",
  "expires_at": null
}

Estrutura Hierárquica

A API organiza documentos em uma estrutura hierárquica para facilitar organização e busca:

┌─────────────────────────────────────────────────────────┐
│ Cliente: 9fc42fe9-a4fd-443c-8d49-b85ece2151b9          │
└─────────────────────────────────────────────────────────┘
                          │
      ┌───────────────────┼───────────────────┐
      │                   │                   │
┌─────▼──────┐   ┌───────▼────────┐  ┌──────▼───────┐
│ production │   │    staging     │  │ development  │
└─────┬──────┘   └────────────────┘  └──────────────┘
      │
      ├─── orders
      │     ├─── invoice
      │     │     ├─── INV-001
      │     │     ├─── INV-002
      │     │     └─── INV-003
      │     └─── quote
      │           ├─── QUO-001
      │           └─── QUO-002
      │
      └─── customers
            └─── client
                  ├─── CUST-001
                  └─── CUST-002

Padrão de URL

Todos os endpoints de documentos seguem este padrão:

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

Exemplo completo:

https://document-hub-api-xp.wake.tech/api/v1/client/9fc42fe9-a4fd-443c-8d49-b85ece2151b9/production/context/orders/type/invoice/INV-001

Criando seu Primeiro Documento

Agora que você tem um cliente e um token, vamos criar seu primeiro documento!

1. Defina a Estrutura

Vamos criar uma fatura no contexto de pedidos:

  • Cliente: {CLIENT_ID} (o UUID que você recebeu)
  • Ambiente: production
  • Contexto: orders
  • Tipo: invoice
  • Chave: INV-001

2. Faça a 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_name": "Empresa XYZ Ltda",
      "customer_document": "12.345.678/0001-90",
      "issue_date": "2024-01-15",
      "due_date": "2024-02-15",
      "amount": 1500.00,
      "currency": "BRL",
      "status": "pending",
      "items": [
        {
          "description": "Serviço de Consultoria",
          "quantity": 10,
          "unit_price": 150.00,
          "total": 1500.00
        }
      ],
      "notes": "Pagamento via transferência bancária"
    }
  }'

3. Resposta Esperada (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",
    "customer_document": "12.345.678/0001-90",
    "issue_date": "2024-01-15",
    "due_date": "2024-02-15",
    "amount": 1500.00,
    "currency": "BRL",
    "status": "pending",
    "items": [
      {
        "description": "Serviço de Consultoria",
        "quantity": 10,
        "unit_price": 150.00,
        "total": 1500.00
      }
    ],
    "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
}

4. Recupere o Documento

Agora vamos buscar o documento que acabamos de criar:

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}"

5. Atualize o Documento

Vamos atualizar o status da fatura para "pago":

curl -X PUT "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_name": "Empresa XYZ Ltda",
      "customer_document": "12.345.678/0001-90",
      "issue_date": "2024-01-15",
      "due_date": "2024-02-15",
      "amount": 1500.00,
      "currency": "BRL",
      "status": "paid",
      "payment_date": "2024-01-20",
      "items": [
        {
          "description": "Serviço de Consultoria",
          "quantity": 10,
          "unit_price": 150.00,
          "total": 1500.00
        }
      ],
      "notes": "Pagamento via transferência bancária"
    }
  }'

Observação: A versão do documento será automaticamente incrementada para 2.

6. Liste os Documentos

Para listar todas as faturas:

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

7. Veja o Histórico

Para ver todas as versões do documento:

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

Exemplos Práticos Adicionais

Criar Documento com TTL (Expiração)

Útil para dados temporários como sessões ou cache:

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 {SEU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "cache",
    "type": "session",
    "key": "user-123",
    "data": {
      "user_id": 123,
      "session_token": "xyz789abc",
      "ip_address": "192.168.1.1",
      "last_activity": "2024-01-15T10:30:00Z"
    },
    "ttl": 3600
  }'

O documento expirará em 3600 segundos (1 hora).

Criar Documento com Data de Expiração Específica

curl -X POST "https://document-hub-api-xp.wake.tech/api/v1/client/{CLIENT_ID}/production/context/promotions/type/coupon/SUMMER2024" \
  -H "Authorization: Bearer {SEU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": "promotions",
    "type": "coupon",
    "key": "SUMMER2024",
    "data": {
      "code": "SUMMER2024",
      "discount_percentage": 20,
      "min_purchase": 100.00,
      "max_discount": 50.00
    },
    "expires_at": "2024-03-31T23:59:59Z"
  }'

Buscar com Filtros

Buscar faturas pagas com valor maior que R$ 1.000:

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

Testando com a Interface Swagger

A API possui uma interface Swagger para testar endpoints interativamente:

  1. Acesse: <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>
  2. Clique em "Authorize" no topo
  3. Digite seu token no formato: {TOKEN_ID}|{PLAIN_TEXT_TOKEN}
  4. Explore e teste os endpoints

Troubleshooting

Erro 401 - Unauthorized

Causa: Token inválido ou expirado

Solução:

  • Verifique se o token está correto
  • Verifique se não expirou
  • Certifique-se de usar o formato: Authorization: Bearer {TOKEN}

Erro 403 - Forbidden

Causa: Token válido mas sem permissão para a operação

Solução:

  • Verifique os escopos do token
  • Crie um novo token com as permissões necessárias

Erro 404 - Not Found

Causa: Documento ou recurso não encontrado

Solução:

  • Verifique se os parâmetros da URL estão corretos
  • Verifique se o documento realmente existe

Erro 409 - Conflict

Causa: Tentativa de criar documento que já existe

Solução:

  • Use PUT para atualizar ao invés de POST para criar
  • Ou use uma chave diferente

Erro 422 - Validation Failed

Causa: Dados não passaram na validação (geralmente schema)

Solução:

  • Verifique a mensagem de erro para detalhes
  • Corrija os dados conforme o schema definido

Updated 3 days ago

What’s Next