Skip to content

Abertura de Conta — Referência de Endpoints ​

Prefixo base: https://developer-api.fastgivr.com.br/access

Referência central de todos os endpoints usados nos fluxos de Pessoa Jurídica e Pessoa Física. Use esta página para o contrato completo de cada endpoint (payload, campos, resposta); use as páginas de fluxo para a sequência e as dependências entre etapas.

Autenticação na Fidúcia: o envio do cadastro à Fidúcia usa a API de Onboarding, autenticada em POST /users/auth com client_id, client_secret e scope (painel_api) definidos direto no .env (FIDUCIA_ONBOARDING_*) — não o login da conta. Ver Fidúcia — autenticação por endpoint.

Todas as respostas seguem o envelope padrão:

json
{ "code": 200, "success": true, "data": { ... }, "message": "..." }

POST /access/register/user ​

Finalidade: Criar as credenciais de login (usuário) — primeiro passo de qualquer abertura de conta. Fluxo: PF e PJ (mesmo endpoint — o tipo é decidido pelo tamanho do document) Etapa: 1 — Criar usuário Pré-requisitos: Nenhum.

Payload:

json
{ "name": "...", "email": "...", "document": "...", "phone": "...", "password": "..." }

Campos obrigatórios: name, email, document (11 dígitos = CPF/PF, 14 = CNPJ/PJ), phone, password (mín. 5 caracteres). Campos opcionais: Nenhum.

Resposta: 201 com o usuário criado, ou 200 "Cadastro retomado." se o document já existir e a senha conferir (dados enviados no corpo são ignorados nesse caso). 422 "Documento já cadastrado." se existir e a senha não conferir.

Dados utilizados nas próximas etapas: document (identifica o usuário em todas as chamadas seguintes).


POST /access/register ​

Finalidade: Iniciar a solicitação de abertura de conta (KYC) para o usuário já criado. Fluxo: PF e PJ Etapa: 2 — Iniciar solicitação Pré-requisitos: Usuário criado (POST /access/register/user).

Payload:

json
{ "document": "..." }

Campos obrigatórios: document (precisa já existir). Campos opcionais: Nenhum.

Resposta: 200 com a solicitação criada (ou a existente, se já havia uma para esse document). Inclui id, account_type (1 = PF, 2 = PJ, derivado do document), account_status (inicial: e-mail não verificado).

Dados utilizados nas próximas etapas: id (é o register_id usado em todas as chamadas seguintes), account_type (decide se o fluxo segue como PF ou PJ a partir daqui).


POST /access/register/email — Reenviar código de verificação ​

Finalidade: Reenviar o código de confirmação de e-mail, caso o cliente não tenha recebido ou o código tenha expirado. Fluxo: PF e PJ Etapa: 3 (opcional — só se precisar reenviar) Pré-requisitos: Solicitação iniciada (POST /access/register). Espera de 2 minutos desde o último envio.

Payload:

json
{ "document": "...", "register_id": 1 }

Campos obrigatórios: document, register_id. Campos opcionais: Nenhum.

Resposta: 200 confirmando o reenvio, ou 400 se chamado antes dos 2 minutos de espera.

Dados utilizados nas próximas etapas: Nenhum novo (o código vai por e-mail, não na resposta).


POST /access/register/email/verify ​

Finalidade: Confirmar o código recebido por e-mail e liberar o avanço para a etapa de dados cadastrais. Fluxo: PF e PJ Etapa: 4 — Confirmar e-mail Pré-requisitos: Solicitação iniciada; código de verificação enviado (automático na etapa 2, ou reenviado na etapa 3).

Payload:

json
{ "document": "...", "register_id": 1, "validation_code": "4821" }

Campos obrigatórios: document, register_id, validation_code (código de 4 números, válido por 10 minutos). Campos opcionais: Nenhum.

Resposta: 200 em caso de sucesso — a solicitação avança para a fase de preenchimento de dados. 400 "Código de validação incorreto." ou "O código de validação expirou..." em caso de erro. Depois de 3 erros seguidos, cada erro aumenta a espera até a próxima tentativa: 30 s, 1 min, 2 min, 4 min, 8 min e, a partir daí, 15 min. A espera nunca bloqueia de vez e zera quando o código é confirmado. Com espera imposta, o erro traz data.retry_after (segundos), e uma tentativa durante a espera recebe 429 com o cabeçalho Retry-After.

Dados utilizados nas próximas etapas: Nenhum novo — o e-mail fica marcado como verificado internamente.


PATCH /access/register/personal-data — Dados pessoais (só Pessoa Física) ​

Finalidade: Preencher os dados de KYC de uma solicitação Pessoa Física. Fluxo: PF (recusa com 422 se a solicitação for PJ) Etapa: 5 (PF) — Dados pessoais Pré-requisitos: E-mail confirmado; solicitação precisa ser Pessoa Física (account_type = 1).

Payload:

json
{ "register_id": 1, "document": "...", "mother_name": "...", "birth_date": "YYYY-MM-DD", "invoicing": "...", "social_name": "...", "cbo": "..." }

Campos obrigatórios: register_id, document, mother_name, birth_date, invoicing (faixa de renda mensal, texto livre). Campos opcionais: social_name (nome social), cbo (ocupação).

Resposta: 200 com a solicitação atualizada. Atualização parcial — só os campos enviados são alterados.

Dados utilizados nas próximas etapas: Nenhum novo — só contribui para o status de completude.


PATCH /access/register/company-data — Dados da empresa (só Pessoa Jurídica) ​

Finalidade: Preencher os dados de KYC de uma solicitação Pessoa Jurídica. Fluxo: PJ (recusa com 422 se a solicitação for PF) Etapa: 5 (PJ) — Dados da empresa Pré-requisitos: E-mail confirmado; solicitação precisa ser Pessoa Jurídica (account_type = 2).

Payload:

json
{ "register_id": 1, "document": "...", "legal_nature": "...", "cnae": "...", "founding_date": "YYYY-MM-DD", "invoicing": "...", "profitable": "Y", "trade_name": "..." }

Campos obrigatórios: register_id, document, legal_nature (natureza jurídica — MEI, LTDA, S.A. etc.), cnae (atividade econômica), founding_date, invoicing (faixa de faturamento, texto livre), profitable ("Y"/"N"). Campos opcionais: trade_name (nome fantasia).

Resposta: 200 com a solicitação atualizada. Atualização parcial. A razão social já foi definida na etapa 2, a partir do usuário — não é pedida aqui.

Dados utilizados nas próximas etapas: Nenhum novo — só contribui para o status de completude.


POST /access/register/partners — Adicionar/atualizar sócio (só Pessoa Jurídica) ​

Finalidade: Registrar cada sócio da empresa. Chamado uma vez por sócio. Fluxo: PJ (recusa com 422 se a solicitação for PF) Etapa: 6 (PJ) — Sócios Pré-requisitos: Solicitação precisa ser Pessoa Jurídica. Recomendado preencher depois dos dados da empresa, mas não é obrigatório nessa ordem.

Payload:

json
{ "register_id": 1, "document": "...", "partner_name": "...", "partner_document": "...", "partner_email": "...", "partner_phone": "...", "ownership_percentage": 50, "legal_representative": true }

Campos obrigatórios: register_id, document (da empresa), partner_name, partner_document (CPF do sócio). Campos opcionais: partner_email, partner_phone, ownership_percentage (0–100), legal_representative (booleano — se este sócio é quem assina pela empresa).

Resposta: 200 com o sócio criado/atualizado. Reenviar o mesmo partner_document atualiza o sócio em vez de duplicar.

Dados utilizados nas próximas etapas: Nenhum novo. Pelo menos um sócio é obrigatório para a solicitação ficar completa — ver Status da Solicitação.


DELETE /access/register/partners/{partnerId} — Remover sócio (só Pessoa Jurídica) ​

Finalidade: Remover um sócio cadastrado por engano. Fluxo: PJ Etapa: 6 (PJ) — Sócios (correção) Pré-requisitos: Sócio já criado (partnerId retornado por POST /access/register/partners).

Payload:

json
{ "register_id": 1, "document": "..." }

Campos obrigatórios: register_id, document (da empresa, usado para autenticar a operação). Campos opcionais: Nenhum.

Resposta: 200 confirmando a remoção.

Dados utilizados nas próximas etapas: Nenhum.


PATCH /access/register/address — Endereço ​

Finalidade: Preencher o endereço da solicitação. Fluxo: PF e PJ Etapa: 7 — Endereço Pré-requisitos: Nenhuma ordem obrigatória em relação às demais etapas de dados, mas normalmente vem depois dos dados pessoais/da empresa.

Payload:

json
{ "register_id": 1, "document": "...", "street": "...", "address_number": "...", "neighborhood": "...", "city": "...", "state": "SP", "zip_code": "...", "complement": "..." }

Campos obrigatórios: register_id, document, street, address_number, neighborhood, city, state (2 letras), zip_code. Campos opcionais: complement.

Resposta: 200 com o endereço salvo. Chamar de novo substitui os dados anteriores (idempotente).

Dados utilizados nas próximas etapas: Nenhum novo — só contribui para o status de completude.


PATCH /access/register/phone — Telefone de contato ​

Finalidade: Definir ou atualizar o telefone de contato. Fluxo: PF e PJ Etapa: 8 — Telefone Pré-requisitos: Nenhum.

Payload:

json
{ "register_id": 1, "document": "...", "phone_number": "..." }

Campos obrigatórios: register_id, document, phone_number. Campos opcionais: Nenhum.

Resposta: 200 confirmando a atualização. Trocar o número reseta a validação do telefone (ainda não há endpoint para confirmá-lo).

Dados utilizados nas próximas etapas: Nenhum.


POST /access/register/documents — Enviar documento ​

Finalidade: Enviar um documento (upload de arquivo). Chamado uma vez por tipo de documento. Fluxo: PF e PJ (tipos de documento exigidos diferem — ver as páginas de Pessoa Jurídica e Pessoa Física) Etapa: 9 — Documentos Pré-requisitos: Nenhuma ordem obrigatória em relação às demais etapas.

Payload: multipart/form-data

register_id: 1
document: "..."
type: "identity_front" | "identity_back" | "selfie" | "cnpj_card" | "social_contract" | "proof_of_address" | "cpf" | "complementary_document"
file: (arquivo — jpeg/png/jpg/pdf, máx. 10 MB)

Campos obrigatórios: register_id, document, type, file. Campos opcionais: Nenhum.

Resposta: 200 com a URL pública do arquivo enviado. Um documento por (register_id, type) — reenviar o mesmo tipo substitui o arquivo anterior e limpa um motivo de reprovação anterior desse documento.

Dados utilizados nas próximas etapas: Nenhum — a lista completa de documentos enviados pode ser conferida depois via POST /access/register/resume.

identity_front / identity_back / selfie do titular (PF) e do responsável legal (PJ)

Esses 3 tipos não são mais enviados por aqui para quem responde pelos documentos oficiais do register — eles chegam automaticamente via POST identity-validation/{token}/verify (ver abaixo), junto com a prova de vida. Continuam aceitos por este endpoint (ex.: reenvio manual pelo backoffice), mas o wizard de cadastro não oferece mais esses campos na etapa de Documentos.


POST /access/register/identity-validation — Gerar validação de identidade ​

Finalidade: Gerar (ou retornar a já existente, se ainda não concluída) a sessão/link de validação de identidade (selfie/documento). Ver Validação de Identidade para o conceito completo. Fluxo: PF (titular) e PJ (um por sócio, via partner_document) Etapa: 10 — Validação de Identidade Pré-requisitos: Nenhuma ordem obrigatória em relação às demais etapas. Para PJ, o sócio já precisa ter sido cadastrado (POST /access/register/partners).

Payload:

json
{ "register_id": 1, "document": "...", "partner_document": "..." }

Campos obrigatórios: register_id, document. partner_document obrigatório se Pessoa Jurídica (identifica o sócio), proibido se Pessoa Física. Campos opcionais: Nenhum.

Resposta: A sessão de validação, incluindo token, status (link_generated) e link (URL pública a ser enviada ao usuário/sócio — ver GET identity-validation/{token} e POST identity-validation/{token}/verify abaixo).

Dados utilizados nas próximas etapas: token/link — a pessoa acessa o link e completa a etapa lá, via verify.


GET /access/register/identity-validation/{token} — Consultar por token (pública) ​

Finalidade: Consulta pública usada pela página que o link abre — sem document/register_id, já que quem acessa é o sócio/titular pelo link recebido, não necessariamente autenticado no wizard. Fluxo: PF e PJ Etapa: Consulta auxiliar da etapa 10. Pré-requisitos: Uma sessão já criada via POST /access/register/identity-validation. Payload: Nenhum (token na URL). Resposta: status, expires_at e subject_name (nome do titular ou do sócio) — sem expor document/e-mail/outros dados da solicitação. 404 se o token não existir. Dados utilizados nas próximas etapas: subject_name (personalizar a tela) e status (decidir se ainda precisa enviar as fotos).


POST /access/register/identity-validation/{token}/liveness-session — Abrir sessão de Face Liveness (pública) ​

Finalidade: Abre a sessão de prova de vida (Amazon Rekognition Face Liveness) usada pelo componente FaceLivenessDetector (Amplify UI) no front-end — o vídeo é transmitido direto do navegador pra AWS, nunca passa pelo nosso back-end. Fluxo: PF e PJ Etapa: 10 — Validação de Identidade Pré-requisitos: Uma sessão já criada via POST /access/register/identity-validation. Payload: Nenhum (token na URL). Resposta: { "session_id": "..." }. 422 se a AWS não conseguir abrir a sessão (erro em message). Dados utilizados nas próximas etapas: session_id — usado pelo FaceLivenessDetector e depois enviado de volta em verify.


POST /access/register/identity-validation/{token}/verify — Enviar documento e concluir a validação (pública) ​

Finalidade: Recebe as fotos do documento (frente e verso) e o session_id de uma sessão de Face Liveness já concluída pelo front-end, consulta o resultado na AWS (IDENTITY_VALIDATION_PROVIDER=aws, padrão) e resolve na mesma resposta, sem espera assíncrona. Fluxo: PF e PJ Etapa: 10 — Validação de Identidade (ação final da etapa) Pré-requisitos: Uma sessão de liveness já criada via POST .../liveness-session, concluída pelo FaceLivenessDetector no front-end.

Payload: multipart/form-data

id_document_front: (arquivo de imagem — jpeg/png, máx. 5 MB)
id_document_back: (arquivo de imagem — jpeg/png, máx. 5 MB)
liveness_session_id: "..."

Campos obrigatórios: id_document_front, id_document_back, liveness_session_id. Campos opcionais: Nenhum.

Resposta: status (completed se a prova de vida foi confirmada com confiança suficiente, failed caso contrário) e result ({ "liveness_status": "SUCCEEDED", "confidence": 98.7 } em caso de sucesso, ou { "error": "..." } em caso de falha). Só completed é definitivo — reenviar pra uma validação já completed não reprocessa, mas uma failed pode ser tentada de novo no mesmo token (gerar nova sessão via .../liveness-session e chamar verify de novo).

Quando a validação concluída pertence a quem responde pelos documentos oficiais do register — o titular na PF, ou o sócio marcado como legal_representative na PJ — essas mesmas fotos (já comprovadamente da mesma pessoa que passou pela prova de vida) também substituem os RegisterDocument oficiais identity_front/identity_back, e a ReferenceImage do Rekognition vira o selfie — nenhum desses 3 tipos de documento precisa mais ser enviado separadamente pelo computador na etapa de Documentos. Demais sócios da PJ continuam enviando as próprias fotos aqui, mas só como evidência da sua validação individual (não substituem nenhum RegisterDocument).

Dados utilizados nas próximas etapas: Nenhum — conclui a etapa 10; quando todos os sujeitos obrigatórios (titular na PF, todos os sócios na PJ) estiverem completed, a solicitação pode avançar automaticamente para READY_FOR_ANALYSIS (ver Status da Solicitação).


GET /access/register/identity-validation — Consultar validação de identidade (autenticado) ​

Finalidade: Consultar o status da(s) validação(ões) de identidade — usado pelo wizard de cadastro (com register_id+document), diferente do GET .../{token} público acima. Fluxo: PF (titular) e PJ (um por sócio, via partner_document) Etapa: Consulta auxiliar da etapa 10. Pré-requisitos: Nenhum. Payload: Nenhum (query string). Campos obrigatórios: register_id, document (query string). Campos opcionais: partner_document (query string) — sem ele, retorna a lista de todas as validações da solicitação (útil para PJ com vários sócios); com ele, retorna só a validação daquele sócio. Resposta: Uma validação (partner_document informado) ou uma lista (sem partner_document), cada uma com status (pending | link_generated | in_progress | completed | failed | expired). Dados utilizados nas próximas etapas: Nenhum.


POST /access/register/identity-validation/callback — Callback assíncrono (não usado pelo fluxo atual) ​

Finalidade: Recebe o resultado da validação de um provedor assíncrono baseado em webhook — chamado pelo provedor, não pelo cliente. Idempotente. O fluxo atual (Rekognition, via verify acima) é síncrono e não usa este endpoint; ele fica disponível para um provedor futuro que funcione nesse modelo. Fluxo: PF e PJ Etapa: Não usado pelo fluxo atual — não exige document/register_id (identifica a sessão pelo token). Pré-requisitos: Uma sessão já criada via POST /access/register/identity-validation. Autenticação: cabeçalho X-Callback-Secret igual a IDENTITY_VALIDATION_CALLBACK_SECRET. Sem o segredo, ou com a variável vazia (padrão), responde 403.

Payload:

json
{ "token": "...", "status": "completed", "result": {} }

Campos obrigatórios: token, status (completed ou failed). Campos opcionais: result (objeto livre, guardado como recebido).

Resposta: 200 com a validação atualizada.

Dados utilizados nas próximas etapas: Nenhum.


Endpoints auxiliares (consulta, a qualquer momento) ​

GET /access/register/status?document=... ​

Finalidade: Checar rapidamente se já existe uma solicitação para um documento, sem expor dados sensíveis. Fluxo: PF e PJ Etapa: Consulta auxiliar — pode ser chamado a qualquer momento, antes ou durante o fluxo. Pré-requisitos: Nenhum. Payload: Nenhum (query string document). Campos obrigatórios: document (query string). Campos opcionais: Nenhum. Resposta: document, id, email, name, account_type, account_status — sem dados de KYC. Dados utilizados nas próximas etapas: id (register_id), se o cliente precisar retomar sem senha.

POST /access/register/resume — Retomar por senha ​

Finalidade: Recuperar a solicitação completa (todos os dados já preenchidos) quando o cliente perdeu o register_id local. Fluxo: PF e PJ Etapa: Consulta auxiliar — usada para retomar um cadastro parado no meio. Pré-requisitos: Usuário já criado. Payload:

json
{ "document": "...", "password": "..." }

Campos obrigatórios: document, password. Campos opcionais: Nenhum. Resposta: Todos os dados da solicitação, incluindo address, documents (lista), partners (lista, PJ — cada um já com identity_validation_status), identity_validation (status da validação do titular, só PF), current_step (etapa em aberto — ver enum RegisterStep), completed_steps e pending_steps (listas, na ordem da esteira). 422 documento/senha inválidos; 404 sem solicitação em andamento. Dados utilizados nas próximas etapas: id (register_id), current_step/pending_steps e todos os campos já preenchidos, para decidir em qual etapa retomar o formulário.