Solicitar cuentas anuales de una empresa

1. Introducción

En este mini-tutorial vamos a aprender cómo solicitar el documento de Cuentas Anuales de una empresa mediante LibreBOR API.

Al finalizar habremos solicitado y descargado el documento más importante para poder evaluar la situación financiera y el rendimiento de una empresa, ya que incluye su balance, cuenta de resultados, estado de cambios en el patrimonio neto y memoria explicativa.

En España, las empresas debe presentar las cuentas anuales al final de cada ejercicio económico ya que es obligatorio por ley. La no presentación puede acarrear posibles sanciones o penalizaciones.

La implementación está hecha en el lenguaje de programación Python pero no debería ser complicado de traducir a otros lenguajes. Para más información, consulta el manual de referencia correspondiente.

2. Obtención de credenciales

Lo primero que tenemos que hacer es obtener las credenciales de acceso. Estas se encuentran en tu Panel de Usuario en la sección API > Credenciales.

Anota tu nombre de usuario y contraseña una vez los tengas localizados.

3. Recarga de saldo

Consulta tu saldo disponible desde la sección Documentos y haz una recarga antes de efectuar tu primera solicitud.

Comprueba que tu saldo ha sido actualizado y es positivo antes de pasar a la siguiente sección.

4. Construcción de la URL

A continuación necesitaremos construir la URL correcta para comunicarnos con la API. De la Referencia de API obtenemos los siguientes datos:

• URL base: https://api.librebor.me/v2 (importante: la API solo funciona con https)
• Método HTTP: POST
• Ruta: /documents/order/
• Parámetros: nif, type, year

5. Implementación

En este ejemplo vamos a solicitar las Cuentas Anuales de AENA S.M.E. SA del año 2022.

Por lo tanto la URL es:

https://api.librebor.me/v2/documents/order/

y los parámetros POST necesarios son los siguientes:

• nif: A86212420
• type: accounts
• year: 2022

Ahora vamos a implementar esta petición HTTP a la API en Python usando la librería python-requests:

#!/usr/bin/env python3
import requests

# Credentials
AUTHENTICATION = requests.auth.HTTPBasicAuth("USERNAME", "PASSWORD")
URL_BASE = "https://api.librebor.me/v2"


def order_annual_accounts(nif, document_type, year):
    """Order Annual Accounts document using LibreBOR API."""
    params = {"nif": nif, "type": document_type, "year": year}
    url = f"{URL_BASE}/documents/order/"
    req = requests.post(url, params=params, auth=AUTHENTICATION)
    return req.json()


if __name__ == "__main__":
    doc = order_annual_accounts("A86212420", "accounts", 2022)
    print(doc)

6. Código final

Por último proporcionamos un script Python más completo que solicita este documento y lo descarga cuando está disponible.

#!/usr/bin/env python3
import os
import time

import requests

# Document request (adjust accordingly)
NIF = "A86212420"
DOCUMENT_TYPE = "accounts"
YEAR = 2022

# Credentials (adjust accordingly)
AUTHENTICATION = requests.auth.HTTPBasicAuth("USERNAME", "PASSWORD")

# API base url
URL_BASE = "https://api.librebor.me/v2"


def order_annual_accounts(nif, document_type, year):
    """Order Annual Accounts document using LibreBOR API."""
    params = {"nif": nif, "type": document_type, "year": year}
    url = f"{URL_BASE}/documents/order/"
    req = requests.post(url, params=params, auth=AUTHENTICATION)
    req.raise_for_status()
    return req.json()


def document_details(document_id):
    """Retrieve document details."""
    url = f"{URL_BASE}/documents/{document_id}/"
    req = requests.get(url, auth=AUTHENTICATION)
    req.raise_for_status()
    return req.json()


def document_download(document_id: str, format_: str):
    """Retrieve document details."""
    url = f"{URL_BASE}/documents/{document_id}/download/"
    req = requests.get(url, {"format": format_}, auth=AUTHENTICATION)
    filename = os.path.join(os.getcwd(), f"{document_id}.{format_}")
    with open(filename, "wb") as fp:
        fp.write(req.content)
    return filename


def wait_for_document(document_id, interval_seconds=60):
    while True:
        print(f"Checking if document {document_id} is ready... ", end="")
        doc = document_details(document_id)
        if doc["document"]["status"] != "processing":
            print("YES!")
            break
        print(f"Not yet. Will retry in {interval_seconds} seconds.")
        time.sleep(interval_seconds)
    return doc["document"]


if __name__ == "__main__":
    doc_request = order_annual_accounts(NIF, DOCUMENT_TYPE, YEAR)
    document_id = doc_request["document_id"]

    doc = wait_for_document(document_id)
    print("Document status:", doc["status"])

    filename = document_download(document_id, "pdf")
    print(f"Written file: {filename}")
    filename = document_download(document_id, "xbrl")
    print(f"Written file: {filename}")

7. Métodos alternativos

Usando curl:

#!/bin/sh
NIF=A86212420
YEAR=2022
CREDENTIALS=username:password

curl -u $CREDENTIALS -d nif=$NIF -d type=accounts -d year=$YEAR -d send_email=true https://api.librebor.me/v2/order/

Usando httpie:

#!/bin/sh
NIF=A86212420
YEAR=2022
CREDENTIALS=username:password

http -f -a $CREDENTIALS POST https://api.librebor.me/v2/documents/order/ nif=$NIF type=accounts year=$YEAR send_email=true

Script completo:

#!/bin/sh
NIF=A86212420
DOC_TYPE=accounts
YEAR=2022

CREDENTIALS=username:password
URL_BASE=https://api.librebor.me/v2


order_annual_accounts() {
    nif=$1
    document_type=$2
    year=$3

    response=$(curl -X POST -s -u $CREDENTIALS "$URL_BASE/documents/order/" -d nif=$nif -d type=$document_type -d year=$year)
    document_id=$(echo $response | jq -r .document_id)
    echo $document_id
}


document_details() {
    document_id=$1

    response=$(curl -s -u $CREDENTIALS "$URL_BASE/documents/$document_id/")
    echo $response
}


document_download() {
    document_id=$1
    format=$2
    output="${document_id}.${format}"

    curl -s -L -u $CREDENTIALS "$URL_BASE/documents/$document_id/download/?format=$format" --output ${output}
    echo "Downloaded $output"
}


wait_for_document() {
    while true
    do
        echo -n "Checking if document ${doc_id} is ready... "
        response=$(document_details ${doc_id})
        status=$(echo $response | jq -r .document.status)
        if [ "$status" != "processing" ]; then
            echo "YES!"
            break
        fi
        echo "Not yet. Will retry in 60 seconds."
        sleep 60
    done
    echo "Document status: $status"
}

#############################

doc_id=$(order_annual_accounts $NIF $DOC_TYPE $YEAR)
wait_for_document ${doc_id}
document_download ${doc_id} pdf
document_download ${doc_id} xbrl