ama4devs
EN PT

Início rápido

Do docker run a chamadas com determinismo e população automática do mock do Asaas. Cada comando abaixo pode ser executado como está escrito.

Os exemplos chamam

  1. Suba

    Execute o container oficial do gerador. A porta padrão é 45450 e o serviço fica pronto em milissegundos sem dependências de banco de dados.

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

    Verifique o status do serviço chamando o endpoint de saúde:

    curl https://instituto-ama.github.io/ama4devs/generator/api/v1/index
    {
  "status": "ok",
  "service": "generator",
  "version": "0.2.0"
}

  2. Gere dados

    Gere pessoas fictícias completas com CPFs válidos, datas de nascimento coerentes e endereços reais. Você pode fixar uma data de referência com now para garantir que idades e vencimentos permaneçam imutáveis ao longo do tempo.

    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. Determinismo e semente

    O algoritmo pseudoaleatório (mulberry32) garante que a mesma semente gere rigorosamente o mesmo conjunto de dados em qualquer máquina ou ambiente de CI. Repita a requisição acima com seed=demo e receba exatamente o mesmo resultado.

    curl https://instituto-ama.github.io/ama4devs/generator/api/v1/person/42
    {
  "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"
      }
    }
  ]
}

  4. Validação

    Valide se um CPF, CNPJ, CNH ou PIS atende aos cálculos matemáticos oficiais de dígitos verificadores e rejeição de sequências repetidas.

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

  5. Popule o Asaas

    No compose do repositório (make up), o gerador sobe junto com o mock do Asaas (porta 45450). Os dois se descobrem sozinhos sem configuração: abra o painel do mock do Asaas em http://localhost:45445 e acesse Integrações › Gerador. Clique em Popular esta conta para cadastrar pessoas e empresas com CPF/CNPJ válidos como clientes da conta selecionada na barra superior, gerando cobranças por Pix, boleto e cartão (parte delas já pagas). Ou clique em Abrir o gerador para usar a interface interativa.

    Você também pode popular via API com um único comando HTTP:

    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": "kqfp4hwf",
  "panelUrl": "http://localhost:45445",
  "customers": [
    {
      "id": "cus_651067071968",
      "name": "Daniela Moura Aguiar",
      "cpfCnpj": "81054771812",
      "personType": "FISICA"
    },
    {
      "id": "cus_858206104608",
      "name": "Solange Souza Gonçalves",
      "cpfCnpj": "23558848624",
      "personType": "FISICA"
    }
    … 7 customers in all
  ],
  "payments": [
    {
      "id": "pay_386004571824",
      "customer": "cus_651067071968",
      "billingType": "CREDIT_CARD",
      "value": 4431.17,
      "dueDate": "2026-11-06",
      "status": "CONFIRMED",
      "invoiceUrl": "http://localhost:45445/i/386004571824"
    },
    {
      "id": "pay_679244559146",
      "customer": "cus_651067071968",
      "billingType": "CREDIT_CARD",
      "value": 2152.34,
      "dueDate": "2026-11-12",
      "status": "CONFIRMED",
      "invoiceUrl": "http://localhost:45445/i/679244559146"
    }
    … 14 payments in all
  ],
  "errors": []
}

    A semente no boot fica desligada a menos que definida. Para semear automaticamente na inicialização, defina GENERATOR_ASAAS_SEED_ON_BOOT no seu .env:

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

  6. Interface web

    O gerador conta com uma interface visual interativa completa. Quando executado em container local, acesse http://localhost:45450. No GitHub Pages, acesse ama4devs/generator/app/ para gerar diretamente no navegador sem necessidade de instalar nada.

    Consulte o status da integração com o Asaas pela API:

    curl http://localhost:45450/_mock/asaas/status
    {
  "asaasUrl": "http://localhost:45445",
  "panelUrl": "http://localhost:45445",
  "reachable": true,
  "customers": 28
}

  7. Desligar

    A integração vem ligada por padrão. Para não subir o gerador no compose, use GENERATOR_ENABLED=0 no .env (ele ajusta deploy.replicas). Para desativar a busca no mock do Asaas mesmo com o gerador rodando, defina GENERATOR_URL= (vazia): desligado ou não encontrado, a aba Gerador não aparece no painel do Asaas.