> ## 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.

# Sobre os dados

> De onde vêm os pedidos, o que entra e o que fica de fora, e como tratar os dados do comprador.

## Atraso de alguns segundos

Os pedidos são lidos do índice de busca da Zouti, que acompanha o banco com alguns segundos de
atraso. Uma leitura feita logo depois de uma mudança (um pagamento aprovado, um reembolso) pode
ainda trazer a versão anterior. Repita a leitura em alguns segundos. A
[sincronização](/concepts/sync) já cobre esse atraso com a janela de 5 minutos.

## Quais pedidos entram

* **Só pedidos de infoproduto**, os mesmos que aparecem no dashboard.
* **Pedidos da conta e de coprodução.** O campo `role` diz qual é o caso: `OWNER` quando a conta
  é dona, `COPRODUCER` quando participa por coprodução.
* **Nunca pedidos de outra conta.** Um pedido de outra conta recebe `404`, como um pedido que não
  existe.

## Pagamento recusado aparece

Um cartão recusado no checkout, inclusive pelo antifraude, gera um pedido visível na API:

* `status` do pedido: `UNPAID`;
* `payment.status`: `DECLINED`;
* `payment.decline_code`: o motivo no código padronizado da Zouti (`ZT-` seguido de 4 dígitos),
  com o texto em `payment.decline_message`.

Para listar as recusas, filtre `status=UNPAID` e confira `payment.status`. Veja o
[objeto pedido](/api-reference/order-object).

## Falha técnica da Zouti não aparece

Quando a cobrança no checkout não chega ao banco por uma falha técnica do lado da Zouti (a
comunicação com o adquirente falhou), o pedido não entra na API: não existe `status` `FAILED` no
pedido. Isso não é uma recusa: o banco não chegou a avaliar a compra.

Não confunda com `payment.status` `FAILED`: ele indica um pagamento que não chegou ao banco por
falha de comunicação e pode aparecer num pedido visível, como numa renovação de assinatura.

## Coprodução

* A conta vê o pedido quando é coprodutora do **último pagamento** dele. Quem foi coprodutor só de
  um pagamento anterior do mesmo pedido não vê o pedido. O dashboard segue a mesma regra.
* Os valores (`amount_total`, `payment.amount`, `payment.fee`…) são os do **pedido inteiro**, não
  a parte da conta na coprodução.
* `tracking` e `navigator` vêm `null` para o coprodutor.

## Dados de cartão e do navegador

* **Cartão:** só a bandeira (`payment.card.brand`) e os últimos 4 dígitos
  (`payment.card.last4`). Nenhum outro dado de cartão é exposto.
* **IP do comprador:** nunca é exposto. `navigator` traz o navegador e a origem da visita
  (`user_agent`, `referer`, `device`, `browser`, `origin`), sem o IP.

## Dados pessoais do comprador

Os pedidos trazem dados pessoais do comprador: nome, e-mail, telefone, CPF ou CNPJ e endereço.
Trate-os como dado pessoal, nos termos da LGPD:

* guarde só os campos que a integração usa;
* limite quem acessa a cópia local e a chave de API;
* apague o que não precisar mais.

Depois de copiados para o seu sistema, cuidar desses dados passa a ser responsabilidade da sua
empresa.

<RequestExample>
  ```bash cURL theme={null}
  # Requer jq. Mostra papel, status e motivo de recusa de cada pedido da página.
  curl -sS "https://api.zouti.com.br/v1/orders?limit=100" \
    -H "Authorization: Bearer $ZOUTI_API_KEY" \
    | jq -r '.data[] | [.id, .role, .status, .payment.status, (.payment.decline_code // "-")] | @tsv'
  ```

  ```javascript Node.js theme={null}
  // Node.js 18+ (fetch nativo). Mostra papel, status e motivo de recusa de cada pedido da página.
  const API_KEY = process.env.ZOUTI_API_KEY;
  const BASE_URL = 'https://api.zouti.com.br';

  const response = await fetch(`${BASE_URL}/v1/orders?limit=100`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const body = await response.json();
  if (!response.ok) {
    console.error(`${body.error.code} (${body.error.request_id})`);
    process.exit(1);
  }

  for (const order of body.data) {
    const notes = [];
    if (order.payment.status === 'DECLINED') {
      notes.push(`recusado: ${order.payment.decline_code} (${order.payment.decline_message})`);
    }
    if (order.role === 'COPRODUCER') {
      notes.push('coprodução: valores do pedido inteiro; tracking e navigator null');
    }
    console.log([order.id, order.role, order.status, ...notes].join(' · '));
  }
  ```

  ```python Python theme={null}
  # Python 3 com requests. Mostra papel, status e motivo de recusa de cada pedido da página.
  import os

  import requests

  API_KEY = os.environ["ZOUTI_API_KEY"]
  BASE_URL = "https://api.zouti.com.br"

  response = requests.get(
      f"{BASE_URL}/v1/orders",
      params={"limit": 100},
      headers={"Authorization": f"Bearer {API_KEY}"},
      timeout=30,
  )
  body = response.json()
  if not response.ok:
      raise SystemExit(f"{body['error']['code']} ({body['error']['request_id']})")

  for order in body["data"]:
      notes = []
      payment = order["payment"]
      if payment["status"] == "DECLINED":
          notes.append(f"recusado: {payment['decline_code']} ({payment['decline_message']})")
      if order["role"] == "COPRODUCER":
          notes.append("coprodução: valores do pedido inteiro; tracking e navigator null")
      print(" · ".join([order["id"], order["role"], order["status"], *notes]))
  ```

  ```php PHP theme={null}
  <?php
  // PHP 7.4+ com a extensão curl. Mostra papel, status e motivo de recusa de cada pedido da página.
  const BASE_URL = 'https://api.zouti.com.br';

  $ch = curl_init(BASE_URL . '/v1/orders?limit=100');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ZOUTI_API_KEY')],
  ]);
  $raw = curl_exec($ch);
  if ($raw === false) {
      fwrite(STDERR, curl_error($ch) . PHP_EOL);
      exit(1);
  }
  $body = json_decode($raw, true);
  if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200) {
      fwrite(STDERR, "{$body['error']['code']} ({$body['error']['request_id']})\n");
      exit(1);
  }

  foreach ($body['data'] as $order) {
      $notes = [];
      $payment = $order['payment'];
      if ($payment['status'] === 'DECLINED') {
          $notes[] = "recusado: {$payment['decline_code']} ({$payment['decline_message']})";
      }
      if ($order['role'] === 'COPRODUCER') {
          $notes[] = 'coprodução: valores do pedido inteiro; tracking e navigator null';
      }
      echo implode(' · ', array_merge([$order['id'], $order['role'], $order['status']], $notes)) . "\n";
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Pedido de coprodução theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.