API de integração de arquivos

Esta documentação apresenta as orientações para o consumo dos endpoints de inclusão, consulta e exclusão de arquivos, com exemplos de requisições e respostas para auxiliar na implementação da integração.

Informações gerais

Item	Valor
URL base	https://folha.suite.betha.cloud/dados/v2/arquivos/integracao
Autenticação	Bearer token e cabeçalho user-access
Formato do upload	multipart/form-data
Campo do arquivo	file
Formato das respostas	application/json, exceto DELETE 204

O endereço base das operações é:

https://folha.suite.betha.cloud/dados/v2/arquivos/integracao

Nos exemplos, substitua <TOKEN>, <USER_ACCESS>, <ID> e os caminhos locais pelos valores fornecidos para a integração. As credenciais não devem ser incluídas em arquivos, repositórios ou registros públicos.

Resumo dos endpoints

Método	Caminho	Descrição	Sucesso
POST	/dados/v2/arquivos/integracao	Envia um arquivo multipart.	200 OK
GET	/dados/v2/arquivos/integracao?name={name}	Consulta o mais recente pelo nome.	200 OK
GET	/dados/v2/arquivos/integracao/{id}	Consulta um arquivo pelo identificador.	200 OK
DELETE	/dados/v2/arquivos/integracao?id={id}	Exclui um arquivo pelo identificador.	204 No Content

Cabeçalhos comuns às quatro rotas

Envie os dois cabeçalhos abaixo em todas as requisições.

Cabeçalho	Valor	Obrigatório	Descrição
Authorization	Bearer <TOKEN>	Sim	Token de autenticação da integração.
user-access	<USER_ACCESS>	Sim	Contexto de acesso fornecido para a integração.

Utilize os valores fornecidos para o ambiente da integração. Se um dos cabeçalhos estiver ausente ou inválido, a API responderá com 401 Unauthorized.

POST /dados/v2/arquivos/integracao

Envia um arquivo binário. O corpo deve ser enviado exclusivamente como multipart/form-data, no campo file.

Campos do formulário

Campo	Tipo	Obrigatório	Descrição
file	arquivo binário	Sim	Arquivo que será armazenado.

Exemplo de requisição

curl --request POST \
     --url 'https://folha.suite.betha.cloud/dados/v2/arquivos/integracao' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'user-access: <USER_ACCESS>' \
     --form 'file=@/caminho/documento.pdf;type=application/pdf'

Não defina manualmente o cabeçalho Content-Type. Ao usar --form, o cURL gera o boundary correto do multipart automaticamente.

Exemplo de resposta 200 OK

{
    "id": 1234567,
    "name": "documento.pdf",
    "key": "<CHAVE_DO_ARQUIVO>",
    "bucket": "<BUCKET>",
    "type": "application/pdf",
    "size": 136007
}

Campos da resposta

Campo	Tipo	Descrição
id	inteiro	Identificador utilizado nas rotas de consulta e exclusão.
name	string	Nome original do arquivo, incluindo a extensão.
key	string	Chave de armazenamento gerada para o arquivo.
bucket	string	Repositório de armazenamento associado ao arquivo.
type	string	Tipo MIME informado no upload.
size	inteiro	Tamanho do arquivo em bytes.

Como utilizar o retorno

• A API responde com 200 OK e devolve diretamente o objeto de metadados do arquivo.
• Guarde o campo id. Ele será utilizado para consultar ou excluir o arquivo posteriormente.
• Use o campo name quando precisar realizar a consulta pelo nome completo do arquivo.
• Cada envio recebe um ID próprio, inclusive quando já existe outro arquivo com o mesmo nome.
• Antes do envio, confirme que o formulário contém o campo chamado exatamente file.

GET /dados/v2/arquivos/integracao

Use esta rota para localizar o arquivo mais recente com o nome informado no parâmetro de query name. Informe o nome completo, incluindo a extensão.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome completo do arquivo, incluindo a extensão.

Exemplo de requisição

curl --get \
     --url 'https://folha.suite.betha.cloud/dados/v2/arquivos/integracao' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'user-access: <USER_ACCESS>' \
     --data-urlencode 'name=documento com acento á.pdf'

Exemplo de resposta 200 OK

{
    "id": 1234567,
    "name": "documento com acento á.pdf",
    "key": "<CHAVE_DO_ARQUIVO>",
    "bucket": "<BUCKET>",
    "type": "application/pdf",
    "size": 136007
}

Regras de consulta

• A comparação considera o nome completo, inclusive a extensão.
• Codifique espaços e acentos na URL. No cURL, utilize --data-urlencode como no exemplo.
• Se o nome não for localizado, a API responderá com 200 OK sem corpo. A integração deve verificar se a resposta está vazia.
• Se houver arquivos com o mesmo nome, a API retornará o envio mais recente.
• Para consultar ou excluir um arquivo específico, prefira o ID retornado no upload.

GET /dados/v2/arquivos/integracao/{id}

Use esta rota para consultar um arquivo específico pelo identificador retornado no upload. Informe o ID numérico no caminho da requisição.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	inteiro	Sim	Identificador retornado pelo upload.

Exemplo de requisição

curl --request GET \
     --url 'https://folha.suite.betha.cloud/dados/v2/arquivos/integracao/<ID>' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'user-access: <USER_ACCESS>'

Exemplo de resposta 200 OK

{
    "id": 1234567,
    "name": "documento.pdf",
    "key": "<CHAVE_DO_ARQUIVO>",
    "bucket": "<BUCKET>",
    "type": "application/pdf",
    "size": 136007
}

Arquivo não encontrado 404 Not Found

Se o ID não estiver disponível, a API responderá com 404 sem corpo. Isso também ocorre quando o arquivo já foi excluído.

Tratamento da resposta

• Em 200 OK, utilize os metadados devolvidos conforme a necessidade da integração.
• Envie o ID exatamente como foi retornado pelo POST; o valor deve ser numérico.
• Em 404 Not Found, considere o arquivo inexistente ou já excluído.
• Não envie textos, valores vazios ou outros formatos no parâmetro id.

DELETE /dados/v2/arquivos/integracao

Use esta rota para excluir um arquivo. Informe no parâmetro de query id o identificador numérico recebido no upload.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
id	inteiro	Sim	Identificador retornado pelo upload.

Exemplo de requisição

curl --request DELETE \
     --url 'https://folha.suite.betha.cloud/dados/v2/arquivos/integracao?id=<ID>' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'user-access: <USER_ACCESS>'

Resposta 204 No Content

A exclusão bem-sucedida não possui corpo de resposta.

<sem conteúdo>

Tratamento da resposta

• Em 204 No Content, considere a exclusão concluída. Não tente interpretar um corpo de resposta.
• Em 404 Not Found, o ID informado não corresponde a um arquivo disponível.
• Em 401 Unauthorized, revise Authorization e user-access antes de repetir a chamada.
• Quando necessário, confirme a exclusão executando um GET pelo mesmo ID; o retorno será 404.

Sequência segura de exclusão

Etapa	Operação	Resultado esperado
1	GET por ID	200 e conferência do arquivo correto
2	DELETE com o mesmo ID	204 sem conteúdo
3	GET por ID para confirmação	404 sem conteúdo

Códigos de resposta

Status	Como tratar
200 OK	Operação concluída. Leia o objeto retornado ou verifique se a resposta está vazia na consulta por nome.
204 No Content	Exclusão concluída. A resposta não possui corpo.
401 Unauthorized	Revise os cabeçalhos Authorization e user-access.
404 Not Found	Considere o ID inexistente ou o arquivo já excluído.
500 Internal Server Error	Revise os parâmetros obrigatórios, o ID e a montagem do multipart. Se persistir, acione o suporte.

Valide localmente os parâmetros e o campo file antes da chamada. Isso evita o envio de requisições incompletas ou com tipos inválidos.

Exemplo de fluxo de integração

Etapa	Chamada	Dado a preservar
1	POST multipart com o campo file	id e name retornados
2	GET por ID ou GET por name	metadados conferidos
3	DELETE por id, quando necessário	status 204
4	GET por ID após a exclusão	status 404

Checklist antes de integrar

• Enviar Authorization: Bearer <TOKEN> e user-access em todas as quatro rotas.
• No POST, usar multipart/form-data e o campo chamado exatamente file.
• Não definir manualmente o boundary do multipart.
• Codificar o parâmetro name ao consultar arquivos com espaços ou acentos.
• Persistir o ID retornado pelo POST para consultas e exclusões posteriores.
• Tratar 200, 204, 401, 404 e 500 conforme a tabela de códigos de resposta.
• Validar localmente nome, ID, credenciais e presença do arquivo antes de chamar a API.

---

Os exemplos usam valores ilustrativos. Substitua-os pelos dados do ambiente da integração.