Skip to main content

Como construir integrações 100% via API com a Woovi

Muitos fluxos da Woovi têm duas formas de uso: uma tela hospedada (link de onboarding, checkout, página de resposta de RFI) e a API pura, em que o seu sistema conduz cada passo e o seu cliente nunca sai do seu produto. Esta página junta os padrões que valem para qualquer integração do segundo tipo. Um exemplo completo é o Onboarding KYC 100% via API.

1. Autenticação: uma Aplicação, um AppID, escopos mínimos​

  • Crie uma Aplicação em API/Plugins e use o AppID no header Authorization, sem o prefixo Bearer (Começando a Integração).
  • Dê ao AppID só os escopos que a integração usa (Adicionando escopos ao seu AppID). Cada endpoint documenta o escopo que exige; sem ele a resposta é 403.
  • Use um AppID por ambiente e por integração. Em BaaS, os eventos de onboarding pertencem à API Master.
  • Restrinja por IP quando puder (IP Whitelist).
curl https://api.woovi.com/api/v1/kyc/representatives?correlationID=merchant-4417 \
  -H "Authorization: <APP_ID>"

2. Arquivos: primeiro o upload, depois o fileId​

Nenhuma API de domínio recebe o arquivo em si. O padrão tem duas chamadas:

  1. POST /api/v1/files (multipart/form-data) com o file e o purpose do uso — escopo FILE_POST (Como fazer upload de um arquivo?). Guarde o file.id.
  2. O endpoint de domínio recebe esse id como fileId.
curl -X POST https://api.woovi.com/api/v1/files \
  -H "Authorization: <APP_ID>" \
  -F "[email protected]" \
  -F "purpose=ACCOUNT_REGISTER_DOCUMENT" \
  -F "correlationID=merchant-4417-selfie-maria"
  • O fileId só é válido para a mesma empresa que fez o upload e para o mesmo purpose. Um arquivo subido como DISPUTE_EVIDENCE não serve num KYC.
  • Os endpoints resolvem todos os fileId antes de gravar: se um falhar, nada é gravado. Corrija e reenvie a requisição inteira.
  • A url devolvida é temporária. Não a guarde como link permanente; peça o arquivo de novo quando precisar.

3. correlationID: o seu identificador em tudo​

Envie sempre um correlationID gerado pelo seu sistema (Correlation ID). Ele é:

  • A chave para endereçar o recurso depois. No KYC, todo endpoint recebe o correlationID que você enviou ao criar o onboarding — não é preciso guardar ids internos da Woovi.
  • A chave de idempotência da criação. Repetir a mesma criação com o mesmo correlationID devolve o recurso existente (normalmente 200 em vez de 201), sem duplicar.

Guarde o correlationID antes de chamar a API, para conseguir reenviar a mesma requisição depois de um timeout.

4. Idempotência e retentativas​

Assuma que toda chamada pode dar timeout sem que você saiba se ela foi processada. Por isso (Idempotência):

  • Reenvie com o mesmo correlationID e o mesmo body — nunca gere um id novo para "tentar de novo".
  • Prefira operações que a própria API já torna idempotentes. Exemplos no KYC: o submit de um cadastro que já está em análise responde 200 sem refazer nada; criar uma autenticação Pix com uma cerimônia aberta devolve o mesmo QR Code.
  • Use backoff exponencial em 429, 502 e erros de rede. Quando a resposta traz uma data de retentativa (como nextResendAt), respeite-a.

5. Webhooks em vez de polling​

Processos longos (análise de KYC, pagamentos, disputas) mudam de estado sem que você chame nada. Cadastre webhooks para esses eventos em vez de consultar em loop (criando um webhook via API, tipos de evento; para o KYC, eventos do ciclo de vida do onboarding).

  • Valide a assinatura em toda entrega (x-webhook-signature) antes de processar.
  • Responda 200 rápido e processe de forma assíncrona.
  • A entrega é "pelo menos uma vez" e sem ordem garantida: deduplique e ordene pelos campos do payload, não pela ordem de chegada.
  • Use a API como fonte da verdade para reconciliar de tempos em tempos. Polling curto só onde a própria documentação recomenda, como o resultado de um Pix de autenticação enquanto o QR Code está na tela.

6. Tratamento de erros​

As respostas de erro seguem o formato:

{
  "error": "This account register can no longer receive documents in its current status.",
  "code": "ACCOUNT_REGISTER_NOT_OPEN"
}
  • error é uma mensagem para humanos, já traduzida. Pode mudar: não compare strings.
  • code, quando presente, é estável: é nele que o seu código deve decidir.
  • Erros de validação (400) podem trazer em error a lista de campos inválidos.
HTTPSignificadoO que fazer
400Requisição inválidaCorrija o body; não repita igual
401AppID ausente ou inválidoVerifique o header Authorization
403Falta feature na empresa ou escopo no AppIDHabilite a feature / adicione o escopo
404Recurso não existe para a sua empresaConfira o correlationID
409Conflito com o estado atual do recursoLeia o code, resolva a pendência e tente de novo
422Conteúdo recusado (ex.: documento ilegível)Envie outro arquivo
429Limite de requisiçõesEspere e tente de novo
5xxFalha temporáriaRetente com backoff, com o mesmo correlationID

Integração via API não precisa ser tudo ou nada. Os fluxos que têm tela hospedada gravam no mesmo recurso que a API, então você pode fazer pela API o que já tem no seu produto e mandar o link ao cliente só para o resto. No KYC, por exemplo, a RFI devolve um link para os itens que só se respondem pela tela.

Próximos passos​