Documentación API VeriFactu

⭐⭐⭐⭐⭐ 5/5 en Trustpilot · Proveedor EDI certificado con ALDI Nord

Autenticación

Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

Endpoint

POST https://app.conectaedi.com/api/verifactu/invoices

Estructura del JSON de Entrada

Ejemplo Completo:

{
  "invoice_number": "F-2025-001",
  "invoice_date": "2025-11-15",
  "currency": "EUR",
  "supplier": {
    "business_name": "Mi Empresa SL",
    "tax_id": "B12345678",
    "street_line_1": "Calle Comercio 123",
    "city": "Barcelona",
    "postal_code": "08001",
    "country": "ES"
  },
  "customer": {
    "first_name": "Luis",
    "last_name": "García",
    "street_line_1": "Calle Alcalá 456",
    "city": "Madrid", 
    "postal_code": "28014",
    "country": "ES",
    "tax_id": "00000000T"
  },
  "items": [
    {
      "description": "Suscripción mensual a contenido digital",
      "quantity": 1,
      "unit_price": 9.90,
      "net_amount": 9.90,
      "tax_rate": 21.0,
      "tax_amount": 2.08,
      "total_amount": 11.98,
      "product_code": "DIG_ES_001",
      "tax_type": "VAT"
    }
  ],
  "totals": {
    "total_net_amount": 9.90,
    "total_tax_amount": 2.08,
    "total_amount": 11.98
  },
  "payment": {
    "method": "credit_card",
    "due_date": "2025-12-15"
  }
}

Estructura Detallada

Header (Cabecera – Obligatorio)

{
  "invoice_number": "F-2025-001",
  "invoice_date": "2025-11-15", 
  "currency": "EUR"
}

Supplier (Emisor – Obligatorio)

{
  "supplier": {
    "business_name": "string (razón social)",
    "tax_id": "string (CIF/NIF)",
    "street_line_1": "string (dirección)",
    "city": "string", 
    "postal_code": "string",
    "country": "string (código ISO)"
  }
}

Customer (Cliente – Obligatorio)

{
  "customer": {
    "first_name": "string",
    "last_name": "string", 
    "street_line_1": "string",
    "city": "string",
    "postal_code": "string",
    "country": "string",
    "tax_id": "string (NIF)"
  }
}

Items (Líneas de Factura – Obligatorio)

{
  "items": [
    {
      "description": "Producto o servicio",
      "unit_price": 100.00,        // Precio unitario (sin IVA)
      "quantity": 2,               // Cantidad
      "net_amount": 200.00,        // Base imponible (unit_price * quantity)
      "tax_rate": 21.0,            // Tipo impositivo (%)
      "tax_amount": 42.00,         // Cuota IVA
      "total_amount": 242.00       // Total línea (net_amount + tax_amount)
      }
    }
  ]
}

Totals (Totales de Factura – Obligatorio)

{
  "totals": {
    "total_net_amount": 9.90,
    "total_tax_amount": 2.08, 
    "total_amount": 11.98
  }
}

Payment (Pago – Opcional)

{
  "payment": {
    "method": "string (credit_card, transfer, etc.)",
    "due_date": "string (YYYY-MM-DD)"
  }
}

Respuestas de la API

Éxito (200 OK)

{
  "success": true,
  "jobId": 321,
  "status": "PROCESSING", 
  "message": "Factura recibida y en procesamiento",
  "mapper": "external_json",
  "timestamp": "2025-11-15T16:29:21.490Z"
}

Errores Comunes

400 – Datos Inválidos

{
  "success": false,
  "message": "Payload inválido. Campos requeridos: customer, items"
}

401 – API Key Inválida

{
  "success": false, 
  "message": "API Key inválida o inactiva"
}

500 – Error Interno

{
  "success": false,
  "message": "Error interno del servidor"
}

Ejemplos de Implementación

CURL

curl -X POST "https://app.conectaedi.com/api/verifactu/invoices" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "invoice_number": "F-2025-001",
    "invoice_date": "2025-11-15",
    "currency": "EUR",
    "supplier": {
      "business_name": "Mi Empresa SL",
      "tax_id": "B12345678",
      "street_line_1": "Calle Comercio 123", 
      "city": "Barcelona",
      "postal_code": "08001",
      "country": "ES"
    },
    "customer": {
      "first_name": "Luis",
      "last_name": "García",
      "street_line_1": "Calle Alcalá 456",
      "city": "Madrid",
      "postal_code": "28014",
      "country": "ES", 
      "tax_id": "00000000T"
    },
    "items": [
      {
        "description": "Servicio consultoría EDI",
        "quantity": 1,
        "unit_price": 150.00,
        "net_amount": 150.00,
        "tax_rate": 21.0,
        "tax_amount": 31.50,
        "total_amount": 181.50,
        "product_code": "CONSULT_EDI_001",
        "tax_type": "VAT"
      }
    ],
    "totals": {
      "total_net_amount": 150.00,
      "total_tax_amount": 31.50,
      "total_amount": 181.50
    },
    "payment": {
      "method": "transfer",
      "due_date": "2025-12-15"
    }
  }'

CURL versión compacta

curl -X POST "https://app.conectaedi.com/api/verifactu/invoices" -H "Authorization: Bearer TU_API_KEY" -H "Content-Type: application/json; charset=utf-8" -d '{"invoice_number":"F-2025-001","invoice_date":"2025-11-15","currency":"EUR","supplier":{"business_name":"Mi Empresa SL","tax_id":"B12345678","street_line_1":"Calle Comercio 123","city":"Barcelona","postal_code":"08001","country":"ES"},"customer":{"first_name":"Luis","last_name":"García","street_line_1":"Calle Alcalá 456","city":"Madrid","postal_code":"28014","country":"ES","tax_id":"00000000T"},"items":[{"description":"Servicio consultoría EDI","quantity":1,"unit_price":150.00,"net_amount":150.00,"tax_rate":21.0,"tax_amount":31.50,"total_amount":181.50,"product_code":"CONSULT_EDI_001","tax_type":"VAT"}],"totals":{"total_net_amount":150.00,"total_tax_amount":31.50,"total_amount":181.50},"payment":{"method":"transfer","due_date":"2025-12-15"}}'

PowerShell con Invoke-RestMethod

$body = '{"invoice_number":"F-2025-001","invoice_date":"2025-11-15","currency":"EUR","supplier":{"business_name":"Mi Empresa SL","tax_id":"B12345678","street_line_1":"Calle Comercio 123","city":"Barcelona","postal_code":"08001","country":"ES"},"customer":{"first_name":"Luis","last_name":"García","street_line_1":"Calle Alcalá 456","city":"Madrid","postal_code":"28014","country":"ES","tax_id":"00000000T"},"items":[{"description":"Suscripción mensual a contenido digital","quantity":1,"unit_price":9.90,"net_amount":9.90,"tax_rate":21.0,"tax_amount":2.08,"total_amount":11.98,"product_code":"DIG_ES_001","tax_type":"VAT"}],"totals":{"total_net_amount":9.90,"total_tax_amount":2.08,"total_amount":11.98},"payment":{"method":"credit_card","due_date":"2025-12-15"}}'; $utf8Body = [System.Text.Encoding]::UTF8.GetBytes($body); Invoke-RestMethod -Uri "http://localhost:5000/api/verifactu/invoices" -Method Post -Headers @{"Authorization"="Bearer mgjsb85HnrtyfBGFRmffRTN"} -Body $utf8Body -ContentType "application/json; charset=utf-8"

JavaScript/Node.js

const response = await fetch('https://app.conectaedi.com/api/verifactu/invoices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TU_API_KEY',
    'Content-Type': 'application/json; charset=utf-8'
  },
  body: JSON.stringify({
    "invoice_number": "F-2025-001",
    "invoice_date": "2025-11-15",
    "currency": "EUR",
    "supplier": {
      "business_name": "Mi Empresa SL",
      "tax_id": "B12345678",
      "street_line_1": "Calle Comercio 123",
      "city": "Barcelona",
      "postal_code": "08001", 
      "country": "ES"
    },
    "customer": {
      "first_name": "Luis",
      "last_name": "García",
      "street_line_1": "Calle Alcalá 456",
      "city": "Madrid",
      "postal_code": "28014",
      "country": "ES",
      "tax_id": "00000000T"
    },
    "items": [{
      "description": "Implementación plataforma EDI",
      "quantity": 1,
      "unit_price": 150.00,
      "net_amount": 150.00,
      "tax_rate": 21.0,
      "tax_amount": 31.50,
      "total_amount": 181.50,
      "tax_type": "VAT"
    }],
    "totals": {
      "total_net_amount": 150.00,
      "total_tax_amount": 31.50,
      "total_amount": 181.50
    },
    "payment": {
      "method": "credit_card",
      "due_date": "2025-12-15"
    }
  })
});

Python

import requests

url = "https://app.conectaedi.com/api/verifactu/invoices"
headers = {
    "Authorization": "Bearer TU_API_KEY",
    "Content-Type": "application/json; charset=utf-8"
}
data = {
    "invoice_number": "F-2025-001",
    "invoice_date": "2025-11-15",
    "currency": "EUR",
    "supplier": {
        "business_name": "Mi Empresa SL",
        "tax_id": "B12345678",
        "street_line_1": "Calle Comercio 123",
        "city": "Barcelona",
        "postal_code": "08001",
        "country": "ES"
    },
    "customer": {
        "first_name": "Luis",
        "last_name": "García", 
        "street_line_1": "Calle Alcalá 456",
        "city": "Madrid",
        "postal_code": "28014",
        "country": "ES",
        "tax_id": "00000000T"
    },
    "items": [{
        "description": "Desarrollo integración VERIFACTU",
        "quantity": 1,
        "unit_price": 150.00,
        "net_amount": 150.00,
        "tax_rate": 21.0,
        "tax_amount": 31.50,
        "total_amount": 181.50,
        "tax_type": "VAT"
    }],
    "totals": {
        "total_net_amount": 150.00,
        "total_tax_amount": 31.50,
        "total_amount": 181.50
    },
    "payment": {
        "method": "transfer",
        "due_date": "2025-12-15"
    }
}

response = requests.post(url, headers=headers, json=data)

Notas Importantes

✅ Codificación: Usar siempre UTF-8 para caracteres españoles
✅ Campos obligatorios: supplier, customer, items, totals
✅ Formato fechas: YYYY-MM-DD
✅ Moneda: EUR (por defecto)
✅ Impuestos: Especificar rate como porcentaje (21.0, 10.0, etc.)

Obtención de API Key

Contacta con el equipo de CONECTA EDI para obtener tus credenciales de API.

Conecta EDI

¿Hablamos de tu caso? Sin compromiso y con un experto EDI.

Solicitar demo Hablar con un consultor