O que é Payload?

O conteúdo que a comunicação transporta

Payload significa carga útil: o conteúdo transportado para cumprir a finalidade de uma mensagem. Em uma integração de cadastro, pode ser o conjunto de campos do contato. Em uma notificação de pagamento, pode trazer o identificador da cobrança e sua situação.

O termo não define um formato. O payload pode ser representado em JSON, texto, um arquivo ou outro formato aceito pelo receptor. Para interpretá-lo, você precisa conhecer tanto a estrutura quanto o significado dos campos.

Imagine que um serviço informa que uma cobrança foi paga. A integração recebe uma mensagem com o identificador correspondente e usa essa referência para localizar o registro local. Antes de atualizar a cobrança, precisa reconhecer o tipo da notificação e encontrar os campos previstos para esse evento.

Um exemplo de mensagem

{
"evento_id": "evt_1042",
"tipo": "cobranca.paga",
"cobranca": {
  "id": "cob_85",
  "valor_centavos": 29990,
  "moeda": "BRL"
}
}

Nesse exemplo, evt_1042 identifica a notificação, e cob_85 identifica a cobrança. Os dois valores têm funções diferentes. Usar o identificador do evento para procurar a cobrança faria a integração consultar o registro errado.

O campo valor_centavos explicita a unidade usada no exemplo. O número 29990 representa R$ 299,90 porque esse contrato fictício utiliza centavos. Outra API pode adotar uma representação diferente, que precisa ser confirmada antes de qualquer cálculo.

Payload, body e envelope

Em uma conversa sobre HTTP, payload frequentemente designa o conteúdo do corpo. Já em uma fila, a mensagem pode conter um envelope com informações de roteamento e uma seção específica para o conteúdo do evento. O limite entre essas partes depende do protocolo e do contrato.

Até informações sobre o evento podem aparecer dentro do JSON chamado de payload. Por isso, classificar todos os identificadores como cabeçalhos e todos os valores comerciais como corpo seria uma simplificação incorreta. Leia a estrutura documentada para saber onde cada informação foi colocada.

Da leitura à atualização do sistema

A interpretação do payload também precisa considerar campos ausentes e versões do contrato. Um campo opcional pode não aparecer em todos os eventos. Já a ausência de um identificador obrigatório deve impedir uma atualização baseada em suposições.

Reconhecer os campos não comprova a origem da mensagem. Em um webhook, o receptor precisa conferir a autenticação ou assinatura conforme a documentação do emissor. Um JSON com o texto cobranca.paga não é suficiente para confirmar o pagamento.

O que conferir quando um campo não é encontrado

Compare o conteúdo recebido com a estrutura esperada, incluindo objetos aninhados. cobranca.id e um campo id na raiz são caminhos diferentes. Confira também se a mensagem pertence ao tipo de evento que a integração sabe processar.

Use exemplos fictícios ou registros sem informações pessoais ao compartilhar uma análise. O corpo de uma mensagem pode conter conteúdo sensível mesmo quando os cabeçalhos foram removidos. A explicação de JSON mostra como percorrer os campos e reconhecer seus tipos.

Aplicação na formação

Vibe Coding: Do Zero ao MVP

O payload contém as informações que a integração precisa interpretar para executar sua função.

Conhecer a formação →