Cadastrar pessoa física
POST /persons — cria PF no tenant, devolve JWT e onboardingLink para KYC.
Cadastrar pessoa física
Cria uma pessoa física no tenant, devolve um JWT pronto pra uso e um onboardingLink pra completar o KYC. A entidade começa com status=PENDING e só passa a operar Pix/TEF/Cobranças após concluir o cadastro no link.
Endpoint público — não requer Authorization, só X-Tenant-Id pra identificar a marca. document é o CPF (11 dígitos, apenas números). A resposta já traz um JWT válido (type=PERSON, expira em 1 hora) — você pode usar imediatamente, mas até o KYC concluir (status=PENDING, onboardingStep≠DONE) operações de Pix/TEF/Cobranças ficam bloqueadas. Sempre direcione a pessoa pra onboardingLink antes do primeiro uso real. Depois do KYC, o login posterior é feito por POST /authenticate.
Headers
- AcceptObrigatóriostringapplication/json
- Content-TypeObrigatóriostringapplication/json
- X-Tenant-IdObrigatóriostring (UUID)Identificador do tenant que vai receber a nova pessoa.
Body
- nameObrigatóriostringNome completo da pessoa.
- documentObrigatóriostringCPF (11 dígitos, apenas números).
- emailObrigatóriostringE-mail de login da pessoa. Único dentro do tenant.
- passwordObrigatóriostringSenha de acesso da pessoa — usada depois em /authenticate.
Exemplo de requisição
curl -X POST https://baas.staterpay.io/persons \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000" \ -d '{ "name": "Fulano de Tal", "document": "12345678900", "email": "fulano@example.com", "password": "12345678" }'Resposta
- personobjectDados da pessoa criada.
- person.idstring (UUID)ID interno da pessoa.
- person.emailstringE-mail informado (eco).
- person.emailConfirmationbooleanSe o e-mail já foi confirmado. Inicialmente false.
- person.phonestring | nullTelefone. null no cadastro inicial — definido durante o KYC.
- person.phoneConfirmationbooleanSe o telefone foi confirmado.
- person.namestringNome informado (eco).
- person.documentstringCPF informado (eco).
- person.status"PENDING" | "ACTIVE" | "BLOCKED"Estado da pessoa. Sempre PENDING na criação.
- person.onboardingStep"PENDING" | "IN_PROGRESS" | "DONE"Etapa atual do KYC. Inicialmente PENDING.
- person.onboardingLinkstring (URL)URL para a pessoa completar o cadastro/KYC. Redirecione/envie pra ela.
- person.onboardingRequisitionIdnumberID da requisição de onboarding no provider de KYC.
- person.hasPinbooleanSe a pessoa já definiu PIN operacional. Inicialmente false.
- tokenstring (JWT)JWT já pronto pra uso em chamadas autenticadas (Authorization: Bearer <token>). Payload tem type="PERSON" e expira em 1 hora.
{ "person": { "id": "00000000-0000-0000-0000-0000000000a1", "email": "fulano@example.com", "emailConfirmation": false, "phone": null, "phoneConfirmation": false, "name": "Fulano de Tal", "document": "12345678900", "status": "PENDING", "onboardingStep": "PENDING", "onboardingLink": "https://cadastro.example.com/00000000000000000000000000000000", "onboardingRequisitionId": 0, "hasPin": false }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>"}https://baas.staterpay.io