Aparência
Abertura de Conta — Pessoa Física (PF)
Prefixo base: https://developer-api.fastgivr.com.br/access
Sequência completa para abrir uma conta Pessoa Física. As etapas 5–8 não têm ordem obrigatória entre si e são idempotentes (podem ser repetidas), mas a ordem abaixo é a recomendada. Para o contrato completo de cada endpoint (payload/campos/resposta), ver a Referência de Endpoints.
Visão geral da sequência
1. Criar usuário → POST /access/register/user
2. Iniciar solicitação → POST /access/register
3. Confirmar e-mail → POST /access/register/email/verify
4. Dados pessoais → PATCH /access/register/personal-data
5. Endereço → PATCH /access/register/address
6. Telefone → PATCH /access/register/phone
7. Documentos → POST /access/register/documents (uma vez por tipo)
8. Validação de identidade → POST /access/register/identity-validation
→ status muda para "pronto para análise" automaticamente quando tudo estiver completo,
inclusive a validação de identidade do titularEtapa 1 — Criar usuário
Objetivo: Criar as credenciais de login antes de iniciar a solicitação.
Endpoint: POST /access/register/user
Dados coletados: nome completo, e-mail, CPF, telefone, senha.
| Campo | Obrigatório | Observação |
|---|---|---|
name | Sim | Nome completo |
email | Sim | Único no sistema |
document | Sim | CPF (11 dígitos) — define que o fluxo é PF |
phone | Sim | |
password | Sim | mín. 5 caracteres |
Dependências: Nenhuma — é o primeiro passo.
Dados retornados a reutilizar: document (usado em todas as chamadas seguintes para identificar a solicitação).
Etapa 2 — Iniciar a solicitação
Objetivo: Criar a solicitação de abertura de conta (KYC) vinculada ao usuário da etapa 1.
Endpoint: POST /access/register
Dados coletados: só o document — nome e e-mail já vêm do usuário criado na etapa 1.
| Campo | Obrigatório | Observação |
|---|---|---|
document | Sim | O mesmo CPF da etapa 1 |
Dependências: Requer o usuário já criado (etapa 1).
Dados retornados a reutilizar: id — vira o register_id usado em todas as chamadas seguintes.
Nesse momento a API envia automaticamente um código de verificação por e-mail.
Etapa 3 — Confirmar o e-mail
Objetivo: Validar o e-mail antes de liberar o preenchimento dos dados pessoais.
Endpoint: POST /access/register/email/verify(se o código não chegar ou expirar, reenviar com POST /access/register/email antes de tentar de novo)
Dados coletados: o código de 4 números recebido por e-mail.
| Campo | Obrigatório | Observação |
|---|---|---|
register_id | Sim | Da etapa 2 |
document | Sim | |
validation_code | Sim | Válido por 10 minutos |
Dependências: Requer a solicitação já iniciada (etapa 2).
Dados retornados a reutilizar: Nenhum novo — a solicitação passa a aceitar as próximas etapas.
Etapa 4 — Dados pessoais
Objetivo: Preencher os dados de KYC do titular.
Endpoint: PATCH /access/register/personal-data
Dados coletados: nome da mãe, data de nascimento, faixa de renda, ocupação, nome social.
| Campo | Obrigatório | Observação |
|---|---|---|
register_id / document | Sim | |
mother_name | Sim | Nome completo da mãe |
birth_date | Sim | YYYY-MM-DD |
invoicing | Sim | Faixa de renda mensal, texto livre |
social_name | Não | Nome social |
cbo | Não | Ocupação |
Dependências: Requer e-mail confirmado (etapa 3). Recusa a chamada se a solicitação não for Pessoa Física.
Dados retornados a reutilizar: Nenhum novo.
Etapa 5 — Endereço
Objetivo: Preencher o endereço residencial do titular.
Endpoint: PATCH /access/register/address
| Campo | Obrigatório | Observação |
|---|---|---|
register_id / document | Sim | |
street, address_number, neighborhood, city, state, zip_code | Sim | state com 2 letras |
complement | Não |
Dependências: Nenhuma ordem obrigatória, mas normalmente vem depois dos dados pessoais.
Dados retornados a reutilizar: Nenhum novo.
Etapa 6 — Telefone
Objetivo: Registrar o telefone de contato.
Endpoint: PATCH /access/register/phone
| Campo | Obrigatório |
|---|---|
register_id / document | Sim |
phone_number | Sim |
Dependências: Nenhuma.
Dados retornados a reutilizar: Nenhum novo.
Etapa 7 — Documentos
Objetivo: Enviar os documentos obrigatórios do titular que não dependem de prova de vida.
Endpoint: POST /access/register/documents (uma chamada por tipo de documento)
Documentos enviados nesta etapa (pelo computador):
| Tipo | Descrição |
|---|---|
proof_of_address | Comprovante de endereço |
Dependências: Nenhuma ordem obrigatória. Reenviar o mesmo tipo substitui o arquivo anterior.
Dados retornados a reutilizar: Nenhum — a lista de documentos enviados pode ser conferida via POST /access/register/resume.
identity_front / identity_back / selfie
Esses 3 documentos não são mais enviados nesta etapa — eles são capturados na Etapa 8 (Validação de Identidade), pelo celular, junto com a prova de vida.
Etapa 8 — Validação de Identidade
Objetivo: O titular precisa concluir a validação de identidade (prova de vida + fotos do documento, frente e verso) pelo celular. As fotos enviadas aqui são os RegisterDocument identity_front/identity_back/selfie da solicitação. Ver Validação de Identidade para o conceito completo.
Endpoint: POST /access/register/identity-validation (sem partner_document — é sempre o titular na Pessoa Física)
Dependências: Nenhuma ordem obrigatória com as demais etapas — mas a solicitação só fica "pronta para análise" depois de concluída.
Dados retornados a reutilizar: token/link — enviar ao titular para ele concluir a validação. Quem conclui a etapa é o provedor, via callback (POST /access/register/identity-validation/callback), não uma chamada do cliente.
Depois de completa
Assim que dados, endereço, telefone, todos os documentos obrigatórios e a validação de identidade do titular estiverem completos, o status da solicitação muda automaticamente para "pronto para análise" — não é preciso chamar nenhum endpoint adicional. A partir daí, a equipe de análise assume o processo (ver Revisão e Aprovação).