Docs

Tipos e campos

O gerador suporta doze tipos fundamentais (kinds). Cada chamada retorna um objeto contendo metadados (kind, seed, count) e a lista de items:

1. Pessoa (person)

Representa uma pessoa física com dados demográficos e endereço coerente:

• name (string): Nome completo
• firstName, lastName (string): Primeiro nome e sobrenome
• gender (string): "F" ou "M"
• birthDate (string): Data de nascimento no padrão ISO YYYY-MM-DD
• age (number): Idade calculada na data de referência
• cpf (string): CPF válido com 11 dígitos numéricos
• rg (string): Registro Geral (padrão São Paulo)
• cnh (string): Carteira Nacional de Habilitação (11 dígitos, DENATRAN)
• pis (string): PIS/PASEP (11 dígitos, ponderação 3-2)
• motherName (string): Nome completo da mãe
• email (string): E-mail em domínio seguro RFC 2606 (ex: @example.com)
• mobilePhone (string): Celular com DDD correspondente à cidade do endereço e nono dígito (nunca todos os dígitos iguais)
• phone (string): Telefone fixo com DDD e prefixo comercial/residencial [2-5]
• address (object): Objeto de endereço completo correspondente

2. Empresa (company)

Representa uma pessoa jurídica com sócios e atividade econômica:

• corporateName (string): Razão social
• tradeName (string): Nome fantasia
• cnpj (string): CNPJ filial 0001 com dígitos verificadores válidos
• stateRegistration, municipalRegistration (string): Inscrições estadual e municipal
• openingDate (string): Data de fundação/abertura (YYYY-MM-DD)
• size (string): Porte: "MEI", "ME", "EPP" ou "DEMAIS"
• activity (object): Atividade CNAE com cnae (código oficial) e description
• email, phone, mobilePhone (string): Contatos comerciais
• website (string): Endereço web seguro (ex: https://www.<slug>.example.com)
• address (object): Endereço da sede da empresa
• partners (array): Lista de 1 a 3 pessoas físicas (Person[]) sócias no mesmo estado

3. Endereço (address)

Endereço geográfico real cobrindo todos os 27 estados da federação:

• postalCode (string): CEP de 8 dígitos na faixa oficial da cidade
• street (string): Tipo de logradouro e nome da rua/avenida
• number (string): Número do imóvel ("1" a "4999" ou "S/N")
• complement (string): Complemento (apto, sala, casa, bloco ou vazio)
• district (string): Bairro
• city (string): Nome do município
• state (string): Sigla da Unidade Federativa (UF, ex: "SP")
• stateName (string): Nome por extenso do estado
• ibgeCode (string): Código IBGE oficial de 7 dígitos
• country (string): "Brasil"

4. Documentos individuais (cpf, cnpj, cnh, pis, rg)

Cada documento avulso retorna um objeto simplificado:

• value (string): Valor numérico sem máscara (ou com dígito verificador)
• formatted (string): Valor formatado com pontuação e traços padrão

5. Cartão de crédito (credit-card)

Cartão de teste pronto para ser transacionado:

• holderName (string): Nome do titular em caixa alta
• number (string): Número do cartão (16 dígitos)
• brand (string): Bandeira: VISA, MASTERCARD, ELO ou AMEX
• expiryMonth (string): Mês de expiração ("01" a "12")
• expiryYear (string): Ano de expiração (1 a 6 anos à frente da data de referência)
• ccv (string): Código de segurança de 3 dígitos
• outcome (string): Comportamento no Asaas: "APPROVE", "DECLINE" ou "UNKNOWN"

6. Conta bancária (bank-account)

Conta corrente ou poupança em instituições financeiras brasileiras reais:

• bank (object): Dados do banco com code (ex: "001"), name (ex: "Banco do Brasil") e ispb
• agency, agencyDigit (string): Agência e dígito verificador
• account, accountDigit (string): Número da conta e dígito
• type (string): Modalidade: "CONTA_CORRENTE" ou "CONTA_POUPANCA"

7. Chave Pix (pix-key)

Chave de endereçamento do arranjo Pix do Banco Central:

• type (string): Modalidade: "CPF", "CNPJ", "EMAIL", "PHONE" ou "EVP"
• key (string): Chave no formato adequado (+55 com DDD para telefone, UUID v4 para EVP)

8. Cobrança (charge)

Dados de emissão financeira prontos para envio ao Asaas:

• billingType (string): Forma de pagamento: "PIX", "BOLETO" ou "CREDIT_CARD"
• valueCents (number): Valor em centavos inteiros (ex: 15000)
• value (number): Valor monetário em BRL com duas casas decimais (ex: 150.00)
• dueDate (string): Vencimento no formato YYYY-MM-DD (entre 0 e 30 dias à frente de now)
• description (string): Descrição do serviço ou produto cobrado
• externalReference (string): Identificador único no formato GEN-<8 caracteres>

Parâmetros de consulta

Determinismo

O gerador é totalmente determinístico. Todo o motor de geração baseia-se em uma instância de Rng alimentada pelo algoritmo mulberry32 a partir de uma semente textual ou numérica.

A regra de ouro é: mesmo kind + mesma seed + mesmas opções + mesma data now geram exatamente os mesmos dados. Nenhuma chamada interna utiliza Math.random(), exceto a função utilitária randomSeed() que gera um identificador de 8 caracteres caso nenhuma semente seja informada.

Isso permite que suítes de teste de integração e rotinas de CI sejam 100% reproduzíveis, eliminando oscilações causadas por dados aleatórios imprevisíveis.

Dados seguros

Todos os dados foram arquitetados para serem seguros em testes sem risco de vazamento ou disparo involuntário contra pessoas reais:

• E-mails: restritos aos domínios especiais da RFC 2606: example.com, example.org e example.net. Nenhum e-mail pode ser entregue na internet pública.
• Websites: apontam exclusivamente para subdomínios seguros (ex: https://www.slug.example.com).
• Cartões de crédito:
  • 4444444444444444: número oficial de teste que força aprovação (APPROVE) no mock do Asaas.
  • 5184019740373151: número oficial de teste que força recusa imediata de captura (DECLINE) no mock do Asaas.
  • Opção RANDOM: gera números aleatórios matematicamente válidos pelo algoritmo de Luhn (Visa, Master, Elo, Amex) com status UNKNOWN.
• Documentos: nenhum documento gerado possui todos os dígitos iguais repetidos (ex: 111.111.111-11), prevenindo rejeições por regras básicas de integridade.

Integração com Asaas

A integração entre o gerador e o mock do Asaas opera com descoberta automática nos dois sentidos, sem necessidade de configurar URLs:

• O gerador acha o Asaas: quando ASAAS_URL não estiver definida, o gerador procura o mock nos serviços asaas e asaas-mock do compose, nesta máquina (localhost) e no host do Docker (host.docker.internal) na porta 45445, identificado por GET /health (com status: "ok" e clockMode). A busca ocorre no boot e a cada 10 segundos. Assim, rodar ambos via docker run ou em qualquer compose funciona imediatamente sem variáveis.
• O Asaas acha o gerador: o mock do Asaas busca o serviço generator ou generator-mock na porta 45450 (no compose, nesta máquina ou no host do Docker) no boot e a cada 10 s, aceitando apenas serviços que respondam GET /health com service: "generator". A variável GENERATOR_URL quando definida fixa o destino; vazia, desativa a busca. O navegador o abre por GENERATOR_UI_URL (padrão http://localhost:45450).

A aba do painel do Asaas

Enquanto o gerador for encontrado, o painel do Asaas exibe a aba Integrações › Gerador com as ações Abrir o gerador e Popular esta conta. Ao clicar em popular, pessoas e empresas com CPF/CNPJ válidos tornam-se clientes da conta selecionada na barra superior, com cobranças geradas por Pix, boleto e cartão (parte delas já pagas). Essa ação dispara POST /_admin/generator/populate no Asaas, que repassa a chave de API dessa conta para o gerador. Quando o gerador não é encontrado ou está desligado, a aba não existe no painel.

Endpoint POST /_mock/asaas/populate

O endpoint no gerador pode ser invocado diretamente. O campo apiKey no corpo é opcional e direciona a população para a conta informada (caso omitido, usa ASAAS_API_KEY):

POST /_mock/asaas/populate
Content-Type: application/json

{
  "people": 5,
  "companies": 2,
  "chargesPerCustomer": 2,
  "billingTypes": ["PIX", "BOLETO", "CREDIT_CARD"],
  "confirm": 0.5,
  "seed": "minha-semente-opcional",
  "apiKey": "$aact_hmlg_local_master"
}

O que cada passo executa

1. Criação de Clientes: gera pessoas físicas e empresas com endereços válidos e chama POST /v3/customers no Asaas para cada uma.
2. Emissão de Cobranças: para cada cliente criado, emite chargesPerCustomer cobranças distribuídas entre os tipos de pagamento selecionados via POST /v3/payments.
3. Confirmação de Pagamento: calcula a fração informada em confirm (ex: 0.5 = 50% das cobranças emitidas) e executa POST /v3/sandbox/payment/{id}/confirm na API do Asaas, simulando o pagamento imediato e disparando os webhooks correspondentes.

Tratamento de falhas

Se alguma chamada ao Asaas falhar ou retornar erro HTTP, o endpoint não aborta: ele acumula o erro na lista errors: [{ step, status, message }] e continua o processo para os registros restantes, devolvendo o relatório consolidado ao final.

Compose em outro projeto

Para usar o gerador no docker-compose.yml de outro projeto, basta adicionar o serviço generator ao lado do serviço asaas. Os dois serviços se acham automaticamente pelo nome na rede interna, sem precisar definir variáveis de URL:

  generator:
    image: ghcr.io/instituto-ama/generator-mock:latest
    ports:
      - '45450:45450'
    environment:
      PORT: 45450

Variáveis de ambiente

Proteção local (Local Guard)

Para proteger a máquina do desenvolvedor contra ataques de DNS rebinding e chamadas forjadas entre sites (CSRF originadas de páginas maliciosas na web):

• As rotas sensíveis (/, /_mock/*) validam o cabeçalho Host contra a lista permitida: localhost, 127.0.0.1, ::1, host.docker.internal e os hosts extras definidos em MOCK_ALLOWED_HOSTS.
• Requisições do tipo POST (como POST /_mock/asaas/populate) validam adicionalmente a origem no cabeçalho Origin.
• As rotas públicas de geração sob /v1/* emitem cabeçalho Access-Control-Allow-Origin: *, permitindo que qualquer aplicação frontend de desenvolvimento consulte a API sem restrições.