Configurar capabilities SMP, Peppol Directory y businessCard a través de la API PSB.
La PSB es un Peppol Access Point certificado y un SMP (Service Metadata Publisher). A través de la API se configuran los tipos de documentos que una organización puede recibir, se publican los datos de la empresa en la Peppol Directory y se gestiona la inscripción SMP. Este artículo aborda el contexto técnico y los endpoints API que se utilizan para ello.
Peppol funciona con un modelo de 4 esquinas: el remitente (C1) envía a través de su Access Point (C2) un documento al Access Point del destinatario (C3), que lo reenvía al destinatario (C4). El enrutamiento se basa en dos componentes centrales:
Cuando envía una factura a través de la PSB, esta realiza automáticamente un lookup SML/SMP para encontrar el Access Point correcto del destinatario. Como integrador, no necesita hacerlo usted mismo.
La infraestructura Peppol se desarrolla activamente. Para los integradores que utilizan la API PSB, esto no tiene consecuencias: la PSB gestiona automáticamente los lookups SML/SMP. A continuación se detallan los desarrollos actuales a título informativo.
Internalización SML. OpenPeppol asume la gestión del SML de la Comisión Europea (DG DIGIT). La ventana de migración se abrió el 19 de marzo de 2026. Se aplican dos plazos separados: el plazo para inscripciones SMP es el 31 de mayo de 2026, el periodo de migración para AP Lookup (resolución DNS) se ha ampliado hasta el 31 de agosto de 2026. OpenPeppol discute con la Comisión Europea si el plazo de inscripción SMP también puede ampliarse. Para los integradores API no cambia nada en endpoints o lookups: la PSB gestiona la migración internamente.
Migración CNAME a NAPTR. La migración de registros DNS CNAME a registros NAPTR para lookups SML se completó en marzo de 2026. NAPTR es obligatorio desde el 1 de febrero de 2026. Los antiguos registros CNAME se eliminaron de la red de pruebas SMK (4 de marzo de 2026) y de la red de producción SML (11 de marzo de 2026). Se trata de un cambio DNS interno en la infraestructura Peppol. La PSB ya utiliza NAPTR y no se necesitan ajustes en su integración.
Migración PKI G3. OpenPeppol prepara la transición de los certificados PKI Generation 2 (G2) a Generation 3 (G3). Los certificados G3 se utilizan para la comunicación mutua entre Access Points. El Peppol Testbed admite certificados G2 y G3 desde marzo de 2026, para que los Service Providers puedan probar con anticipación. Aún no se ha publicado una fecha de transición obligatoria. Para los integradores API no cambia nada: la PSB gestiona la renovación de certificados internamente.
Peppol admite tipos de documentos logísticos además de facturas a través de la especificación Peppol Logistics. La versión 1.2 es obligatoria desde el 16 de marzo de 2026. La versión 1.3 está en member review hasta el 15 de abril de 2026, con publicación prevista el 18 de mayo de 2026.
Documentos logísticos admitidos:
Nuevas funciones en la versión 1.3:
La versión 1.3 resuelve los RFC LLC-27 a LLC-35, incluyendo alineamiento de ItemInstance, actualizaciones de no facturación y códigos de subtratamiento para residuos.
Al registrar una party en el SMP de eConnect, se determinan a través de capabilities qué tipos de documentos puede recibir esa party. Cada capability tiene tres estados posibles:
onoffinheritedEl valor recomendado para nuevas inscripciones es inherited, a menos que una party deba desviarse específicamente del estándar.
invoicesselfbillinginvoice_bisv2reviewsinvoiceResponseordersorderOnlyorderAdvancedorderResponseorderResponseAdvancedLas capabilities se configuran a través del endpoint Peppol config:
PUT /api/v1/peppol/config/party/{partyId}
En el cuerpo de la solicitud, especifique el estado deseado por capability. Un ejemplo:
{
"capabilities": {
"invoices": "on",
"selfbilling": "inherited",
"invoiceResponse": "on",
"orderOnly": "on",
"orderAdvanced": "off"
}
}
La Peppol Directory es el registro público de todos los participantes Peppol. Al publicar una businessCard, una party se vuelve localizable en la directory. La businessCard contiene:
La businessCard se publica a través del endpoint Enrollment o a través de la configuración SMP. Tras la publicación, la organización es localizable en directory.peppol.eu.
La API PSB no deriva ningún campo de un registro mercantil vinculado. Independientemente del esquema de identificador (KvK 0106, IVA 9944, OIN 0190, GLN 0088 u otro), tanto names como un address con código de país deben estar explícitamente presentes en la carga útil. Un ejemplo de una businessCard correctamente configurada:
"businessCard": {
"names": {
"value": "eVerbinding, eConnect",
"state": "on",
"description": "Business names."
},
"address": {
"value": "Pelmolenlaan 16A, 3447 GW, Woerden, NL",
"state": "on",
"description": "Geographic information."
},
"emailAddress": {
"value": "[email protected]",
"state": "on",
"description": "Technical contact"
},
"state": "on"
}
El código de país (en el ejemplo anterior, NL al final del campo address) debe incluirse explícitamente.
Both name(s) and country code are required when adding a business cardEste mensaje de error es diagnósticamente inequívoco: la carga útil enviada carece de names, o el address no contiene un código de país. La solución consiste siempre en añadir esos campos explícitamente en la carga útil de la businessCard, y no en modificar otro nivel (party, identificador, capacidades SMP). El mensaje aparece en la práctica con relativa frecuencia en la integración GLN (0088), porque los socios de integración GLN utilizan con menos frecuencia una plantilla que envíe estos campos por defecto. La PSB no presenta un comportamiento distinto para GLN respecto a otros esquemas.
La verificación previa de que un destinatario es accesible en Peppol se realiza por tipo de documento y mediante un endpoint de lookup avanzado:
POST /api/v1/{partyId}/salesInvoice/queryRecipientParty["0106:..."] o { "partyIds": [...], "metaAttributes": {...} }; parámetros opcionales ?preferredDocumentTypeId, ?includeOptionsPOST /api/v1/{partyId}/purchaseOrder/queryRecipientParty?documentFamily=OrderGET /api/v1/peppol/deliveryOption?partyIds=...&documentFamily=...&isCredit=...partyId, documentTypeId, processId, protocol (As2/As4), url, certificateLa respuesta muestra los canales disponibles, el Access Point seleccionado y los tipos de documentos admitidos. Utilice estos endpoints para validar de antemano si un envío tendrá éxito. Están disponibles de forma ilimitada en todos los planes (detección/discovery proactiva de rutas).
Nota: en caso de una discrepancia SML/SMP en el endpoint
deliveryOption, la llamada no falla inmediatamente. No existe manejo fail-fast en producción: la llamada continúa y devuelve un tiempo de espera después de aproximadamente 30 segundos. Tenga esto en cuenta en el manejo de errores de su integración.
Cada party en el SMP se identifica mediante un identificador con un schemeID. Los esquemas más utilizados:
01060106:1234567801900190:0000000123456789000099449944:NL123456789B010208BE:EN0208:01234567899925BE:VAT9925:BE0835689642 (también BE1xxxxxxxxx es válido desde 2025)00880088:1234567890123La API PSB acepta tanto el schemeID numérico como el código de letras: 9925:BE0835689642 es equivalente a BE:VAT:BE0835689642. Con herramientas de búsqueda externas (como el SMP lookup), deben utilizarse los schemeIDs numéricos oficiales.
Una party puede tener varios identificadores, pero cada factura solo puede contener un EndpointID.
En Bélgica se utilizan dos tipos de identificadores para Peppol. El número de empresa (KBO, schemeID 0208) es el número de identificación principal y obligatorio para la recepción Peppol. La inscripción por número de IVA (schemeID 9925) es opcional, por lo que buscar una organización belga por número de empresa tiene más éxito que por número de IVA.
El número de empresa se puede derivar del número de IVA eliminando el prefijo del código de país (BE). Por ejemplo: el número de IVA BE0835689642 corresponde al número de empresa 0835689642.
Al enviar un documento, la PSB extrae el identificador Peppol del elemento EndpointID en el XML. Este elemento determina a qué destinatario se enruta el documento. Si el EndpointID falta o está incorrectamente rellenado, el documento no es válido y recibe el estado InvoiceSentError.
Un XML incorrecto no se reintenta automáticamente. La corrección corresponde al sistema de origen (el paquete de software que genera la factura), no a la PSB. Verifique previamente a través de queryRecipientParty si el destinatario es accesible en la red Peppol.
¿Desea automatizar el proceso completo de registro? Consulte el artículo sobre la Enrollment API, que permite configurar registro, capabilities y hooks en una sola llamada API.
Consultar los endpoints SMP