Documentação da API SudoPay

Verificação de Comprovativos Bancários (Multicaixa Express & BAI Directo)

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}")