> For the complete documentation index, see [llms.txt](https://docs.plenit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plenit.com/docs-pt/reference/getting-started/beginners-guide-payload-headers-and-example-request.md).
# Guia para iniciantes: Payload, cabeçalhos e um exemplo prático
## O que é um payload e como é usado num pedido de API?
Quando envia um pedido para uma API, por vezes precisa de incluir informação para que a API saiba exatamente o que pretende que faça. Esta informação é enviada no corpo do pedido e é chamada de **payload** .
Pode pensar no payload como o “conteúdo da encomenda”: o pedido é o envelope, e o payload é o que está dentro.
Neste caso, o payload é um **JSON** ficheiro que contém os dados necessários para criar um disco e anexá-lo a um servidor.
***
## Um exemplo prático
Vamos explicá-lo usando o seguinte exemplo
### O endpoint que vamos usar
O endpoint é:
/api/servers/v1/subscriptions/\[subscriptionId]/disks
Este endpoint é usado para **criar um novo disco** dentro de uma subscrição e **anexá-lo a um servidor**.
**O que é** \[subscriptionId]? Este valor faz parte do URL, não do payload. Significa que deve substituir \[subscriptionId] pelo ID real da sua subscrição.
Exemplo:
/api/servers/v1/subscriptions/abc123/disks
***
### O que vai dentro do payload?
O payload JSON que envia deve incluir estes parâmetros:
**serverId** → O ID do servidor ao qual o disco será anexado
**name** → O nome que pretende dar ao disco
**zone** → A zona onde o disco será criado
**size** → O tamanho do disco (por exemplo, 25 GB)
Aqui está o modelo JSON base:
JSON
```json
{
"serverId": null,
"name": null,
"zone": "",
"size": 25
}
```
Num pedido real, substituiria os valores, por exemplo:
```json
{
"serverId": "srv-12345",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}
```
***
### Cabeçalhos obrigatórios no pedido
Além do payload, o seu pedido deve incluir cabeçalhos específicos para que a API o possa processar corretamente:
Authorization: Bearer \[your-access-token] Accept: application/json Content-Type: application/json
Estes cabeçalhos têm a seguinte finalidade:
**Authorization** → Identifica-o usando um **token**
**Accept** → Indica à API que pretende a resposta em JSON
**Content-Type** → Indica que o seu payload também está em JSON
***
### Exemplo completo de cURL
Aqui está um pedido **POST** completo usando cURL:
Bash
```curl
curl -X POST "https://your-domain.com/api/servers/v1/subscriptions/abc123/disks" \\
-H "Authorization: Bearer my-secret-token" \\
-H "Accept: application/json" \\
-H "Content-Type: application/json" \\
-d '{
"serverId": "srv-12345",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}'
```
**O que se passa aqui?**
* -X POST → Está a indicar à API que pretende **criar** algo.
* O \*\*URL\*\* inclui o \[subscriptionId] (abc123).
* As linhas -H enviam os cabeçalhos necessários **headers** .
* O bloco -d envia o **payload** como um objeto JSON.
***
### Exemplo para Windows no PowerShell
Abaixo está o **mesmo pedido usando** curl.exe **no Windows PowerShell** . Envia um pedido POST para criar um disco e anexá-lo a um servidor, incluindo os cabeçalhos necessários e um payload JSON.
PowerShell
```powershell
$subscriptionId = "abc123"
$token = "my-secret-token"
$baseUrl = "https://your-domain.com"
$endpoint = "/api/servers/v1/subscriptions/$subscriptionId/disks"
$url = "$baseUrl$endpoint"
# Corpo JSON como uma here-string (mais fácil de escrever sem escapar aspas)
$jsonBody = @'
{
"serverId": "srv-12345",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}
'@
# Pedido POST com curl.exe
curl.exe -X POST $url `
-H "Authorization: Bearer $token" `
-H "Accept: application/json" `
-H "Content-Type: application/json" `
-d $jsonBody
```
**O que isto faz**
* Coloca subscriptionId no URL (não no JSON).
* Envia o cabeçalho Authorization com o seu token de acesso.
* Define Accept: application/json e Content-Type: application/json.
* Envia o payload (JSON) com os campos obrigatórios: serverId, name, zone, size.
**Dica opcional**
Se quiser inserir variáveis diretamente no JSON, use uma here-string expansível (@" ... "@) em vez da literal:
PowerShell
```powershell
$serverId = "srv-12345"
$jsonBody = @"
{
"serverId": "$serverId",
"name": "secondary-data",
"zone": "eu-madrid-1",
"size": 25
}
"@
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.plenit.com/docs-pt/reference/getting-started/beginners-guide-payload-headers-and-example-request.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.