Docs

Kinds & fields

The core generation engine supports 12 distinct kinds. Standalone document kinds (cpf, cnpj, cnh, pis, rg) produce an object containing value and optional formatted representations, while complex entity kinds return rich structured objects.

person

Realistic individual with valid documents, contact details, and address matching the individual's location:

• name (string): Full name
• firstName (string): Given name
• lastName (string): Family name
• gender ('F' | 'M'): Gender indicator
• birthDate (string): Birth date formatted as YYYY-MM-DD
• age (number): Calculated age in years relative to now
• cpf (string): Valid CPF check digits
• rg (string): SP identity document number
• cnh (string): 11-digit DENATRAN driver license number
• pis (string): 11-digit mod-11 PIS number
• motherName (string): Mother's full name
• email (string): Safe email address on an RFC 2606 domain
• mobilePhone (string): DDD matching address city + 9 + 8 subscriber digits
• phone (string): Landline phone (DDD + [2-5] + 7 digits)
• address (object): Complete nested address object

company

Brazilian business entity with active tax numbers, partners, and CNAE activity:

• corporateName (string): Legal entity name (Razão Social)
• tradeName (string): Commercial name (Nome Fantasia)
• cnpj (string): Valid CNPJ branch 0001
• stateRegistration (string): State tax registration (Inscrição Estadual)
• municipalRegistration (string): Municipal registration (Inscrição Municipal)
• openingDate (string): Formation date formatted as YYYY-MM-DD
• size ('MEI' | 'ME' | 'EPP' | 'DEMAIS'): Company size
• activity (object): { cnae: string, description: string }
• email (string): Company contact email
• phone (string): Landline phone
• mobilePhone (string): Mobile phone
• website (string): Domain format https://www.slug.example.com
• address (object): Company address
• partners (array): 1 to 3 person objects (minimum age 21, matching state)

address

Postal address with verified Brazilian postal code (CEP) range and IBGE code:

• postalCode (string): 8-digit postal code within the city's assigned range
• street (string): Street type and name
• number (string): Building number (or 'S/N')
• complement (string): Apartment, suite, room, or empty
• district (string): Neighborhood name (Bairro)
• city (string): Municipality name
• state (string): 2-letter state abbreviation (UF)
• stateName (string): Full state name
• ibgeCode (string): Official 7-digit IBGE city code
• country (string): 'Brasil'

credit-card

Test credit card details with expiration dates in the future:

• holderName (string): Cardholder name
• number (string): 16-digit card number (4444444444444444 for APPROVE, 5184019740373151 for DECLINE, or random Luhn-valid)
• brand (string): Card network (Visa, Mastercard, Elo, Amex)
• expiryMonth (string): 2-digit month (01–12)
• expiryYear (string): 4-digit expiration year (1 to 6 years ahead of now)
• ccv (string): 3-digit security code
• outcome ('APPROVE' | 'DECLINE' | 'UNKNOWN'): Configured transaction result

bank-account

Bank account with verified Brazilian clearing codes:

• bank (object): { code: string, name: string, ispb: string }
• agency (string): 4-digit branch code
• agencyDigit (string): Branch check digit
• account (string): Account number
• accountDigit (string): Account check digit
• type ('CONTA_CORRENTE' | 'CONTA_POUPANCA'): Account type

pix-key

Pix identification key:

• type ('CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'EVP'): Key category
• key (string): Generated key value (UUIDv4 for EVP, E.164 format for phone)

charge

Financial invoice or charge for payment processing:

• billingType ('PIX' | 'BOLETO' | 'CREDIT_CARD'): Payment method
• valueCents (number): Total amount in centavos
• value (number): Amount in BRL with 2 decimal places
• dueDate (string): Due date between 0 and 30 days after now
• description (string): Line-item service or product description
• externalReference (string): Unique identifier prefixed with GEN-

Document Kinds (cpf, cnpj, cnh, pis, rg)

Stand-alone document generations produce:

• value (string): Digits-only string (SP RG check digit may be 'X')
• formatted (string, optional): Masked string when formatted=true (e.g. 123.456.789-09)

Query parameters

The GET /v1/:kind endpoint accepts the following query parameters:

Determinism

All core generation functions use an internal mulberry32 pseudo-random number generator initialized from the provided seed string. There is no call to Math.random() inside the core generation modules.

Given identical inputs (kind, seed, parameters, and reference date now), the output is guaranteed to be 100% identical. This makes the generator ideal for end-to-end regression suites, reproducible snapshot tests, and deterministic database fixtures.

Safe data guarantees

Generated data is designed never to collide with real-world credentials or deliver emails to unintended recipients:

• RFC 2606 Domains: All email addresses use reserved testing domains (example.com, example.org, example.net).
• Websites: Formatted with RFC 2606 domains as https://www..example.com.
• Test Cards: Approvals and declines use the well-known test card numbers accepted by the Asaas mock (4444444444444444 and 5184019740373151).
• Phone numbers: Adhere to telecommunication standards without repeated subscriber digits, preventing spam flags during automated tests.

Asaas population

The POST /_mock/asaas/populate endpoint populates the Asaas mock server with customers and payments in a single operation.

Automatic Discovery Both Ways

The Asaas mock looks for the generator on boot and every 10 s at the compose service generator (or generator-mock), on this machine (localhost) and on the Docker host (host.docker.internal), port 45450, the closest first, and takes a place only when it answers GET /health with service: "generator". When GENERATOR_URL is set, it is used as given; set empty, it is turned off. GENERATOR_UI_URL (default http://localhost:45450) specifies where the browser opens it.

The generator finds the Asaas mock by itself when ASAAS_URL is unset: it probes asaas, asaas-mock, localhost, and the Docker host on port 45445, identified by its /health endpoint, on boot and every 10 s. Thus, running both via docker run or within any Docker Compose setup requires no URL environment variables.

The Panel Integration

While the generator is found, the Asaas panel displays an Integrations › Generator tab showing connection status, an "Open generator" link, and a "Populate this account" button. Clicking it creates customers (people and companies with valid CPF/CNPJ) for the account selected in the topbar, registers charges by Pix, boleto, and card, and marks a configurable share of them as paid. This executes through that account's API key via POST /_admin/generator/populate. When the generator is not found or turned off, the tab does not exist.

Request Body

{
  "people": 5,
  "companies": 2,
  "chargesPerCustomer": 2,
  "billingTypes": ["PIX", "BOLETO", "CREDIT_CARD"],
  "confirm": 0.5,
  "seed": "optional-seed",
  "apiKey": "optional-account-api-key"
}

Execution Steps

1. Target Account: Uses the apiKey specified in the request body to authenticate against Asaas, defaulting to the server's configured ASAAS_API_KEY if omitted.
2. Create Customers: For each person and company generated, issues a POST /v3/customers request to the Asaas mock API.
3. Create Payments: For each customer, creates charges using POST /v3/payments matching the specified chargesPerCustomer and billingTypes.
4. Confirm Payments: Based on the confirm ratio (0.0 to 1.0), issues POST /v3/sandbox/payment/{id}/confirm to transition selected charges from pending to confirmed/received status.
5. Report Results: Returns an array of customer IDs, payment records with invoice links, and an errors array listing any failed steps with status codes and error messages.

Configuration

The generator server is configured via environment variables:

Docker Compose

In another project's compose, add a generator service next to asaas. Both find each other automatically by service name without requiring any configuration variables:

  generator:
    image: ghcr.io/instituto-ama/generator-mock:0.2.0
    ports:
      - '45450:45450'
    depends_on:
      - asaas

Local guard

To prevent unauthorized access or cross-site request attacks against developer environments, the server enforces a Host and Origin security guard on the root UI route (/) and mock management endpoints (/_mock/*).

Allowed hosts default to localhost, 127.0.0.1, ::1, and host.docker.internal. On POST requests, the Origin header is validated against the permitted origins. Public API endpoints under /v1/* remain unrestricted with Access-Control-Allow-Origin: *.