Petición HTTP Pura (Cualquier Lenguaje)

Si programas en un lenguaje más atípico o quieres montar la petición HTTP en crudo (raw), la API del Micro Server de VeriFactu cumple con los estándares HTTP REST universales en todas sus operaciones.

Cualquier sistema moderno que sepa emitir un paquete TCP al exterior servirá: desde utilidades de visualización como Postman / Insomnia, scripts en herramientas NoCode como Make o Zapier, hasta un script de Bash clásico con curl.

WARNING

Aviso sobre el bloque metadata (JSON de Facturas) En algunos JSON de prueba locales verás un bloque raíz llamado "metadata": { "enviar_aeat": false, "simulacion": true, ... }. La API funciona perfectamente CON y SIN ese bloque. Se introdujo exclusivamente por compatibilidad con futuras versiones, pero se aconseja encarecidamente que prescindas totalmente de él para los procesos y desarrollos actuales, enviando únicamente "cabecera" y "detalle".

Naturaleza Agnóstica

TIP

No requerimos de vídeo demostrativo para el protocolo HTTP, porque es la capa inferior pura y dura subyacente. Si deseas entender cómo es el flujo mental lógico entre la emisión y la captura de resultados, te aconsejamos ver el vídeo de Python o C# en esta misma documentación, ya que demuestran qué impacto genera este puñado de peticiones por debajo.

A continuación detallamos el ciclo de vida completo orquestado estrictamente con comandos de terminal curl. Puedes exportarlos a la colección sintáctica del lenguaje que prefieras.

📦 Colección de Ejemplos en cURL (Bash)

Aquí te dejamos el desglose modular de las acciones expuestas en crudo:

`README.md`

Instrucciones de uso en terminal.

Ver/Ocultar Código Fuente (README.md)

markdown

# Integración mediante HTTP Puro (REST / cURL)

La forma más estandarizada e independiente del lenguaje de programación de conectarse al Micro Server VeriFactu B2B es mediante **peticiones HTTP REST puras**. 

Si estás programando en un lenguaje corporativo antiguo sin librerías de alto nivel, programando un PLC en una máquina industrial, o simplemente orquestando flujos vía *Bash* o utilidades como *Postman*, aquí tienes los cimientos de la arquitectura.

## Uso Rápido en Consola (Linux / WSL / Mac)

Los ficheros proporcionados en este paquete son scripts ejecutables de Bash (cURL).

1. Abre el terminal en esta ruta.
2. Da permisos de ejecución: `chmod +x *.sh`
3. Ejecuta en orden para simular el ciclo de vida de una factura:
   ```bash
   ./01_ingestar_factura.sh
   ./02_consultar_estado.sh
   ./03_ver_pendientes.sh
   ./04_confirmar_ack.sh

Nota: Asegúrate de tener instalado jq (sudo apt install jq) para que la salida de la consola te muestre el resultado bonito con colores, aunque puedes borrarlo de los scripts si lo prefieres.


</details>

### `factura_ejemplo.json`
Plantilla de factura (JSON).

<details>
<summary><strong>Ver/Ocultar Código Fuente (factura_ejemplo.json)</strong></summary>

```json
{
   
    "cabecera": {
        "emisor": "",
        "numfactura": "500",
        "serie": "FGH",
        "rectificativa": "N",
        "tipofacturarectificativa": "",
        "fecharectificada": "",
        "facturarectificada": "",
        "rectificativasustitucion": "",
        "facturaf3": "N",
        "numseriesustituidaf3": "",
        "fechafactsustituidaf3": "",
        "descripcionoperacion": "Tickets de venta cafetería A",
        "eliminacion": "",
        "tipodoc": "02",
        "pais": "ES",
        "nif": "",
        "nombre": "",
        "fecha": "15/02/2026",
        "totaliva": "14.36",
        "totalrecargo": "0.00",
        "base": "271.28",
        "base1": "250.65",
        "piva1": "4.00",
        "iva1": "10.03",
        "precargo1": "",
        "recargo1": "",
        "base2": "20.63",
        "piva2": "21.00",
        "iva2": "4.33",
        "precargo2": "",
        "recargo2": "",
        "base3": "",
        "piva3": "",
        "iva3": "",
        "precargo3": "",
        "recargo3": "",
        "base4": "",
        "piva4": "",
        "iva4": "",
        "precargo4": "",
        "recargo4": ""
    },
    "detalle": {
        "base": [
            "250.65",
            "20.63",
            "",
            ""
        ],
        "piva": [
            "4.00",
            "21.00",
            "",
            ""
        ],
        "iva": [
            "10.03",
            "4.33",
            "",
            ""
        ],
        "precargo": [
            "",
            "",
            "",
            ""
        ],
        "recargo": [
            "",
            "",
            "",
            ""
        ]
    }
}

`01_ingestar_factura.sh`

Petición HTTP equivalente a enviar factura.

Ver/Ocultar Código Fuente (01_ingestar_factura.sh)

bash

#!/bin/bash
# ==============================================================================
# VeriFactu API - Ejemplo 01: Ingestar Factura
# Permite remitir una factura en formato JSON para su validación contra AEAT
# ==============================================================================

# Configuración Base
MICROSERVER_URL="http://127.0.0.1:8000"
API_KEY="vf_sys_fgh_BEwEMUFqXWEfPOBKcY9INWdmaRFoAhLV"
NIF_EMISOR="B12345678"

# Validamos que el JSON de ejemplo exista
if [ ! -f "factura_ejemplo.json" ]; then
    echo "⚠️ Error: No se encontró 'factura_ejemplo.json' en el directorio actual."
    exit 1
fi

echo "🚀 Enviando JSON al Micro Server VeriFactu..."

curl -s -X POST "$MICROSERVER_URL/v1/ingesta" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Verifactu-Emisor: $NIF_EMISOR" \
  -d @factura_ejemplo.json | jq .

echo -e "\n✅ Petición finalizada."

`02_consultar_estado.sh`

Petición HTTP equivalente a verificar estado de factura enviada.

Ver/Ocultar Código Fuente (02_consultar_estado.sh)

bash

#!/bin/bash
# ==============================================================================
# VeriFactu API - Ejemplo 02: Consultar Estado de Factura (Polling)
# Permite consultar si una factura previamente enviada ha sido procesada por AEAT
# ==============================================================================

MICROSERVER_URL="http://127.0.0.1:8000"
API_KEY="vf_sys_fgh_BEwEMUFqXWEfPOBKcY9INWdmaRFoAhLV"
NIF_EMISOR="B12345678"

SERIE="FGH"
NUMERO="500"

echo "🔍 Consultando estado de la factura $SERIE-$NUMERO..."

curl -s -X GET "$MICROSERVER_URL/v1/check_status?emisor=$NIF_EMISOR&serie=$SERIE&num=$NUMERO" \
  -H "X-API-Key: $API_KEY" | jq .

echo -e "\n✅ Consulta finalizada."

`03_ver_pendientes.sh`

Petición HTTP equivalente a listar bandeja de facturas validadas.

Ver/Ocultar Código Fuente (03_ver_pendientes.sh)

bash

#!/bin/bash
# ==============================================================================
# VeriFactu API - Ejemplo 03: Ver Bandeja de Pendientes
# Obtiene el listado de facturas procesadas que están a la espera de confirmación (ACK)
# ==============================================================================

MICROSERVER_URL="http://127.0.0.1:8000"
API_KEY="vf_sys_fgh_BEwEMUFqXWEfPOBKcY9INWdmaRFoAhLV"
NIF_EMISOR="B12345678"
LIMITE=50

echo "📬 Solicitando últimas facturas validadas..."

curl -s -X GET "$MICROSERVER_URL/verifactu/pendientes?nif_emisor=$NIF_EMISOR&n_ultimos=$LIMITE" \
  -H "X-API-Key: $API_KEY" | jq .

echo -e "\n✅ Consulta finalizada."

`04_confirmar_ack.sh`

Petición HTTP equivalente a mandar Acuse de Recibo.

Ver/Ocultar Código Fuente (04_confirmar_ack.sh)

bash

#!/bin/bash
# ==============================================================================
# VeriFactu API - Ejemplo 04: Confirmar Acuse de Recibo (ACK)
# Elimina una factura de la bandeja de pendientes mediante su 'indice_log' interno
# ==============================================================================

MICROSERVER_URL="http://127.0.0.1:8000"
API_KEY="vf_sys_fgh_BEwEMUFqXWEfPOBKcY9INWdmaRFoAhLV"
NIF_EMISOR="B12345678"

# IMPORTANTE: Reemplaza este número por el 'indice_log' que obtengas del script 03
INDICE_LOG=1234 

echo "✔️ Confirmando ACK del ID de log: $INDICE_LOG..."

curl -s -X POST "$MICROSERVER_URL/verifactu/ack" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
        "nif_emisor": "'"$NIF_EMISOR"'",
        "indice_log": '"$INDICE_LOG"'
      }' | jq .

echo -e "\n✅ Operación finalizada."

Petición HTTP Pura (Cualquier Lenguaje) ​

Naturaleza Agnóstica ​

📦 Colección de Ejemplos en cURL (Bash) ​

README.md ​

01_ingestar_factura.sh ​

02_consultar_estado.sh ​

03_ver_pendientes.sh ​

04_confirmar_ack.sh ​

Petición HTTP Pura (Cualquier Lenguaje)

Naturaleza Agnóstica

📦 Colección de Ejemplos en cURL (Bash)

`README.md`

`01_ingestar_factura.sh`

`02_consultar_estado.sh`

`03_ver_pendientes.sh`

`04_confirmar_ack.sh`