> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first successful request

> Choose the environment, verify your key, and save a customer ID.

**Goal:** make one authenticated request and create one test customer. You do not need
SAT certificates to complete these steps. Use a terminal with Bash, `curl`, and `jq`.

## 1. Set your environment

Create a test key in [API settings](https://app.gigstack.pro/settings?tab=api).
Read the key locally so it does not appear in the command you save or share:

```bash theme={null}
set -euo pipefail
export GIGSTACK_BASE_URL='https://api.gigstack.io/v2'
read -rsp 'gigstack test API key: ' GIGSTACK_API_KEY; echo
export GIGSTACK_API_KEY
```

<Note>
  **Test mode and staging are different.** Ordinary live and test keys use the public URL
  above. An internal staging key belongs to a separate environment; use the base URL
  provided with it. A `livemode` field in your JSON does not change the key's mode.
  See [environments](/authentication#environments).
</Note>

## 2. Read your customers

```bash theme={null}
curl --fail-with-body --get "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  --data-urlencode 'limit=2' > clients.json

jq '{count: (.data | length), has_more, next}' clients.json
```

**Expected:** HTTP `200`, a `data` array, `has_more`, and `next`. An empty array is a
valid result. It means this team and mode have no matching customers.

If you receive `401`, check the `Bearer ` prefix and key. If you receive `403` with
`API Key inválida`, check that the key and base URL belong to the same environment.
Other `403` responses can indicate team, role, or plan restrictions.

## 3. Create one test customer

```bash theme={null}
curl --fail-with-body "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Workshop customer","email":"customer@example.com"}' \
  > client.json

CLIENT_ID=$(jq -er '.data.id' client.json)
export CLIENT_ID
jq '{id: .data.id, livemode: .data.livemode}' client.json
```

**Expected:** HTTP `201`, a `client_...` ID, and **`livemode: false`** for a test key.
Stop and check your key if the returned mode is `true`.

You now have a customer record. Fiscal validation may be `skipped` because this small
example contains contact details only. Nothing has been invoiced or charged.

## Pick your next task

Before adding fiscal details, choose [Mexico](/countries/mexico) or
[Colombia](/countries/colombia). The [shared-fields guide](/concepts/shared-fields) explains
which inputs carry over between countries.

<CardGroup cols={2}>
  <Card title="Avoid duplicate customers" icon="users" href="/recipes/customer">
    Find the same customer using an ID from your application.
  </Card>

  <Card title="Understand Mexican invoicing" icon="book-open" href="/concepts/invoicing">
    Learn the difference between a payment, receipt, draft, and CFDI.
  </Card>

  <Card title="Issue your first Mexican invoice" icon="file-invoice" href="/recipes/invoice">
    Save a draft, preview it, and inspect the issued result.
  </Card>

  <Card title="Record a bank transfer" icon="money-bill-transfer" href="/recipes/payment">
    Record money already received, with duplicate protection.
  </Card>
</CardGroup>

The commands use `--fail-with-body`: `curl` exits with code `22` on an HTTP error while
preserving its response body. If `jq -e` exits nonzero, inspect that body before proceeding.
See [troubleshooting](/troubleshooting) for examples.


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