API atual/Referência completa/Exportação para BI

Destinos de exportação

Cadastra o bucket S3 que recebe a exportação, guarda as credenciais criptografadas e testa se a plataforma consegue gravar nele.

Um destino é o bucket para onde os arquivos vão. A plataforma só grava; nunca lê o seu bucket. As chaves de acesso são guardadas criptografadas e nenhuma rota as devolve: depois de gravadas, só dá para substituí-las.

Listar destinos

GET/api/v1/admin/warehouse/destinationsAdmin

Lista os destinos de exportação

Exige o privilégio manage_settings (também para ler). Do mais novo para o mais antigo; não inclui os apagados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/warehouse/destinations" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Destinos retornados

json

[
  {
    "id": "e7c0b063-711d-4109-aea0-36fcbd40fa3b",
    "name": "Data lake BI",
    "kind": "s3",
    "endpoint": "https://s3.sa-east-1.amazonaws.com",
    "region": "sa-east-1",
    "bucket": "minha-loja-bi",
    "prefix": "venddor",
    "created_at": "2026-10-11T21:50:00.000000Z",
    "updated_at": "2026-10-11T21:50:00.000000Z"
  }
]

A resposta é um vetor JSON direto, sem objeto envolvendo.

Campos da resposta

[].iduuid

Id do destino.

[].namestring

Nome para você reconhecer o destino.

[].kindstring

s3

Tipo de destino. Hoje só s3 (armazenamento compatível com S3).

[].endpointstring

URL do serviço S3. Vazio = AWS.

[].regionstring

Região do bucket.

[].bucketstring

Nome do bucket.

[].prefixstring

Pasta raiz dentro do bucket.

[].created_atstring

Criação, RFC 3339 em UTC.

[].updated_atstring

Última alteração, RFC 3339 em UTC.

Criar um destino

POST/api/v1/admin/warehouse/destinationsAdmin

Cria um destino de exportação

Exige o privilégio manage_settings (também para ler).

Corpo da requisição

namestring

Nome para você reconhecer o destino. Não é validado.

endpointstring

URL do serviço compatível com S3 (MinIO, R2...). Vazio usa a AWS. O acesso usa o estilo de caminho (endpoint/bucket/chave).

regionstringpadrão: us-east-1

Região do bucket.

bucketstring

Nome do bucket. Não é validado na criação.

prefixstringpadrão: venddor

Pasta raiz dentro do bucket.

access_keystring

Chave de acesso. Só escrita.

secret_keystring

Chave secreta. Só escrita.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/destinations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data lake BI",
    "endpoint": "https://s3.sa-east-1.amazonaws.com",
    "region": "sa-east-1",
    "bucket": "minha-loja-bi",
    "prefix": "venddor",
    "access_key": "AKIAEXEMPLO",
    "secret_key": "segredo-de-exemplo"
  }'

Resposta

200Destino criado

json

{
  "id": "e7c0b063-711d-4109-aea0-36fcbd40fa3b",
  "name": "Data lake BI",
  "kind": "",
  "endpoint": "https://s3.sa-east-1.amazonaws.com",
  "region": "sa-east-1",
  "bucket": "minha-loja-bi",
  "prefix": "venddor",
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z"
}

A criação responde 200 (não 201) e devolve o que você enviou, sem as chaves, com kind vazio e datas zeradas. Leia o destino na listagem para ver os valores reais (kind: "s3").

Alterar um destino

Regrava name, endpoint, region, bucket e prefix com o que você enviar: o que faltar fica vazio. As chaves só mudam se você enviar access_key e secret_key juntas. Responde 204, sem corpo.

PUT/api/v1/admin/warehouse/destinations/{id}Admin

Altera um destino de exportação

Exige o privilégio manage_settings (também para ler).

Parâmetros de caminho

iduuidobrigatório

Id do destino.

Corpo da requisição

namestring

Nome para você reconhecer o destino. Não é validado.

endpointstring

URL do serviço compatível com S3 (MinIO, R2...). Vazio usa a AWS. O acesso usa o estilo de caminho (endpoint/bucket/chave).

regionstring

Região do bucket. Sem padrão na alteração: omitir grava vazio.

bucketstring

Nome do bucket. Não é validado na criação.

prefixstring

Pasta raiz dentro do bucket. Sem padrão na alteração: omitir grava vazio.

access_keystring

Chave de acesso. Só escrita.

secret_keystring

Chave secreta. Só escrita.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/warehouse/destinations/$DESTINATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data lake BI",
    "endpoint": "https://s3.sa-east-1.amazonaws.com",
    "region": "sa-east-1",
    "bucket": "minha-loja-bi",
    "prefix": "venddor",
    "access_key": "AKIAEXEMPLO",
    "secret_key": "segredo-de-exemplo"
  }'

Resposta

Status 204 No Content, sem corpo.

Apagar um destino

Exclusão lógica: o destino some da listagem e deixa de receber arquivos. Os jobs que apontavam para ele continuam existindo e passam a falhar a cada execução até serem apagados ou recriados. Responde 204.

DELETE/api/v1/admin/warehouse/destinations/{id}Admin

Apaga um destino de exportação

Exige o privilégio manage_settings (também para ler).

Parâmetros de caminho

iduuidobrigatório

Id do destino.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/warehouse/destinations/$DESTINATION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

Status 204 No Content, sem corpo.

Testar a gravação

Grava e apaga um objeto minúsculo (<prefix>/_venddor_test) no bucket. Responde sempre 200: veja o campo ok. Em caso de falha, error traz o motivo, sem as chaves.

POST/api/v1/admin/warehouse/destinations/{id}/testAdmin

Testa um destino de exportação

Exige o privilégio manage_settings (também para ler). Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do destino.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/destinations/$DESTINATION_ID/test" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Teste bem-sucedido

json

{
  "ok": true
}

200Teste com falha

json

{
  "ok": false,
  "error": "upload probe failed: operation error S3: PutObject, ... no such host"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}`
503	Exportação indisponível nesta instalação	`{"error":"warehouse export unavailable"}`
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
500	Criar sem o serviço de criptografia configurado na instalação; `id` que não é UUID; falha interna	`{"error":"failed to create destination","detail":"warehouse: credential encryption not configured; cannot store credentials"}`

Veja também

API atual/Referência completa/Exportação para BI

Destinos de exportação

Cadastra o bucket S3 que recebe a exportação, guarda as credenciais criptografadas e testa se a plataforma consegue gravar nele.

Listar destinos

GET/api/v1/admin/warehouse/destinationsAdmin

Lista os destinos de exportação

Exige o privilégio manage_settings (também para ler). Do mais novo para o mais antigo; não inclui os apagados.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/warehouse/destinations" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Destinos retornados

json

[
  {
    "id": "e7c0b063-711d-4109-aea0-36fcbd40fa3b",
    "name": "Data lake BI",
    "kind": "s3",
    "endpoint": "https://s3.sa-east-1.amazonaws.com",
    "region": "sa-east-1",
    "bucket": "minha-loja-bi",
    "prefix": "venddor",
    "created_at": "2026-10-11T21:50:00.000000Z",
    "updated_at": "2026-10-11T21:50:00.000000Z"
  }
]

A resposta é um vetor JSON direto, sem objeto envolvendo.

Campos da resposta

[].iduuid

Id do destino.

[].namestring

Nome para você reconhecer o destino.

[].kindstring

s3

Tipo de destino. Hoje só s3 (armazenamento compatível com S3).

[].endpointstring

URL do serviço S3. Vazio = AWS.

[].regionstring

Região do bucket.

[].bucketstring

Nome do bucket.

[].prefixstring

Pasta raiz dentro do bucket.

[].created_atstring

Criação, RFC 3339 em UTC.

[].updated_atstring

Última alteração, RFC 3339 em UTC.

Criar um destino

POST/api/v1/admin/warehouse/destinationsAdmin

Cria um destino de exportação

Exige o privilégio manage_settings (também para ler).

Corpo da requisição

namestring

Nome para você reconhecer o destino. Não é validado.

endpointstring

URL do serviço compatível com S3 (MinIO, R2...). Vazio usa a AWS. O acesso usa o estilo de caminho (endpoint/bucket/chave).

regionstringpadrão: us-east-1

Região do bucket.

bucketstring

Nome do bucket. Não é validado na criação.

prefixstringpadrão: venddor

Pasta raiz dentro do bucket.

access_keystring

Chave de acesso. Só escrita.

secret_keystring

Chave secreta. Só escrita.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/destinations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data lake BI",
    "endpoint": "https://s3.sa-east-1.amazonaws.com",
    "region": "sa-east-1",
    "bucket": "minha-loja-bi",
    "prefix": "venddor",
    "access_key": "AKIAEXEMPLO",
    "secret_key": "segredo-de-exemplo"
  }'

Resposta

200Destino criado

json

{
  "id": "e7c0b063-711d-4109-aea0-36fcbd40fa3b",
  "name": "Data lake BI",
  "kind": "",
  "endpoint": "https://s3.sa-east-1.amazonaws.com",
  "region": "sa-east-1",
  "bucket": "minha-loja-bi",
  "prefix": "venddor",
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z"
}

A criação responde 200 (não 201) e devolve o que você enviou, sem as chaves, com kind vazio e datas zeradas. Leia o destino na listagem para ver os valores reais (kind: "s3").

Alterar um destino

PUT/api/v1/admin/warehouse/destinations/{id}Admin

Altera um destino de exportação

Exige o privilégio manage_settings (também para ler).

Parâmetros de caminho

iduuidobrigatório

Id do destino.

Corpo da requisição

namestring

Nome para você reconhecer o destino. Não é validado.

endpointstring

URL do serviço compatível com S3 (MinIO, R2...). Vazio usa a AWS. O acesso usa o estilo de caminho (endpoint/bucket/chave).

regionstring

Região do bucket. Sem padrão na alteração: omitir grava vazio.

bucketstring

Nome do bucket. Não é validado na criação.

prefixstring

Pasta raiz dentro do bucket. Sem padrão na alteração: omitir grava vazio.

access_keystring

Chave de acesso. Só escrita.

secret_keystring

Chave secreta. Só escrita.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/warehouse/destinations/$DESTINATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data lake BI",
    "endpoint": "https://s3.sa-east-1.amazonaws.com",
    "region": "sa-east-1",
    "bucket": "minha-loja-bi",
    "prefix": "venddor",
    "access_key": "AKIAEXEMPLO",
    "secret_key": "segredo-de-exemplo"
  }'

Resposta

Status 204 No Content, sem corpo.

Apagar um destino

DELETE/api/v1/admin/warehouse/destinations/{id}Admin

Apaga um destino de exportação

Exige o privilégio manage_settings (também para ler).

Parâmetros de caminho

iduuidobrigatório

Id do destino.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/warehouse/destinations/$DESTINATION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

Status 204 No Content, sem corpo.

Testar a gravação

Grava e apaga um objeto minúsculo (<prefix>/_venddor_test) no bucket. Responde sempre 200: veja o campo ok. Em caso de falha, error traz o motivo, sem as chaves.

POST/api/v1/admin/warehouse/destinations/{id}/testAdmin

Testa um destino de exportação

Exige o privilégio manage_settings (também para ler). Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id do destino.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/warehouse/destinations/$DESTINATION_ID/test" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Teste bem-sucedido

json

{
  "ok": true
}

200Teste com falha

json

{
  "ok": false,
  "error": "upload probe failed: operation error S3: PutObject, ... no such host"
}

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","privilege_required_any":["manage_settings"]}`
503	Exportação indisponível nesta instalação	`{"error":"warehouse export unavailable"}`
400	Corpo que não é JSON	`{"error":"invalid body","detail":"..."}`
500	Criar sem o serviço de criptografia configurado na instalação; `id` que não é UUID; falha interna	`{"error":"failed to create destination","detail":"warehouse: credential encryption not configured; cannot store credentials"}`