Skip to main content
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. Read the key locally so it does not appear in the command you save or share:
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.

​
2. Read your customers

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

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 or Colombia. The shared-fields guide explains which inputs carry over between countries.

Avoid duplicate customers

Find the same customer using an ID from your application.

Understand Mexican invoicing

Learn the difference between a payment, receipt, draft, and CFDI.

Issue your first Mexican invoice

Save a draft, preview it, and inspect the issued result.

Record a bank transfer

Record money already received, with duplicate protection.
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 for examples.