> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intention.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# ID de ordem do cliente
> Associar um identificador próprio a uma ordem para poder cancelá-la e reconciliá-la por um valor à sua escolha, em vez de um que a cadeia atribui.
Quando submete uma ordem, a cadeia atribui-lhe um ID de ordem. Esse ID é a referência que faz fé, mas só fica a conhecê-lo *depois* de a ordem ser aceite — o que é um problema quando o que precisa de fazer é cancelar uma ordem cuja aceitação nunca chegou a ver.
O ID de ordem do cliente resolve isso. Gera o identificador, associa-o na submissão e passa a poder agir sobre a ordem por esse identificador desde o instante em que a envia.
Porque isto importa mais do que parece
Imagine uma submissão que atinge o tempo limite. Chegou à cadeia? Não sabe. Sem um ID de ordem do cliente, as opções são consultar as ordens recentes e adivinhar por mercado, lado, preço e quantidade, ou não fazer nada e esperar pelo melhor.
Com um, a ambiguidade desaparece. Cancela pelo identificador que gerou. Se a ordem existia, fica cancelada. Se nunca chegou, o cancelamento não encontra nada. Em qualquer dos casos acaba num estado conhecido, que é aquilo de que um sistema a funcionar sem supervisão humana realmente precisa.
É também isto que torna a reconciliação viável. Os seus registos são indexados por um identificador que atribuiu, pelo que confrontar a sua visão com a da cadeia passa a ser uma consulta em vez de uma heurística.
O identificador é um **valor de 16 bytes**, submetido como uma cadeia hexadecimal minúscula de 32 caracteres com prefixo `0x`.
```
0xa1b2c3d4e5f6789012345678901234ab
```
Três regras que o protocolo impõe:
* **Apenas minúsculas.** Hexadecimal em maiúsculas é rejeitado, não normalizado.
* **Comprimento exato.** Valores mais curtos ou mais longos são rejeitados.
* **O valor todo a zeros está reservado.** `0x00000000...0000` é a sentinela que significa *ausente* e não pode ser usado como identificador.
O campo é opcional. Uma ordem sem ele comporta-se normalmente em todos os aspetos — simplesmente não pode ser cancelada por ID de ordem do cliente, apenas pelo ID de ordem atribuído pela cadeia.
Unicidade
A unicidade tem por âmbito a **subconta**: a combinação do endereço de assinatura com a subconta abaixo dele.
Daqui decorrem duas consequências. Subcontas diferentes sob o mesmo endereço podem usar o mesmo identificador sem conflito — útil quando executa estratégias independentes que geram cada uma os seus próprios IDs. E dentro de uma subconta, reutilizar um identificador que pertence a uma ordem ativa é um erro, não uma substituição.
Gere identificadores aleatoriamente e não sequencialmente. Um contador é tentador porque torna a ordenação visível, mas um reinício que perca o contador produz colisões com ordens que ainda estão ativas, e 16 bytes aleatórios nunca colidem na prática.
O que pode fazer com ele
| Operação | Comportamento |
| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Cancelar por ID de ordem do cliente** | Cancela a ordem ativa que tem esse identificador, sem precisar do ID atribuído pela cadeia |
| **Consultar por ID de ordem do cliente** | Obtém o estado atual e o histórico da ordem |
| **Reconciliar** | Confrontar os seus registos com os da cadeia por um identificador que atribuiu |
Tempo de vida
O identificador pertence à ordem, não à sua sessão. Continua consultável depois de a ordem ser executada ou cancelada, e é isso que o torna útil para reconciliação a posteriori.
Volta a ficar disponível assim que a ordem que identificava deixa de estar ativa. Na prática há pouca razão para reutilizar um — um novo valor aleatório não custa nada e elimina qualquer dúvida sobre a que ordem se refere um registo histórico.
Para onde ir a seguir
Alterar uma ordem ativa e o que acontece aos seus identificadores.
Aquilo a que pode associar um identificador.
Submeter ordens e tratar respostas ambíguas em código.
Por que razão um cancelamento submetido no mesmo bloco corre antes de uma ordem agressora.