# Parâmetros opcionais TLV do SMPP

> Os TLVs (parâmetros opcionais, introduzidos na v3.4) estendem um PDU para além dos seus campos obrigatórios. Cada um é codificado como uma Tag de 2 bytes, um Length de 2 bytes e um Value de Length bytes, todos big-endian. Os TLVs surgem após o corpo obrigatório, em qualquer ordem, e permitem ao SMPP transportar conteúdos, metadados de concatenação e correlação de recibos sem alterar a disposição fixa de campos.

- URL canônico: https://www.broadnet.me/pt/reference/smpp-tlv-parameters
- Idioma: pt
- Última atualização: 2026-07-18
- Editor: BroadNet (https://www.broadnet.me)

Os parâmetros opcionais do SMPP usam um formato Tag-Length-Value. A disposição de bytes do TLV mais as tags comuns: message_payload, receipted_message_id, message_state, user_message_reference e o conjunto de concatenação sar_*.

## O formato TLV

Um TLV (também chamado parâmetro opcional) é um campo autodescritivo: uma Tag de 2 octetos identifica o parâmetro, um Length de 2 octetos dá o tamanho do Value em octetos e o Value segue-se. Tanto a Tag como o Length são big-endian. Por serem etiquetados, os TLVs podem surgir em qualquer ordem após os parâmetros obrigatórios e o recetor simplesmente ignora as tags que não reconhece.

*TLV message_payload a transportar um valor de 5 bytes*

```hex
04 24        Tag    = 0x0424 (message_payload)
00 05        Length = 5 octets
48 65 6C 6C 6F   Value = "Hello"
```

## Tags TLV comuns

Um punhado de TLVs faz a maior parte do trabalho em produção. O message_payload transporta uma mensagem demasiado longa para o short_message. O receipted_message_id e o message_state tornam os relatórios de entrega interpretáveis por máquina. O user_message_reference permite anexar o seu próprio id de correlação. O conjunto sar_* fornece concatenação baseada em normas sem bytes de UDH no corpo.

*Parâmetros opcionais usados frequentemente*

| Tag | Nome | Valor | Usar |
|---|---|---|---|
| 0x0424 | message_payload | Octet String | Corpo da mensagem quando excede short_message |
| 0x001E | receipted_message_id | C-Octet String (65) | message_id original num relatório de entrega |
| 0x0427 | message_state | Integer (1) | Estado final/intermediário num relatório de entrega (veja abaixo) |
| 0x0204 | user_message_reference | Integer (2) | Referência de correlação atribuída pelo ESME |
| 0x020C | sar_msg_ref_num | Integer (2) | Concatenação: referência partilhada entre segmentos |
| 0x020E | sar_total_segments | Integer (1) | Concatenação: número total de segmentos |
| 0x020F | sar_segment_seqnum | Integer (1) | Concatenação: a sequência deste segmento |
| 0x0423 | network_error_code | Octet String (3) | Detalhe de falha específico da rede num relatório de entrega |
| 0x0426 | more_messages_to_send | Integer (1) | Sinaliza que mais segmentos seguem |
| 0x020A | source_port | Integer (2) | Endereçamento de porta de aplicação (fonte) |
| 0x020B | dest_port | Integer (2) | Endereçamento de porta de aplicação (destino) |

## Valores de message_state

O TLV message_state (0x0427) reporta numericamente o estado do ciclo de vida de uma mensagem — o companheiro legível por máquina da palavra-chave stat do texto do DLR. Estes valores surgem também no query_sm_resp.

*Valores de message_state*

| Valor | Estado | Palavra-chave stat do DLR |
|---|---|---|
| 1 | ENROUTE | (em trânsito) |
| 2 | DELIVERED | DELIVRD |
| 3 | EXPIRED | EXPIRED |
| 4 | DELETED | DELETED |
| 5 | UNDELIVERABLE | UNDELIV |
| 6 | ACCEPTED | ACCEPTD |
| 7 | UNKNOWN | UNKNOWN |
| 8 | REJECTED | REJECTD |
| 9 | SKIPPED (v5.0) | — |

## Concatenação SAR vs UDH

O SMPP oferece duas formas de concatenar uma mensagem longa. O método UDH coloca um User Data Header de 6 bytes dentro do short_message e ativa o bit UDHI do esm_class. O método SAR mantém o corpo limpo e transporta em vez disso os três TLVs sar_*. Escolha um e seja consistente por rota — algumas redes aceitam apenas UDH, outras apenas SAR. Nunca misture os dois na mesma mensagem.

## Regras e armadilhas

Não preencha short_message e message_payload em simultâneo — os fornecedores rejeitam-no. TLVs personalizados fora das gamas aprovadas pelo seu fornecedor são frequentemente removidos ou causam erros de interpretação a jusante, por isso envie metadados apenas em tags acordadas. Um recetor tem de tolerar TLVs desconhecidos ignorando Length bytes; um Length malformado é a causa clássica de uma interpretação corrompida de tudo o que se segue.

## Perguntas frequentes

### O que significa TLV no SMPP?

Tag-Length-Value. Cada parâmetro opcional é codificado como uma tag de 2 bytes, um length de 2 bytes e esse número de bytes de valor. Os TLVs foram introduzidos no SMPP v3.4 e surgem após o corpo obrigatório de um PDU.

### Quando devo usar message_payload em vez de short_message?

Use o TLV message_payload (0x0424) quando a mensagem excede o campo short_message de 254 octetos, ou quando o seu fornecedor o prefere para conteúdo longo. Não defina ambos os campos no mesmo PDU.

### Como correlaciono um relatório de entrega com a minha mensagem submetida?

Compare o TLV receipted_message_id (0x001E) do recibo com o message_id que guardou do submit_sm_resp. Normalize primeiro os formatos, pois alguns SMSCs devolvem o id em hexadecimal no submit e em decimal no recibo.

### Os TLVs sar_* são melhores que o UDH para concatenação?

Nenhum é universalmente melhor — são duas codificações da mesma ideia. O SAR mantém o corpo da mensagem livre de bytes de cabeçalho; o UDH é mais amplamente aceite. Use o que a sua rota suportar e mantenha-se consistente.

### Posso acrescentar os meus próprios TLVs personalizados?

Apenas dentro da gama de tags específica do fabricante que o seu fornecedor aprovar. TLVs personalizados não aprovados são frequentemente removidos ou rejeitados em trânsito, por isso acorde primeiro as tags e o seu significado com o fornecedor.

## Fontes

- [SMPP v3.4 specification — §5.3 optional parameters](https://smpp.org/SMPP_v3_4_Issue1_2.pdf)
- [SMPP v5.0 specification](https://smpp.org/SMPP_v5.pdf)

## Relacionados

- [Relatórios de entrega SMPP (formato DLR)](https://www.broadnet.me/pt/reference/smpp-delivery-receipts-dlr)
- [Segmentação SMS e UDH](https://www.broadnet.me/pt/reference/sms-segmentation-concatenation-udh)
- [Referência submit_sm SMPP](https://www.broadnet.me/pt/reference/smpp-submit-sm)
- [Decodificador de PDU SMPP (ferramenta gratuita)](https://www.broadnet.me/pt/tools/smpp-pdu-decoder)
- [Anatomia do PDU SMPP](https://www.broadnet.me/pt/reference/smpp-pdu-anatomy)