Integración API

Visión general de la API

Nuestra API REST proporciona acceso programático a todas las funcionalidades de Jd-xa, permitiéndote integrar la automatización de facturación directamente en tus aplicaciones y flujos de trabajo existentes.

Arquitectura RESTful

Nuestra API sigue los principios de diseño RESTful, utilizando métodos HTTP estándar, URLs predecibles y formatos de respuesta JSON para una integración sencilla y consistente.

Seguridad avanzada

Todas las comunicaciones están protegidas mediante TLS/SSL y autenticación OAuth 2.0, garantizando que tus datos estén siempre seguros durante la transmisión.

Rendimiento optimizado

Nuestra API está diseñada para manejar grandes volúmenes de solicitudes con tiempos de respuesta mínimos, permitiéndote procesar facturas en masa de manera eficiente.

Características principales

Endpoints RESTful intuitivos

Respuestas JSON estructuradas

Paginación para grandes conjuntos

Filtrado y ordenación avanzados

Control de versiones API

Límites de tasa configurables

Webhooks para eventos

Documentación interactiva

Endpoints principales

Nuestra API proporciona endpoints para gestionar todo el ciclo de vida de las facturas, desde la creación hasta el seguimiento de pagos.

GET

/api/v1/clientes

Gestión de clientes

Permite gestionar la información de clientes para la facturación.

Operaciones disponibles:

GET Listar y filtrar clientes
POST Crear nuevo cliente
PUT Actualizar cliente existente
DELETE Eliminar cliente

{
  "id": "cli_12345",
  "nombre": "Empresa Ejemplo S.L.",
  "cif": "B12345678",
  "direccion": {
    "calle": "Calle Principal 123",
    "ciudad": "Madrid",
    "codigo_postal": "28001",
    "pais": "España"
  },
  "contacto": {
    "nombre": "Juan Pérez",
    "email": "juan@ejemplo.com",
    "telefono": "+34612345678"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-02-20T15:45:00Z"
}

GET

/api/v1/facturas

Gestión de facturas

Permite crear, consultar y gestionar facturas electrónicas.

Operaciones disponibles:

GET Listar y filtrar facturas
POST Crear nueva factura
PUT Actualizar factura (si no está emitida)
PATCH Actualizar estado de factura

{
  "id": "fac_67890",
  "numero": "FAC-2025-0123",
  "cliente_id": "cli_12345",
  "fecha_emision": "2025-03-10T12:00:00Z",
  "fecha_vencimiento": "2025-04-10T23:59:59Z",
  "estado": "emitida",
  "moneda": "EUR",
  "items": [
    {
      "descripcion": "Servicio de consultoría",
      "cantidad": 10,
      "precio_unitario": 100.00,
      "impuesto": 21,
      "importe": 1000.00
    }
  ],
  "subtotal": 1000.00,
  "impuestos": 210.00,
  "total": 1210.00,
  "notas": "Factura por servicios prestados en febrero 2025",
  "created_at": "2025-03-10T12:00:00Z",
  "updated_at": "2025-03-10T12:00:00Z"
}

POST

/api/v1/envios

Envío de facturas

Permite gestionar el envío de facturas a través de diferentes canales.

Operaciones disponibles:

POST Enviar factura por email
POST Enviar factura a plataforma FACe
GET Consultar estado de envíos
POST Reenviar factura

{
  "factura_id": "fac_67890",
  "canal": "email",
  "destinatarios": [
    "juan@ejemplo.com",
    "contabilidad@ejemplo.com"
  ],
  "asunto": "Factura FAC-2025-0123",
  "mensaje": "Adjuntamos factura por los servicios prestados",
  "adjuntos": [
    {
      "tipo": "pdf"
    },
    {
      "tipo": "xml"
    }
  ],
  "programado_para": null,
  "estado": "enviado",
  "fecha_envio": "2025-03-10T12:05:30Z",
  "intentos": 1,
  "id": "env_54321"
}

GET

/api/v1/pagos

Gestión de pagos

Permite registrar y consultar pagos asociados a facturas.

Operaciones disponibles:

GET Consultar pagos de facturas
POST Registrar nuevo pago
PUT Actualizar información de pago
DELETE Eliminar registro de pago

{
  "id": "pag_98765",
  "factura_id": "fac_67890",
  "fecha": "2025-03-25T14:30:00Z",
  "importe": 1210.00,
  "metodo": "transferencia",
  "referencia": "TR-123456789",
  "notas": "Pago recibido en cuenta bancaria",
  "estado": "confirmado",
  "created_at": "2025-03-25T15:00:00Z",
  "updated_at": "2025-03-25T15:00:00Z"
}

Estos son solo algunos ejemplos de los endpoints disponibles. Nuestra API incluye muchas más funcionalidades para cubrir todos los aspectos de la automatización de facturación.

Ver documentación completa de la API

Gestión de claves API

Nuestro panel de administración te permite:

Generar y revocar claves API
Establecer permisos granulares por clave
Monitorizar el uso de cada clave
Configurar límites de tasa por clave

Autenticación y seguridad

Nuestra API utiliza estándares de seguridad avanzados para proteger tus datos durante la transmisión y garantizar que solo usuarios autorizados puedan acceder a tus recursos.

OAuth 2.0

Utilizamos el protocolo OAuth 2.0 para la autenticación, proporcionando un método seguro y estándar para autorizar el acceso a tus recursos sin compartir credenciales.

Ejemplo de autenticación

// Solicitud de token
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

// Respuesta
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

TLS/SSL

Todas las comunicaciones con nuestra API están protegidas mediante TLS 1.3, garantizando que todos los datos transmitidos estén cifrados y sean seguros contra interceptaciones.

Control de acceso basado en roles

Implementamos un sistema de permisos granular que te permite controlar exactamente qué operaciones puede realizar cada clave API, siguiendo el principio de privilegio mínimo.

Auditoría y monitorización

Registramos y monitorizamos todas las solicitudes a la API, proporcionándote visibilidad completa sobre quién accede a tus datos y qué operaciones se realizan.

SDKs y bibliotecas de cliente

Para facilitar aún más la integración, ofrecemos bibliotecas de cliente oficiales en varios lenguajes de programación populares.

PHP

Biblioteca cliente para PHP con soporte para Composer y compatible con PHP 7.4 y superior.

composer require Jd-xa/api-client-php

Ver en GitHub

Node.js

Biblioteca cliente para Node.js con soporte para promesas, async/await y TypeScript.

npm install @Jd-xa/api-client

Ver en GitHub

Python

Biblioteca cliente para Python 3.7+ con soporte para sincronización y asincronía.

pip install Jd-xa-api-client

Ver en GitHub

También ofrecemos bibliotecas para Java, .NET, Go y Ruby. Si necesitas soporte para otro lenguaje, no dudes en contactarnos.

Ver todas las bibliotecas

Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre eventos importantes en tu cuenta de Jd-xa, permitiéndote construir integraciones reactivas y mantener tus sistemas sincronizados.

Eventos disponibles

Recibe notificaciones para una amplia variedad de eventos:

factura.creada

factura.emitida

factura.enviada

factura.vista

factura.pagada

factura.vencida

pago.recibido

cliente.creado

Seguridad en webhooks

Todos los webhooks incluyen una firma digital que te permite verificar que la notificación proviene realmente de Jd-xa y no ha sido manipulada.

Configuración flexible

Configura múltiples endpoints para diferentes eventos, estableciendo filtros específicos para recibir solo las notificaciones que te interesan.

Ejemplo de payload de webhook

{
  "id": "evt_123456",
  "tipo": "factura.pagada",
  "created_at": "2025-03-25T15:05:30Z",
  "datos": {
    "factura_id": "fac_67890",
    "numero": "FAC-2025-0123",
    "cliente_id": "cli_12345",
    "total": 1210.00,
    "pago": {
      "id": "pag_98765",
      "fecha": "2025-03-25T14:30:00Z",
      "importe": 1210.00,
      "metodo": "transferencia"
    }
  }
}

Verificación de firma

Cada webhook incluye un encabezado X-Jd-xa-Signature que puedes usar para verificar la autenticidad del mensaje:

// Ejemplo en PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_Jd-xa_SIGNATURE'];
$secret = 'tu_clave_secreta_de_webhook';

$calculatedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($calculatedSignature, $signature)) {
  // El webhook es auténtico
  $data = json_decode($payload, true);
  // Procesar el evento...
} else {
  // Firma inválida, rechazar el webhook
  http_response_code(403);
  exit();
}

Integración API

Visión general de la API

Arquitectura RESTful

Seguridad avanzada

Rendimiento optimizado

Características principales

Endpoints principales

/api/v1/clientes

Operaciones disponibles:

/api/v1/facturas

Operaciones disponibles:

/api/v1/envios

Operaciones disponibles:

/api/v1/pagos

Operaciones disponibles:

Gestión de claves API

Autenticación y seguridad

OAuth 2.0

Ejemplo de autenticación

TLS/SSL

Control de acceso basado en roles

Auditoría y monitorización

SDKs y bibliotecas de cliente

PHP

Node.js

Python

Webhooks

Eventos disponibles

Seguridad en webhooks

Configuración flexible

Ejemplo de payload de webhook

Verificación de firma

¿Listo para integrar?

Este sitio utiliza cookies