> ## Documentation Index > Fetch the complete documentation index at: https://developers.zouti.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Buscar pedido > Um pedido da conta (dona ou coprodutora). Pedido inexistente e pedido de outra conta respondem o mesmo 404. Devolve um [objeto pedido](/api-reference/order-object) pelo `id` (`ord_...`), quando a conta é dona do pedido ou participa dele por coprodução. * **Mesmo 404 para pedido de outra conta.** Um pedido que não existe e um pedido de outra conta recebem a mesma resposta `404` `resource_missing`. A API não revela se um `id` existe fora da sua conta. * **Mesmo formato da lista.** O pedido devolvido aqui é igual ao que aparece em `data` de [Listar pedidos](/api-reference/orders/list): os mesmos campos, com as mesmas regras de coprodução. ## OpenAPI ````yaml GET /v1/orders/{id} openapi: 3.1.0 info: title: Zouti API pública version: 1.0.0 description: > API pública da Zouti para integrar a conta aos sistemas do seller (ERP, CRM, BI). Guias, conceitos e exemplos em várias linguagens: https://developers.zouti.com.br **Autenticação:** chave de API da conta no header `Authorization: Bearer zt_live_...`, criada em Configurações → Chaves de API no dashboard. A chave nunca é aceita na query string. A conta é sempre a dona da chave. A autenticação vem antes da validação dos parâmetros: chave inválida responde 401 mesmo com a query inválida. **Dados:** lidos do índice de busca da Zouti; podem ficar alguns segundos atrás da mudança (um webhook pode chegar antes de o `GET` refletir o novo status). **Rate limit:** por conta, somando todas as chaves e recursos — rajada de 20 requisições e reposição de 10 por segundo. Toda resposta autenticada traz `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset`; o 429 traz `Retry-After`. Por IP: 30 respostas `401` do mesmo IP em 60 s bloqueiam o IP até a janela acabar (a chave autenticada com sucesso nas últimas 24 h segue passando), e acima de 15.000 requisições em 5 minutos a borda responde 429 sem corpo JSON. **Paginação:** por cursor. Envie o `next_cursor` da página anterior em `cursor`, com os mesmos filtros, até `has_more` ser `false`. Não há contagem total. Toda resposta traz `Request-Id`; informe-o ao suporte. servers: - url: https://api.zouti.com.br description: produção security: - apiKey: [] tags: - name: orders description: Pedidos da conta (próprios e de coprodução). paths: /v1/orders/{id}: get: tags: - orders summary: Buscar pedido description: > Um pedido da conta (dona ou coprodutora). Pedido inexistente e pedido de outra conta respondem o mesmo 404. operationId: orders_get parameters: - in: path name: id required: true description: Identificador do pedido (`ord_...`). schema: type: string responses: '200': description: O pedido. headers: Request-Id: $ref: '#/components/headers/RequestId' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Order' examples: owner_card: $ref: '#/components/examples/OrderOwnerCard' coproducer_pix: $ref: '#/components/examples/OrderCoproducerPix' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: e4ba739c-4319-4fd5-a387-ba9983292dc3 '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: headers: RequestId: description: Identificador único da requisição (`req_...`). Informe ao suporte. schema: type: string RateLimitLimit: description: Capacidade do bucket da conta (requisições em rajada). schema: type: integer RateLimitRemaining: description: Requisições restantes no bucket da conta. schema: type: integer RateLimitReset: description: Segundos até o bucket da conta encher de novo. schema: type: integer RetryAfter: description: Segundos inteiros (≥ 1) até poder repetir a requisição. schema: type: integer schemas: Order: type: object description: > Pedido da conta. O formato é fixo: campo sem valor vem `null`, nunca ausente. Valores monetários em centavos (inteiros). properties: object: type: string enum: - order description: 'Tipo do objeto: sempre `order`.' id: type: string description: Identificador do pedido (`ord_...`). role: type: string enum: - OWNER - COPRODUCER description: > `OWNER` quando a conta é dona do pedido; `COPRODUCER` quando participa por coprodução. O coprodutor vê os valores do pedido inteiro, não a parte dele; só `tracking` e `navigator` vêm `null`. status: type: string enum: - AWAITING_PAYMENT - UNPAID - PAID - CANCELED - SHIPPED - DELIVERED - REFUNDED - DISPUTED - TRIAL description: > Situação do pedido: - `AWAITING_PAYMENT`: PIX ou boleto emitido e ainda pagável; também o pagamento dividido entre a primeira e a segunda parte, e o primeiro status do parcelado inteligente. - `UNPAID`: cobrança tentada sem pagamento — cartão recusado (inclusive pelo antifraude), PIX ou boleto expirado, período de teste de assinatura expirado sem conversão, assinatura cancelada no prazo de inadimplência. - `PAID`: todo pagamento cobrado está pago (no pagamento dividido, todas as partes). Estorno parcial mantém `PAID`. - `CANCELED`: pagamento dividido não concluído em 20 minutos; as partes pagas são estornadas. - `SHIPPED`, `DELIVERED`: reservados; não são usados hoje. - `REFUNDED`: todo pagamento cobrado foi estornado por inteiro. - `DISPUTED`: chargeback em todo pagamento cobrado; disputa ganha volta a `PAID`. - `TRIAL`: assinatura em período de teste, cartão guardado sem cobrança; valores `0`. A renovação de assinatura não muda o status do pedido: o pagamento novo entra no mesmo pedido e aparece em `payment`. Um pedido pode mudar de status mais de uma vez; aceite qualquer transição. currency: type: - string - 'null' description: Moeda do pedido (ISO 4217, ex. `BRL`). amount_total: type: integer description: >- Valor cobrado no checkout, em centavos (parcelado inteligente, o valor total do contrato). amount_subtotal: type: - integer - 'null' description: Soma de preço × quantidade dos produtos, em centavos. amount_in_brl: type: - integer - 'null' description: >- Valor total em BRL, em centavos. Hoje igual a `amount_total` nos pedidos de infoproduto. created_at: type: string format: date-time description: Instante de criação do pedido. paid_at: type: - string - 'null' format: date-time description: Instante em que o pedido foi pago; `null` quando não há. canceled_at: type: - string - 'null' format: date-time description: Instante do cancelamento; `null` quando não há. updated_at: type: - string - 'null' format: date-time description: > Instante (UTC, com milissegundos) em que algum campo deste objeto mudou pela última vez: status, valores, pagamento, estorno, cliente, endereço, itens, oferta, cupom, UTM ou metadata. Reprocessamento interno que não muda nada do que a API devolve não avança este campo. `null` em pedido que ainda não passou pelo preenchimento inicial. customer: type: object description: Comprador. properties: name: type: string description: Nome do comprador. email: type: string description: E-mail do comprador. phone: type: - string - 'null' description: Telefone do comprador. document: type: - string - 'null' description: CPF (11 dígitos) ou CNPJ (14 dígitos) do comprador, só dígitos. document_type: type: - string - 'null' enum: - CPF - CNPJ - null description: >- `CPF` ou `CNPJ`, pelo número de dígitos de `document`; `null` quando não há documento. required: - name - email - phone - document - document_type shipping_address: type: - object - 'null' description: >- Endereço de entrega informado no checkout; `null` quando o pedido não tem endereço. properties: line1: type: string description: Logradouro. line2: type: string description: Número. line3: type: - string - 'null' description: Complemento. neighborhood: type: string description: Bairro. city: type: string description: Cidade. state: type: string description: Estado. country: type: string description: País. postal_code: type: string description: CEP. full_name: type: - string - 'null' description: Nome do destinatário. required: - line1 - line2 - line3 - neighborhood - city - state - country - postal_code - full_name payment: type: object description: > Último pagamento do pedido (o mais recente pela data de criação). Os valores somam as partes pagas só no pagamento dividido (`method` `MULTIPLE`); nos demais casos (renovação de assinatura, parcelado inteligente, nova tentativa) são os do último pagamento. properties: method: type: string enum: - CREDIT_CARD - BOLETO - PIX - MULTIPLE description: > Forma de pagamento: `CREDIT_CARD` (cartão de crédito), `BOLETO`, `PIX` ou `MULTIPLE` (pagamento dividido em 2 ou mais pagamentos, com cartão e/ou PIX, mínimo de R$ 5 por parte; nenhum pagamento individual tem esse método). status: type: string enum: - PENDING - FAILED - DECLINED - PAID - UNPAID - PARTIALLY_REFUNDED - REFUNDED - DISPUTED - TRIAL description: > Situação do último pagamento: - `PENDING`: em andamento. - `FAILED`: não chegou ao banco (falha de comunicação da Zouti); pode aparecer num pedido visível, como uma renovação que falhou. - `DECLINED`: recusado pelo banco, pelo adquirente ou pelo antifraude. - `PAID`: pago. - `UNPAID`: PIX ou boleto expirado. - `PARTIALLY_REFUNDED`: estornado em parte. - `REFUNDED`: estornado por inteiro. - `DISPUTED`: chargeback. - `TRIAL`: período de teste de assinatura, sem cobrança. installments: type: - integer - 'null' description: >- Número de parcelas, ≥ 1 (PIX e boleto: `1`). `null` só em registro antigo. amount: type: integer description: > Valor cobrado no último pagamento, em centavos (pagamento dividido: soma das partes pagas); `0` em `TRIAL`. interest_amount: type: integer description: Juros de parcelamento do pagamento, em centavos. discount_amount: type: integer description: > Desconto do pagamento, em centavos, positivo: soma de cupom, desconto por forma de pagamento e desconto por quantidade. fee: type: integer description: > Taxa da Zouti pelo plano da conta, em centavos. Não inclui a taxa do adquirente nem a comissão de afiliado. amount_refunded: type: - integer - 'null' description: Total estornado, acumulado e bruto, em centavos. refunded_at: type: - string - 'null' format: date-time description: Instante do estorno do último pagamento; `null` quando não há. decline_code: type: - string - 'null' pattern: ^ZT-\d{4}$ description: > Motivo da recusa no código padronizado da Zouti (ex. `ZT-1000`), igual ao do webhook. `null` quando o último pagamento do pedido não foi recusado. Cartão recusado no checkout (inclusive pelo antifraude) deixa o pedido `UNPAID` com `payment.status` `DECLINED` e este campo preenchido; o mesmo vale para uma renovação de assinatura recusada. Pedido com falha da infraestrutura da Zouti (`FAILED`) não aparece nesta API. decline_message: type: - string - 'null' description: >- Texto do motivo da recusa para mostrar ao comprador. `null` quando não houve recusa. card: type: - object - 'null' description: >- Só bandeira e últimos 4 dígitos. `null` quando o pagamento não foi com cartão. properties: brand: type: - string - 'null' description: > Bandeira do cartão: `AMERICAN_EXPRESS`, `DINERS_CLUB_INTERNATIONAL`, `DISCOVER`, `ELO`, `ELO_DISCOVER`, `HIPERCARD`, `JCB`, `MAESTRO`, `MASTERCARD`, `OUROCARD`, `SODEXO`, `UNIONPAY` ou `VISA`. `null` quando a bandeira não é reconhecida. A lista pode crescer. last4: type: string description: Últimos 4 dígitos do cartão. required: - brand - last4 required: - method - status - installments - amount - interest_amount - discount_amount - fee - amount_refunded - refunded_at - decline_code - decline_message - card items: type: array description: Produtos do pedido. items: type: object properties: product_id: type: string description: Identificador do produto (`prod_...`). name: type: string description: Nome do produto. quantity: type: integer description: Quantidade. unit_price: type: integer description: Preço unitário, em centavos. sub_total: type: integer description: '`unit_price` × `quantity`, em centavos.' currency: type: string description: Moeda do item; hoje sempre `BRL`. offer_id: type: - string - 'null' description: >- Oferta do produto pela qual o item foi vendido (`prod_offer_...`); `null` quando não há. plan_id: type: - string - 'null' description: >- Plano da oferta do item (`prod_offer_plan_...`); `null` quando não há. order_bump_id: type: - string - 'null' description: >- Order bump que acrescentou o item (`ob_...`); `null` quando o item não veio de order bump. required: - product_id - name - quantity - unit_price - sub_total - currency - offer_id - plan_id - order_bump_id offer: type: - object - 'null' description: Oferta do checkout em que o pedido foi feito; `null` quando não há. properties: id: type: string description: Identificador da oferta (`prod_offer_...`). name: type: string description: Nome da oferta. required: - id - name promocode: type: - object - 'null' description: Cupom aplicado no pedido; `null` sem cupom. properties: code: type: string description: Código do cupom. description: type: - string - 'null' description: Descrição do cupom. amount: type: integer description: > Desconto do cupom em centavos, **negativo** (ex. `-1970`). `payment.discount_amount` traz o desconto como valor positivo. required: - code - description - amount utm: type: - object - 'null' description: Parâmetros UTM do checkout; `null` quando o pedido não tem UTM. properties: utm_source: type: - string - 'null' description: Valor de `utm_source`. utm_medium: type: - string - 'null' description: Valor de `utm_medium`. utm_campaign: type: - string - 'null' description: Valor de `utm_campaign`. utm_term: type: - string - 'null' description: Valor de `utm_term`. utm_content: type: - string - 'null' description: Valor de `utm_content`. required: - utm_source - utm_medium - utm_campaign - utm_term - utm_content tracking: type: - object - 'null' description: > Parâmetros de rastreamento que vieram na URL do checkout (ex. `sck`, `src`, `xcod`), como chave → valor. `null` quando o pedido não tem rastreamento ou quando quem consulta é coprodutor (`role: COPRODUCER`). additionalProperties: type: string navigator: type: - object - 'null' description: > Navegador do comprador no checkout. Nunca traz o IP. `null` quando o pedido não registrou navegador nem página de origem, ou quando quem consulta é coprodutor (`role: COPRODUCER`). properties: user_agent: type: - string - 'null' description: User-Agent do navegador do comprador. referer: type: - string - 'null' description: Página de onde o comprador chegou ao checkout. device: type: - string - 'null' description: Derivado do `user_agent`. Hoje `Mobile`, `Tablet` ou `Desktop`. browser: type: - string - 'null' description: > Derivado do `user_agent` (ex. `Chrome`, `Safari`, `Instagram`). `null` quando não reconhecido. origin: type: - string - 'null' description: Domínio do `referer`, sem `www.` (ex. `instagram.com`). required: - user_agent - referer - device - browser - origin metadata: type: - object - 'null' description: > Metadados comerciais do pedido. Cada chave só aparece quando existe no pedido. properties: order_parent_id: type: string description: Pedido de origem de um upsell. origin: type: string description: Origem do checkout. currency_rate: type: number description: Câmbio usado para converter o pedido em outra moeda para BRL. additionalProperties: false required: - object - id - role - status - currency - amount_total - amount_subtotal - amount_in_brl - created_at - paid_at - canceled_at - updated_at - customer - shipping_address - payment - items - offer - promocode - utm - tracking - navigator - metadata Error: type: object description: >- Erro da API pública. `code` é estável; `message` é em português e pode mudar. properties: error: type: object properties: type: type: string enum: - authentication_error - permission_error - invalid_request_error - rate_limit_error - api_error code: type: string enum: - invalid_api_key - account_blocked - insufficient_access - resource_missing - invalid_request - rate_limited - internal_error - service_unavailable description: > - `invalid_api_key` (401): chave ausente, malformada, inexistente, revogada ou expirada. - `account_blocked` (403): a conta dona da chave está bloqueada; fale com o suporte. - `insufficient_access` (403): a chave não tem o nível de acesso da rota. - `resource_missing` (404): recurso inexistente ou de outra conta, ou rota inexistente. - `invalid_request` (400): parâmetro inválido, nomeado em `param`. - `rate_limited` (429): limite da conta excedido; espere `Retry-After` segundos. - `internal_error` (500): erro inesperado; informe o `request_id` ao suporte. - `service_unavailable` (503): indisponibilidade temporária; tente de novo. message: type: string param: type: string description: >- Parâmetro que causou o erro (`limit`, `cursor`, `status`…), quando houver. request_id: type: string description: Mesmo valor do header `Request-Id`. required: - type - code - message - request_id required: - error examples: OrderOwnerCard: summary: Pedido próprio pago com cartão value: object: order id: ord_8k2m4q6s1v3x5z7b9d0f2h role: OWNER status: PAID currency: BRL amount_total: 27730 amount_subtotal: 29700 amount_in_brl: 27730 created_at: '2026-10-14T13:05:22.418Z' paid_at: '2026-10-14T13:05:24.902Z' canceled_at: null updated_at: '2026-10-14T13:05:25.117Z' customer: name: Maria Oliveira email: maria.oliveira@example.com phone: '+5511999998888' document: '12345678909' document_type: CPF shipping_address: line1: Rua das Flores line2: '123' line3: Apto 45 neighborhood: Centro city: São Paulo state: SP country: BR postal_code: '01001000' full_name: Maria Oliveira payment: method: CREDIT_CARD status: PAID installments: 1 amount: 27730 interest_amount: 0 discount_amount: 1970 fee: 1386 amount_refunded: 0 refunded_at: null decline_code: null decline_message: null card: brand: MASTERCARD last4: '4242' items: - product_id: prod_3n7p1r5t9w2y4a6c8e0g1j name: Curso Completo de Fotografia quantity: 1 unit_price: 19700 sub_total: 19700 currency: BRL offer_id: prod_offer_5d1f3h7k9m2p4r6t8v0x2z plan_id: null order_bump_id: null - product_id: prod_6b8d0f2h4k6m8p0r2t4v6x name: Pacote de Presets quantity: 1 unit_price: 10000 sub_total: 10000 currency: BRL offer_id: null plan_id: null order_bump_id: ob_2c4e6g8j0l2n4q6s8u0w2y offer: id: prod_offer_5d1f3h7k9m2p4r6t8v0x2z name: Oferta de lançamento promocode: code: BEMVINDO10 description: 10% de desconto no curso amount: -1970 utm: utm_source: instagram utm_medium: social utm_campaign: lancamento-outubro utm_term: null utm_content: stories tracking: sck: parceiro-123 src: bio navigator: user_agent: >- Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 Instagram 350.0.0 referer: https://www.instagram.com/ device: Mobile browser: Instagram origin: instagram.com metadata: {} OrderCoproducerPix: summary: Pedido de coprodução pago com PIX value: object: order id: ord_1q3s5u7w9y0a2c4e6g8i0k role: COPRODUCER status: PAID currency: BRL amount_total: 9700 amount_subtotal: 9700 amount_in_brl: 9700 created_at: '2026-10-13T18:42:10.036Z' paid_at: '2026-10-13T18:43:51.274Z' canceled_at: null updated_at: '2026-10-13T18:43:52.009Z' customer: name: Maria Oliveira email: maria.oliveira@example.com phone: '+5511999998888' document: '12345678909' document_type: CPF shipping_address: null payment: method: PIX status: PAID installments: 1 amount: 9700 interest_amount: 0 discount_amount: 0 fee: 485 amount_refunded: 0 refunded_at: null decline_code: null decline_message: null card: null items: - product_id: prod_9x1z3b5d7f9h1k3m5p7r9t name: Mentoria em Grupo quantity: 1 unit_price: 9700 sub_total: 9700 currency: BRL offer_id: prod_offer_4w6y8a0c2e4g6j8l0n2q4s plan_id: null order_bump_id: null offer: id: prod_offer_4w6y8a0c2e4g6j8l0n2q4s name: Mentoria em Grupo promocode: null utm: null tracking: null navigator: null metadata: order_parent_id: ord_7h9k1m3p5r7t9v1x3z5b7d ErrorInvalidApiKey: summary: Chave inválida (`invalid_api_key`) value: error: type: authentication_error code: invalid_api_key message: Chave de API inválida. request_id: req_8f2kq1x7c3m9v4b6n0zd5a ErrorResourceMissing: summary: Recurso não encontrado (`resource_missing`) value: error: type: invalid_request_error code: resource_missing message: Recurso não encontrado. request_id: req_8f2kq1x7c3m9v4b6n0zd5a ErrorRateLimited: summary: Limite da conta excedido (`rate_limited`) value: error: type: rate_limit_error code: rate_limited message: Limite de requisições excedido. Tente novamente em instantes. request_id: req_8f2kq1x7c3m9v4b6n0zd5a ErrorInternal: summary: Erro inesperado (`internal_error`) value: error: type: api_error code: internal_error message: Erro interno. Se persistir, informe o request_id ao suporte. request_id: req_8f2kq1x7c3m9v4b6n0zd5a ErrorServiceUnavailable: summary: Indisponibilidade temporária (`service_unavailable`) value: error: type: api_error code: service_unavailable message: Serviço temporariamente indisponível. Tente novamente em instantes. request_id: req_8f2kq1x7c3m9v4b6n0zd5a responses: Unauthorized: description: >- Chave ausente, malformada, inexistente, revogada ou expirada (`invalid_api_key`). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_api_key: $ref: '#/components/examples/ErrorInvalidApiKey' NotFound: description: Recurso inexistente ou de outra conta (`resource_missing`). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: resource_missing: $ref: '#/components/examples/ErrorResourceMissing' TooManyRequests: description: > Limite de requisições excedido. Três limites respondem 429: - **Conta** (`rate_limited`): rajada de 20 requisições e reposição de 10 por segundo, somando todas as chaves da conta. `Retry-After` diz quantos segundos esperar. - **Falhas de autenticação por IP** (`rate_limited`): 30 respostas `401` do mesmo IP em 60 s bloqueiam o IP até a janela acabar; `Retry-After` diz quanto falta. Uma chave autenticada com sucesso nas últimas 24 h segue passando. - **Volume por IP na borda**: acima de 15.000 requisições em 5 minutos do mesmo IP. Este 429 vem sem corpo JSON (sem `error.code`) e com `Retry-After: 300`. headers: Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: $ref: '#/components/examples/ErrorRateLimited' InternalError: description: Erro inesperado (`internal_error`). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: internal_error: $ref: '#/components/examples/ErrorInternal' ServiceUnavailable: description: Indisponibilidade temporária (`service_unavailable`). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: service_unavailable: $ref: '#/components/examples/ErrorServiceUnavailable' securitySchemes: apiKey: type: http scheme: bearer description: >- Chave de API da conta (`zt_live_...`), criada em Configurações → Chaves de API no dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.