API atual/Referência completa/Mini-loja WhatsApp: pedidos

Anexos do pedido

Envia, lista e baixa arquivos de um pedido, como o comprovante de um Pix manual.

Um anexo é um arquivo (imagem ou PDF) ligado a um pedido, com um tipo (kind). O uso de hoje é o comprovante de Pix manual: quando a loja recebe Pix na própria chave, sem QR gerado pela plataforma, o cliente paga no app do banco e anexa o comprovante ao pedido para a loja conferir.

O arquivo é guardado com o pedido, validado pelo conteúdo (nunca pelo tipo declarado) e só volta pelo token do próprio cliente. Todas as rotas abaixo respondem 404 order_not_found para pedido que não é do cliente.

Enviar um anexo

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/attachmentsPública

Envia um arquivo para o pedido

A requisição é multipart/form-data, não JSON. Enviar de novo cria outro anexo (cada pedido guarda até 20).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

Corpo da requisição (multipart/form-data)

kindstringobrigatório

comprovante_pix

Tipo do anexo. Hoje só comprovante_pix é aceito, e apenas em loja com a funcionalidade de comprovante de Pix manual ligada. Os tipos ordem_de_compra, proposta e outro existem no sistema mas são recusados com 403 attachment_kind_disabled.

filefileobrigatório

Arquivo de até 8 MB, nos formatos JPEG, PNG, WebP, HEIC ou PDF. O formato é reconhecido pelo conteúdo do arquivo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33/attachments" \
  -F "kind=comprovante_pix" \
  -F "file=@comprovante.pdf"

Resposta

201Anexo guardado

json

{
  "id": "0b6f6f0e-7c6d-4b2e-9e7a-3d8a4c1b2f55",
  "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33",
  "kind": "comprovante_pix",
  "filename": "comprovante.pdf",
  "mime": "application/pdf",
  "size_bytes": 48213,
  "source": "webview",
  "created_at_unix": 1791745000
}

Campos da resposta

iduuid

Id do anexo. Use no download.

order_iduuid

Pedido do anexo.

kindstring

Tipo do anexo.

filenamestring

Nome do arquivo, limpo (sem caminho nem aspas, até 120 caracteres). A extensão é completada pelo formato quando falta.

mimestring

Tipo real do arquivo, detectado pelo conteúdo: image/jpeg, image/png, image/webp, image/heic ou application/pdf.

size_bytesinteger

Tamanho em bytes.

sourcestring

webviewwhatsapp

Por onde chegou: a mini-loja (webview) ou a conversa do WhatsApp (whatsapp). Por esta rota é sempre webview.

created_at_unixinteger

Quando foi enviado, em segundos Unix.

Erros

Status	Quando	Corpo
400	Formulário ilegível.	`{"error":"invalid_form"}`
400	Sem o campo `file`, ou arquivo vazio.	`{"error":"attachment_empty"}`
403	`kind` desconhecido ou não habilitado na loja.	`{"error":"attachment_kind_disabled"}`
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`
409	O pedido já tem 20 anexos.	`{"error":"attachment_limit_reached"}`
413	Arquivo maior que 8 MB.	`{"error":"attachment_too_large"}`
415	O conteúdo não é JPEG, PNG, WebP, HEIC nem PDF.	`{"error":"attachment_type_not_allowed"}`
500	Falha inesperada ao guardar.	`{"error":"attachment_unavailable"}`
500	A consulta do pedido falhou (banco indisponível).	`{"error":"db_unavailable"}`

Listar os anexos

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/attachmentsPública

Lista os anexos de um pedido

Os mais novos primeiro, no máximo 50. Os mesmos anexos também vêm no detalhe do pedido (campo attachments) quando a forma de pagamento é Pix manual.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

Resposta

200Anexos do pedido

json

{
  "attachments": [
    {
      "id": "0b6f6f0e-7c6d-4b2e-9e7a-3d8a4c1b2f55",
      "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33",
      "kind": "comprovante_pix",
      "filename": "comprovante.pdf",
      "mime": "application/pdf",
      "size_bytes": 48213,
      "source": "webview",
      "created_at_unix": 1791745000
    }
  ]
}

Cada item tem os campos de Enviar um anexo. attachments é [] quando não há nenhum.

Erros

Status	Quando	Corpo
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`

Baixar um anexo

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/attachments/{attID}Pública

Devolve o arquivo de um anexo

Responde com os bytes do arquivo, não JSON. O Content-Type é o tipo detectado, o arquivo vem para exibição (Content-Disposition: inline) e a resposta leva X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; sandbox e Cache-Control: private, no-store, para que o conteúdo nunca rode como página.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

attIDuuidobrigatório

Id do anexo.

Exemplo de requisição

bash

curl -o comprovante.pdf \
  "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33/attachments/0b6f6f0e-7c6d-4b2e-9e7a-3d8a4c1b2f55"

Erros

Status	Quando	Corpo
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`
404	O anexo não existe neste pedido.	`{"error":"attachment_not_found"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: pedidos

Anexos do pedido

Envia, lista e baixa arquivos de um pedido, como o comprovante de um Pix manual.

Enviar um anexo

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/attachmentsPública

Envia um arquivo para o pedido

A requisição é multipart/form-data, não JSON. Enviar de novo cria outro anexo (cada pedido guarda até 20).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

Corpo da requisição (multipart/form-data)

kindstringobrigatório

comprovante_pix

filefileobrigatório

Arquivo de até 8 MB, nos formatos JPEG, PNG, WebP, HEIC ou PDF. O formato é reconhecido pelo conteúdo do arquivo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33/attachments" \
  -F "kind=comprovante_pix" \
  -F "file=@comprovante.pdf"

Resposta

201Anexo guardado

json

{
  "id": "0b6f6f0e-7c6d-4b2e-9e7a-3d8a4c1b2f55",
  "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33",
  "kind": "comprovante_pix",
  "filename": "comprovante.pdf",
  "mime": "application/pdf",
  "size_bytes": 48213,
  "source": "webview",
  "created_at_unix": 1791745000
}

Campos da resposta

iduuid

Id do anexo. Use no download.

order_iduuid

Pedido do anexo.

kindstring

Tipo do anexo.

filenamestring

Nome do arquivo, limpo (sem caminho nem aspas, até 120 caracteres). A extensão é completada pelo formato quando falta.

mimestring

Tipo real do arquivo, detectado pelo conteúdo: image/jpeg, image/png, image/webp, image/heic ou application/pdf.

size_bytesinteger

Tamanho em bytes.

sourcestring

webviewwhatsapp

Por onde chegou: a mini-loja (webview) ou a conversa do WhatsApp (whatsapp). Por esta rota é sempre webview.

created_at_unixinteger

Quando foi enviado, em segundos Unix.

Erros

Status	Quando	Corpo
400	Formulário ilegível.	`{"error":"invalid_form"}`
400	Sem o campo `file`, ou arquivo vazio.	`{"error":"attachment_empty"}`
403	`kind` desconhecido ou não habilitado na loja.	`{"error":"attachment_kind_disabled"}`
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`
409	O pedido já tem 20 anexos.	`{"error":"attachment_limit_reached"}`
413	Arquivo maior que 8 MB.	`{"error":"attachment_too_large"}`
415	O conteúdo não é JPEG, PNG, WebP, HEIC nem PDF.	`{"error":"attachment_type_not_allowed"}`
500	Falha inesperada ao guardar.	`{"error":"attachment_unavailable"}`
500	A consulta do pedido falhou (banco indisponível).	`{"error":"db_unavailable"}`

Listar os anexos

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/attachmentsPública

Lista os anexos de um pedido

Os mais novos primeiro, no máximo 50. Os mesmos anexos também vêm no detalhe do pedido (campo attachments) quando a forma de pagamento é Pix manual.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

Resposta

200Anexos do pedido

json

{
  "attachments": [
    {
      "id": "0b6f6f0e-7c6d-4b2e-9e7a-3d8a4c1b2f55",
      "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33",
      "kind": "comprovante_pix",
      "filename": "comprovante.pdf",
      "mime": "application/pdf",
      "size_bytes": 48213,
      "source": "webview",
      "created_at_unix": 1791745000
    }
  ]
}

Cada item tem os campos de Enviar um anexo. attachments é [] quando não há nenhum.

Erros

Status	Quando	Corpo
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`

Baixar um anexo

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/attachments/{attID}Pública

Devolve o arquivo de um anexo

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

attIDuuidobrigatório

Id do anexo.

Exemplo de requisição

bash

curl -o comprovante.pdf \
  "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33/attachments/0b6f6f0e-7c6d-4b2e-9e7a-3d8a4c1b2f55"

Erros

Status	Quando	Corpo
404	O pedido não existe ou não é deste cliente.	`{"error":"order_not_found"}`
404	O anexo não existe neste pedido.	`{"error":"attachment_not_found"}`