📚 Índice

Informações Gerais
Autenticação
Endpoints - Documentos
Endpoints - Tokens
Endpoints - Schemas
Endpoints - Webhooks
Códigos de Resposta HTTP
Erros e Tratamento
Rate Limiting
Paginação

Informações Gerais

URL Base

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

Formato de Dados

Content-Type: application/json
Accept: application/json
Charset: UTF-8
Datas: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)

Versionamento

A API utiliza versionamento na URL:

Versão atual: v1
URL base: /api/v1/...

Autenticação

Header de Autenticação

Authorization: Bearer {TOKEN_ID}|{PLAIN_TEXT_TOKEN}

Exemplo:

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

Métodos Alternativos

X-Client-Key: {TOKEN_ID}
X-Client-Token: {PLAIN_TEXT_TOKEN}

Endpoints - Documentos

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

Cria um novo documento.

Parâmetros de URL

Parâmetro	Tipo	Descrição
`client`	UUID	ID do cliente
`environment`	string	Ambiente (production, staging, etc.)
`context`	string	Contexto de negócio
`type`	string	Tipo do documento
`key`	string	Chave única do documento

Headers

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

Escopo Necessário

document:create

Body

{
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "key": "INV-001",
  "data": {
    /* seus dados JSON */
  },
  "expires_at": "2025-12-31T23:59:59Z",
  "ttl": 3600
}

Campo	Tipo	Obrigatório	Descrição
`environment`	string	Sim	Deve corresponder à URL
`context`	string	Sim	Deve corresponder à URL
`type`	string	Sim	Deve corresponder à URL
`key`	string	Sim	Deve corresponder à URL
`data`	object	Sim	Dados do documento (JSON)
`expires_at`	timestamp	Não	Data de expiração
`ttl`	integer	Não	Tempo de vida em segundos

Response (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": { /* seus dados */ },
  "version": 1,
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z",
  "expires_at": null
}

Possíveis Erros

Código	Descrição
400	Parâmetros da URL não correspondem ao body
401	Token inválido
403	Sem permissão `document:create`
409	Documento já existe
422	Validação de schema falhou

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

Obtém um documento específico.

Parâmetros de URL

Parâmetro	Tipo	Descrição
`client`	UUID	ID do cliente
`environment`	string	Ambiente
`context`	string	Contexto
`type`	string	Tipo
`key`	string	Chave do documento

Query Parameters

Parâmetro	Tipo	Descrição
`deleted`	boolean	Incluir documentos deletados (soft delete)

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

document:read

Request

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

Response (200 OK)

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

Possíveis Erros

Código	Descrição
401	Token inválido
403	Sem permissão `document:read`
404	Documento não encontrado

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

Atualiza um documento existente.

Parâmetros de URL

Mesmos do GET.

Headers

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

Escopo Necessário

document:update

Body

{
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "key": "INV-001",
  "data": {
    /* novos dados */
  },
  "expires_at": "2025-12-31T23:59:59Z",
  "ttl": 3600
}

Response (200 OK)

Retorna o documento atualizado com a versão incrementada.

Possíveis Erros

Código	Descrição
400	Parâmetros da URL não correspondem ao body
401	Token inválido
403	Sem permissão `document:update`
404	Documento não encontrado
422	Validação de schema falhou

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

Deleta um documento (soft delete).

Parâmetros de URL

Mesmos do GET.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

document:delete

Request

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

Response (200 OK)

{
  "message": "Document deleted successfully"
}

Possíveis Erros

Código	Descrição
401	Token inválido
403	Sem permissão `document:delete`
404	Documento não encontrado

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

Lista documentos com paginação.

Parâmetros de URL

Mesmos do GET, mas sem {key}.

Query Parameters

Parâmetro	Tipo	Descrição
`page`	integer	Número da página (padrão: 1)
`per_page`	integer	Itens por página (padrão: 15)
`deleted`	boolean	Incluir documentos deletados
`filter[campo]`	mixed	Filtrar por campo (ver guia de filtragem)
`filter[campo_gt]`	mixed	Campo maior que
`filter[campo_gte]`	mixed	Campo maior ou igual
`filter[campo_lt]`	mixed	Campo menor que
`filter[campo_lte]`	mixed	Campo menor ou igual
`filter[campo_neq]`	mixed	Campo diferente de
`filter[campo_like]`	string	Campo contém string

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

document:read

Request

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[status]=paid" \
  --data-urlencode "filter[amount_gt]=1000" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=50"

Response (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": "9fc43d2a-...",
      "key": "INV-001",
      "data": { /* dados */ },
      ...
    },
    {
      "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": [
    {"url": null, "label": "&laquo; Previous", "active": false},
    {"url": "https://api.../invoice?page=1", "label": "1", "active": true},
    {"url": "https://api.../invoice?page=2", "label": "2", "active": false},
    {"url": "https://api.../invoice?page=2", "label": "Next &raquo;", "active": false}
  ],
  "next_page_url": "https://api.../invoice?page=2",
  "path": "https://api.../invoice",
  "per_page": 15,
  "prev_page_url": null,
  "to": 15,
  "total": 150
}

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

Cria ou atualiza múltiplos documentos em lote.

Parâmetros de URL

Mesmos do GET (sem {key}).

Headers

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

Escopo Necessário

document:create e document:update

Body

{
  "documents": [
    {
      "key": "PROD-001",
      "data": {
        "name": "Produto 1",
        "price": 100.00
      }
    },
    {
      "key": "PROD-002",
      "data": {
        "name": "Produto 2",
        "price": 200.00
      }
    }
  ]
}

Response (200 OK)

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

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

Obtém o histórico de versões de um documento.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

document:read

Query Parameters

Parâmetro	Tipo	Descrição
`page`	integer	Número da página
`per_page`	integer	Itens por página

Response (200 OK)

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

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

Restaura uma versão anterior do documento.

Parâmetros de URL

Parâmetro	Tipo	Descrição
`history_id`	integer	ID da versão no histórico

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

document:update

Response (200 OK)

Retorna o documento com os dados restaurados e versão incrementada.

Endpoints - Tokens

GET `/api/v1/client/{client}/tokens`

Lista todos os tokens do cliente.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

token:manage

Query Parameters

Parâmetro	Tipo	Descrição
`page`	integer	Número da página
`per_page`	integer	Itens por página

Response (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": "9fc42fe9-1234-...",
      "client_id": "9fc42fe9-a4fd-...",
      "name": "Token Admin",
      "scopes": ["document:create", "document:read"],
      "status": "active",
      "last_used_at": "2024-01-20T14:30:00.000000Z",
      "expires_at": null,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "per_page": 15,
  "total": 5
}

POST `/api/v1/client/{client}/tokens`

Cria um novo token de acesso.

Headers

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

Escopo Necessário

token:manage

Body

{
  "name": "Nome do Token",
  "scopes": ["document:read", "document:create"],
  "expires_at": "2025-12-31T23:59:59Z"
}

Ou com escopos granulares:

{
  "name": "Token Granular",
  "scopes": {
    "permissions": ["document:read"],
    "document_rules": [
      {
        "environment": "production",
        "context": "orders",
        "permissions": ["document:update"]
      }
    ]
  },
  "expires_at": "2025-12-31T23:59:59Z"
}

Response (201 Created)

{
  "message": "Token created successfully. This is the only time the token will be displayed.",
  "token": "9fc42fe9-1234|abcdef1234567890abcdef1234567890abcdef12",
  "token_details": {
    "id": "9fc42fe9-1234-5678-9abc-def123456789",
    "client_id": "9fc42fe9-a4fd-443c-8d49-b85ece2151b9",
    "name": "Nome do Token",
    "scopes": ["document:read", "document:create"],
    "status": "active",
    "expires_at": "2025-12-31T23:59:59.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

⚠️ IMPORTANTE: Guarde o campo token em local seguro. Ele nunca mais será exibido!

PUT `/api/v1/client/{client}/tokens/{tokenId}`

Atualiza um token existente.

Headers

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

Escopo Necessário

token:manage

Body

{
  "name": "Novo Nome",
  "scopes": ["document:read", "document:create", "document:update"],
  "status": "active"
}

Response (200 OK)

Retorna o token atualizado.

DELETE `/api/v1/client/{client}/tokens/{tokenId}`

Revoga (deleta) um token.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

token:manage

Response (204 No Content)

Sem corpo de resposta.

Endpoints - Schemas

POST `/api/v1/client/{client}/{environment}/context/{context}/type/{type}/schema`

Cria ou atualiza um schema JSON.

Headers

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

Escopo Necessário

schema:manage

Body

{
  "schema": {
    "type": "object",
    "required": ["name", "email"],
    "properties": {
      "name": {
        "type": "string",
        "minLength": 2
      },
      "email": {
        "type": "string",
        "format": "email"
      }
    }
  }
}

Response (201 Created ou 200 OK)

{
  "id": 1,
  "client_id": "9fc42fe9-a4fd-443c-8d49-b85ece2151b9",
  "environment": "production",
  "context": "orders",
  "type": "invoice",
  "schema": { /* JSON Schema */ },
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z"
}

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

Obtém o schema JSON.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

schema:manage

Response (200 OK)

Retorna o schema completo.

Response (404 Not Found)

Se não existe schema para este escopo.

DELETE `/api/v1/client/{client}/{environment}/context/{context}/type/{type}/schema`

Deleta um schema JSON.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

schema:manage

Response (204 No Content)

Sem corpo de resposta.

Endpoints - Webhooks

GET `/api/v1/client/{client}/webhooks`

Lista todos os webhooks do cliente.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

webhook:manage

Query Parameters

Parâmetro	Tipo	Descrição
`page`	integer	Número da página
`per_page`	integer	Itens por página

Response (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": "9fc42fe9-1234-5678-9abc-def123456789",
      "client_id": "9fc42fe9-a4fd-443c-8d49-b85ece2151b9",
      "url": "https://meu-app.com/webhooks",
      "events": ["document.created", "document.updated"],
      "status": "active",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "per_page": 15,
  "total": 3
}

POST `/api/v1/client/{client}/webhooks`

Cria um novo webhook.

Headers

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

Escopo Necessário

webhook:manage

Body

{
  "url": "https://meu-app.com/webhooks/documents",
  "events": ["document.created", "document.updated"],
  "status": "active"
}

Campo	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL que receberá notificações (deve ser única)
`events`	array	Sim	Lista de eventos (`document.created`, `document.updated`, `document.deleted`, `document.read`)
`status`	string	Não	`active` (padrão) ou `inactive`

Response (201 Created)

{
  "id": "9fc42fe9-1234-5678-9abc-def123456789",
  "client_id": "9fc42fe9-a4fd-443c-8d49-b85ece2151b9",
  "url": "https://meu-app.com/webhooks/documents",
  "events": ["document.created", "document.updated"],
  "status": "active",
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z"
}

GET `/api/v1/client/{client}/webhooks/{webhookId}`

Obtém um webhook específico.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

webhook:manage

Response (200 OK)

Retorna o webhook completo.

PUT `/api/v1/client/{client}/webhooks/{webhookId}`

Atualiza um webhook existente.

Headers

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

Escopo Necessário

webhook:manage

Body

{
  "url": "https://nova-url.com/webhooks",
  "events": ["document.created"],
  "status": "inactive"
}

Response (200 OK)

Retorna o webhook atualizado.

DELETE `/api/v1/client/{client}/webhooks/{webhookId}`

Deleta um webhook.

Headers

Authorization: Bearer {TOKEN}

Escopo Necessário

webhook:manage

Response (204 No Content)

Sem corpo de resposta.

Códigos de Resposta HTTP

Código	Significado	Descrição
`200 OK`	Sucesso	Requisição processada com sucesso
`201 Created`	Criado	Recurso criado com sucesso
`204 No Content`	Sem Conteúdo	Operação bem-sucedida sem retorno
`400 Bad Request`	Requisição Inválida	Dados da requisição inválidos
`401 Unauthorized`	Não Autorizado	Token ausente, inválido ou expirado
`403 Forbidden`	Proibido	Token válido mas sem permissão
`404 Not Found`	Não Encontrado	Recurso não existe
`409 Conflict`	Conflito	Recurso já existe ou há conflito
`422 Unprocessable Entity`	Entidade Não Processável	Validação falhou
`429 Too Many Requests`	Muitas Requisições	Rate limit excedido
`500 Internal Server Error`	Erro Interno	Erro no servidor
`503 Service Unavailable`	Serviço Indisponível	Serviço temporariamente indisponível

Erros e Tratamento

Formato de Erro

Todos os erros retornam no seguinte formato:

{
  "message": "Descrição do erro",
  "errors": {
    "campo": ["Mensagem de erro específica"]
  }
}

Exemplos de Erros

400 Bad Request

{
  "message": "Validation failed: route parameters do not match payload"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing token"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scope: document:create"
}

404 Not Found

{
  "message": "Not Found"
}

409 Conflict

{
  "message": "Conflict: Document could not be created. It might already exist."
}

422 Unprocessable Entity (Schema Validation)

{
  "message": "Schema validation failed",
  "errors": [
    {
      "property": "email",
      "message": "Does not match format email"
    },
    {
      "property": "age",
      "message": "Must be greater than or equal to 0"
    }
  ]
}

429 Too Many Requests

{
  "message": "Too Many Requests",
  "retry_after": 60
}

Rate Limiting

Limites

Tipo	Limite	Janela
Requisições gerais	1000	1 minuto
Endpoints de autenticação	60	1 minuto

Headers de Resposta

Todas as respostas incluem headers de rate limiting:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642284000

Header	Descrição
`X-RateLimit-Limit`	Número total de requisições permitidas
`X-RateLimit-Remaining`	Requisições restantes na janela atual
`X-RateLimit-Reset`	Timestamp Unix quando o limite será resetado

Tratamento de Rate Limit

Quando o limite é excedido (429):

# Aguarde o tempo especificado
sleep ${retry_after}

# Ou aguarde até o reset
sleep $((reset_timestamp - current_timestamp))

Paginação

Parâmetros de Paginação

Todos os endpoints que retornam listas suportam paginação:

Parâmetro	Tipo	Padrão	Descrição
`page`	integer	1	Número da página
`per_page`	integer	15	Itens por página

Formato de Resposta Paginada

{
  "current_page": 1,
  "data": [ /* array de itens */ ],
  "first_page_url": "https://api.../resource?page=1",
  "from": 1,
  "last_page": 10,
  "last_page_url": "https://api.../resource?page=10",
  "links": [
    {"url": null, "label": "&laquo; Previous", "active": false},
    {"url": "https://api.../resource?page=1", "label": "1", "active": true},
    {"url": "https://api.../resource?page=2", "label": "2", "active": false},
    {"url": "https://api.../resource?page=2", "label": "Next &raquo;", "active": false}
  ],
  "next_page_url": "https://api.../resource?page=2",
  "path": "https://api.../resource",
  "per_page": 15,
  "prev_page_url": null,
  "to": 15,
  "total": 150
}

Navegação entre Páginas

# Primeira página
curl "https://api.../resource?page=1&per_page=50"

# Próxima página (use o next_page_url)
curl "https://api.../resource?page=2&per_page=50"

# Última página (use o last_page_url)
curl "https://api.../resource?page=10&per_page=50"