Documentación API VeriFactu – Conecta EDI

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

1. ✅ Codificación: Usar siempre UTF-8 para caracteres españoles
2. ✅ Campos obligatorios: supplier, customer, items, totals
3. ✅ Formato fechas: YYYY-MM-DD
4. ✅ Moneda: EUR (por defecto)
5. ✅ 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.