# FAQ

## Perguntas frequentes sobre a API PIX.

### Preciso integrar com cada banco separadamente?
Não. Você integra apenas com a API Dados Jah. Nós nos comunicamos com o banco/PSP escolhido.

### Posso usar a API sem certificado digital?
Depende do PSP. PSPs como Shipay, Mercado Pago, QQPag e PixPDV não exigem certificado. Outros, como Bradesco, exigem.

### Quanto tempo demora para uma cobrança ser processada?
Cobranças com um único item são processadas de forma síncrona e retornam o QR Code imediatamente. Lotes com vários itens são processados de forma assíncrona e retornam um idBatch para acompanhamento.

### O que acontece se o cliente não pagar?
A cobrança permanece com status ATIVA até o prazo de expiração. Após isso, o PSP pode removê-la automaticamente.

### Posso cancelar uma cobrança?
Sim, desde que ainda não tenha sido paga. Use os endpoints de cancelamento de COB ou COBV.

### Posso fazer devolução parcial?
Sim. Informe o valor exato que deseja devolver no campo correspondente.

### Posso usar a API em homologação para sempre?
Não. O ambiente de homologação é apenas para testes. Quando estiver pronto, migre para produção.

### Como sei se estou em homologação ou produção?
Na API Dados Jah, o ambiente é definido pelo campo tpAmb de cada conta bancária cadastrada. Consulte o valor do tpAmb na resposta do GET /user/account:
tpAmb	Ambiente
0	Homologação (sandbox)
1	Produção
2	Pré-Produção
Na prática: se sua conta tem tpAmb: 0, você está em homologação (testes, sem dinheiro real). Se tem tpAmb: 1, está em produção (transações reais). As credenciais e certificados devem ser compatíveis com o ambiente da conta.

### Onde encontro as credenciais do PSP?
No portal do desenvolvedor do banco escolhido. Cada banco tem o seu processo de cadastro e aprovação, consulte o gerente ou o suporte do seu banco.

### Posso cadastrar várias contas bancárias para o mesmo usuário?
Sim. Use POST /user/account quantas vezes forem necessárias, desde que cada conta tenha uma chave Pix e credenciais válidas.

> Dica: Nunca compartilhe clientSecret, tokens JWT ou certificados.
> Armazene segredos em variáveis de ambiente, nunca no código-fonte.
> Use sempre HTTPS em produção.
> Renove certificados antes do vencimento.
> Monitore logs e transações regularmente.

## Resolvendo problemas comuns

### Erro 401 — Unauthorized

**Causas mais comuns:**

- Token não foi enviado no header Authorization.
- Token expirado.
- Token de sistema usado em rota de usuário, ou vice-versa.

**Como resolver:**

- Faça login novamente e copie o novo accessToken.
- Verifique se o header está no formato correto: Authorization: Bearer eyJhbG....
- Confirma se está usando o token correto para a rota.

### Erro 400 — Bad Request

**Causas mais comuns:**

- Campo obrigatório faltando.
- Valor enviado como número em vez de string.
- CPF/CNPJ inválido.
- Data no formato errado.

**Como resolver:**

- Leia a mensagem de erro retornada no campo message.
- Compare o seu payload com os exemplos da documentação.
- Valide CPF/CNPJ antes de enviar.

### Erro 403 — Forbidden

**Causas mais comuns:**

- O token não tem o scope necessário para a operação.
- A conta Pix usada não tem permissão para aquela ação.

**Como resolver:**

- Verifique os scopes cadastrados em POST /user/account.
- Inclua todos os scopes necessários para o fluxo.

### Erro 409 — Conflict

**Causas mais comuns:**

- txid já foi usado em outra cobrança.
- Usuário ou e-mail já cadastrado.

**Como resolver:**

- Gere um novo txid único.
- Para usuários, verifique se o e-mail/CPF já existe.

### Erro 422 — Unprocessable Entity

**Causas mais comuns:**

- O PSP rejeitou os dados.
- Certificado incorreto ou expirado.
- ClientId/clientSecret inválidos.

**Como resolver:**

- Teste as credenciais diretamente no portal do desenvolvedor do PSP.
- Verifique se o certificado ainda é válido.
- Confirme se está usando o ambiente correto (homologação vs produção).

### Erro 500 — Internal Server Error

**Causas mais comuns:**

- Falha interna na API ou no PSP.
- Timeout na comunicação com o banco.

**Como resolver:**

- Aguarde alguns segundos e tente novamente.
- Verifique o campo situation: se for Error, leia a mensagem detalhada.
- Se persistir, entre em contato com o suporte.