Introdução
A API SudoPay permite validar e extrair informações de comprovativos de transferência bancária em formato PDF, gerados por aplicativos como Multicaixa Express e BAI Directo. Com um simples pedido POST, pode automatizar a confirmação de pagamentos no seu sistema, aumentando a eficiência e a segurança.
Autenticação
A autenticação é realizada através de uma chave de API. Deverá incluir a sua chave em cada pedido. A chave pode ser obtida no seu painel de controlo SudoPay.
Nota: A sua chave de API é secreta! Não a exponha no lado do cliente (frontend). Todas as chamadas à API devem ser feitas a partir do seu servidor (backend).
Endpoint de Validação
Para validar um comprovativo, envie um pedido para o seguinte endpoint:
POST
|
https://comprovativos.sudomakes.com/validar/
Estrutura do Pedido (Request)
O pedido deve ser do tipo
multipart/form-data
e conter os seguintes campos:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| sudopay_key | string | Sim | A sua chave de API secreta. |
| recibo | file | Sim | O ficheiro do comprovativo em formato PDF. |
Estrutura da Resposta (Response)
Resposta de Sucesso (Código 200)
Se o comprovativo for válido, a API retornará um objeto JSON com os dados extraídos.
{
"APLICATIVO": "MULTICAIXA EXPRESS",
"STATUS": 200,
"LOG": "MULTICAIXA EXPRESS",
"B_IBAN": "AO06.0044.0000.4152.8821.1018.5",
"B_NOME": "JOSE ARTUR KASSALA",
"O_IBAN": "AO06.0051.0000.8382.9381.1014.7",
"O_NOME": "NOME DO ORDENANTE",
"B_BANCO": "BFA",
"O_BANCO": "BAI",
"MONTANTE": "52.000,00",
"DINHEIRO": 52000,
"TRANSACAO": "8000246",
"TIPO": "Transferência Bancária",
"DATA": {
"data": "2025-08-02",
"tempo": "08:30:12",
"dataHora": "2025-08-02 08:30:12",
"dia": 2,
"mes": 8,
"ano": 2025,
"hora": 8,
"minuto": 30,
"segundo": 12
}
}
Respostas de Erro
Em caso de erro, a API retornará um JSON com o status e uma mensagem descritiva.
| Código HTTP | Mensagem de Erro |
|---|---|
| 400 Bad Request | "Nenhum ficheiro pdf foi encontrado..." |
| 403 Forbidden | "os motivos podem variar entre: A chave de autenticação não existe ou o site não foi registado." |
| 406 Not Acceptable | "O documento é inválido." |
| 415 Unsupported Media Type | "Ficheiro nao suportado." (Apenas PDF é aceite) |
| 423 Locked | "O documento não representa uma transferencia Bancaria." |
Descrição dos Atributos
| Atributo | Descrição |
|---|---|
| APLICATIVO | Mostra o nome do aplicativo usado como BAI DIRECT ou MULTICAIXA EXPRESS. |
| STATUS | Mostra o código de sucesso (200) ou de erro. |
| LOG | Mostra o motivo de algum erro, ou o nome do aplicativo usado caso não ocorra nenhum erro. |
| B_NOME | Mostra o nome da entidade que recebeu a transferência (Nome do Beneficiário). |
| O_NOME | Mostra o nome da entidade que enviou a transferência (Nome do Ordenante). |
| B_IBAN | Mostra o nº do IBAN da entidade que recebeu a transferência (Nº do IBAN do Beneficiário). |
| O_IBAN | Mostra o nº do IBAN da entidade que enviou a transferência (Nº do IBAN do Ordenante). |
| O_CONTA | Mostra o nº da conta da entidade que envia a transferência (Nº da conta do ordenante). |
| B_BANCO | Mostra o nome do banco da entidade que recebeu a transferência (Banco do Beneficiário). |
| B_SWIFT | Mostra o código SWIFT da entidade que recebeu a transferência. |
| O_BANCO | Mostra o nome do banco da entidade que enviou a transferência (Banco do Ordenante). |
| TRANSACAO | Obtém o número de transação, que é um número único que identifica uma transação bancária. |
| MONTANTE | Obtém o valor da transação (string formatada). |
| DINHEIRO | Obtém o valor da transação (número inteiro ou float, sem formatação). |
| TIPO | Obtém o tipo de operação que representa o comprovativo. |
| DATA | Obtém um objeto com a data e hora em que a transferência foi efetuada, com vários formatos. |
Exemplos de Código
PHP (cURL)
<?php
$apiKey = 'SUA_CHAVE_DE_API_AQUI';
$filePath = '/caminho/para/seu/comprovativo.pdf';
$url = 'https://comprovativos.sudomakes.com/validar/';
if (!file_exists($filePath)) {
die('Erro: Ficheiro não encontrado em ' . $filePath);
}
// Cria um objeto CURLFile
$cFile = new CURLFile($filePath, 'application/pdf', basename($filePath));
// Dados para o POST
$postData = [
'sudopay_key' => $apiKey,
'recibo' => $cFile,
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// Descomente as duas linhas abaixo se tiver problemas com SSL
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
echo 'Erro cURL: ' . curl_error($ch);
} else {
echo "Código de Status HTTP: " . $httpCode . "\n";
echo "Resposta:\n";
print_r(json_decode($response, true));
}
curl_close($ch);
?>
JavaScript (Fetch API - Node.js)
Nota: Este exemplo usa
node-fetch e
form-data.
Instale-os com
npm install node-fetch form-data.
import fetch from 'node-fetch';
import FormData from 'form-data';
import fs from 'fs';
const apiKey = 'SUA_CHAVE_DE_API_AQUI';
const filePath = '/caminho/para/seu/comprovativo.pdf';
const url = 'https://comprovativos.sudomakes.com/validar/';
async function validarComprovativo() {
try {
const form = new FormData();
form.append('sudopay_key', apiKey);
form.append('recibo', fs.createReadStream(filePath));
const response = await fetch(url, {
method: 'POST',
body: form,
});
const data = await response.json();
console.log('Status:', response.status);
console.log('Dados:', data);
} catch (error) {
console.error('Ocorreu um erro:', error);
}
}
validarComprovativo();
Python (Requests)
Nota: Necessita da biblioteca
requests. Instale
com
pip install requests.
import requests
import os
api_key = 'SUA_CHAVE_DE_API_AQUI'
file_path = '/caminho/para/seu/comprovativo.pdf'
url = 'https://comprovativos.sudomakes.com/validar/'
if not os.path.exists(file_path):
print(f"Erro: Ficheiro não encontrado em {file_path}")
else:
# Prepara os dados e o ficheiro para o upload
payload = {'sudopay_key': api_key}
files = {
'recibo': (os.path.basename(file_path), open(file_path, 'rb'), 'application/pdf')
}
try:
response = requests.post(url, data=payload, files=files)
print(f"Código de Status HTTP: {response.status_code}")
# Tenta descodificar a resposta como JSON
try:
print("Resposta:")
print(response.json())
except requests.exceptions.JSONDecodeError:
print("Resposta não é um JSON válido:")
print(response.text)
except requests.exceptions.RequestException as e:
print(f"Ocorreu um erro na requisição: {e}")