📝 Observações do Grupo de Pedido

📋 Visão Geral

As Observações permitem registrar anotações textuais livres em um grupo de pedido. São usadas por operadores autenticados para documentar informações relevantes ao atendimento, como acordos com o cliente, instruções de entrega ou qualquer ocorrência operacional.

Cada observação é criada por um usuário da plataforma e fica vinculada permanentemente ao grupo de pedido correspondente. O registro ocorre no momento da criação e não pode ser alterado posteriormente.

🔄 Entidades Envolvidas

Uma observação é composta pelos seguintes campos:

• id — Identificador único da observação, gerado automaticamente pelo sistema.
• orderGroupId — Referência ao grupo de pedido ao qual a observação pertence.
• userId — ID do usuário autenticado que registrou a observação. Pode ser null caso o contexto não possua usuário associado.
• userEmail — E-mail do usuário autenticado no momento da criação. Pode ser null nas mesmas condições que userId.
• text — Conteúdo textual da observação, fornecido pelo operador. Campo obrigatório.
• createdAt — Data e hora de criação do registro, definida automaticamente pelo servidor.

📌 Notas e Considerações

• O escopo ORDER_WRITE é obrigatório para registrar observações. Requisições sem esse escopo são rejeitadas.
• A criação bem-sucedida retorna HTTP 201 Created com o objeto da observação gerada.
• O campo text é obrigatório e deve ser uma string. Não há limite de tamanho definido na validação.
• Observações são imutáveis — não existe endpoint de atualização ou remoção. Uma vez criada, a observação permanece no grupo de pedido.

📝 Inclusão de Observação no Grupo de Pedido

📋 Descrição

Endpoint responsável por registrar anotações internas ou comentários operacionais em um grupo de pedido — útil para documentar tratativas com o cliente, instruções de logística reversa ou qualquer detalhe relevante para a rastreabilidade interna da operação.

O sistema registra automaticamente o identificador e e-mail do usuário responsável pela inclusão.

🔐 Permissão

• UserAuth — autenticação do usuário administrativo
• ORDER_WRITE — escopo de permissão para gerenciamento de pedidos

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/orders/groups/3710/observation' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "text": "Cliente solicitou alteração na embalagem para presente."
7  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 10,
5    "orderGroupId": 3710,
6    "userId": 5,
7    "userEmail": "atendimento@loja.com.br",
8    "text": "Cliente solicitou alteração na embalagem para presente.",
9    "createdAt": "2026-04-27 10:30:00"
10  }
11}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.