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

4. Implementación

Para este ejemplo imaginemos que nos interesa solicitar las Cuentas Anuales de MERCADONA SA del año 2020.

Por lo tanto la URL es:

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

y los parámetros POST necesarios son los siguientes:

• nif: A46103834
• type: accounts
• year: 2020

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("A46103834", "accounts", 2020)
    print(doc)

5. 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 time

import requests


# Document request (adjust accordingly)
NIF = "A46103834"
DOCUMENT_TYPE = "accounts"
YEAR = 2020

# 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 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!")
            print("")
            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"]
    print(doc_request)
    print("")

    doc = wait_for_document(document_id)

    print("Document status:", doc["status"])
    print("Download link", doc["download_link"])

    req = requests.get(doc["download_link"])
    filename = "memoria.pdf"
    with open(filename, "wb") as fp:
        fp.write(req.content)
    print(f"\nWritten file: {filename}")

6. Métodos alternativos

Usando curl:

#!/bin/sh
NIF=B65208183
YEAR=2020
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/
curl -u $CREDENTIALS https://api.librebor.me/v2/order/db6105e7-8559-48fe-8089-903595a1c289/

Usando httpie:

#!/bin/sh
NIF=B65208183
YEAR=2020
CREDENTIALS=username:password

http -f -a $CREDENTIALS POST https://api.librebor.me/v2/documents/order/ nif=$NIF type=accounts year=$YEAR send_email=true
http -a $CREDENTIALS https://api.librebor.me/v2/order/db6105e7-8559-48fe-8089-903595a1c289/

Script completo:

#!/bin/sh
NIF=B65208183
YEAR=2020
CREDENTIALS=username:password

result=$(http -f -a $username:$password POST https://api.librebor.me/v2/documents/order/ nif=$NIF type=accounts year=$YEAR send_email=true)
doc_id=$(echo $result | jq -r .document_id)

while true
do
    echo -n "Checking if document ${doc_id} is ready... "
    document=$(http -a $username:$password https://api.librebor.me/v2/documents/${doc_id}/)
    status=$(echo $document | jq -r .document.status)
    if [ "$status" != "processing" ]; then
        echo "YES!\n"
        break
    fi
    echo "Not yet. Will retry in 60 seconds."
    sleep 60
done

download_link=$(echo $document | jq -r .document.download_link)
echo "Document status: $status"
echo "Download link: $download_link"

wget $download_link