ReferĆŖncias de API
Start typing to searchā€¦

DocumentHub API

šŸ“š ƍndice

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Ć¢metroTipoDescriĆ§Ć£o
clientUUIDID do cliente
environmentstringAmbiente (production, staging, etc.)
contextstringContexto de negĆ³cio
typestringTipo do documento
keystringChave Ćŗ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
}
CampoTipoObrigatĆ³rioDescriĆ§Ć£o
environmentstringSimDeve corresponder Ć  URL
contextstringSimDeve corresponder Ć  URL
typestringSimDeve corresponder Ć  URL
keystringSimDeve corresponder Ć  URL
dataobjectSimDados do documento (JSON)
expires_attimestampNĆ£oData de expiraĆ§Ć£o
ttlintegerNĆ£oTempo 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Ć³digoDescriĆ§Ć£o
400ParĆ¢metros da URL nĆ£o correspondem ao body
401Token invƔlido
403Sem permissĆ£o document:create
409Documento jĆ” existe
422ValidaĆ§Ć£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Ć¢metroTipoDescriĆ§Ć£o
clientUUIDID do cliente
environmentstringAmbiente
contextstringContexto
typestringTipo
keystringChave do documento

Query Parameters

ParĆ¢metroTipoDescriĆ§Ć£o
deletedbooleanIncluir 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Ć³digoDescriĆ§Ć£o
401Token invƔlido
403Sem permissĆ£o document:read
404Documento 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Ć³digoDescriĆ§Ć£o
400ParĆ¢metros da URL nĆ£o correspondem ao body
401Token invƔlido
403Sem permissĆ£o document:update
404Documento nĆ£o encontrado
422ValidaĆ§Ć£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Ć³digoDescriĆ§Ć£o
401Token invƔlido
403Sem permissĆ£o document:delete
404Documento 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Ć¢metroTipoDescriĆ§Ć£o
pageintegerNĆŗmero da pĆ”gina (padrĆ£o: 1)
per_pageintegerItens por pĆ”gina (padrĆ£o: 15)
deletedbooleanIncluir documentos deletados
filter[campo]mixedFiltrar por campo (ver guia de filtragem)
filter[campo_gt]mixedCampo maior que
filter[campo_gte]mixedCampo maior ou igual
filter[campo_lt]mixedCampo menor que
filter[campo_lte]mixedCampo menor ou igual
filter[campo_neq]mixedCampo diferente de
filter[campo_like]stringCampo 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": "« 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 »", "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Ć¢metroTipoDescriĆ§Ć£o
pageintegerNĆŗmero da pĆ”gina
per_pageintegerItens 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Ć¢metroTipoDescriĆ§Ć£o
history_idintegerID 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Ć¢metroTipoDescriĆ§Ć£o
pageintegerNĆŗmero da pĆ”gina
per_pageintegerItens 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Ć¢metroTipoDescriĆ§Ć£o
pageintegerNĆŗmero da pĆ”gina
per_pageintegerItens 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"
}
CampoTipoObrigatĆ³rioDescriĆ§Ć£o
urlstringSimURL que receberĆ” notificaƧƵes (deve ser Ćŗnica)
eventsarraySimLista de eventos (document.created, document.updated, document.deleted, document.read)
statusstringNĆ£oactive (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Ć³digoSignificadoDescriĆ§Ć£o
200 OKSucessoRequisiĆ§Ć£o processada com sucesso
201 CreatedCriadoRecurso criado com sucesso
204 No ContentSem ConteĆŗdoOperaĆ§Ć£o bem-sucedida sem retorno
400 Bad RequestRequisiĆ§Ć£o InvĆ”lidaDados da requisiĆ§Ć£o invĆ”lidos
401 UnauthorizedNĆ£o AutorizadoToken ausente, invĆ”lido ou expirado
403 ForbiddenProibidoToken vĆ”lido mas sem permissĆ£o
404 Not FoundNĆ£o EncontradoRecurso nĆ£o existe
409 ConflictConflitoRecurso jĆ” existe ou hĆ” conflito
422 Unprocessable EntityEntidade NĆ£o ProcessĆ”velValidaĆ§Ć£o falhou
429 Too Many RequestsMuitas RequisiƧƵesRate limit excedido
500 Internal Server ErrorErro InternoErro no servidor
503 Service UnavailableServiƧo IndisponƭvelServiƧ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

TipoLimiteJanela
RequisiƧƵes gerais10001 minuto
Endpoints de autenticaĆ§Ć£o601 minuto

Headers de Resposta

Todas as respostas incluem headers de rate limiting:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642284000
HeaderDescriĆ§Ć£o
X-RateLimit-LimitNĆŗmero total de requisiƧƵes permitidas
X-RateLimit-RemainingRequisiƧƵes restantes na janela atual
X-RateLimit-ResetTimestamp 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Ć¢metroTipoPadrĆ£oDescriĆ§Ć£o
pageinteger1NĆŗmero da pĆ”gina
per_pageinteger15Itens 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": "« 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 »", "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"