ama4devs
EN PT

Quick start

From docker run to reproducible test fixtures and instant Asaas mock population. Every command below runs as written against a fresh container.

The examples call

  1. Run it

    Run the generator container in Docker. In this repository, running make up brings it automatically alongside the Asaas mock.

    docker run --rm -p 45450:45450 ghcr.io/instituto-ama/generator-mock:latest

    The service listens on port 45450. You can verify its health status:

    curl https://instituto-ama.github.io/ama4devs/generator/api/v1/index

  2. Generate data

    Request data for any of the 12 supported kinds. Use the count query parameter to fetch multiple items:

    curl https://instituto-ama.github.io/ama4devs/generator/api/v1/person
curl https://instituto-ama.github.io/ama4devs/generator/api/v1/cnpj
    {
  "kind": "person",
  "seed": "demo",
  "count": 2,
  "items": [
    {
      "name": "Letícia Lima Pinto",
      "firstName": "Letícia",
      "lastName": "Lima Pinto",
      "gender": "F",
      "birthDate": "1994-12-21",
      "age": 31,
      "cpf": "75423753180",
      "rg": "480240619",
      "cnh": "17784470214",
      "pis": "79734031356",
      "motherName": "Denise Correia Sampaio",
      "email": "leticia.pinto91@example.org",
      "mobilePhone": "19937392567",
      "phone": "1954050838",
      "address": {
        "postalCode": "13986184",
        "street": "Estrada São Roque",
        "number": "1619",
        "complement": "",
        "district": "Brooklin",
        "city": "Campinas",
        "state": "SP",
        "stateName": "São Paulo",
        "ibgeCode": "3509502",
        "country": "Brasil"
      }
    },
    {
      "name": "Marcelo Cavalcanti Andrade",
      "firstName": "Marcelo",
      "lastName": "Cavalcanti Andrade",
      "gender": "M",
      "birthDate": "1961-11-01",
      "age": 64,
      "cpf": "44981554168",
      "rg": "870099644",
      "cnh": "43525537763",
      "pis": "63870502741",
      "motherName": "Jussara Nascimento Farias",
      "email": "marcelo.andrade@example.com",
      "mobilePhone": "11958054794",
      "phone": "1132725780",
      "address": {
        "postalCode": "05673977",
        "street": "Via Dos Campos",
        "number": "4451",
        "complement": "Bloco B",
        "district": "Alto da Lapa",
        "city": "São Paulo",
        "state": "SP",
        "stateName": "São Paulo",
        "ibgeCode": "3550308",
        "country": "Brasil"
      }
    }
  ]
}

  3. Reproducible seeds

    Same seed always produces the same output. Add &now=YYYY-MM-DD to freeze the reference date so calculated ages, credit card expirations, and due dates remain perfectly stable over time:

    curl https://instituto-ama.github.io/ama4devs/generator/api/v1/person/42
    {
  "kind": "person",
  "seed": "demo",
  "count": 1,
  "items": [
    {
      "name": "Letícia Lima Pinto",
      "firstName": "Letícia",
      "lastName": "Lima Pinto",
      "gender": "F",
      "birthDate": "1994-12-21",
      "age": 31,
      "cpf": "75423753180",
      "rg": "480240619",
      "cnh": "17784470214",
      "pis": "79734031356",
      "motherName": "Denise Correia Sampaio",
      "email": "leticia.pinto91@example.org",
      "mobilePhone": "19937392567",
      "phone": "1954050838",
      "address": {
        "postalCode": "13986184",
        "street": "Estrada São Roque",
        "number": "1619",
        "complement": "",
        "district": "Brooklin",
        "city": "Campinas",
        "state": "SP",
        "stateName": "São Paulo",
        "ibgeCode": "3509502",
        "country": "Brasil"
      }
    }
  ]
}

  4. Validate documents

    Validate CPF, CNPJ, CNH, or PIS strings directly against official checksum algorithms:

    curl https://instituto-ama.github.io/ama4devs/generator/api/v1/validate/cpf/11144477735
    {
  "type": "cpf",
  "value": "11144477735",
  "valid": true
}

  5. Populate Asaas

    When running alongside the Asaas mock (such as with make up), the integration is zero-config: the Asaas mock discovers the generator by itself on boot and every 10 s. The Asaas panel (http://localhost:45445) displays an Integrations › Generator tab with status, a link to open the generator, and a Populate this account button to seed the account selected in the topbar with customers and charges.

    You can also populate the mock in one HTTP call. The generator creates customers, generates charges with varied billing types (Pix, boleto, credit card), and automatically confirms payments for a configurable percentage:

    curl -X POST http://localhost:45450/_mock/asaas/populate \
  -H 'Content-Type: application/json' \
  -d '{"people":5,"companies":2,"chargesPerCustomer":2,"confirm":0.5}'
    {
  "seed": "t0fj7hjs",
  "panelUrl": "http://localhost:45445",
  "customers": [
    {
      "id": "cus_628178853456",
      "name": "Wanda Maciel Azevedo",
      "cpfCnpj": "93810722138",
      "personType": "FISICA"
    },
    {
      "id": "cus_813080613088",
      "name": "Amanda Moura Lima",
      "cpfCnpj": "04736054654",
      "personType": "FISICA"
    }
    … 7 customers in all
  ],
  "payments": [
    {
      "id": "pay_041947707232",
      "customer": "cus_628178853456",
      "billingType": "PIX",
      "value": 4555.45,
      "dueDate": "2026-11-23",
      "status": "PENDING",
      "invoiceUrl": "http://localhost:45445/i/041947707232"
    },
    {
      "id": "pay_006960851291",
      "customer": "cus_628178853456",
      "billingType": "BOLETO",
      "value": 177.41,
      "dueDate": "2026-11-23",
      "status": "CONFIRMED",
      "invoiceUrl": "http://localhost:45445/i/006960851291"
    }
    … 14 payments in all
  ],
  "errors": []
}

    To populate automatically when the stack starts up, configure GENERATOR_ASAAS_SEED_ON_BOOT in your .env file (stays off unless set):

    GENERATOR_ASAAS_SEED_ON_BOOT=people=10,companies=3,charges=2,confirm=0.5

  6. Interactive UI

    Open http://localhost:45450 to view the local web UI, or explore the hosted web app on GitHub Pages. The UI lets you generate, inspect, format, copy, and export data in JSON, CSV, or tabular formats.

  7. Turn it off

    The generator is enabled by default. In Docker Compose, set GENERATOR_ENABLED=0 in .env to keep the service down (via deploy.replicas). On the Asaas mock side, setting GENERATOR_URL= (empty) disables generator discovery. When turned off or unreachable, the Integrations › Generator tab does not exist in the Asaas panel.