Guia do BaaS Asaas

Confira o guia BaaS Asaas para mais informações.

Este endpoint permite consultar os documentos pendentes de envio para aprovação cadastral da conta Asaas e recuperar o onboardingUrl correspondente, quando o envio do documento precisar ser realizado por meio de um link externo.

Esse recurso é utilizado principalmente em fluxos de criação de subcontas, especialmente em operações BaaS, em que a plataforma integradora precisa orientar o usuário final sobre quais documentos ainda precisam ser enviados para concluir a análise da conta.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• verificar quais documentos ainda estão pendentes para aprovação da conta;
• recuperar o onboardingUrl para envio de documentos;
• identificar se o documento deve ser enviado via link externo ou por API;
• orientar o usuário final durante o onboarding;
• acompanhar a etapa documental após a criação de uma subconta;
• evitar que a plataforma solicite documentos incorretos ou desnecessários;
• validar se ainda existem pendências antes de consultar a situação cadastral da conta.

Esse endpoint deve fazer parte do fluxo de onboarding e aprovação cadastral da conta.

Fluxo recomendado

Em uma integração típica, a verificação de documentos pendentes deve seguir o fluxo abaixo:

Criar subconta
↓
Aguardar no mínimo 15 segundos
↓
Consultar documentos pendentes
↓
Verificar se o documento possui onboardingUrl
↓
Direcionar o usuário ao link ou seguir com envio via API
↓
Acompanhar a análise dos documentos
↓
Consultar a situação cadastral da conta

Pré-requisitos

Antes de utilizar este endpoint, verifique se:

• a subconta já foi criada;
• a integração está autenticada com a chave de API correta;
• a chamada está sendo feita no contexto da conta que precisa verificar os documentos;
• o tempo mínimo de 15 segundos após a criação da subconta foi respeitado;
• sua aplicação está preparada para tratar documentos com e sem onboardingUrl.

Parâmetros da requisição

Este endpoint não utiliza parâmetros no path, query ou body.

A requisição deve ser enviada sem corpo.

Exemplo de chamada

curl --request GET \
  --url https://api-sandbox.asaas.com/v3/myAccount/documents \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY'

Exemplo de resposta

A resposta retorna os documentos ou grupos de documentos relacionados à análise cadastral da conta.

{
  "data": [
    {
      "id": "172ed152-4fa4-43ad-9b69-39c323e9526c",
      "status": "PENDING",
      "type": "IDENTIFICATION",
      "title": "Documento de identificação",
      "description": "Envie um documento de identificação válido.",
      "onboardingUrl": "https://www.asaas.com/onboarding/documents/...",
      "documents": []
    },
    {
      "id": "da90162b-61ea-48a1-bf73-4638e079043a",
      "status": "PENDING",
      "type": "IDENTIFICATION_SELFIE",
      "title": "Selfie de identificação",
      "description": "Envie uma selfie para validação de identidade.",
      "onboardingUrl": "https://www.asaas.com/onboarding/selfie/...",
      "documents": []
    }
  ]
}

Principais campos da resposta

Como interpretar o onboardingUrl

O campo onboardingUrl indica que o envio daquele documento deve ser realizado por meio de um link externo.

Estados e interpretação dos documentos

A situação de cada documento deve ser interpretada conforme o status retornado pela API.

De forma geral:

Enquanto existirem documentos pendentes ou rejeitados, a conta pode permanecer com aprovação cadastral incompleta.

Comportamentos relevantes

Ao utilizar este endpoint, considere os seguintes comportamentos:

• a lista de documentos pode variar conforme o tipo de conta e os dados cadastrais;
• documentos podem ser solicitados em momentos diferentes da análise;
• uma consulta feita logo após a criação da subconta pode retornar dados incompletos;
• o onboardingUrl deve ser utilizado quando estiver presente na resposta;
• documentos rejeitados podem exigir nova ação do usuário;
• a aprovação dos documentos pode não significar aprovação imediata da conta;
• a situação geral da conta deve ser acompanhada por meio dos recursos de consulta cadastral ou webhooks relacionados.

Estratégia de retentativas

Após criar uma subconta, evite chamar este endpoint repetidamente em sequência.

Recomenda-se:

1. Aguardar no mínimo 15 segundos após a criação da subconta.
2. Realizar a primeira consulta.
3. Exibir ao usuário apenas os documentos retornados após esse período.
4. Aguardar uma ação do usuário ou um intervalo controlado antes de consultar novamente.
5. Acompanhar mudanças relevantes por webhooks, quando disponíveis.

Evite polling agressivo, pois ele pode gerar chamadas desnecessárias e exibir informações inconsistentes ao usuário.

Impacto na experiência do usuário

Este endpoint costuma ser utilizado em fluxos de onboarding. Por isso, a forma como sua integração trata os documentos pendentes impacta diretamente a conclusão do cadastro.

Uma boa implementação deve:

• informar claramente quais documentos estão pendentes;
• direcionar corretamente para o onboardingUrl, quando existir;
• evitar solicitar documentos antes da validação inicial da conta;
• atualizar a tela após envio ou rejeição de documentos;
• orientar o usuário quando houver necessidade de novo envio;
• evitar mensagens genéricas que não indiquem a ação necessária.

Erros comuns

Boas práticas

Ao implementar a verificação de documentos pendentes, recomenda-se:

• respeitar o tempo mínimo de 15 segundos após a criação da subconta;
• enviar requisições GET sem body;
• utilizar a chave de API da conta correta;
• consultar os documentos antes de montar a tela de envio;
• verificar a existência de onboardingUrl antes de definir o método de envio;
• exibir mensagens claras para o usuário final;
• registrar logs das consultas e respostas;
• evitar chamadas repetidas em curto intervalo;
• acompanhar a situação cadastral da conta após o envio dos documentos;
• utilizar webhooks quando possível para reduzir consultas manuais.

Impactos operacionais

Uma implementação incorreta deste fluxo pode causar:

• solicitação de documentos desnecessários;
• envio de documentos pelo método errado;
• atraso na aprovação da conta;
• aumento de contatos com suporte;
• inconsistência entre a situação exibida na sua plataforma e a situação real da conta;
• bloqueio ou limitação de funcionalidades da subconta;
• piora na experiência de onboarding do usuário final.

Por isso, este endpoint deve ser tratado como uma etapa importante do processo de aprovação cadastral.

Conteúdos relacionados

Consulte também:

• Guia do BaaS Asaas;
• Criação de subcontas;
• Criação de subcontas com o BaaS do Asaas;
• Enviar documento;
• Visualizar documento enviado;
• Atualizar documento enviado;
• Remover documento enviado;
• Consultar situação cadastral da conta;
• Webhooks de situação da conta.