Resolução de problemas de erros da API da Pleo

O pedido é inválido ou não passa na validação.

• Lê o corpo da resposta para identificar campos em falta ou valores inválidos.
• Compara o teu pedido com a documentação do endpoint. Verifica os campos obrigatórios, a estrutura do pedido, os formatos de data e os valores permitidos.
• Corrige o problema identificado e repete o pedido.

Não foi possível autenticar o pedido.

• Faz corresponder a credencial à API e ao ambiente. Compara o anfitrião do pedido com a documentação para programadores. Não mistures credenciais da nova API e da API antiga, nem credenciais de teste e de produção.
• Verifica o cabeçalho de autorização ("Authorization"). As novas chaves da API usam autenticação Basic, com a chave como nome de utilizador e uma palavra-passe vazia. Os tokens de acesso OAuth usam autenticação Bearer. Para tokens antigos, segue a documentação da API antiga. Remove espaços ou quebras de linha acidentais das credenciais.
• Verifica o estado da credencial. Confirma que não expirou nem foi revogada. Para OAuth, usa o token de acesso — não o token de atualização — e verifica se o fluxo de atualização do token está a funcionar.

O pedido foi autenticado, mas o acesso não é permitido.

• Verifica os âmbitos. Compara os âmbitos atribuídos à tua credencial com os exigidos pelo endpoint. Se não conseguires vê-los, pede à pessoa que gere a credencial para os confirmar.
• Verifica a empresa e o ambiente. A credencial tem de corresponder à empresa ou entidade cujos dados estás a pedir e ao ambiente que estás a chamar.
• Verifica a disponibilidade do endpoint. Confirma na documentação para programadores que o endpoint é compatível com o teu método de autenticação e caso de utilização.

Se corresponderem, mas o acesso continuar a ser recusado, contacta o Suporte para confirmar o acesso à API da empresa. Indica se a mesma credencial funciona noutros endpoints.

Não foi possível encontrar o endpoint ou recurso solicitado.

• Compara o URL base, a versão da API e o caminho do endpoint com a documentação para programadores.
• Confirma que o ID do recurso identifica o recurso que pretendias solicitar.
• Verifica se o recurso pertence à empresa e ao ambiente associados à credencial. Não mistures IDs de teste e de produção.

Um recurso pode devolver 404 mesmo que exista na Pleo, se pertencer a outra empresa ou ambiente.

O pedido entra em conflito com uma operação ou estado existente.

• Lê a resposta de erro e verifica se a mesma operação já foi enviada. Revê a resposta anterior ou a operação resultante antes de a enviares novamente.
• Segue as orientações sobre conflitos e idempotência do endpoint na documentação para programadores.

A tua integração está a enviar pedidos com demasiada frequência.

• Verifica os cabeçalhos da resposta para obter orientações sobre repetição ou limites de taxa.
• Reduz a frequência dos pedidos e evita repetições imediatas num ciclo apertado.
• Usa espera exponencial, seguindo as orientações de repetição do endpoint.

Se isto continuar com um volume baixo de pedidos, inclui a frequência dos pedidos e o comportamento de repetição ao contactar o Suporte.

Ocorreu um erro do lado do servidor. Recolhe a resposta de erro e os detalhes do pedido indicados em “Ainda precisas de ajuda?” e contacta o Suporte. Indica se aconteceu uma vez ou se ocorre repetidamente.

Se os eventos de webhook não estiverem a chegar à tua integração ou não forem processados por ela:

• Verifica a acessibilidade. O teu endpoint de receção tem de estar acessível publicamente através de HTTPS e não pode bloquear pedidos da Pleo.
• Verifica os registos de entrega. Procura a tentativa de entrega, o estado da resposta e o tempo de resposta. Devolve prontamente uma resposta 2xx, cumprindo os requisitos da documentação do webhook.
• Verifica a validação da assinatura. Utiliza o corpo do pedido no formato exigido pela documentação do webhook, incluindo o corpo bruto quando indicado.
• Processa as entregas duplicadas em segurança. Elimina duplicados usando o identificador do evento ou webhook especificado na documentação.

Depois de fazeres uma alteração, verifica uma entrega posterior. Se continuar a falhar, inclui o ID da subscrição, o ID do evento ou webhook, o carimbo de data e hora da entrega, o estado da resposta do endpoint e os registos anonimizados ao contactar o Suporte.